Apple Pay Push to Card

Merchants paying out users from a Coinflow wallet can save a user’s Apple Pay card as a reusable payout destination, rather than passing the raw Apple Pay token on every disbursement. This mirrors the way a debit card is linked with POST /withdraw/debit-card: the Apple Pay token is collected once, and the returned account token is used for every subsequent payout.

Step 1: Create a session key for the user

Each user is identified to Coinflow by an ID you choose (for example, your internal user ID). Create a session key for that user by calling Get Session Key with your API key and the user’s ID in the x-coinflow-auth-user-id header.

GET

/api/auth/session-key

1 curl https://api-sandbox.coinflow.cash/api/auth/session-key \
2      -H "x-coinflow-auth-user-id: <apiKey>" \
3      -H "Content-Type: application/json"

Try it

Response

1 {
2   "key": "a1b2c3d4e5f67890abcdef1234567890"
3 }

Step 2: Verify the user (KYC)

An Apple Pay card can only be linked to an approved withdrawer, so the user must complete identity verification first. The simplest path is Coinflow’s hosted Bank Authentication UI, opened with the session key from Step 1. You can also run KYC entirely through the API — see the merchant payout guide for the API-driven verification options.

Step 3: Link the Apple Pay card

Collect an Apple Pay token object from the Apple Pay SDK’s disbursement flow — see the Apple Pay Payouts API Implementation recipe — then link the card server-to-server by calling POST /withdraw/apple-pay. Pass the full ApplePayResponseObject — the token plus the billingContact — as applePayPayment, authenticating with your API key and the same x-coinflow-auth-user-id header used in Step 1.

Coinflow decrypts the token, tokenizes the underlying card, and runs a BIN check to confirm the card is a debit card that is eligible for push-to-card. Non-debit cards are rejected. On success the endpoint returns the account token for the saved Apple Pay card.

POST

/api/withdraw/apple-pay

1 curl -X POST https://api-sandbox.coinflow.cash/api/withdraw/apple-pay \
2      -H "x-coinflow-auth-user-id: <apiKey>" \
3      -H "Content-Type: application/json" \
4      -d '{
5   "applePayPayment": {
6     "token": {
7       "transactionIdentifier": "string",
8       "paymentMethod": {
9         "network": "Visa",
10         "displayName": "string"
11       },
12       "paymentData": {
13         "version": "string",
14         "header": {
15           "transactionId": "string",
16           "ephemeralPublicKey": "string",
17           "publicKeyHash": "string"
18         },
19         "signature": "string",
20         "data": "string"
21       }
22     },
23     "billingContact": {
24       "givenName": "string",
25       "familyName": "string",
26       "addressLines": [
27         "string"
28       ],
29       "locality": "string"
30     }
31   }
32 }'

Try it

Response

1 "string"

Step 4: Initiate the delegated payout

Push funds to the linked card by calling POST /merchant/withdraws/payout/delegated with the user’s ID as userId, the token from Step 3 as account, and a speed of card — exactly as you would for a saved debit card. The payout is funded from your merchant settlement wallet. (The same account token also works on POST /merchant/withdraws/payout for user-initiated payouts.)

POST

/api/merchant/withdraws/payout/delegated

1 curl -X POST https://api-sandbox.coinflow.cash/api/merchant/withdraws/payout/delegated \
2      -H "Authorization: <apiKey>" \
3      -H "Content-Type: application/json" \
4      -d '{
5   "speed": "same_day",
6   "account": "card_4f3a2b1c9d8e7f6a",
7   "userId": "user_1234567890abcdef",
8   "idempotencyKey": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
9   "amount": {
10     "cents": 25000
11   }
12 }'

Try it

Response

1 {
2   "effectiveSpeed": "same_day",
3   "signature": "3045022100dff9a1b2c3d4e5f67890123456789abcdef0123456789abcdef0123456789ab02207c9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e"
4 }

Pass a unique idempotencyKey on every payout so a retried request can never double-pay, and read effectiveSpeed from the response to confirm how the payout was actually processed.

Step 5: Monitor the payout

Track payout status through Withdraw Webhooks, correlated by the signature returned in Step 4. The linked card stays saved on the withdrawer and can be reused for future payouts without re-collecting an Apple Pay token.