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.

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 Session

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

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 token.

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

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 token. If the application has apple-pay:reveal, then the data element will contain the unencrypted card information. If the application has apple-pay:reveal, 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",
  "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"
  }
}

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

Permissions​

Request​

Request Parameters​

Response​

Tokenize​

Permissions​

Request​

Request Parameters​

Response​

Retrieve​

Permissions​

Request​

Response​

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 Session

Permissions

Request

Request Parameters

Response

Tokenize

Permissions

Request

Request Parameters

Response

Retrieve

Permissions

Request

Response