Apple Pay™

Token Types

Every Apple Pay™ resource has a type field that indicates which kind of network token Apple issued for the transaction.

Type	Full Name	Description
`dpan`	Device Primary Account Number	A device-specific network token provisioned during wallet enrollment. Persists across transactions on the same device. Each transaction uses a new one-time cryptogram. Used for standard one-time payments.
`mpan`	Merchant Primary Account Number	A merchant-specific network token issued when the payment request includes a recurring, automatic reload, or deferred payment configuration. Subject to issuer and network support. Supports lifecycle management via Apple webhooks, which Basis Theory processes automatically.

The token type is determined by Apple at the time of payment authorization and cannot be requested directly. To receive an mpan, the payment request must be configured for a recurring or deferred payment scenario, and the issuer must support merchant tokenization for the card. Refer to Apple's documentation for the payment request configuration options.

Register Domain Address

Apple Pay™ requires websites to associate their domain address with a merchant identifier. Basis Theory handles the merchant and certificate handling. To utilize Basis Theory's Apple Pay™ integration, you will need to add your domain and subdomains to our merchant. Review Apple's documentation for important considerations regarding your domain.

Each Tenant can register up to 99 domains.

If you're making direct calls to Apple APIs that require a merchant ID, set the merchant ID to your tenant ID.

Prerequisite

Before registering your domain with Basis Theory, our domain verification file needs to be available to Apple via your website. Download the file and add it to your server at the URL https://<YOUR_DOMAIN>/.well-known/apple-developer-merchantid-domain-association.

POST

https://api.basistheory.com/apple-pay/domain-registration

Permissions

apple-pay:manage

Request

cURL
Node
C#
Python

curl --request POST \
  --url https://api.basistheory.com/apple-pay/domain-registration \
  --header 'BT-API-KEY: <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "domain": "<YOUR_DOMAIN>"
  }'

await client.applePay.domain.register({
  domain: "domain",
});

await client.ApplePay.Domain.RegisterAsync(
  new ApplePayDomainRegistrationRequest { Domain = "domain" }
);

client.apple_pay.domain.register(
  domain="domain",
)

Attribute	Required	Description
`domain`	true	Domain to register.

Response

{
  "domains": [
    {
      "domain": "...",
      "status": "verified"
    }
    ...
  ]
}

Attribute	Type	Description
domains	Array	List of domains associated with the tenant
domains[].domain	string	Domain or subdomain
domains[].status	string	Verification status of domain. Only `verified`

Errors

Status Code
422	Ensure that the domain registration file is available from the domain being registered
50X	Please contact Basis Theory support and provide the domain name in your message.

Register All Domain Addresses

PUT

https://api.basistheory.com/apple-pay/domain-registration

Permissions

apple-pay:manage

Request

cURL
Node
C#
Python
Terraform

curl --request PUT \
  --url https://api.basistheory.com/apple-pay/domain-registration \
  --header 'BT-API-KEY: <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "domains": ["<DOMAIN_ONE>", "DOMAIN_TWO"]
  }'

client.applePay.domain.registerAll({
  domains: ["DOMAIN_ONE", "DOMAIN_TWO"]
})

await client.ApplePay.Domain.RegisterAllAsync(new ApplePayDomainRegistrationListRequest
  {
    Domains = ["DOMAIN_ONE", "DOMAIN_TWO"]
  });

client.apple_pay.domain.register_all(domains=["DOMAIN_ONE", "DOMAIN_TWO"])

resource "basistheory_applepay_domain" "my_apple_pay_domains" {
  domains = ["DOMAIN_ONE", "DOMAIN_TWO"]
}

Attribute	Required	Description
`domains`	true	List of domain names to register.

Response

{
  "domains": [
    {
      "domain": "...",
      "status": "verified"
    }
    ...
  ]
}

Attribute	Type	Description
domains	Array	List of domains associated with the tenant
domains[].domain	string	Domain or subdomain
domains[].status	string	Verification status of domain. Only `verified`

Errors

Status Code
422	Ensure that the domain registration file is available from the domain being registered
50X	Please contact Basis Theory support and provide the domain name in your message.

Get Domain Registrations

GET

https://api.basistheory.com/apple-pay/domain-registration

Permissions

apple-pay:manage

Request

cURL
Node
C#
Python

curl --request GET \
  --url https://api.basistheory.com/apple-pay/domain-registration \
  --header 'BT-API-KEY: <API_KEY>'

await client.applePay.domain.get();

await client.ApplePay.Domain.GetAsync();

client.apple_pay.domain.get()

Response

{
  "domains": [
    {
      "domain": "...",
      "status": "verified"
    }
    ...
  ]
}

Attribute	Type	Description
domains	Array	List of domains associated with the tenant
domains[].domain	string	Domain or subdomain
domains[].status	string	Verification status of domain. Only `verified`

Deregister Domain

POST

https://api.basistheory.com/apple-pay/domain-deregistration

Permissions

apple-pay:manage

Request

cURL
Node
C#
Python

curl --request POST \
  --url https://api.basistheory.com/apple-pay/domain-deregistration \
  --header 'BT-API-KEY: <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "domain": "cdn.basistheory.com"
  }'

await client.applePay.domain.deregister({
  domain: "domain",
});

await client.ApplePay.Domain.DeregisterAsync(
  new ApplePayDomainDeregistrationRequest { Domain = "domain" }
);

client.apple_pay.domain.deregister(
  domain="domain",
)

Attribute	Required	Description
`domain`	true	Domain to deregister.

Response

204 No Content

Create Merchant Session

A proxy endpoint to start an Apple Pay™ merchant payment session using Basis Theory's merchant identifier. See the documentation on Apple's site for more details.

You can specify which merchant registration to use for a session request so the correct associated keys are selected when creating the Apple Pay™ session.

POST

https://api.basistheory.com/apple-pay/session

Permissions

apple-pay:session

Request

cURL
Node
C#
Python

curl --request POST \
  --url https://api.basistheory.com/apple-pay/session \
  --header 'BT-API-KEY: <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "validation_url": "https://apple-pay-gateway.apple.com/paymentservices/paymentSession",
  "display_name": "My Ecommerce Store",
  "domain": "my-site.example.com",
  "merchant_registration_id": ""
}'

await client.applePay.session.create({});

await client.ApplePay.Session.CreateAsync(new ApplePaySessionRequest());

client.apple_pay.session.create()

Request Parameters

Attribute	Required	Description
`validation_url`	false	Validation URL returned from the `onvalidatemerchant` event. Default: https://apple-pay-gateway.apple.com/paymentservices/paymentSession
`display_name`	true	A string of 64 or fewer UTF-8 characters containing the canonical name for your store, suitable for display. A good display name remains a consistent value for the store and doesn't contain dynamic values such as incrementing order numbers. Don’t localize the name. Use only characters from the supported character sets in the fonts listed in the table below.
`domain`	true	The fully qualified domain name of the website requesting the Apple Pay™ session.
`merchant_registration_id`	false	The unique identifier of the merchant registration created through the Basis Theory Merchant API.

Response

Returns an opaque Apple Pay™ session object that will be passed into the completeMerchantValidation method.

Errors

Status Code	Description
422	Certificate configuration is missing or invalid. Check that the merchant registration has valid certificates associated with it.
503	Apple Pay™ session service is unavailable.

Tokenize

Decrypts an Apple Pay™ token and creates an Apple Pay™ resource.

You can specify the merchant registration to use for a request, ensuring the correct associated keys are selected to decrypt and tokenize the incoming payment data.

POST

https://api.basistheory.com/apple-pay

Permissions

apple-pay:create

Request

cURL
Node
C#
Python

curl --request POST \
--url https://api.basistheory.com/apple-pay \
--header 'BT-API-KEY: <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
  "expires_at": "2030-12-25",
  "apple_payment_data": {
    "paymentData": {
      "data": "...",
      "signature": "...",
      "header": {
        "transactionId": "...",
        "publicKeyHash": "...",
        "applicationData": "...",
        "ephemeralPublicKey": "..."
      },
      "version": "EC_v1"
    },
    "transactionIdentifier": "..."
  },
  "merchant_registration_id": ""
}'

await client.applePay.create();

await client.ApplePay.CreateAsync(new ApplePayCreateRequest());

client.apple_pay.create()

Request Parameters

Attribute	Required	Description
`expires_at`	false	An optional expiration date for the token. If blank, defaults to the expiration date in the decrypted Apple Payment data.
`apple_payment_data`	true	The payment token object from the Apple Pay™ `onpaymentauthorized` event (web) or `PKPaymentToken` (iOS). Only `paymentData` and `transactionIdentifier` are used; other fields such as `paymentMethod` are ignored.
`apple_payment_data.paymentData`	true	The encrypted payment data object. Contains `data`, `signature`, `header`, and `version`.
`apple_payment_data.transactionIdentifier`	true	The unique transaction identifier generated by Apple.
`merchant_registration_id`	false	The unique identifier of the merchant registration created through the Basis Theory Merchant API.

Response

Returns an Apple Pay™ resource wrapped in an apple_pay object. The return will include the Card BIN enrichments according to the tenant settings. The decrypted card number, expiration, and other plaintext data fields are not included in the tokenization response — retrieve them via the Retrieve endpoint with apple-pay:reveal or reference them in proxy expressions.

{
  "apple_pay": {
    "id": "c2995d93-600a-44a2-b6f1-2c25e46603a9",
    "type": "dpan",
    "tenant_id": "...",
    "status": "active",
    "expires_at": "2030-12-15T00:00:00+00:00",
    "created_by": "0a6475a5-4bb8-4165-8c31-7fbc058843bf",
    "created_at": "2025-05-19T16:19:50.9013495+00:00",
    "transaction_id": "4f8a3b2c1d9e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0",
    "payment_data_type": "3DSecure",
    "device_manufacturer_identifier": "040010030273",
    "fingerprint": "7bAjvyqJqfPc4jRjniEk87vNrjR74Xax1HnMREWsTiMz",
    "card": {...},
    "authentication": {
      "threeds_cryptogram": "AAAAAA...",
      "eci_indicator": "07"
    }
  }
}

To compute the fingerprint for Apple Pay™ resources, the system utilizes the card number contained within the encrypted payment token.

Retrieve

GET

https://api.basistheory.com/apple-pay/{:id}

Permissions

apple-pay:read apple-pay:reveal

Request

cURL
Node
C#
Python

curl --request GET \
  --url https://api.basistheory.com/apple-pay/c2995d93-600a-44a2-b6f1-2c25e46603a9 \
  --header 'BT-API-KEY: <API_KEY>'

await client.applePay.get("id");

await client.ApplePay.GetAsync("id");

client.apple_pay.get(
id="id",
)

Response

Returns an Apple Pay™ resource at the top level (unlike the Tokenize response, which is wrapped in an apple_pay object). If the application has apple-pay:reveal, then the data element will contain the unencrypted card information. If the application has apple-pay:read, then the data element will contain masked card information.

{
  "id": "c2995d93-600a-44a2-b6f1-2c25e46603a9",
  "type": "dpan",
  "tenant_id": "0def1587-e30b-44b7-ad3f-484b323a3917",
  "status": "active",
  "expires_at": "2025-12-12T00:00:00+00:00",
  "created_by": "0a6475a5-4bb8-4165-8c31-7fbc058843bf",
  "created_at": "2025-05-19T16:19:50.9013495+00:00",
  "modified_by": "0a6475a5-4bb8-4165-8c31-7fbc058843bf",
  "modified_at": "2025-05-20T10:00:00.0000000+00:00",
  "transaction_id": "4f8a3b2c1d9e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0",
  "payment_data_type": "3DSecure",
  "device_manufacturer_identifier": "040010030273",
  "fingerprint": "7bAjvyqJqfPc4jRjniEk87vNrjR74Xax1HnMREWsTiMz",
  "card": {
    "bin": "42424242",
    "last4": "4242",
    "expiration_month": 6,
    "expiration_year": 2025,
    "brand": "mastercard",
    "funding": "credit",
    "authentication": "sca_required",
    "issuer": {
      "country": "PL",
      "name": "3DS Test Cards (TEST)"
    },
    "issuer_country": {
      "alpha2": "PL",
      "name": "Bermuda",
      "numeric": "369"
    },
    "segment": "Commercial"
  },
  "data": {
    "number": "4242424242424242",
    "expiration_month": 6,
    "expiration_year": 2025
  },
  "authentication": {
    "threeds_cryptogram": "AAAAAA=",
    "eci_indicator": "7"
  }
}

Response Attributes

Attribute	Type	Description
`id`	uuid	Unique identifier for the Apple Pay™ resource.
`type`	string	Type of Apple Pay™ resource. See Token Types.
`tenant_id`	uuid	Identifier for the tenant that owns the resource.
`status`	string	Status of the resource. One of: `active`, `unlinked`.
`expires_at`	string	ISO 8601 date when the resource expires.
`created_by`	uuid	Identifier of the application that created the resource.
`created_at`	string	ISO 8601 date when the resource was created.
`modified_by`	uuid	Identifier of the application that last modified the resource. `null` if never modified.
`modified_at`	string	ISO 8601 date when the resource was last modified. `null` if never modified.
`transaction_id`	string	The transaction identifier from the Apple Pay™ payment token.
`payment_data_type`	string	The payment data type from the decrypted Apple Pay™ token. One of `3DSecure` or `EMV`.
`device_manufacturer_identifier`	string	The device manufacturer identifier from the decrypted Apple Pay™ token.
`fingerprint`	string	A fingerprint derived from the card number in the Apple Pay™ payment token.
`card`	object	Card BIN enrichment data. Populated according to tenant settings.
`data`	object	The decrypted card data. Requires `apple-pay:reveal` for unmasked values; `apple-pay:read` returns masked values.
`authentication`	object	Authentication data from the decrypted Apple Pay™ token, including the 3DS cryptogram and ECI indicator.

Unlink
DEPRECATED

Unlinks an Apple Pay™ mpan token, marking it as unlinked. This operation can only be performed on tokens of type mpan. Unlinked tokens will be scheduled for deletion 30 days after unlinking.

For more information, review the documentation on Apple's site.

POST

https://api.basistheory.com/apple-pay/{:id}/unlink

Permissions

apple-pay:unlink

Request

cURL
Node
C#
Python

curl --request POST \
  --url https://api.basistheory.com/apple-pay/c2995d93-600a-44a2-b6f1-2c25e46603a9/unlink \
  --header 'BT-API-KEY: <API_KEY>'

await client.applePay.unlink("id");

await client.ApplePay.UnlinkAsync("id");

client.apple_pay.unlink(
  id="id",
)

Response

Returns the unlinked Apple Pay™ resource with basic information.

{
 "apple_pay": {
   "id": "c2995d93-600a-44a2-b6f1-2c25e46603a9",
   "type": "mpan",
   "tenant_id": "0def1587-e30b-44b7-ad3f-484b323a3917",
   "status": "unlinked",
   "expires_at": "2025-12-12T00:00:00+00:00"
 }
}

Attribute	Type	Description
apple_pay	Object	The unlinked Apple Pay™ resource
apple_pay.id	string	Unique identifier for the Apple Pay™ resource
apple_pay.type	string	Type of Apple Pay™ resource. Will be `mpan`
apple_pay.tenant_id	string	Identifier for the tenant that owns the resource
apple_pay.status	string	Status of the resource. Will be 'unlinked'
apple_pay.expires_at	string	ISO 8601 formatted date when the resource expires

Errors

Status Code	Description
401	Unauthorized - check API key permissions
403	Forbidden - insufficient permissions to perform this action
422	Token not found or token is not of type `mpan`
503	Unable to unlink token - please contact support

Delete

Deletes an existing Apple Pay™ resource. If the token type is mpan, the resource is additionally unlinked and marked as unlinked. In cases where the unlink operation fails, the resource will still be deleted.

For more information, review the documentation on Apple's site.

DELETE

https://api.basistheory.com/apple-pay/{:id}

Permissions

apple-pay:delete

Request

cURL
Node
C#
Python

curl --request DELETE \
--url https://api.basistheory.com/apple-pay/c2995d93-600a-44a2-b6f1-2c25e46603a9 \
--header 'BT-API-KEY: <API_KEY>'

await client.applePay.delete("id");

await client.ApplePay.DeleteAsync("id");

client.apple_pay.delete(
id="id",
)

Response

Returns the deleted Apple Pay™ resource with basic information.

{
 "apple_pay": {
   "id": "c2995d93-600a-44a2-b6f1-2c25e46603a9",
   "type": "mpan",
   "tenant_id": "0def1587-e30b-44b7-ad3f-484b323a3917",
   "status": "unlinked",
   "expires_at": "2025-12-12T00:00:00+00:00"
 }
}

Attribute	Type	Description
apple_pay	Object	The deleted Apple Pay™ resource
apple_pay.id	string	Unique identifier for the Apple Pay™ resource
apple_pay.type	string	Type of Apple Pay™ resource.
apple_pay.tenant_id	string	Identifier for the tenant that owns the resource
apple_pay.status	string	Status of the resource. Will be 'unlinked'
apple_pay.expires_at	string	ISO 8601 formatted date when the resource expires

Errors

Status Code	Description
401	Unauthorized - check API key permissions
403	Forbidden - insufficient permissions to perform this action
404	Token not found
503	Unable to unlink resource - please contact support

Apple Pay™ Merchant Registration

Basis Theory now supports Apple Pay™ using your own merchant identifiers and certificates, giving you full ownership and control over your Apple Pay™ configuration. This replaces the previous model where Apple Pay™ domains, merchant IDs, and certificates were managed and shared through Basis Theory.

With merchant-owned credentials, you manage your Apple Pay™ setup directly with Apple, while Basis Theory securely stores and uses your encrypted certificates to tokenize Apple Pay™ payment data.

Overview

Apple Pay™ requires:

A merchant identifier registered with Apple
Merchant and payment processor certificates
Domain verification for each website using Apple Pay™

Under this new model, all of these are owned and managed by the merchant, not Basis Theory. Basis Theory’s role is to:

Securely store encrypted certificate material
Select the correct merchant and certificate set at runtime
Decrypt and tokenize Apple Pay™ payment data

Merchant-Owned Apple Pay™ Configuration

Basis Theory now supports Apple Pay™ using your own merchant identifiers and certificates. This gives you direct control over your Apple Pay™ configuration while maintaining the same tokenization and API experience.

With the merchant-owned model:

Domains are verified under your own Apple Pay™ merchant ID
Merchant certificates are generated, rotated, and managed by you
Apple API calls use your merchant identifier instead of a shared tenant identifier

This model is ideal for merchants that require full ownership of their Apple Pay™ credentials or need to align with internal security, compliance, or certificate-rotation policies.

Prerequisites

Before using this API, ensure you have completed the following with Apple:

Created an Apple Pay™ merchant identifier
Verified your domain(s) with Apple
Generated:
- A Merchant Identity Certificate
- A Payment Processing Certificate
- Exported both certificates as password-protected P12 files Refer to Apple’s official documentation for details:
Merchant ID creation
Domain verification
Certificate generation and rotation

A merchant represents your Apple Pay™ merchant identifier and serves as the root configuration for certificates and tokenization.

Create Merchant Registration

Registers a resource representing an Apple Pay™ merchant.

POST

https://api.basistheory.com/apple-pay/merchant-registration

Permissions

apple-pay:manage

Request

cURL
Node
C#
Python

curl --request POST \
--url https://api.basistheory.com/apple-pay/merchant-registration \
--header 'BT-API-KEY: <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
  "merchant_identifier": "..."
}'

await client.applePay.merchant.create();

await client.ApplePay.Merchant.CreateAsync(new ApplePayMerchantRegisterRequest());

client.apple_pay.merchant.create()

Request Parameters

Attribute	Required	Description
`merchant_identifier`	true	The merchant identifier as registered with the Apple Pay™ API. For example `merchant.com.reversed.domain`.

Response

Returns a Apple Pay™ Merchant registration with the registered merchant_identifier. Returns an error if there were validation errors, or the resource failed to create.

{
  "id": "b7248b11-acfb-3949-93a9-9609f90ec038",
  "tenant_id": "893e4980-8732-4166-934c-6217476e3391",
  "merchant_identifier": "merchant.com.yourcompany.app",
  "created_by": "50c63e9b-91e5-4a6a-9f9e-81088d106f2c",
  "created_at": "2025-08-06T11:02:53.9261435+00:00"
}

Retrieve Merchant Registration

Retrieves an Apple Pay™ merchant registration and its associated metadata.

GET

https://api.basistheory.com/apple-pay/merchant-registration/{:id}

Permissions

apple-pay:manage

Request

cURL
Node
C#
Python

curl --request GET \
--url https://api.basistheory.com/apple-pay/merchant-registration/3c367ed4-678d-4b98-9cec-d7eaa0f0c26e \
--header 'BT-API-KEY: <API_KEY>'

await client.applePay.merchant.get("id");

await client.ApplePay.Merchant.GetAsync("id");

client.apple_pay.merchant.get(
id="id",
)

Response

Returns an Apple Pay™ Merchant registration.

{
  "id": "b7248b11-acfb-3949-93a9-9609f90ec038",
  "tenant_id": "893e4980-8732-4166-934c-6217476e3391",
  "merchant_identifier": "merchant.com.mycompany.shop",
  "created_by": "50c63e9b-91e5-4a6a-9f9e-81088d106f2c",
  "created_at": "2025-08-06T11:02:53.9261435+00:00"
}

Delete Merchant Registration

Deletes an existing Apple Pay™ merchant registration and its associated configuration.

DELETE

https://api.basistheory.com/apple-pay/merchant-registration/{:id}

Permissions

apple-pay:manage

Request

cURL
Node
C#
Python

curl --request DELETE \
--url https://api.basistheory.com/apple-pay/merchant-registration/3c367ed4-678d-4b98-9cec-d7eaa0f0c26e \
--header 'BT-API-KEY: <API_KEY>'

await client.applePay.merchant.delete("id");

await client.ApplePay.Merchant.DeleteAsync("id");

client.apple_pay.merchant.delete(
id="id",
)

Response

Returns a Apple Pay™ Merchant registration with summarized information.

{
  "id": "b7248b11-acfb-3949-93a9-9609f90ec038",
  "tenant_id": "893e4980-8732-4166-934c-6217476e3391",
  "merchant_identifier": "merchant.com.mycompany.shop",
  "created_by": "50c63e9b-91e5-4a6a-9f9e-81088d106f2c",
  "created_at": "2025-08-06T11:02:53.9261435+00:00"
}

Apple Pay™ Merchant Certificates

Once a merchant is registered, merchant-owned encryption certificates can be associated with it and will be used to decrypt and tokenize Apple Pay™ payment data during tokenization requests.

Create Merchant Certificates

Registers a new merchant encryption certificate that will be used to decrypt and tokenize Apple Pay™ payment data.

POST

https://api.basistheory.com/apple-pay/merchant-registration/{:id}/certificates

Permissions

apple-pay:manage

Request

cURL
Node
C#
Python

curl --request POST \
--url https://api.basistheory.com/apple-pay/merchant-registration/3c367ed4-678d-4b98-9cec-d7eaa0f0c26e/certificates \
--header 'BT-API-KEY: <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
  "merchant_certificate_data": "MIIJVQIBAzCCCR8GCSqGSIb3...",
  "merchant_certificate_password": "identity_cert_password",
  "payment_processor_certificate_data": "MIIJVQIBAzCCCR8GCSqGSIb3...",
  "payment_processor_certificate_password": "processing_cert_password",
  "domain": "shop.mycompany.com"
}'

await client.applePay.merchant.certificates.create("merchantId", request: ApplePayMerchantCertificatesRegisterRequest = {})

await client.ApplePay.Merchant.Certificates.CreateAsync("merchantId",
new ApplePayMerchantCertificatesRegisterRequest()
);

client.client.apple_pay.merchant.certificates.create(
merchant_id="merchantId",
merchant_certificate_data="",
merchant_certificate_password="",
payment_processor_certificate_data=""
)

Request Parameters

Attribute	Required	Description
`payment_processor_certificate_data`	true	A base64-encoded, password-protected `P12` file containing the Apple Pay Payment Processing Certificate and its private key. Used by Basis Theory to decrypt payment tokens for both web and iOS integrations.
`payment_processor_certificate_password`	true	The password used to decrypt `payment_processor_certificate_data`.
`merchant_certificate_data`	false	A base64-encoded, password-protected `P12` file containing the Apple Pay Merchant Identity Certificate and its private key. Used for mutual TLS authentication during merchant session creation with Apple's servers. Required for web integrations; omit for iOS-only.
`merchant_certificate_password`	false	The password used to decrypt `merchant_certificate_data`. Required when `merchant_certificate_data` is provided.
`domain`	false	The domain verified with Apple that this Merchant Identity Certificate is associated with. Required when `merchant_certificate_data` is provided.

merchant_certificate_data, merchant_certificate_password, and domain are only required for web integrations. They enable merchant session creation, which Apple Pay on the Web requires before a payment can be authorized. iOS integrations do not use merchant sessions — omit all three fields when registering certificates for an iOS-only integration.

Response

Retrieves a resource representing a registered Apple Pay™ merchant encryption certificate. Returns an error if there were validation errors, if the certificate failed to decrypt, validate against Apple Pay™ API or the certificate failed to create.

{
  "id": "b7248b11-acfb-3949-93a9-9609f90ec038",
  "tenant_id": "893e4980-8732-4166-934c-6217476e3391",
  "merchant_identifier": "merchant.com.mycompany.shop",
  "merchant_certificate_expiration_date": "2029-08-06T11:02:53.9261435+00:00",
  "merchant_certificate_fingerprint": "a1:b2:c3:d4:e5:f6:78:90:ab:cd:ef:12:34:56:78:90:12:34:56:78",
  "payment_processor_certificate_expiration_date": "2029-08-06T11:02:53.9261435+00:00",
  "payment_processor_certificate_fingerprint": "f1:e2:d3:c4:b5:a6:97:88:77:66:55:44:33:22:11:00:aa:bb:cc:dd",
  "created_by": "50c63e9b-91e5-4a6a-9f9e-81088d106f2c",
  "created_at": "2025-08-06T11:02:53.9261435+00:00",
  "domain": "shop.mycompany.com"
}

There is a limitation of two active certificates per merchant at any given time.

Retrieve Merchant Certificates

Retrieves an already registered Apple Pay™ merchant encryption certificate.

GET

https://api.basistheory.com/apple-pay/merchant-registration/{:merchantId}/certificates/{:id}

Permissions

apple-pay:manage

Request

cURL
Node
C#
Python

curl --request GET \
--url https://api.basistheory.com/apple-pay/merchant-registration/3c367ed4-678d-4b98-9cec-d7eaa0f0c26e/certificates/343067ed4-678d-4b98-9cec-d7eaa0f0c26e \
--header 'BT-API-KEY: <API_KEY>'

await client.applePay.merchant.certificates.get("merchantId", "id")

await client.ApplePay.Merchant.Certificates.GetAsync("merchantId", "id");

client.apple_pay.merchant.certificates.get(
merchant_id="merchantId",
id="id",
)

Response

Returns a Apple Pay™ merchant encryption certificate.

{
  "id": "b7248b11-acfb-3949-93a9-9609f90ec038",
  "tenant_id": "893e4980-8732-4166-934c-6217476e3391",
  "merchant_identifier": "merchant.com.mycompany.shop",
  "merchant_certificate_expiration_date": "2029-08-06T11:02:53.9261435+00:00",
  "merchant_certificate_fingerprint": "a1:b2:c3:d4:e5:f6:78:90:ab:cd:ef:12:34:56:78:90:12:34:56:78",
  "payment_processor_certificate_expiration_date": "2029-08-06T11:02:53.9261435+00:00",
  "payment_processor_certificate_fingerprint": "f1:e2:d3:c4:b5:a6:97:88:77:66:55:44:33:22:11:00:aa:bb:cc:dd",
  "created_by": "50c63e9b-91e5-4a6a-9f9e-81088d106f2c",
  "created_at": "2025-08-06T11:02:53.9261435+00:00",
  "domain": "shop.mycompany.com"
}

Delete Merchant Certificates

Deletes an existing Apple Pay™ merchant encryption certificate and its associated configuration.

DELETE

https://api.basistheory.com/apple-pay/merchant-registration/{:merchantId}/certificates/{:id}

Permissions

apple-pay:manage

Request

cURL
Node
C#
Python

curl --request DELETE \
--url https://api.basistheory.com/apple-pay/merchant-registration/3c367ed4-678d-4b98-9cec-d7eaa0f0c26e/certificates/343067ed4-678d-4b98-9cec-d7eaa0f0c26e \
--header 'BT-API-KEY: <API_KEY>'

await client.applePay.merchant.certificates.delete("merchantId", "id")

await client.ApplePay.Merchant.Certificates.DeleteAsync("merchantId", "id");

client.apple_pay.merchant.certificates.delete(
merchant_id="merchantId",
id="id",
)

Response

Returns a Apple Pay™ merchant encryption certificate with summarized information.

{
  "id": "b7248b11-acfb-3949-93a9-9609f90ec038",
  "tenant_id": "893e4980-8732-4166-934c-6217476e3391",
  "merchant_identifier": "merchant.com.mycompany.shop",
  "merchant_certificate_expiration_date": "2029-08-06T11:02:53.9261435+00:00",
  "merchant_certificate_fingerprint": "a1:b2:c3:d4:e5:f6:78:90:ab:cd:ef:12:34:56:78:90:12:34:56:78",
  "payment_processor_certificate_expiration_date": "2029-08-06T11:02:53.9261435+00:00",
  "payment_processor_certificate_fingerprint": "f1:e2:d3:c4:b5:a6:97:88:77:66:55:44:33:22:11:00:aa:bb:cc:dd",
  "created_by": "50c63e9b-91e5-4a6a-9f9e-81088d106f2c",
  "created_at": "2025-08-06T11:02:53.9261435+00:00",
  "domain": "shop.mycompany.com"
}

Testing without an Apple Pay™ token

Basis Theory provides a mechanism to create fake Apple Pay™ resources using the create endpoint for testing purposes. Changing the version to "BasisTheory" within the apple_payment_data payload body will instead process a fake Apple payment token in a different manner.

The data field within paymentData should contain decrypted data referencing a card. Use applicationPrimaryAccountNumber for the card number and applicationExpirationDate for the expiration date.

Testing with Apple Pay™ Sandbox

For end-to-end testing with real Apple Pay™ tokens, TEST tenants receive the actual decrypted payload — including the sandbox DPAN, expiration date, cryptogram, and ECI indicator. This lets you verify your integration against your payment processor's sandbox using realistic card data.

To set up sandbox testing:

Sign in with a Sandbox Apple ID on a test device.
Add one of Apple's sandbox test cards to Wallet. See Apple's Sandbox Testing page for the full list of available test cards.
Trigger an Apple Pay™ payment in your application. The device returns a real EC_v1-encrypted payment token containing a sandbox DPAN.
Send the token to Basis Theory using your TEST tenant API key. Basis Theory decrypts it with your stored Payment Processing Certificate and returns the sandbox card data.
Forward the result to your processor's sandbox to verify the end-to-end flow.

Only use Apple's sandbox test cards in TEST environments. Sending a live Apple Pay™ token to a TEST tenant is your responsibility — Basis Theory does not validate whether the token originates from a sandbox device.

{
  "apple_payment_data": {
    "paymentData": {
      "data": "{\"applicationPrimaryAccountNumber\":\"4242424242424242\",\"applicationExpirationDate\":\"300930\",\"currencyCode\":\"840\",\"transactionAmount\":1,\"cardholderName\":\"Maggie Lin\",\"deviceManufacturerIdentifier\":\"040010030273\",\"merchantTokenIdentifier\":\"{{merchantTokenIdentifier}}\",\"paymentDataType\":\"3DSecure\",\"paymentData\":{\"onlinePaymentCryptogram\":\"AeEWvBoAFhtv7IX....\",\"eciIndicator\":\"7\"}}",
      "signature": "MIAGCSqGS...",
      "header": {
        "transactionId": "a57f68...",
        "publicKeyHash": "1bDMpis1k...",
        "applicationData": "e7e8920...",
        "ephemeralPublicKey": "MFkwEwY..."
      },
      "version": "BasisTheory"
    },
    "paymentMethod": {
      "displayName": "Visa 4242",
      "network": "Visa",
      "type": "credit"
    },
    "transactionIdentifier": "13jNasniq2..."
  }
}

Token Types​

Register Domain Address​

Prerequisite​

Permissions​

Request​

Response​

Errors​

Register All Domain Addresses​

Permissions​

Request​

Response​

Errors​

Get Domain Registrations​

Permissions​

Request​

Response​

Deregister Domain​

Permissions​

Request​

Response​

Create Merchant Session​

Permissions​

Request​

Request Parameters​

Response​

Errors​

Tokenize​

Permissions​

Request​

Request Parameters​

Response​

Retrieve​

Permissions​

Request​

Response​

Response Attributes​

Unlink DEPRECATED​

Permissions​

Request​

Response​

Errors​

Delete​

Permissions​

Request​

Response​

Errors​

Apple Pay™ Merchant Registration​

Overview​

Merchant-Owned Apple Pay™ Configuration​

Prerequisites​

Create Merchant Registration​

Permissions​

Request​

Request Parameters​

Response​

Retrieve Merchant Registration​

Permissions​

Request​

Response​

Delete Merchant Registration​

Permissions​

Request​

Response​

Apple Pay™ Merchant Certificates​

Create Merchant Certificates​

Permissions​

Request​

Request Parameters​

Response​

Retrieve Merchant Certificates​

Permissions​

Request​

Response​

Delete Merchant Certificates​

Permissions​

Request​

Response​

Testing without an Apple Pay™ token​

Testing with Apple Pay™ Sandbox​

Token Types

Register Domain Address

Prerequisite

Permissions

Request

Response

Errors

Register All Domain Addresses

Permissions

Request

Response

Errors

Get Domain Registrations

Permissions

Request

Response

Deregister Domain

Permissions

Request

Response

Create Merchant Session

Permissions

Request

Request Parameters

Response

Errors

Tokenize

Permissions

Request

Request Parameters

Response

Retrieve

Permissions

Request

Response

Response Attributes

Unlink
DEPRECATED

Permissions

Request

Response

Errors

Delete

Permissions

Request

Response

Errors

Apple Pay™ Merchant Registration

Overview

Merchant-Owned Apple Pay™ Configuration

Prerequisites

Create Merchant Registration

Permissions

Request

Request Parameters

Response

Retrieve Merchant Registration

Permissions

Request

Response

Delete Merchant Registration

Permissions

Request

Response

Apple Pay™ Merchant Certificates

Create Merchant Certificates

Permissions

Request

Request Parameters

Response

Retrieve Merchant Certificates

Permissions

Request

Response

Delete Merchant Certificates

Permissions

Request

Response

Testing without an Apple Pay™ token

Testing with Apple Pay™ Sandbox