Withdraw funds using stored Apple Pay card-on-file device tokens.
Apple Pay in Payout Drop-in is a stored-instrument flow. The accordion lists vaulted Apple Pay device tokens for the authenticated shopper. The shopper selects a token and submits the withdrawal. Drop-in uses those vaulted tokens only; it doesn't open a native Apple Pay payment sheet.
This method gives you:
- Stored token selection: Shoppers choose from eligible Apple Pay vault tokens already on file.
- Unified callbacks: Same
onBeforeSubmit,onSubmit,onSuccess, andonErrorpattern as card and Google Pay card-on-file methods. - No CVC: Card-on-file payout submit doesn't require CVC for these tokens.
- Token maintenance: Where the list UI allows it, shoppers can delete tokens and edit expiry.
- Branding: Panel styling comes from your payout site configuration.
The flow works like this:
- Your payout session allows Apple Pay under
allowedFundingTypes.wallets.applePay. - You return a shopper ID from
onGetShopper. - Drop-in loads active tokens and keeps only Apple Pay device tokens that aren't expired or blacklisted.
- If at least one token remains, Apple Pay appears in the accordion.
- The shopper selects a token and confirms the withdrawal.
- Optional
onBeforeSubmitandonSubmitrun, then payout initiation completes withonSuccessoronError.
If every method is filtered out, Drop-in reports SDK1701.
Apple Pay must be allowed on the payout session through allowedFundingTypes.wallets.applePay. The SDK treats Apple Pay as a candidate method when the applePay object is present. A merchantId value may appear on that object when Apple Pay is enabled for the site.
Example session fragment:
{
"allowedFundingTypes": {
"wallets": {
"applePay": {}
}
}
}Match transactionData.amount and transactionData.currency to the payout session amounts.
Apple Pay appears only when these shopper and token checks pass:
| Requirement | Description |
|---|---|
onGetShopper | The authenticated shopper ID used by the token vault. Without it, token retrieval is skipped and Apple Pay won't appear. |
| Wallet type | The token walletType must be ApplePay. |
| PAN type | The token panType must be Device. |
| Expiry | Whether the token is still in date. Expired tokens are filtered out. The current month remains valid. |
| Blacklist | Tokens listed in methodConfig.applePay.blacklistedInstruments are hidden. |
After filtering, Drop-in shows up to five tokens, ranked by most recent successful purchase or payout activity.
When Apple Pay is a candidate and a shopper ID is present, Drop-in retrieves active tokens for ownerType MerchantGroup (set during initialisation) and your configured ownerId, for that shopper.
Typical path:
From that shared list, Apple Pay keeps tokens with walletType ApplePay and panType Device only. If the token call fails or returns nothing usable for Apple Pay, the method is omitted without necessarily calling onError.
Showing a token in Drop-in doesn't authorise the payout. Confirm the amount, destination, and eligibility on your backend before treating the withdrawal as complete.
Use methodConfig.applePay for blacklists only.
Use blacklistedInstruments to hide specific tokens from the Apple Pay panel:
import type { PayoutDropInMethodConfig } from '@pxpio/web-components-sdk';
const methodConfig: PayoutDropInMethodConfig = {
applePay: {
blacklistedInstruments: {
gatewayTokenIds: ['<GATEWAY_TOKEN_ID>'],
schemeTokenIds: ['<SCHEME_TOKEN_ID>'],
},
},
};blacklistedInstruments accepts:
| Property | Description |
|---|---|
gatewayTokenIds | The gateway token IDs to hide from the panel. |
schemeTokenIds | The scheme token IDs to hide from the panel. |
Blacklisting hides instruments in the accordion. When closed-loop enforcement is active, the same blacklist values are also sent on the closed-loop allocation request. Confirm payout eligibility on your backend.
Override the accordion label:
localisation: {
payoutDropIn: {
applePayLabel: 'Apple Pay',
},
},The following example initialises Drop-in for an Apple Pay payout, including optional onBeforeSubmit and onSubmit hooks on the card-on-file path:
import {
PayoutDropIn,
type PayoutDropInSubmitResult,
} from '@pxpio/web-components-sdk';
import type { BaseSdkException } from '@pxpio/web-components-sdk';
const payoutDropIn = PayoutDropIn.initialize({
environment: 'test',
session: sessionData,
ownerId: 'YOUR-MERCHANT-GROUP-ID',
transactionData: {
currency: 'USD',
amount: 40,
entryType: 'Ecom',
merchantTransactionId: crypto.randomUUID(),
merchantTransactionDate: () => new Date().toISOString(),
},
onGetShopper: async () => ({ id: 'shopper-123' }),
onBeforeSubmit: async (payoutMethod) => {
if (payoutMethod !== 'ApplePay') {
return true;
}
return confirmWithdrawal();
},
onSubmit: (payoutMethod) => {
if (payoutMethod === 'ApplePay') {
showLoading(true);
}
},
onSuccess: async (result: PayoutDropInSubmitResult) => {
showLoading(false);
console.log('Apple Pay payout submitted', result.systemTransactionId);
console.log('Payout method', result.payoutMethod);
await verifyPayoutOnBackend(result);
},
onError: (error: BaseSdkException) => {
showLoading(false);
console.error(error.ErrorCode, error.message);
},
});
await payoutDropIn.create('payout-drop-in-container');On success, onSuccess receives a PayoutDropInSubmitResult with at least:
| Property | Description |
|---|---|
systemTransactionId | The PXP system transaction ID. |
merchantTransactionId | Your merchant transaction ID. |
payoutMethod | ApplePay for this method. |
Treat onSuccess as submission acknowledgement. Verify the transaction with your webhook handler or a server-side lookup before updating the shopper's withdrawal status.
A successful Apple Pay payout merchant webhook looks like this:
{ "eventDate": "2025-12-16T07:37:11.1613200Z", "eventCategory": "transaction", "eventData": { "state": "Authorised", "amount": { "transaction": 40, "currencyCode": "USD" }, "transactionMethod": "Payout", "merchant": "merchant-1", "site": "site-1", "merchantTransactionDate": "2025-12-16T07:37:11.1613200Z", "merchantTransactionId": "APPLEPAY-PAYOUT-001", "systemTransactionId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "fundingData": { "card": { … } } } }
See Quickstart for the end-to-end session and reconciliation pattern, and Manage webhooks for subscription and signature validation.
Card gaming payout token rules aren't automatically applied to Apple Pay token filtering in Drop-in. Don't assume card gaming rules extend to Apple Pay without backend confirmation.
These codes are the ones you're most likely to see on the Apple Pay path:
| Code | Typical Apple Pay context |
|---|---|
SDK1701 | No payout methods remain. For example, no eligible Apple Pay device tokens and no other methods. |
SDK1703 | Card-on-file payout initiation failed. Inspect message and details. Correlate with the backend transaction state. |
See Error handling.
Validate the path with these steps:
- Use
environment: 'test'with sandbox credentials. - Prepare a test shopper that already has an Apple Pay device token in the vault (
walletType: ApplePay,panType: Device). - Create a payout session with
allowedFundingTypes.wallets.applePayenabled. - Confirm the Apple Pay accordion appears, token selection works, and submit reaches
onSuccessor a clearSDK1703. - Verify the transaction on your backend before treating the withdrawal as complete.
See Testing.