<!--
{
  "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

[`required ApplePayLineItem total;`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/total)

A line item that represents the total for the payment.

[`sequence <ApplePayLineItem> lineItems;`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/lineItems)

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

[`dictionary ApplePayLineItem {
	ApplePayLineItemType type;
	DOMString label;
	DOMString amount;
	ApplePayPaymentTiming paymentTiming;
	Date recurringPaymentStartDate;
	ApplePayRecurringPaymentDateUnit recurringPaymentIntervalUnit;
	long recurringPaymentIntervalCount;
	Date recurringPaymentEndDate;
	Date deferredPaymentDate;
	DOMString automaticReloadPaymentThresholdAmount;
};`](/documentation/ApplePayontheWeb/ApplePayLineItem)

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

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

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

### Requesting recurring payments

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

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

[`dictionary ApplePayRecurringPaymentRequest {
	required DOMString paymentDescription;
	required ApplePayLineItem regularBilling;
	ApplePayLineItem trialBilling;
	DOMString billingAgreement;
	required DOMString managementURL;
	DOMString tokenNotificationURL;
};`](/documentation/ApplePayontheWeb/ApplePayRecurringPaymentRequest)

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

### Requesting automatic reload payments

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

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

[`dictionary ApplePayAutomaticReloadPaymentRequest {
	required DOMString paymentDescription;
	required ApplePayLineItem automaticReloadBilling;
	DOMString billingAgreement;
	required DOMString managementURL;
	DOMString tokenNotificationURL;
};`](/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

[`ApplePayDeferredPaymentRequest 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

[`sequence <ApplePayPaymentTokenContext> multiTokenContexts;`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/multiTokenContexts)

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

[`dictionary ApplePayPaymentTokenContext {
	required DOMString merchantIdentifier;
	required DOMString externalIdentifier;
	required DOMString merchantName;
	DOMString merchantDomain;
	required DOMString amount;
};`](/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

[`required DOMString countryCode;`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/countryCode)

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

[`required DOMString currencyCode;`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/currencyCode)

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

[`required sequence <ApplePayMerchantCapability> merchantCapabilities;`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/merchantCapabilities)

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

[`sequence <ApplePayShippingMethod> shippingMethods;`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/shippingMethods)

The list of shipping methods available for a payment request.

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

An optional value that indicates how to ship purchased items.

[`sequence <DOMString> supportedCountries;`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/supportedCountries)

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

[`required sequence <DOMString> supportedNetworks;`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/supportedNetworks)

The payment networks the merchant supports.

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

The payment capabilities the merchant supports.

[`dictionary ApplePayShippingMethod {
	required DOMString label;
	required DOMString detail;
	required DOMString amount;
	required DOMString identifier;
	ApplePayDateComponentsRange dateComponentsRange;
};`](/documentation/ApplePayontheWeb/ApplePayShippingMethod)

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

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

A type that indicates how to ship purchased items.

### Requesting billing and shipping contact information

[`sequence <ApplePayContactField> requiredBillingContactFields;`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/requiredBillingContactFields)

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

[`sequence <ApplePayContactField> requiredShippingContactFields;`](/documentation/ApplePayontheWeb/ApplePayPaymentRequest/requiredShippingContactFields)

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

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

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

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

Field names for requesting contact information in a payment request.

[`enum 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

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

Billing contact information for the user.

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

Shipping contact information for the user.

[`dictionary ApplePayPaymentContact {
	DOMString phoneNumber;
	DOMString emailAddress;
	DOMString givenName;
	DOMString familyName;
	DOMString phoneticGivenName;
	DOMString phoneticFamilyName;
	sequence <DOMString> addressLines;
	DOMString subLocality;
	DOMString locality;
	DOMString postalCode;
	DOMString subAdministrativeArea;
	DOMString administrativeArea;
	DOMString country;
	DOMString countryCode;
};`](/documentation/ApplePayontheWeb/ApplePayPaymentContact)

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

### Working with coupon codes

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

The initial coupon code for the payment request.

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

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

### Adding custom data

[`DOMString 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)