<!--
{
  "availability" : [

  ],
  "documentType" : "symbol",
  "framework" : "ApplePayontheWeb",
  "identifier" : "/documentation/ApplePayontheWeb/ApplePayPaymentRequest",
  "metadataVersion" : "0.1.0",
  "role" : "Structure",
  "symbol" : {
    "kind" : "Structure",
    "modules" : [
      "Apple Pay on the Web"
    ],
    "preciseIdentifier" : "struct/ApplePayPaymentRequest"
  },
  "title" : "ApplePayPaymentRequest"
}
-->

# ApplePayPaymentRequest

A request for payment, which includes information about payment-processing capabilities, the payment amount, and shipping information.

```
dictionary ApplePayPaymentRequest {
	required sequence <ApplePayMerchantCapability> merchantCapabilities;
	required sequence <DOMString> supportedNetworks;
	required DOMString countryCode;
	sequence <ApplePayContactField> requiredBillingContactFields;
	ApplePayPaymentContact billingContact;
	sequence <ApplePayContactField> requiredShippingContactFields;
	ApplePayPaymentContact shippingContact;
	DOMString applicationData;
	sequence <DOMString> supportedCountries;
	boolean supportsCouponCode;
	DOMString couponCode;
	ApplePayShippingContactEditingMode shippingContactEditingMode;
	required ApplePayLineItem total;
	sequence <ApplePayLineItem> lineItems;
	required DOMString currencyCode;
	ApplePayShippingType shippingType;
	sequence <ApplePayShippingMethod> shippingMethods;
	sequence <ApplePayPaymentTokenContext> multiTokenContexts;
	ApplePayAutomaticReloadPaymentRequest automaticReloadPaymentRequest;
	ApplePayRecurringPaymentRequest recurringPaymentRequest;
	ApplePayDeferredPaymentRequest deferredPaymentRequest;
};
```

## Overview

Use an [`ApplePayPaymentRequest`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest) dictionary to represent a merchant request for payment for goods or services. Your website creates a payment request as soon as the user taps the Apple Pay button to make a purchase.

A payment request contains information that describes the purchase, such as the merchant information, supported payment networks, and the line items, including the total, the currency code, the billing and shipping contact, and more.

A typical payment request is for a one-time payment. To support different types of payment requests, provide one of the following options in the payment request:

- A [`recurringPaymentRequest`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/recurringPaymentRequest) object to request a recurring payment. Recurring payments, such as subscriptions, can feature different payment intervals (for example, annually or monthly), and either regular or trial billing cycles.
- An [`automaticReloadPaymentRequest`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/automaticReloadPaymentRequest) object to set up automatic reload payments. Automatic reload payments, such as store card top-ups, feature a balance threshold and a reload amount. The card automatically reloads with the reload amount when the account drops below the balance threshold.
- Use the [`deferredPaymentRequest`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/deferredPaymentRequest) property to set up a deferred payment request using the [`ApplePayDeferredPaymentRequest`](/documentation/ApplePayontheWeb/ApplePayDeferredPaymentRequest) class. Deferred payments include purchases, such as hotel bookings or pre-orders, where the card renders payment at a later date upon the receipt of goods or delivery of services.
- Use the [`applePayLaterAvailability`](/documentation/ApplePayontheWeb/ApplePayRequestBase/applePayLaterAvailability) property to indicate whether this payment request is eligible for Apple Pay Later. You can indicate that Apple Pay Later is unavailable for certain kinds of transactions, including subscriptions, items that require recurring payments or prohibited items, such as gift cards.
- A [`multiTokenContexts`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/multiTokenContexts) sequence to request multiple payment tokens to support multimerchant payments. Set up multitoken transactions to process and display payment requests with multiple merchants on one payment sheet, for example, a booking site where a user pays for a hotel, flight, and car rental from different merchants.

> Note:
> You can set only one of these optional payment request type properties on a payment request object.

For recurring payments and automatic reload payments, you can optionally set up merchant token life-cycle notifications for the request. For more information, see <doc://com.apple.documentation/documentation/MerchantTokenNotificationServices>.

## Topics

### Setting the total and summary line items

[`total`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/total)

A line item that represents the total for the payment.

[`lineItems`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/lineItems)

A set of line items that explain recurring payments and additional charges and discounts.

[`ApplePayLineItem`](/documentation/ApplePayontheWeb/ApplePayLineItem)

A line item in a payment request—for example, total, tax, discount, or grand total.

[`ApplePayLineItemType`](/documentation/ApplePayontheWeb/ApplePayLineItemType)

A type that indicates whether a line item is final or pending.

### Requesting recurring payments

[`recurringPaymentRequest`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/recurringPaymentRequest)

A property that requests a recurring payment, typically a subscription.

[`ApplePayRecurringPaymentRequest`](/documentation/ApplePayontheWeb/ApplePayRecurringPaymentRequest)

A dictionary that represents a request to set up a recurring payment, typically a subscription.

### Requesting automatic reload payments

[`automaticReloadPaymentRequest`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/automaticReloadPaymentRequest)

A property that requests an automatic reload payment, such as a store card top-up.

[`ApplePayAutomaticReloadPaymentRequest`](/documentation/ApplePayontheWeb/ApplePayAutomaticReloadPaymentRequest)

A dictionary that represents a request to set up an automatic reload payment, such as a store card top-up or a prepaid account.

### Requesting deferred payments

[`deferredPaymentRequest`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/deferredPaymentRequest)

A property that requests a deferred payment, such as a hotel booking or a pre-order.

### Requesting multitoken or multimerchant payments

[`multiTokenContexts`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/multiTokenContexts)

An array of payment token contexts that requests multiple payment tokens to support a multimerchant payment.

[`ApplePayPaymentTokenContext`](/documentation/ApplePayontheWeb/ApplePayPaymentTokenContext)

A dictionary that defines the context for a single payment token in a payment request for multimerchant payments.

### Working with transaction information

[`countryCode`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/countryCode)

The merchant’s two-letter ISO 3166 country code.

[`currencyCode`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/currencyCode)

The three-letter ISO 4217 currency code for the payment.

[`merchantCapabilities`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/merchantCapabilities)

An array of the payment capabilities that the merchant supports, such as credit or debit.

[`shippingMethods`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/shippingMethods)

The list of shipping methods available for a payment request.

[`shippingType`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/shippingType)

An optional value that indicates how to ship purchased items.

[`supportedCountries`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/supportedCountries)

A list of two-letter country codes for limiting payment to cards from specific countries or regions.

[`supportedNetworks`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/supportedNetworks)

The payment networks the merchant supports.

[`ApplePayMerchantCapability`](/documentation/ApplePayontheWeb/ApplePayMerchantCapability)

The payment capabilities the merchant supports.

[`ApplePayShippingMethod`](/documentation/ApplePayontheWeb/ApplePayShippingMethod)

A dictionary that describes the shipping method for delivering physical goods.

[`ApplePayShippingType`](/documentation/ApplePayontheWeb/ApplePayShippingType)

A type that indicates how to ship purchased items.

### Requesting billing and shipping contact information

[`requiredBillingContactFields`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/requiredBillingContactFields)

The fields of billing information the user must provide to process the transaction.

[`requiredShippingContactFields`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/requiredShippingContactFields)

The fields of shipping information the user must provide to fulfill the order.

[`shippingContactEditingMode`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/shippingContactEditingMode)

A value that indicates whether the shipping mode prevents the user from editing the shipping address.

[`ApplePayContactField`](/documentation/ApplePayontheWeb/ApplePayContactField)

Field names for requesting contact information in a payment request.

[`ApplePayShippingContactEditingMode`](/documentation/ApplePayontheWeb/ApplePayShippingContactEditingMode)

Values that indicate whether the shipping mode prevents the user from editing fields of the shipping address.

### Providing known contact information

[`billingContact`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/billingContact)

Billing contact information for the user.

[`shippingContact`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/shippingContact)

Shipping contact information for the user.

[`ApplePayPaymentContact`](/documentation/ApplePayontheWeb/ApplePayPaymentContact)

Contact information fields to use for billing and shipping contact information.

### Working with coupon codes

[`couponCode`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/couponCode)

The initial coupon code for the payment request.

[`supportsCouponCode`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/supportsCouponCode)

A Boolean value that determines whether the payment sheet displays the coupon code field.

### Adding custom data

[`applicationData`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/applicationData)

A Base64-encoded string for application-specific data.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)