# Create Apple Pay token

`POST /accounts/{accountID}/apple-pay/tokens`

API version: `v2026.10.00`. Send `X-Moov-Version: v2026.10.00` to get the behavior described here.

> AI agents: search and read all Moov docs with the docs MCP server at https://docs.moov.io/mcp (no API key). Setup: https://docs.moov.io/guides/developer-tools/mcp-ai/docs-mcp/index.md

Connect an Apple Pay token to the specified account.

Read our [Apple Pay tutorial](https://docs.moov.io/guides/sources/cards/apple-pay/#register-your-domains) to learn more.
The `token` data is defined by Apple Pay and should be passed through from Apple Pay's response unmodified.

To access this endpoint using an [access token](https://docs.moov.io/api/authentication/access-tokens/)
you'll need to specify the `/accounts/{accountID}/cards.write` scope.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `X-Moov-Version` | header | string |  | Set this header to v2026.10.00 to use the API described in this specification. When omitted, the server defaults to v2024.01.00, the earliest supported version, which may not match the behavior documented here. An unrecognized well-formed version uses the latest supported version that is not newer than the requested version, when one exists. For example, `v2026.08.00` uses `v2026.07.00`. A malformed value, such as `2022`, returns a `404` response. Values: `v2026.10.00`. |
| `accountID` | path | string | Yes | ID of the Moov account representing the cardholder. |

## Request body

Content type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | object | Yes | Contains the user's payment information as returned from Apple Pay. Refer to [Apple's documentation](https://developer.apple.com/documentation/apple_pay_on_the_web/applepaypaymenttoken) for more information. |
| `token.paymentData` | object | Yes | Contains the encrypted payment data. Refer to [Apple's documentation](https://developer.apple.com/documentation/apple_pay_on_the_web/applepaypaymenttoken/1916115-paymentdata) for more information. |
| `token.paymentData.version` | string | Yes | Specifies the encryption used for the payment token ("EC_v1" or "RSA_v1"). |
| `token.paymentData.data` | string | Yes | The encrypted, base64-encoded payment data. |
| `token.paymentData.signature` | string | Yes | A base64 encoded signature of the payment and header data. |
| `token.paymentData.header` | object | Yes | Information needed to decrypt Apple Pay payment data. Refer to [Apple's documentation](https://developer.apple.com/documentation/passkit/payment-token-format-reference#Header-keys-and-values) for more information. |
| `token.paymentData.header.ephemeralPublicKey` | string |  | Base64-encoded ephemeral public key, used for ECC-encrypted payment data. |
| `token.paymentData.header.publicKeyHash` | string | Yes | A base64-encoded, SHA-256 hash of the merchant's public key. |
| `token.paymentData.header.transactionId` | string | Yes | A device-generated identifier for the transaction. |
| `token.paymentMethod` | object | Yes | Provides information about the underlying card. Refer to [Apple's documentation](https://developer.apple.com/documentation/apple_pay_on_the_web/applepaypaymenttoken/1916113-paymentmethod) for more information. |
| `token.paymentMethod.displayName` | string | Yes | A display-friendly discription of the card. |
| `token.paymentMethod.network` | string | Yes | The card's payment network. |
| `token.paymentMethod.type` | string | Yes | The type of card. |
| `token.transactionIdentifier` | string | Yes | A unique identifier provided by Apple Pay for this payment. |
| `billingContact` | object |  | Billing contact information as returned from Apple Pay. Refer to [Apple's documentation](https://developer.apple.com/documentation/apple_pay_on_the_web/applepaypaymentcontact) for more information. |
| `billingContact.addressLines` | array of string |  | Address lines 1 and 2 for the contact. |
| `billingContact.locality` | string |  | The contact's city. |
| `billingContact.postalCode` | string |  | The contact's postal code. |
| `billingContact.administrativeArea` | string |  | The contact's two-letter state code. |
| `billingContact.countryCode` | string |  | The contact's two-letter ISO 3166 |

## Response 200

The request completed successfully.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `[].paymentMethodID` | string | Yes | The new payment method's ID. |
| `[].paymentMethodType` | string | Yes | The payment method type that represents a payment rail and directionality Values: `moov-wallet`, `ach-debit-fund`, `ach-debit-collect`, `ach-credit-standard`, `ach-credit-same-day`, `rtp-credit`, `card-payment`, `push-to-card`, `pull-from-card`, `apple-pay`, `card-present-payment`, `instant-bank-credit`, `push-to-apple-pay`, `pull-from-apple-pay`, `google-pay`, `push-to-google-pay`, `pull-from-google-pay`. |
| `[].applePay` | object | Yes | Describes an Apple Pay token on a Moov account. |
| `[].applePay.brand` | string | Yes | The card brand. Values: `American Express`, `Discover`, `Mastercard`, `Visa`, `Unknown`. |
| `[].applePay.cardType` | string | Yes | The type of the card. Values: `debit`, `credit`, `prepaid`, `unknown`. |
| `[].applePay.cardDisplayName` | string | Yes | User-friendly name of the tokenized card returned by Apple. It usually contains the brand and the last four digits of the underlying card. There is no standard format. |
| `[].applePay.fingerprint` | string | Yes | Uniquely identifies a linked payment card or token. For Apple Pay, the fingerprint is based on the tokenized card number and may vary based on the user's device. This field can be used to identify specific payment methods across multiple accounts on your platform. |
| `[].applePay.expiration` | object | Yes | The expiration date of the card or token. |
| `[].applePay.dynamicLastFour` | string | Yes | The last four digits of the Apple Pay token, which may differ from the tokenized card's last four digits. |
| `[].applePay.issuerCountry` | string |  | Country where the underlying card was issued. |

## Errors

| Status | Meaning |
| --- | --- |
| 400 | The server could not understand the request due to invalid syntax. |
| 401 | The request contained missing or expired authentication. |
| 403 | The user is not authorized to make the request. |
| 404 | The requested resource was not found. |
| 409 | The request conflicted with the current state of the target resource. |
| 422 | The request was well-formed, but the contents failed validation. Check the request for missing or invalid fields. |
| 429 | Request was refused due to rate limiting. |
| 500 | The request failed due to an unexpected error. |
| 504 | The request failed because a downstream service failed to respond. |

## Examples

### cURL

```bash
curl -X POST "https://api.moov.io/accounts/{accountID}/apple-pay/tokens" \
  -H "Authorization: Bearer {token}" \
  -H "X-Moov-Version: v2026.10.00" \
  -d '{
  "token": {
    "paymentData": {
      "version": "EC_v1",
      "data": "3+f4oOTwPa6f1UZ6tG...CE=",
      "signature": "MIAGCSqGSIb3DQ.AAAA==",
      "header": {
        "publicKeyHash": "l0CnXdMv...D1I=",
        "transactionId": "32b...4f3"
      }
    },
    "paymentMethod": {
      "displayName": "Visa 1234",
      "network": "Visa",
      "type": "debit"
    },
    "transactionIdentifier": "32b...4f3"
  }
}'
```

### Typescript (SDK)

```typescript
import { Moov } from "@moovio/sdk";

const moov = new Moov({
  security: {
    username: "",
    password: "",
  },
});

async function run() {
  const result = await moov.applePay.linkToken({
    accountID: "bf498c07-3852-4060-b561-bf992e26a851",
    linkApplePay: {
      token: {
        paymentData: {
          version: "EC_v1",
          data: "3+f4oOTwPa6f1UZ6tG...CE=",
          signature: "MIAGCSqGSIb3DQ.AAAA==",
          header: {
            ephemeralPublicKey: "MFkwEK...Md==",
            publicKeyHash: "l0CnXdMv...D1I=",
            transactionId: "32b...4f3",
          },
        },
        paymentMethod: {
          displayName: "Visa 1234",
          network: "Visa",
          type: "debit",
        },
        transactionIdentifier: "32b...4f3",
      },
      billingContact: {
        addressLines: [
          "123 Sesame Street",
        ],
        locality: "Phoenix",
        postalCode: "30345",
        administrativeArea: "AZ",
        countryCode: "US",
      },
    },
  });

  console.log(result);
}

run();
```

Full reference with SDK examples in every language: https://docs.moov.io/api/v2026.10.00/sources/apple-pay/token/