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.

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"
    },
    "paymentMethod": {
      "displayName": "...",
      "network": "...",
      "type": "..."
    },
    "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 Apple Pay™ token from the `onpaymentauthorized` event.
`merchant_registration_id`	false	The unique identifier of the merchant registration created through the Basis Theory Merchant API.

Response

Returns an Apple Pay™ resource. The return will include the Card BIN enrichments according to the tenant settings.

{
  "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",
    "fingerprint": "7bAjvyqJqfPc4jRjniEk87vNrjR74Xax1HnMREWsTiMz",
    "card": {...}
  }
}

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. 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",
  "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"
  }
}

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
`merchant_certificate_data`	true	A base64-encoded, encrypted `P12` file containing both the certificate and the private key used to encrypt payment data for the merchant.
`merchant_certificate_password`	true	The password used to decrypt the `merchant_certificate_data`. `AES-256-CBC` with `PBKDF2` is used to decrypt the certificate data.
`payment_processor_certificate_data`	true	A base64 encoded `P12` file with encryption. This `P12` file should contain both the cert and the private key used for identifying the payment processor. Will use `AES-256-CBC` with `PBKDF2` to decrypt the certificate data.
`payment_processor_certificate_password`	true	The password used to decrypt the `payment_processor_certificate_data`.
`domain`	true	The domain associated to the certificates

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 bin 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​

Tokenize​

Permissions​

Request​

Request Parameters​

Response​

Retrieve​

Permissions​

Request​

Response​

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

Tokenize

Permissions

Request

Request Parameters

Response

Retrieve

Permissions

Request

Response

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