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/connections/apple-pay/domain-registration

Permissions

tenant:update

Request

cURL
Node
C#
Python

curl --request POST \
  --url https://api.basistheory.com/connections/apple-pay/domain-registration \
  --header 'BT-API-KEY: <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "domain": "<YOUR_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

POST

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

Permissions

tenant:update

Request

cURL
Node
C#
Python
Terraform

curl --request PUT \
  --url https://api.basistheory.com/connections/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/connections/apple-pay/domain-registration

Permissions

tenant:read

Request

cURL
Node
C#
Python

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

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/connections/apple-pay/domain-deregistration

Permissions

tenant:update

Request

cURL
Node
C#
Python

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

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/connections/apple-pay/session

Permissions

token-intent:create

Request

cURL
Node
C#
Python

curl --request POST \
  --url https://api.flock-dev.com/connections/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"
}'

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 a Token Intent.

POST

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

Permissions

token-intent:create

Request

cURL
Node
C#
Python

curl --request POST \
  --url https://api.basistheory.com/connections/apple-pay/tokenize \
  --header 'BT-API-KEY: <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "apple_payment_method_token": {
    "paymentData": {
      "data": "...",
      "signature": "...",
      "header": {
        "transactionId": "...",
        "publicKeyHash": "...",
        "applicationData": "...",
        "ephemeralPublicKey": "..."
      },
      "version": "EC_v1"
    },
    "paymentMethod": {
      "displayName": "...",
      "network": "...",
      "type": "..."
    },
    "transactionIdentifier": "..."
  }
}'

Request Parameters

Attribute	Required	Description
`apple_payment_method_token`	true	The Apple Pay token from the `onpaymentauthorized` event.

Response

Returns a Token Intent if successful. Returns an error if there were validation errors, if the Apple payment token failed to decrypt create, or the Token Intent failed to create.

{
  "token_intent": {
    "id": "78f0fc3e-cebb-4e93-8609-d81594ce1fb0",
    "type": "network_token",
    "tenant_id": "9492840c-1308-4f5a-bb03-af66b83a04f9",
    "fingerprint": "7bAjvyqJqfPc4jRjniEk87vNrjR74Xax1HnMREWsTiMz",
    "created_by": "00ea333f-2fd7-4da2-b5fe-ec86316db024",
    "created_at": "2025-03-05T20:58:59.8718437+00:00",
    "expires_at": "2025-03-06T20:58:59.8718437+00:00",
    "network_token": {
      "bin": "411111",
      "last4": "1111",
      "expiration_month": 12,
      "expiration_year": 2027,
      "brand": "visa",
      "funding": "credit",
      "issuer_country": {
        "alpha2": "US",
        "name": "UNITED STATES OF AMERICA",
        "numeric": "840"
      }
    },
    "authentication": {
      "threeds_cryptogram": "AcbNS...",
      "eci_indicator": "7"
    },
    "_extras": {
      "tsp_details": {
        "tsp": "Apple",
        "eci_indicator": "7",
        "transaction_id": "abb87500d95157439c689e876c229cb9dfaf0c71737f4ac09f6703018c78519a",
        "currency_code": "840",
        "transaction_amount": 1,
        "device_manufacturer_identifier": "040010030273",
        "payment_data_type": "3DSecure"
      }
    }
  }
}

Token Intents and the resulting tokens created from an Apple payment token will contain a tsp_details object in the _extras attribute.

The attributes in the _extras object are NOT addressable in proxies or reactors.

Attribute	Type	Description
`_extras`	Object	Parent object containing additional details.
`tsp_details`	Object	Details related to the transaction service provider (TSP).
`tsp_details.tsp`	String	The name of the transaction service provider.
`tsp_details.transaction_id`	String	Transaction identifier, generated on the device
`tsp_details.currency_code`	String	ISO 4217 numeric currency code, as a string to preserve leading zeros
`tsp_details.transaction_amount`	String	Transaction amount
`tsp_details.cardholder_name`	String	Optional. Cardholder name.
`tsp_details.device_manufacturer_identifier`	String	Hex-encoded device manufacturer identifier
`tsp_details.payment_data_type`	String	Either `3DSecure` or `EMV`
`tsp_details.merchant_token_identifier`	String	For a merchant token request, the provisioned merchant token identifier from the payment network
`tsp_details.authentication_responses[].merchant_identifier`	String	The submerchant identifier as provided by the coordinator merchant
`tsp_details.authentication_responses[].authentication_data`	String	Payment network-generated cryptogram for the submerchant
`tsp_details.authentication_responses[].transaction_amount`	String	The authorized amount for a given submerchant

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​

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