## 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).

See the [Payment Request Button Element quickstart](/stripe-js/elements/payment-request-button.md) for a high-level overview of when you’d want to do this.

## Create a PaymentRequestObject

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](https://www.w3.org/TR/payment-request/).

> `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.

**Syntax:** `stripe.paymentRequest(...)`

- `options` (object) **required**
  A set of options to create this `PaymentRequest` instance with.
These options can be updated using [`paymentRequest.update`](/js/payment_request/update.md).

  - `country` (string) **required**
    The two-letter country code of your Stripe account (e.g., `US`).

  - `currency` (string) **required**
    Three character currency code (e.g., `usd`).

  - `total` (PaymentItem) **required**
    A [PaymentItem](#payment_item_object) object.
This `PaymentItem` is shown to the customer in the browser’s payment interface.

  - `displayItems` (array)
    An array of [PaymentItem](#payment_item_object) 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` (boolean)
    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](/js/appendix/payment_response.md) 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` (boolean)
    See the [`requestPayerName`](#payment_request_create-options-requestPayerName) option.

  - `requestPayerPhone` (boolean)
    See the [`requestPayerName`](#payment_request_create-options-requestPayerName) option.

  - `requestShipping` (boolean)
    Collect shipping address by setting this option to `true`.
The address appears in the [PaymentResponse](/js/appendix/payment_response.md).

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` (array)
    An array of [ShippingOption](/js/appendix/shipping_option.md) objects.
The first shipping option listed appears in the browser payment interface as the default option.

  - `disableWallets` (array)
    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, and/or browser-saved cards.

  - `applePay` (object)
    Specify Apple Pay specific options. These are passed through to the Apple Pay API.

    - `recurringPaymentRequest` (object)
      Specify a request to set up a recurring payment. See the [Apple Pay documentation](https://developer.apple.com/documentation/apple_pay_on_the_web/applepayrecurringpaymentrequest) for more details.

      - `paymentDescription` (string) **required**

      - `managementURL` (string) **required**

      - `regularBilling` (object) **required**

        - `amount` (number) **required**

        - `label` (string) **required**

        - `recurringPaymentStartDate` (Date)

        - `recurringPaymentEndDate` (Date)

        - `recurringPaymentIntervalUnit` ('year' | 'month' | 'day' | 'hour' | 'minute')

        - `recurringPaymentIntervalCount` (number)

      - `trialBilling` (object)

        - `amount` (number) **required**

        - `label` (string) **required**

        - `recurringPaymentStartDate` (Date)

        - `recurringPaymentEndDate` (Date)

        - `recurringPaymentIntervalUnit` ('year' | 'month' | 'day' | 'hour' | 'minute')

        - `recurringPaymentIntervalCount` (number)

      - `billingAgreement` (string)

    - `deferredPaymentRequest` (object)
      Specify a request to set up a deferred payment. See the [Apple Pay documentation](https://developer.apple.com/documentation/apple_pay_on_the_web/applepaydeferredpaymentrequest) for more details.

      - `paymentDescription` (string) **required**

      - `managementURL` (string) **required**

      - `deferredBilling` (object) **required**

        - `amount` (number) **required**

        - `label` (string) **required**

        - `deferredPaymentDate` (Date) **required**

      - `billingAgreement` (string)

      - `freeCancellationDate` (Date)
        If set, you must also supply a freeCancellationDateTimeZone.

      - `freeCancellationDateTimeZone` (string)
        If set, you must also supply a freeCancellationDate.

These are [tz](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) timezones such as `America/Los_Angeles`, `Europe/Dublin`, and `Asia/Singapore`.

    - `automaticReloadPaymentRequest` (object)
      Specify a request to set up an automatic reload payment. See the [Apple Pay documentation](https://developer.apple.com/documentation/apple_pay_on_the_web/applepayautomaticreloadpaymentrequest) for more details.

      - `paymentDescription` (string) **required**

      - `managementURL` (string) **required**

      - `automaticReloadBilling` (object) **required**

        - `amount` (number) **required**

        - `label` (string) **required**

        - `automaticReloadPaymentThresholdAmount` (number) **required**

      - `billingAgreement` (string)

    - `cardFunding` ('supportsDebit' | 'supportsCredit')
      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` (string)
    The Stripe account ID which is the business of record. See [use cases](/connect/charges.md) to determine if this option is relevant for your integration. This should match the [on_behalf_of](/api/payment_intents/create.md#create_payment_intent-on_behalf_of) provided on the Intent used when confirming payment.

### Create a PaymentRequestObject

```js
var paymentRequest = stripe.paymentRequest({
  country: 'US',
  currency: 'usd',
  total: {
    label: 'Demo total',
    amount: 1000,
  },
  requestPayerName: true,
  requestPayerEmail: true,
});
```

```es_next
const paymentRequest = stripe.paymentRequest({
  country: 'US',
  currency: 'usd',
  total: {
    label: 'Demo total',
    amount: 1000,
  },
  requestPayerName: true,
  requestPayerEmail: true,
});
```

## Check if a payment can be made

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.

**NOTE**: The `paymentRequestButton` element automatically shows the correct wallet branding.
You shouldn't need to inspect the return object's properties unless you are building your own custom button.

> `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)
> 
> For more information, see [Testing your integration](/stripe-js/elements/payment-request-button.md#testing).

**Syntax:** `paymentRequest.canMakePayment(...)`

### Return object properties

- `applePay` (boolean)
  `true` if Apple Pay wallet is ready to pay.
In this case:
  - `paymentRequestButton` Element will show as a branded Apple Pay button automatically.
  - When using a custom button, you‘ll want to show a button that conforms to the Apple Pay [Human Interface Guidelines](https://developer.apple.com/apple-pay/web-human-interface-guidelines/).

- `googlePay` (boolean)
  `true` if Google Pay wallet is ready to pay.
In this case:
  - `paymentRequestButton` Element will show as a branded Google Pay button automatically.
  - When using a custom button, you'll want to show a button that conforms to the Google Pay [Brand Guidelines](https://developers.google.com/pay/api/web/guides/brand-guidelines).

- `link` (boolean)
  `true` if Link wallet is ready to pay.
In this case:
  - `paymentRequestButton` Element will show as a branded Link button automatically.
  - Link is not supported in custom button configurations.

### paymentRequest.canMakePayment

```es_next
const result = await paymentRequest.canMakePayment();
if (result) {
  // Mount paymentRequestButtonElement to the DOM
}
```

```js
paymentRequest.canMakePayment().then(result => {
  if (result) {
    // Mount paymentRequestButtonElement to the DOM
  }
});
```

## Show the payment request interface

Shows the browser’s payment interface.
When using the `paymentRequestButton` [Element](/js/element.md), this is called for you automatically.
This method must be called as the result of a user interaction (for example, in a click handler).

**Syntax:** `paymentRequest.show(...)`

### Show the payment request interface

```js
paymentRequest.show();
```

```es_next
paymentRequest.show();
```

## Update a PaymentRequest 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.
Listen to the [click](/js/element/events.md) and [cancel](/js/element/events.md) events to detect if the payment interface has been initiated.
To update the `PaymentRequest` right before the payment interface is initiated, call `paymentRequest.update` in your click event handler.

**Syntax:** `paymentRequest.update(...)`

- `options` (object) **required**
  A set of options to update this PaymentRequest instance with.

  - `currency` (string)
    Three character currency code (e.g., `usd`).

  - `total` (object)
    A [PaymentItem](#payment_item_object) object.
This `PaymentItem` is shown to the customer in the browser’s payment interface.

  - `displayItems` (array)
    An array of [PaymentItem](#payment_item_object) 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` (array)
    An array of [ShippingOption](/js/appendix/shipping_option.md) objects.
The first shipping option listed appears in the browser payment interface as the default option.

  - `applePay` (object)
    Specify Apple Pay specific options. These are passed through to the Apple Pay API.

    - `recurringPaymentRequest` (object)
      Specify a request to set up a recurring payment. See the [Apple Pay documentation](https://developer.apple.com/documentation/apple_pay_on_the_web/applepayrecurringpaymentrequest) for more details.

      - `paymentDescription` (string) **required**

      - `managementURL` (string) **required**

      - `regularBilling` (object) **required**

        - `amount` (number) **required**

        - `label` (string) **required**

        - `recurringPaymentStartDate` (Date)

        - `recurringPaymentEndDate` (Date)

        - `recurringPaymentIntervalUnit` ('year' | 'month' | 'day' | 'hour' | 'minute')

        - `recurringPaymentIntervalCount` (number)

      - `trialBilling` (object)

        - `amount` (number) **required**

        - `label` (string) **required**

        - `recurringPaymentStartDate` (Date)

        - `recurringPaymentEndDate` (Date)

        - `recurringPaymentIntervalUnit` ('year' | 'month' | 'day' | 'hour' | 'minute')

        - `recurringPaymentIntervalCount` (number)

      - `billingAgreement` (string)

    - `deferredPaymentRequest` (object)
      Specify a request to set up a deferred payment. See the [Apple Pay documentation](https://developer.apple.com/documentation/apple_pay_on_the_web/applepaydeferredpaymentrequest) for more details.

      - `paymentDescription` (string) **required**

      - `managementURL` (string) **required**

      - `deferredBilling` (object) **required**

        - `amount` (number) **required**

        - `label` (string) **required**

        - `deferredPaymentDate` (Date) **required**

      - `billingAgreement` (string)

      - `freeCancellationDate` (Date)
        If set, you must also supply a freeCancellationDateTimeZone.

      - `freeCancellationDateTimeZone` (string)
        If set, you must also supply a freeCancellationDate.

These are [tz](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) timezones such as `America/Los_Angeles`, `Europe/Dublin`, and `Asia/Singapore`.

    - `automaticReloadPaymentRequest` (object)
      Specify a request to set up an automatic reload payment. See the [Apple Pay documentation](https://developer.apple.com/documentation/apple_pay_on_the_web/applepayautomaticreloadpaymentrequest) for more details.

      - `paymentDescription` (string) **required**

      - `managementURL` (string) **required**

      - `automaticReloadBilling` (object) **required**

        - `amount` (number) **required**

        - `label` (string) **required**

        - `automaticReloadPaymentThresholdAmount` (number) **required**

      - `billingAgreement` (string)

    - `cardFunding` ('supportsDebit' | 'supportsCredit')
      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'.

### Update a PaymentRequest

```js
paymentRequest.update({
  total: {
    label: 'Demo total',
    amount: 2000,
  },
  shippingOptions: [
    {
      id: 'basic',
      label: 'Ground shipping',
      detail: 'Ground shipping via UPS or FedEx',
      amount: 995,
    },
  ],
});
```

```es_next
paymentRequest.update({
  total: {
    label: 'Demo total',
    amount: 2000,
  },
  shippingOptions: [
    {
      id: 'basic',
      label: 'Ground shipping',
      detail: 'Ground shipping via UPS or FedEx',
      amount: 995,
    },
  ],
});
```

## PaymentRequest events

`PaymentRequest` instances emit several different types of events.

## Token event

Stripe.js automatically creates a [Token](/api/tokens.md) after the customer is done interacting with the browser’s payment interface.
To access the created `Token`, listen for this event.

**Syntax:** `paymentRequest.on(...)`

- `event` (string) **required**
  The name of the event. In this case, `token`.

- `handler` (function) **required**
  A callback function that will be called with a [PaymentResponse](/js/appendix/payment_response.md) object when the event is fired.
The `PaymentResponse` object will contain a `token` field.

### Handle 'token' event

```js
paymentRequest.on('token', function(event) {
  // event.token is available
});
```

```es_next
paymentRequest.on('token', ({token}) => {
  // token is available
});
```

## PaymentMethod event

Stripe.js automatically creates a [PaymentMethod](/api/payment_methods.md) after the customer is done interacting with the browser’s payment interface.
To access the created `PaymentMethod`, listen for this event.

**Syntax:** `paymentRequest.on(...)`

- `event` (string) **required**
  The name of the event. In this case, `paymentmethod`.

- `handler` (function) **required**
  A callback function that will be called with a [PaymentResponse](/js/appendix/payment_response.md) object when the event is fired.
The `PaymentResponse` object will contain a `paymentMethod` field.

### Handle 'paymentmethod' event

```js
paymentRequest.on('paymentmethod', function(event) {
  // event.paymentMethod is available
});
```

```es_next
paymentRequest.on('paymentmethod', ({paymentMethod}) => {
  // paymentMethod is available
});
```

## Source event

Stripe.js automatically creates a [Source](/api/sources.md) after the customer is done interacting with the browser’s payment interface.
To access the created source, listen for this event.

**Syntax:** `paymentRequest.on(...)`

- `event` (string) **required**
  The name of the event. In this case, `source`.

- `handler` (function) **required**
  A callback function that will be called with a [PaymentResponse](/js/appendix/payment_response.md) object when the event is fired.
The `PaymentResponse` object will contain a `source` field.

### Handle 'source' event

```js
paymentRequest.on('source', function(event) {
  // event.source is available
});
```

```es_next
paymentRequest.on('source', ({source}) => {
  // source is available
});
```

## Cancel event

The `cancel` event is emitted from a [PaymentRequest](/js/payment_request.md) 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.

**Syntax:** `paymentRequest.on(...)`

- `event` (string) **required**
  The name of the event.
In this case, `cancel`.

- `handler` (function) **required**
  A callback function that you will provide that will be called when the event is fired.

### Handle 'cancel' event

```js
paymentRequest.on('cancel', function() {
  // handle cancel event
});
```

```es_next
paymentRequest.on('cancel', () => {
  // handle cancel event
});
```

## Shipping address change event

The `shippingaddresschange` event is emitted from a [PaymentRequest](/js/payment_request.md) whenever the customer selects a new address in the browser's payment interface.

**Syntax:** `paymentRequest.on(...)`

- `event` (string) **required**
  The name of the event. In this case, `shippingaddresschange`.

- `handler` (function) **required**
  `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` (function)
    `updateWith(updateDetails) => void` is a Stripe.js provided function that is called with an [UpdateDetails](/js/appendix/update_details.md) 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` (ShippingAddress)
    The customer's selected [ShippingAddress](/js/appendix/shipping_address.md).

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](/js/appendix/payment_response.md) object after the purchase is confirmed in the browser’s payment interface

### Handle 'shippingaddresschange' event

```js
paymentRequest.on('shippingaddresschange', function(event) {
  var updateWith = event.updateWith;
  var shippingAddress = event.shippingAddress;
  // handle shippingaddresschange event

  // call event.updateWith within 30 seconds
  updateWith(updateDetails);
});
```

```es_next
paymentRequest.on('shippingaddresschange', (event) => {
  const {updateWith, shippingAddress} = event;
  // handle shippingaddresschange event

  // call event.updateWith within 30 seconds
  updateWith(updateDetails);
});
```

## Shipping option change event

The `shippingoptionchange` event is emitted from a [PaymentRequest](/js/payment_request.md) whenever the customer selects a new shipping option in the browser's payment interface.

**Syntax:** `paymentRequest.on(...)`

- `event` (string) **required**
  The name of the event. In this case, `shippingoptionchange`.

- `handler` (function) **required**
  `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` (function)
    `updateWith(updateDetails) => void` is a Stripe.js provided function that is called with an [UpdateDetails](/js/appendix/update_details.md) 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` (ShippingOption)
    The customer's selected [ShippingOption](/js/appendix/shipping_option.md).

### Handle 'shippingoptionchange' event

```js
paymentRequest.on('shippingoptionchange', function(event) {
  var updateWith = event.updateWith;
  var shippingOption = event.shippingOption;
  // handle shippingoptionchange event

  // call event.updateWith within 30 seconds
  updateWith(updateDetails);
});
```

```es_next
paymentRequest.on('shippingoptionchange', (event) => {
  const {updateWith, shippingOption} = event;
  // handle shippingoptionschange event

  // call event.updateWith within 30 seconds
  updateWith(updateDetails);
});
```