Recurring Payments
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 token
Use the encrypted or decrypted Apple Pay payload to create a single‑use payment token.
See Create an Apple Pay Single-Use Token in the Customer Vault API Reference.
{
"applePayPaymentToken": {
"billingContact": {
"addressLines": [
"New York City, 123 Str"
],
"administrativeArea": "MC",
"country": "USA",
"countryCode": "US",
"givenName": "John",
"familyName": "Doe",
"locality": "Mad",
"phoneticGivenName": "string",
"phoneticFamilyName": "string",
"postalCode": "MC-23",
"subAdministrativeArea": "string",
"subLocality": "string"
},
"token": {
"paymentData": {
"version": "EC_v1",
"data": "<passkit_encrypted_payment_data>",
"signature": "<signature_for_payment_and_header_data>",
"header": {
"transactionId": "b53e22ef6669ce7f50951cfd6821908f4e679f050f5a551a1b5f6202253136ae",
"ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEB39YqvWZG0NOYjbkL5D61Mxip6uw23Q7m8gWgxL41k4fs0BgJ+MFcIGYOH86kAGL/wjiftDahRkUnzOGls2hzw==",
"publicKeyHash": "O5gJ/P5sQ7ufMZQXA7ccLoOkJ13VNknbu+4K0TaCQXE="
}
},
"transactionIdentifier": "string",
"paymentMethod": {
"displayName": "Visa Debit 0224",
"network": "visa",
"type": "debit"
}
}
}
}
{
"id": "a02e52c7-c991-4418-966a-b62989cb0eae",
"paymentToken": "ABC4AFQQBC5UR5H",
"timeToLiveSeconds": 899,
"transaction": {
"amount": "1000",
"currencyCode": "USD"
},
"applePayPaymentToken": {
"billingContact": {
"addressLines": [
"string"
],
"administrativeArea": "string",
"country": "USA",
"countryCode": "US",
"givenName": "John",
"familyName": "Doe",
"locality": "Mad",
"phoneticGivenName": "string",
"phoneticFamilyName": "string",
"postalCode": "string",
"subAdministrativeArea": "string",
"subLocality": "string"
},
"token": {
"paymentData": {
"version": "EC_v1",
"signature": "<signature_for_payment_and_header_data>",
"header": {
"transactionId": "b53e22ef6669ce7f50951cfd6821908f4e679f050f5a551a1b5f6202253136ae",
"publicKeyHash": "O5gJ/P5sQ7ufMZQXA7ccLoOkJ13VNknbu+4K0TaCQXE="
}
},
"paymentMethod": {
"displayName": "Visa Debit 0224",
"network": "visa",
"type": "debit"
}
}
},
"card": {
"status": "ACTIVE",
"cardBin": "462294",
"lastDigits": "0224",
"holderName": "John Doe",
"cardType": "VI",
"cardCategory": "DEBIT",
"issuingCountry": "US",
"tokenType": "APPLE_PAY",
"applePay": {
"bin": "462294",
"lastDigits": "9319",
"expiry": {
"year": 2027,
"month": 11
},
"status": "ACTIVE",
"subtype": "MERCHANT"
}
},
"authentication": {
"eci": "5"
}
}
2. Process a customer‑initiated transaction
Use the single‑use payment token to process a customer‑initiated transaction.
See Authorization in the Card Payments API Reference.
{
"merchantRefNum": "{{$guid}}",
"amount": 123,
"settleWithAuth": false,
"card": {
"paymentToken": "A9kZkIybP0BugZT"
},
"merchantDescriptor": {
"dynamicDescriptor": "Reccuring Test"
},
"description": "Reccuring Test",
"profile": {
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@somedomain.com"
},
"storedCredential": {
"type": "RECURRING ",
"occurrence": "INITIAL"
}
}
{
"id": "aef6618d-0bf1-42b4-a129-9fe20018f093",
"merchantRefNum": "fcdd2eff-5638-4960-9ec9-b7274ff4709c",
"txnTime": "2026-03-13T09:28:54Z",
"status": "COMPLETED",
"acquirerResponse": {
"code": "NAG",
"responseCode": "00",
"responseCodeDescription": "Approved",
"avsCode": "Z",
"mid": "00404940"
},
"cardSchemeTransactionId": "AGZZ3016201800",
"amount": 123,
"settleWithAuth": false,
"preAuth": false,
"availableToSettle": 123,
"card": {
"tokenType": "APPLE_PAY",
"applePay": {
"expiry": {
"month": 11,
"year": 2027
},
"lastDigits": "9319",
"subtype": "MERCHANT"
},
"type": "VI",
"lastDigits": "0224",
"cardExpiry": {
"month": 11,
"year": 2027
},
"issuingCountry": "US",
"cardBin": "462294"
},
"authentication": {
"eci": 5
},
"authCode": "463236",
"profile": {
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@somedomain.com"
},
"billingDetails": {
"street": "New York City, 123 Str",
"city": "Mad",
"country": "US",
"zip": "MC23"
},
"merchantDescriptor": {
"dynamicDescriptor": "Yordan Test"
},
"visaAdditionalAuthData": {},
"description": "Reccuring Test",
"currencyCode": "CAD",
"avsResponse": "MATCH_ZIP_ONLY",
"cvvVerification": "MATCH",
"links": [
{
"rel": "self",
"href": "https://api.test.paysafe.com/cardpayments/v1/accounts/1002788600/auths/aef6618d-0bf1-42b4-a129-9fe20018f093"
}
],
"storedCredential": {
"type": "RECURRING",
"occurrence": "INITIAL"
}
}
3. Create a customer profile and a multi‑use payment token
Use the single‑use payment token to create a customer profile and a multi‑use payment token. See Create a Profile in the Customer Vault API Reference.
If the consumer already has a profile, simply add the card to their existing profile. See Create a Card in the Customer Vault API Reference.
{
"merchantCustomerId": "{{$guid}}",
"dupCheck": false,
"locale": "en_GB",
"firstName": "John",
"lastName": "Doe",
"dateOfBirth": {
"year": 1986,
"month": 10,
"day": 24
},
"email": "john.doe@paysafe.com",
"phone": "777-444-8888",
"ip": "192.168.0.1",
"gender": "M",
"status": "ACTIVE",
"nationality": "United States",
"cellPhone": "123456789",
"card": {
"singleUseToken": "A9kZkIybP0BugZT"
}
}
{
"id": "a29abd61-29d6-425a-a388-7055214641b7",
"status": "ACTIVE",
"merchantCustomerId": "0c1277c6-6d56-4d37-bd24-1c8e57760395",
"locale": "en_GB",
"firstName": "John",
"lastName": "Doe",
"dateOfBirth": {
"year": 1986,
"month": 10,
"day": 24
},
"ip": "192.168.0.1",
"gender": "M",
"nationality": "United States",
"paymentToken": "Pm2LADBU3QIJN1p",
"phone": "777-444-8888",
"cellPhone": "123456789",
"email": "john.doe@paysafe.com",
"creationTime": "2026-03-13T09:31:16Z",
"addresses": [
{
"id": "ad007806-2586-4e5b-8853-508b28d1bb37",
"street": "New York City, 123 Str",
"city": "Mad",
"country": "US",
"zip": "MC-23",
"defaultShippingAddressIndicator": false,
"status": "ACTIVE"
}
],
"cards": [
{
"status": "ACTIVE",
"id": "48959df7-0825-463e-be01-05a33d8c5cab",
"cardBin": "462294",
"lastDigits": "0224",
"cardExpiry": {
"year": 2027,
"month": 11
},
"holderName": "John Doe",
"billingAddressId": "ad007806-2586-4e5b-8853-508b28d1bb37",
"cardType": "VI",
"cardCategory": "DEBIT",
"paymentToken": "CrSpVqeLvBkJ8qz",
"defaultCardIndicator": true,
"issuingCountry": "US",
"tokenType": "APPLE_PAY",
"applePay": {
"bin": "462294",
"lastDigits": "9319",
"expiry": {
"year": 2027,
"month": 11
},
"status": "ACTIVE",
"subtype": "MERCHANT"
}
}
]
}
4. Process subsequent transactions in the recurring cycle
Use the multi‑use payment token for all subsequent transactions in the recurring cycle.
See Authorization in the Card Payments API Reference.
{
"merchantRefNum": "{{$guid}}",
"amount": 123,
"settleWithAuth": false,
"card": {
"paymentToken": "CrSpVqeLvBkJ8qz"
},
"merchantDescriptor": {
"dynamicDescriptor": "Merchant Test"
},
"description": "Reccuring Test",
"profile": {
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@somedomain.com"
},
"storedCredential": {
"type": "RECURRING ",
"occurrence": "SUBSEQUENT",
"initialTransactionId":"aef6618d-0bf1-42b4-a129-9fe20018f093"
}
}
{
"id": "f03dee34-97a3-462d-886c-d19fafbd6262",
"merchantRefNum": "97d8881c-399b-446f-9003-b4d87cc71237",
"txnTime": "2026-03-13T09:35:05Z",
"status": "COMPLETED",
"acquirerResponse": {
"code": "NAG",
"responseCode": "00",
"responseCodeDescription": "Approved",
"avsCode": "Z",
"mid": "00404940"
},
"cardSchemeTransactionId": "AGZZ3016201800 ",
"amount": 123,
"settleWithAuth": false,
"preAuth": false,
"availableToSettle": 123,
"card": {
"tokenType": "APPLE_PAY",
"applePay": {
"expiry": {
"month": 11,
"year": 2027
},
"lastDigits": "9319",
"subtype": "MERCHANT"
},
"type": "VI",
"lastDigits": "0224",
"cardExpiry": {
"month": 11,
"year": 2027
},
"issuingCountry": "US",
"cardBin": "462294"
},
"authCode": "165908",
"profile": {
"merchantCustomerId": "0c1277c6-6d56-4d37-bd24-1c8e57760395",
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@somedomain.com",
"dateOfBirth": {
"day": 24,
"month": 10,
"year": 1986
}
},
"billingDetails": {
"street": "New York City, 123 Str",
"city": "Mad",
"country": "US",
"zip": "MC23",
"phone": "777-444-8888"
},
"merchantDescriptor": {
"dynamicDescriptor": "Yordan Test"
},
"visaAdditionalAuthData": {},
"description": "Reccuring Test",
"currencyCode": "CAD",
"avsResponse": "MATCH_ZIP_ONLY",
"cvvVerification": "MATCH",
"links": [
{
"rel": "self",
"href": "https://api.test.paysafe.com/cardpayments/v1/accounts/1002788600/auths/f03dee34-97a3-462d-886c-d19fafbd6262"
}
],
"storedCredential": {
"type": "RECURRING",
"occurrence": "SUBSEQUENT",
"initialTransactionId": "aef6618d-0bf1-42b4-a129-9fe20018f093"
}
}
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.