CheckoutPayment ScenariosSubsequent Transactions

📱 Apple Pay Subsequent Transactions

Learn how to charge a customer’s saved Apple Pay card for subsequent purchases without re-presenting the Apple Pay sheet.

Overview

Coinflow supports Card on File (COF) transactions for Apple Pay. Once a customer completes an initial Apple Pay purchase, Coinflow securely saves their Apple Pay card so you can process subsequent, customer-initiated purchases without showing the Apple Pay sheet again — no re-authentication with Face ID or Touch ID required.

This uses the same Card on File Checkout endpoint as regular card payments. Coinflow automatically detects that the original payment was made with Apple Pay — no additional parameters are required.

Customer Initiated Only

Apple Pay subsequent transactions are supported for Card on File (Customer Initiated) transactions only. Merchant Initiated Transactions (MIT) — such as automated subscription renewals — are not supported with Apple Pay. The customer must be present and actively confirming each purchase.

How Apple Pay Cards Are Saved

When Card on File is enabled on your merchant account, every successful Apple Pay checkout automatically saves the customer’s card:

1

Customer Pays with Apple Pay

The customer completes a purchase through the Apple Pay sheet, authenticating with Face ID or Touch ID.

2

Coinflow Saves the Card

Coinflow tokenizes the card behind the Apple Pay payment and stores it securely in Coinflow’s PCI-compliant vault, attached to the customer’s profile.

3

Card Appears on the Customer Profile

The saved card is returned in the mobiles array of the Get Customer response, including a display alias (e.g. “Visa 1234”), the card token, and expiration details.

GET
/api/customer/v2
1curl https://api-sandbox.coinflow.cash/api/customer/v2 \
2     -H "x-coinflow-auth-session-key: <apiKey>"
Try it
Response
1{
2  "customer": {
3    "_id": "string",
4    "email": "string",
5    "createdAt": "2024-01-15T09:30:00Z",
6    "merchant": "string",
7    "customerId": "string",
8    "bankAccounts": [
9      {
10        "last4": "string",
11        "accountHash": "string",
12        "alias": "string",
13        "token": "string",
14        "reference": "string"
15      }
16    ],
17    "cards": [
18      {
19        "last4": "string",
20        "token": "string",
21        "type": "VISA",
22        "disbursementStatus": "Immediate",
23        "createdAt": "2024-01-15T09:30:00Z",
24        "hasAddress": true
25      }
26    ],
27    "sepas": [
28      {
29        "last4": "string",
30        "accountHash": "string",
31        "alias": "string",
32        "token": "string",
33        "reference": "string",
34        "sortCode": "string"
35      }
36    ],
37    "fasterPayments": [
38      {
39        "last4": "string",
40        "accountHash": "string",
41        "alias": "string",
42        "token": "string",
43        "reference": "string",
44        "sortCode": "string"
45      }
46    ],
47    "interacs": [
48      {
49        "alias": "string",
50        "token": "string",
51        "type": "interac"
52      }
53    ],
54    "mobiles": [
55      {
56        "alias": "Visa 1234",
57        "token": "4111114324324111_bt",
58        "type": "mobile",
59        "genus": "applepay",
60        "hasAddress": true,
61        "expMonth": "12",
62        "expYear": "28"
63      }
64    ]
65  }
66}

No Extra Integration Work for Saving

Card saving happens automatically on every successful Apple Pay purchase when Card on File is enabled — there is no separate “save card” call.

Prerequisites

Before processing Apple Pay subsequent transactions, make sure:

  1. Apple Pay is implemented — See Implement Apple Pay
  2. Card on File is enabled on your merchant account — contact your Coinflow integration representative to enable it and configure your velocity limits
  3. An initial Apple Pay purchase is complete — you need either the paymentId from that purchase or the saved card token from the customer profile

Processing Configuration

Apple Pay Card on File is not available on every processing configuration. If your requests return 403 - Card on file not available, contact your Coinflow integration representative.

Implementation Guide

1

Step 1: Complete the Initial Apple Pay Purchase

The customer’s first purchase must go through the standard Apple Pay flow, where they authenticate on their device. After a successful purchase, save either of the following identifiers:

  • The paymentId from the checkout response or webhook
  • The card token from the mobiles array on the Get Customer response
2

Step 2 (Optional): Verify the Card Is Authorized

Before starting a session that depends on subsequent transactions (for example, an auction or a tab), confirm the saved card can still be charged:

POST
/api/checkout/card-on-file-authorized
1curl -X POST https://api-sandbox.coinflow.cash/api/checkout/card-on-file-authorized \
2     -H "x-coinflow-auth-user-id: <apiKey>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjYXJkSWQiOiIxMjM0NTY3ODkwIiwidXNlcklkIjoiYWJjZGVmMTIzNDU2IiwiaWF0IjoxNjgwMDAwMDAwfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
6}'
Try it
Response
1{
2  "authorized": true
3}

If authorized is false, direct the customer through a fresh Apple Pay purchase to create a new original payment reference.

3

Step 3: Process the Subsequent Transaction

Call the Card on File Checkout endpoint with either the original Apple Pay paymentId or the saved card token:

View Card on File Checkout API Reference

Using the Original Payment ID:

POST
/api/checkout/card-on-file
1curl -X POST https://api-sandbox.coinflow.cash/api/checkout/card-on-file \
2     -H "x-coinflow-auth-user-id: <apiKey>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "subtotal": {
6    "cents": 2500,
7    "currency": "USD"
8  },
9  "token": "4111114324324111_bt"
10}'
Try it

Using the Card Token:

POST
/api/checkout/card-on-file
1curl -X POST https://api-sandbox.coinflow.cash/api/checkout/card-on-file \
2     -H "x-coinflow-auth-user-id: <apiKey>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "subtotal": {
6    "cents": 2500,
7    "currency": "USD"
8  },
9  "token": "4111114324324111_bt"
10}'
Try it

Response:

Response
1{
2  "paymentId": "string"
3}

Example Values

The IDs, tokens, and amounts above are examples only and do not reflect real production values. Use the identifiers returned by your own checkout responses, webhooks, and customer profiles.

Original Payment Must Be Apple Pay

The originalPaymentId must reference a successful Apple Pay purchase, and a token must belong to a saved Apple Pay card. You cannot mix payment sources — referencing a regular card payment for an Apple Pay saved card (or vice versa) returns a 400 error.

4

Step 4: Handle Chargeback Protection (If Enabled)

If chargeback protection is enabled on your account, include the Coinflow device ID header and chargebackProtectionData in the request, exactly as with regular Card on File transactions.

Handling Expired References (410 Errors)

Every integration must handle 410 responses

A 410 Gone response means the original Apple Pay payment can no longer be used as a Card on File reference. Unlike regular card payments, there is no CVV re-entry fallback for Apple Pay — the only way to recover is for the customer to complete a new purchase through the Apple Pay sheet, which creates a fresh original payment reference.

A 410 is returned when any of your Card on File velocity limits are hit:

LimitSettingWhen It Triggers
Payment countmaxCount / periodToo many Card on File payments against the original payment within the period
AmountmaxMultipleThe transaction exceeds the allowed multiple of the original payment amount
Reference windowexpirationToo much time has passed since the original Apple Pay purchase

Recommended flow:

1async function chargeSavedApplePayCard({originalPaymentId, subtotal}) {
2  const response = await fetch('/api/checkout/card-on-file', {
3    method: 'POST',
4    headers: {
5      'Content-Type': 'application/json',
6      Authorization: 'your-merchant-api-key',
7      'x-coinflow-auth-user-id': 'your-customer-id',
8    },
9    body: JSON.stringify({subtotal, originalPaymentId}),
10  });
11
12  if (response.status === 410) {
13    // The reference is exhausted or expired. Show a friendly message and
14    // re-present the Apple Pay sheet so the customer authenticates on-device.
15    // The new purchase becomes the original payment reference going forward.
16    return promptApplePayPurchase({subtotal});
17  }
18
19  if (!response.ok) throw new Error((await response.json()).message);
20  return response.json();
21}

Avoid 410s Mid-Session

Call POST /checkout/card-on-file-authorized before starting a session that depends on subsequent transactions (an auction, a tab, a table). It runs the same velocity checks with a zero-amount total, so you can route the customer through a fresh Apple Pay purchase before they are mid-session rather than failing at charge time.

Differences from Regular Card on File

FeatureCard on File (Regular Card)Card on File (Apple Pay)
Endpoint/api/checkout/card-on-file/api/checkout/card-on-file
CVV RequiredNoNo
3DS EligibleYesNo — the customer authenticated on-device during the original purchase
Original PaymentCVV-verified card paymentSuccessful Apple Pay purchase
Merchant Initiated (MIT)SupportedNot supported
Velocity LimitsCard on File settingsSame Card on File settings

Velocity limits (maxCount, period, maxMultiple, expiration) are shared with your regular Card on File configuration.

Error Handling

Error Message:

{merchantId} does not support card on file transactions

Cause: Card on File is not enabled or not configured on your merchant account.

Resolution: Contact your Coinflow integration representative to enable Card on File.

Error Message:

Card on file not available. Please contact your integrations representative.

Cause: Your processing configuration does not support Apple Pay Card on File.

Resolution: Contact your Coinflow integration representative.

Error Message:

Cannot perform card on file operations with different payment source

Cause: The originalPaymentId references a payment made with a different payment source — for example, a regular card payment when charging a saved Apple Pay card, or a mobile wallet other than Apple Pay.

Resolution:

  • Only reference an original payment made with Apple Pay
  • Google Pay payments cannot be used for subsequent transactions

Error Message:

Cannot perform card on file operations for a originalPaymentId which is a card on file transaction,
please pass the originalPaymentId which processed with ApplePay

Cause: The originalPaymentId references a Card on File payment rather than the original Apple Pay purchase.

Resolution: Always reference the initial Apple Pay purchase — do not chain Card on File transactions.

The original payment reference can no longer be used — a velocity limit was hit or the reference window expired. See Handling Expired References above for the recovery flow, and the Card on File error reference for the exact error messages.

Frequently Asked Questions

No. Subsequent transactions run against the saved card without presenting the Apple Pay sheet. The customer’s on-device authentication from the original purchase serves as the cardholder verification.

No. Subsequent transactions are currently supported for Apple Pay only. Google Pay customers must authenticate through the Google Pay flow for every purchase.

No. Apple Pay saved cards support Customer Initiated (Card on File) transactions only — the customer must actively confirm each purchase in your application.

Use the mobiles array on the Get Customer response. Each saved Apple Pay card includes an alias (the card’s display name from Apple Pay, e.g. “Visa 1234”) you can show at confirmation.

Next Steps

Implement Apple Pay

Set up the initial Apple Pay purchase flow

Card on File

Learn how Card on File works for regular card payments

Webhooks

Get notified about payment results

Merchant Initiated Transactions

Automated charges with regular card payments