Apple Pay™

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.

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"
}'

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.

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.

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": "..."
  }
}'

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.

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

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.

{
  "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 6969",
      "network": "Visa",
      "type": "credit"
    },
    "transactionIdentifier": "13jNasniq2..."
  }
}

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​

Testing without an Apple Pay token​

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

Testing without an Apple Pay token