Payment Request

The Payment Request object A PaymentRequest object is used to collect payment information through an interface controlled and styled by the browser itself (i.e., not by you or your page). ## Create a PaymentRequestObject stripe.paymentRequest(options: object) Use stripe.paymentRequest to create a PaymentRequest object. Creating a PaymentRequest requires that you configure it with an options object. In Safari, stripe.paymentRequest uses Apple Pay, and in other browsers it uses the Payment Request API standard. > stripe.paymentRequest abstracts over a number of implementation > details to work uniformly across Apple Pay and the Payment Request > browser standard. In particular, under the hood we set supportedNetworks > to its most permissive setting, dynamically accounting for country > and platform. It is currently not possible to override this and make > supportedNetworks be more restrictive. - options A set of options to create this PaymentRequest instance with. These options can be updated using paymentRequest.update. - country The two-letter country code of your Stripe account (e.g., US). - currency Three character currency code (e.g., usd). - total A PaymentItem object. This PaymentItem is shown to the customer in the browser’s payment interface. - displayItems An array of PaymentItem objects. These objects are shown as line items in the browser’s payment interface. Note that the sum of the line item amounts does not need to add up to the total amount above. - requestPayerName By default, the browser‘s payment interface only asks the customer for actual payment information. A customer name can be collected by setting this option to true. This collected name will appears in the PaymentResponse object. We highly recommend you collect name as this also results in collection of billing address for Apple Pay. The billing address can be used to perform address verification and block fraudulent payments. For all other payment methods, the billing address is automatically collected when available. - requestPayerEmail See the requestPayerName option. - requestPayerPhone See the requestPayerName option. - requestShipping Collect shipping address by setting this option to true. The address appears in the PaymentResponse. You must also supply a valid [ShippingOptions] to the shippingOptions property. This can be up front at the time stripe.paymentRequest is called, or in response to a shippingaddresschange event using the updateWith callback. - shippingOptions An array of ShippingOption objects. The first shipping option listed appears in the browser payment interface as the default option. - disableWallets An array of wallet strings. Can be one or more of applePay, googlePay, link, and browserCard. Use this option to disable Apple Pay, Google Pay, Link (also known as Onelink in the UK), and/or browser-saved cards. - applePay Specify Apple Pay specific options. These are passed through to the Apple Pay API. - recurringPaymentRequest Specify a request to set up a recurring payment. See the Apple Pay documentation for more details. - paymentDescription - managementURL - regularBilling - amount - label - recurringPaymentStartDate - recurringPaymentEndDate - recurringPaymentIntervalUnit - recurringPaymentIntervalCount - trialBilling - amount - label - recurringPaymentStartDate - recurringPaymentEndDate - recurringPaymentIntervalUnit - recurringPaymentIntervalCount - billingAgreement - deferredPaymentRequest Specify a request to set up a deferred payment. See the Apple Pay documentation for more details. - paymentDescription - managementURL - deferredBilling - amount - amountType Indicates whether the billing amount is known at request time. When set to 'final', the Apple Pay payment sheet shows the configured amount. - label - deferredPaymentDate - billingAgreement - freeCancellationDate If set, you must also supply a freeCancellationDateTimeZone. - freeCancellationDateTimeZone If set, you must also supply a freeCancellationDate. These are tz timezones such as America/Los_Angeles, Europe/Dublin, and Asia/Singapore. - automaticReloadPaymentRequest Specify a request to set up an automatic reload payment. See the Apple Pay documentation for more details. - paymentDescription - managementURL - automaticReloadBilling - amount - label - automaticReloadPaymentThresholdAmount - billingAgreement - cardFunding By default, Apple Pay allows both credit and debit cards. You can specify if you only want to support one type of card with either 'supportsDebit' or 'supportsCredit'. - onBehalfOf The Stripe account ID which is the business of record. See use cases to determine if this option is relevant for your integration. This should match the on_behalf_of provided on the Intent used when confirming payment. ### Example title Create a PaymentRequestObject ## Check if a payment can be made paymentRequest.canMakePayment() Returns a Promise that resolves with an object detailing if an enabled wallet is ready to pay. If no wallet is available, it resolves with null. The resolution object has the properties in the table below. When using a custom button, inspect the return object's properties to determine which wallet branding to display. > canMakePayment resolves to null outside the following supported cases: > > * Safari 10.1+ (desktop and mobile) > * with a saved Apple Pay card > * or when in a Private Browsing window > * or when the “Allow websites to check if Apple Pay is set up” preference is disabled > * Chrome 61+ (desktop and mobile) > * with a saved Google Pay card > * or when the browser has a saved card (i.e. autofill) ### Return object properties - applePay true if Apple Pay wallet is ready to pay. Use a custom button that conforms to the Apple Pay Human Interface Guidelines. - googlePay true if Google Pay wallet is ready to pay. Use a custom button that conforms to the Google Pay Brand Guidelines. - link true if Link wallet is ready to pay (Link is also known as Onelink in the UK). Link is not supported in custom button configurations. ### Example title paymentRequest.canMakePayment ## Show the payment request interface paymentRequest.show() Shows the browser’s payment interface. This method must be called as the result of a user interaction (for example, in a click handler). ### Example title Show the payment request interface ## Update a PaymentRequest object paymentRequest.update(options: object) PaymentRequest instances can be updated with an options object. Available options are documented below. paymentRequest.update can only be called when the browser payment interface is not showing. To update the PaymentRequest right before the payment interface is initiated, call paymentRequest.update in your click event handler before calling paymentRequest.show. - options A set of options to update this PaymentRequest instance with. - currency Three character currency code (e.g., usd). - total A PaymentItem object. This PaymentItem is shown to the customer in the browser’s payment interface. - displayItems An array of PaymentItem objects. These payment items are shown as line items in the browser’s payment interface. Note that the sum of the line item amounts does not need to add up to the total amount above. - shippingOptions An array of ShippingOption objects. The first shipping option listed appears in the browser payment interface as the default option. - applePay Specify Apple Pay specific options. These are passed through to the Apple Pay API. - recurringPaymentRequest Specify a request to set up a recurring payment. See the Apple Pay documentation for more details. - paymentDescription - managementURL - regularBilling - amount - label - recurringPaymentStartDate - recurringPaymentEndDate - recurringPaymentIntervalUnit - recurringPaymentIntervalCount - trialBilling - amount - label - recurringPaymentStartDate - recurringPaymentEndDate - recurringPaymentIntervalUnit - recurringPaymentIntervalCount - billingAgreement - deferredPaymentRequest Specify a request to set up a deferred payment. See the Apple Pay documentation for more details. - paymentDescription - managementURL - deferredBilling - amount - amountType Indicates whether the billing amount is known at request time. When set to 'final', the Apple Pay payment sheet shows the configured amount. - label - deferredPaymentDate - billingAgreement - freeCancellationDate If set, you must also supply a freeCancellationDateTimeZone. - freeCancellationDateTimeZone If set, you must also supply a freeCancellationDate. These are tz timezones such as America/Los_Angeles, Europe/Dublin, and Asia/Singapore. - automaticReloadPaymentRequest Specify a request to set up an automatic reload payment. See the Apple Pay documentation for more details. - paymentDescription - managementURL - automaticReloadBilling - amount - label - automaticReloadPaymentThresholdAmount - billingAgreement - cardFunding By default, Apple Pay allows both credit and debit cards. You can specify if you only want to support one type of card with either 'supportsDebit' or 'supportsCredit'. ### Example title Update a PaymentRequest ## PaymentRequest events PaymentRequest instances emit several different types of events. ## Token event paymentRequest.on(event: string, handler: function) Stripe.js automatically creates a Token after the customer is done interacting with the browser’s payment interface. To access the created Token, listen for this event. - event The name of the event. In this case, token. - handler A callback function that will be called with a PaymentResponse object when the event is fired. The PaymentResponse object will contain a token field. ### Example title Handle 'token' event ## PaymentMethod event paymentRequest.on(event: string, handler: function) Stripe.js automatically creates a PaymentMethod after the customer is done interacting with the browser’s payment interface. To access the created PaymentMethod, listen for this event. - event The name of the event. In this case, paymentmethod. - handler A callback function that will be called with a PaymentResponse object when the event is fired. The PaymentResponse object will contain a paymentMethod field. ### Example title Handle 'paymentmethod' event ## Source event paymentRequest.on(event: string, handler: function) Stripe.js automatically creates a Source after the customer is done interacting with the browser’s payment interface. To access the created source, listen for this event. - event The name of the event. In this case, source. - handler A callback function that will be called with a PaymentResponse object when the event is fired. The PaymentResponse object will contain a source field. ### Example title Handle 'source' event ## Cancel event paymentRequest.on(event: string, handler: function) The cancel event is emitted from a PaymentRequest when the browser‘s payment interface is dismissed. Note that in some browsers, the payment interface may be dismissed by the customer even after they authorize the payment. This means that you may receive a cancel event on your PaymentRequest object after receiving a token, paymentmethod, or source event. If you’re using the cancel event as a hook for canceling the customer’s order, make sure you also refund the payment that you just created. - event The name of the event. In this case, cancel. - handler A callback function that you will provide that will be called when the event is fired. ### Example title Handle 'cancel' event ## Shipping address change event paymentRequest.on(event: string, handler: function) The shippingaddresschange event is emitted from a PaymentRequest whenever the customer selects a new address in the browser's payment interface. - event The name of the event. In this case, shippingaddresschange. - handler handler(event) => void is a callback function that you provide that will be called when the event is fired. When called it will be passed an event object with the following properties: - updateWith updateWith(updateDetails) => void is a Stripe.js provided function that is called with an UpdateDetails object to merge your updates into the current PaymentRequest object. Note that if you subscribe to shippingaddresschange events, then you must call updateWith within 30 seconds. - shippingAddress The customer's selected shipping address. To maintain privacy, browsers may anonymize the shipping address by removing sensitive information that is not necessary to calculate shipping costs. Depending on the country, some fields can be missing or partially redacted. For example, the shipping address in the U.S. may only contain a city, state, and ZIP code. The full shipping address appears in the PaymentResponse object after the purchase is confirmed in the browser’s payment interface - country Two-letter country code, capitalized. Valid two-letter country codes are specified by the related setting alpha-2. - addressLine An array of address line items. For example, 185 Berry St., Suite 500, P.O. Box 12345, etc. - region The most coarse subdivision of a country. Depending on the country, this might correspond to a state, a province, an oblast, a prefecture, or something else along these lines. - city The name of a city, town, village, etc. - postalCode The postal code or ZIP code, also known as PIN code in India. - recipient The name of the recipient. This might be a person, a business name, or contain "care of" (c/o) instructions. - phone The phone number of the recipient. Note that this might be different from any phone number you collect with requestPayerPhone. - sortingCode The sorting code as used in, for example, France. Not present on Apple platforms. - dependentLocality A logical subdivision of a city. Can be used for things like neighborhoods, boroughs, districts, or UK dependent localities. Not present on Apple platforms. ### Example title Handle 'shippingaddresschange' event ## Shipping option change event paymentRequest.on(event: string, handler: function) The shippingoptionchange event is emitted from a PaymentRequest whenever the customer selects a new shipping option in the browser's payment interface. - event The name of the event. In this case, shippingoptionchange. - handler handler(event) => void is a callback function that you provide that will be called when the event is fired. When called it will be passed an event object with the following properties: - updateWith updateWith(updateDetails) => void is a Stripe.js provided function that is called with an UpdateDetails object to merge your updates into the current PaymentRequest object. Note that if you subscribe to shippingoptionchange events, then you must call updateWith within 30 seconds. - shippingOption The customer's selected ShippingOption. ### Example title Handle 'shippingoptionchange' event