Apple Pay Recurring Transactions
Apple Pay merchant tokens (MPANs) are secure, non–device-specific digital tokens that link a consumer’s card, a merchant, and the Apple Pay system. They enable reliable, long‑term recurring and subscription payments, ensuring payment continuity even if a consumer changes devices or their physical card expires.
Apple Pay merchant tokens create a persistent link between a business and a consumer, allowing uninterrupted rebilling even if the consumer’s device changes.
Additionally, saved Apple Pay merchant tokens receive updates if the card’s metadata changes — for example, if the card is reissued with a new PAN.
Merchant tokens are recommended for subsequent transactions because:
- They maintain continuity of the rebilling cycle regardless of changes to the consumer’s device or if it has been lost or stolen.
- Merchant token details persist across multiple devices.
- Physical card metadata remains up to date.
Supported Apple Pay Request Types
To receive an Apple Pay merchant token, use one of the two PK request types listed below.
Each request type represents a different kind of rebilling transaction and determines how the Apple Pay payment sheet is presented to the consumer.
| Request Type | Type of Transaction | Availability |
|---|---|---|
| PKRecurringPaymentRequest | Used for RECURRING transactions — scheduled, merchant‑initiated recurring requests. | Apple Pay on the Web iOS > v16.0 |
| PKAutomaticReloadPaymentRequest | Used for TOPUP transactions — unscheduled merchant‑initiated requests when a consumer’s balance falls below a defined threshold. | Apple Pay on the Web iOS > v16.0 |
Important: You must include Paysafe’s URL ending with your Apple Pay merchantId as the value of the tokenNotificationURL property in the payment details. This allows Apple Pay to notify Paysafe of FPAN changes, enabling Paysafe to update your merchant tokens accordingly.
For example:
"tokenNotificationURL": "https://applepay-notifications.paysafe.com/v1/applepay/merchanttokens/merchant.mycompany.prod"
where merchant.mycompany.prod is the merchantId registered with Apple.
Consumer Experience
Below are examples of the consumer experience for both RecurringPaymentRequest and AutomaticReloadPaymentRequest.
RecurringPaymentRequest payment sheet
AutomaticReloadPaymentRequest payment sheet
Apple Pay Merchant Token Updates
We receive two types of update event for Apple Pay merchant tokens. Paysafe handles these updates on your behalf.
- Card metadata update
We receive this event when the physical card’s metadata changes — for example, the card’s last four digits, expiry date, issuing country, or its short and long descriptions. - Unlink
Apple Pay sends this event when the card has been terminated or when the consumer or card issuer decides to end their relationship with the website or app. This event indicates that the MPAN is no longer active, and any recurring cycles associated with that MPAN should no longer proceed for the given merchant. We deactivate the MPAN in our system.
Processing with Apple Pay Merchant Tokens
Apple Pay merchant tokens are designed to support rebilling cycles, which come with certain limitations.
-
When processing RECURRING and TOPUP transactions with Apple Pay merchant tokens, you must follow our guidelines for credentials-on-file transactions.
-
Customer-initiated transactions (CITs) using a saved Apple Pay merchant token as card‑on‑file are not allowed; for example, when a consumer attempts a transaction using a saved card.
-
Payouts using an Apple Pay merchant token are not supported.
Important: If a consumer starts a new recurring cycle with the same debit or credit card within the same website or mobile application, Apple Pay will return the same merchant token.
Example flow
1. Create a single‑use payment handle
Use the encrypted or decrypted Apple Pay payload to generate a single‑use payment handle.
See Create a Payment Handle in the API Reference.
{
"merchantRefNum": "06bb27c9-1149-4380-8a1d-f4ce6d5563de",
"transactionType": "PAYMENT",
"paymentType": "CARD",
"currencyCode": "USD",
"accountId": "1000000000",
"amount": 1499,
"applePay": {
"applePayPaymentToken": {
"billingContact": {
"addressLines": [
"string"
],
"administrativeArea": "string",
"country": "United States",
"countryCode": "US",
"givenName": "John",
"familyName": "doeh",
"locality": "Jacksonvielle",
"phoneticGivenName": "string",
"phoneticFamilyName": "string",
"postalCode": "string",
"subAdministrativeArea": "string",
"subLocality": "string"
},
"token": {
"paymentData": {
"data": "crc1wsC.....0ieF",
"signature": "MIAGC......AAAAAAAA=",
"header": {
"publicKeyHash": "jaI8zb3+bTPrkEHLe/edIBuRjWbkRm1YKtUXX/FuIRw=",
"ephemeralPublicKey": "MFkwEw....CQ==",
"transactionId": "c85....31"
},
"version": "EC_v1"
},
"transactionIdentifier": "string",
"paymentMethod": {
"displayName": "MasterCard Debit 0224",
"network": "MasterCard",
"type": "Debit"
}
}
}
},
"returnLinks": [
{
"rel": "on_completed",
"href": "https://www.paysafe.com/en/",
"method": "GET"
},
{
"rel": "on_failed",
"href": "https://developer.paysafe.com/en",
"method": "GET"
},
{
"rel": "default",
"href": "https://www.google.com",
"method": "GET"
}
]
}
{
"merchantRefNum": "{{$guid}}",
"transactionType": "PAYMENT",
"paymentType": "CARD",
"currencyCode": "USD",
"accountId": "1000000000",
"amount": 1499,
"applePay": {
"applePayPaymentToken": {
"billingContact": {
"addressLines": [
"string"
],
"administrativeArea": "string",
"country": "United States",
"countryCode": "US",
"givenName": "John",
"familyName": "doeh",
"locality": "Jacksonvielle",
"phoneticGivenName": "string",
"phoneticFamilyName": "string",
"postalCode": "string",
"subAdministrativeArea": "string",
"subLocality": "string"
},
"token": {
"paymentData": {
"decryptedData": {
"version": "EC_v1",
"applicationPrimaryAccountNumber": "5076020000000006",
"applicationExpirationDate": "281111",
"currencyCode": "840",
"transactionAmount": "1499",
"cardholderName": "John Smith",
"deviceManufacturerIdentifier": "OPAY",
"paymentDataType": "3DSecure",
"merchantTokenIdentifier": "MAPLAB001M342",
"merchantTokenMetadata": {
"cardArt": [
{
"name": "cardBackgroundCombined@2x.....",
"type": "image/png",
"url": "https://pr-pod4-smp-device-...."
}
],
"cardMetadata": {
"longDescription": "Platinum Cashback",
"shortDescription": "Platinum Cashback",
"cardCountry": "GB",
"fpanSuffix": "0224"
}
},
"paymentData": {
"onlinePaymentCryptogram": "MFNyroCRmAPANZWxrEK4TgACVUA",
"eciIndicator": "2"
}
}
},
"transactionIdentifier": "string",
"paymentMethod": {
"displayName": "MasterCard Debit 0224",
"network": "MasterCard",
"type": "Debit"
}
}
}
},
"returnLinks": [
{
"rel": "on_completed",
"href": "https://www.paysafe.com/en/",
"method": "GET"
},
{
"rel": "on_failed",
"href": "https://developer.paysafe.com/en",
"method": "GET"
},
{
"rel": "default",
"href": "https://www.google.com",
"method": "GET"
}
]
}
{
"id": "06bb27c9-1149-4380-8a1d-f4ce6d5563de",
"accountId": "1000000000",
"paymentType": "CARD",
"paymentHandleToken": "APdVZYS3XKM6YzU",
"merchantRefNum": "bead4089-ef39-4775-8b13-c165010b16f3",
"currencyCode": "USD",
"txnTime": "2026-01-06T09:13:31Z",
"customerIp": "192.168.0.1",
"status": "PAYABLE",
"amount": 1499,
"action": "NONE",
"usage": "SINGLE_USE",
"timeToLiveSeconds": 899,
"transactionType": "PAYMENT",
"executionMode": "SYNCHRONOUS",
"card": {
"holderName": "John doeh",
"status": "ACTIVE",
"lastDigits": "0224",
"cardCategory": "DEBIT",
"tokenType": "APPLE_PAY",
"applePay": {
"lastDigits": "0006",
"expiry": {
"month": "11",
"year": "2028"
},
"subtype": "MERCHANT"
}
},
"applePay": {
"applePayPaymentToken": {
"token": {
"paymentData": {
"version": null,
"data": null,
"signature": null,
"header": null,
"decryptedData": {
"version": "EC_v1",
"applicationPrimaryAccountNumber": "5076020000000006",
"applicationExpirationDate": "281111",
"currencyCode": "840",
"transactionAmount": "1499",
"cardholderName": "John doeh",
"deviceManufacturerIdentifier": "OPAY",
"paymentDataType": "3DSecure",
"merchantTokenIdentifier": "MAPLAB001M342",
"merchantTokenMetadata": {
"cardArt": [
{
"name": "cardBackgroundCombined@2x.....",
"type": "image/png",
"url": "https://pr-pod4-smp-device-...."
}
],
"cardMetadata": {
"longDescription": "Platinum Cashback",
"shortDescription": "Platinum Cashback",
"cardCountry": "GB",
"fpanSuffix": "0224"
}
},
"paymentData": {
"onlinePaymentCryptogram": "MFNyroCRmAPANZWxrEK4TgACVUA",
"eciIndicator": "2"
}
}
},
"paymentMethod": {
"displayName": "MasterCard Debit 0224",
"network": "MasterCard",
"type": "Debit"
},
"transactionIdentifier": "string"
},
"billingContact": {
"addressLines": [
"string"
],
"administrativeArea": "string",
"country": "United States",
"countryCode": "US",
"familyName": "doeh",
"givenName": "John",
"locality": "Jacksonville",
"phoneticFamilyName": "string",
"phoneticGivenName": "string",
"postalCode": "string",
"subAdministrativeArea": "string",
"subLocality": "string"
}
}
},
"returnLinks": [
{
"rel": "on_completed",
"href": "https://www.paysafe.com/en/",
"method": "GET"
},
{
"rel": "on_failed",
"href": "https://developer.paysafe.com/en",
"method": "GET"
},
{
"rel": "default",
"href": "https://www.google.com",
"method": "GET"
}
],
"skip3ds": false
}
2. Process a customer‑initiated transaction
Use the single‑use payment handle to process a customer‑initiated transaction.
See Process Payment in the API Reference.
{ "accountId":"1000000000",
"merchantRefNum": "f5d52342-1c0e-4eb8-a672-8380da73eb67",
"amount": 1499,
"currencyCode": "USD",
"dupCheck": true,
"settleWithAuth": true,
"paymentHandleToken": "APdVZYS3XKM6YzU",
"description": "Netflix GBR",
"storedCredential": {
"type": "RECURRING",
"occurrence": "INITIAL"
}
}
{
"id": "f5d52342-1c0e-4eb8-a672-8380da73eb67",
"accountId": "1000000000",
"paymentType": "CARD",
"paymentHandleToken": "APdVZYS3XKM6YzU",
"merchantRefNum": "beb1ec4a-2de6-44df-b0c0-532343fd3278",
"currencyCode": "USD",
"settleWithAuth": true,
"txnTime": "2026-01-06T14:15:46Z",
"billingDetails": {
"street": "string",
"city": "Jacksonville",
"zip": "string",
"country": "US"
},
"customerIp": "192.168.0.1",
"status": "COMPLETED",
"amount": 1499,
"preAuth": false,
"description": "Netflix GBR",
"availableToSettle": 0,
"gatewayResponse": {
"code": "NAG",
"responseCode": "00",
"responseCodeDescription": "Approved",
"avsCode": "M",
"mid": "00464800",
"authCode": "121831",
"avsResponse": "MATCH",
"cvvVerification": "MATCH",
"serializable": true
},
"merchantDescriptor": {
"dynamicDescriptor": "Paysafe Test"
},
"settlements": [
{
"merchantRefNum": "beb1ec4a-2de6-44df-b0c0-532343fd3278",
"amount": 1499,
"id": "f5d52342-1c0e-4eb8-a672-8380da73eb67",
"availableToRefund": 1499,
"txnTime": 1767708946000,
"status": "PENDING",
"gatewayReconciliationId": "4488131110"
}
],
"authentication": {
"eci": "2"
},
"card": {
"cardExpiry": {
"month": "11",
"year": "2028"
},
"holderName": "John Doe",
"status": "ACTIVE",
"cardType": "MC",
"lastDigits": "0224",
"cardCategory": "DEBIT",
"tokenType": "APPLE_PAY",
"applePay": {
"lastDigits": "0006",
"expiry": {
"month": "11",
"year": "2028"
},
"subtype": "MERCHANT"
}
},
"cardSchemeTransactionId": "AGZZ4488131110",
"storedCredential": {
"type": "RECURRING",
"occurrence": "INITIAL",
"initialTransactionId": null,
"externalInitialTransactionId": null
}
}
3. Create a customer profile and a multi‑use payment handle
Use the single‑use payment handle to create a customer profile and a multi‑use payment handle. See Create a Customer in the API Reference.
If the consumer already has a profile, simply add the card to their existing profile. See Create a Payment Handle For a Customer in the API Reference.
{
"merchantCustomerId": "12d92411-e0ee-445a-8550-4db808b0f30b",
"locale": "en_US",
"paymentHandleTokenFrom": "APdVZYS3XKM6YzU",
"accountId": "1000000000",
"email": "john.doe@paysafe.com",
"firstName": "John",
"lastName": "doeh",
"cellPhone": "777-444-8888"
}
{
"id": "12d92411-e0ee-445a-8550-4db808b0f30b",
"status": "ACTIVE",
"merchantCustomerId": "0d68e67a-0386-4f45-888c-d672754f9544",
"locale": "en_US",
"firstName": "John",
"lastName": "Doeh",
"email": "john.doe@paysafe.com",
"cellPhone": "777-444-8888",
"paymentToken": "P27t8zZ7FvXLxvp",
"addresses": [
{
"id": "5b944470-08f9-4b73-9554-75368b45be9c",
"city": "Jacksonville",
"state": "FL",
"country": "US",
"zip": "32256",
"status": "ACTIVE",
"street": "5335 Gate Pkwy"
}
],
"paymentHandleTokenFrom": "APdVZYS3XKM6YzU",
"paymentHandles": [
{
"id": "ccb0c692-2f2c-4c2e-b5ab-8a0916a50190",
"merchantRefNum": "bead4089-ef39-4775-8b13-c165010b16f3",
"status": "PAYABLE",
"usage": "MULTI_USE",
"paymentType": "CARD",
"executionMode": "SYNCHRONOUS",
"paymentHandleToken": "CwucLVMB64wYR3I",
"card": {
"id": "bd17fb2a-a6bd-4178-859d-155c77e5135e",
"lastDigits": "0224",
"cardExpiry": {
"month": "11",
"year": "2028"
},
"cardBin": "507602",
"cardType": "MC",
"holderName": "John Doe",
"status": "ACTIVE",
"cardCategory": "DEBIT",
"applePay": {
"lastDigits": "0006",
"expiry": {
"month": "11",
"year": "2028"
},
"subtype": "MERCHANT"
},
"tokenType": "APPLE_PAY",
"issuingCountry": "CA"
},
"billingDetailsId": "a40d33c6-c30f-4c03-aad6-38e2ed0abfc1"
}
]
}
4. Process subsequent transactions in the recurring cycle
Use the multi‑use payment handle for all following transactions in the recurring cycle.
{
"accountId":"1000000000",
"merchantRefNum": "54fb5aac-2239-4eb3-91dd-e5d28420e9bd",
"amount": 1499,
"currencyCode": "USD",
"dupCheck": true,
"settleWithAuth": true,
"paymentHandleToken": "CwucLVMB64wYR3I",
"customerIp": "192.168.0.1",
"description": "Netflix GBR",
"storedCredential": {
"initialTransactionId":"f5d52342-1c0e-4eb8-a672-8380da73eb67",
"type": "RECURRING",
"occurrence": "SUBSEQUENT"
}
}
{
"id": "54fb5aac-2239-4eb3-91dd-e5d28420e9bd",
"accountId": "1000000000",
"paymentType": "CARD",
"paymentHandleToken": "CwucLVMB64wYR3I",
"merchantRefNum": "5d877505-62cf-4097-8231-275c18511554",
"currencyCode": "USD",
"settleWithAuth": true,
"txnTime": "2026-01-06T14:27:57Z",
"billingDetails": {
"street": "string",
"city": "Jacksonville",
"zip": "string",
"state": "string",
"country": "US"
},
"customerIp": "192.168.0.1",
"status": "COMPLETED",
"amount": 1499,
"preAuth": false,
"description": "Netflix GBR",
"availableToSettle": 0,
"gatewayResponse": {
"code": "NAG",
"responseCode": "00",
"responseCodeDescription": "Approved",
"avsCode": "M",
"mid": "00464800",
"authCode": "141171",
"avsResponse": "MATCH",
"cvvVerification": "MATCH",
"serializable": true
},
"merchantDescriptor": {
"dynamicDescriptor": "Paysafe Test"
},
"settlements": [
{
"merchantRefNum": "5d877505-62cf-4097-8231-275c18511554",
"amount": 1499,
"id": "54fb5aac-2239-4eb3-91dd-e5d28420e9bd",
"availableToRefund": 1499,
"txnTime": 1767709677000,
"status": "PENDING",
"gatewayReconciliationId": "4488131130"
}
],
"card": {
"cardExpiry": {
"month": "11",
"year": "2028"
},
"holderName": "John Doe",
"cardType": "MC",
"cardBin": "507602",
"lastDigits": "0224",
"cardCategory": "DEBIT",
"tokenType": "APPLE_PAY"
},
"cardSchemeTransactionId": "AGZZ4488131110 ",
"storedCredential": {
"type": "RECURRING",
"occurrence": "SUBSEQUENT",
"initialTransactionId": "f5d52342-1c0e-4eb8-a672-8380da73eb67",
"externalInitialTransactionId": null
}
}
Configure Webhooks
To learn how to set up your webhooks, see Configure Webhooks.
Further Testing
To simulate negative processing scenarios, use one of the predefined amounts from our fixed-amount simulator.
For more information, see Simulating Card Payments.