API Reference / Endpoints

Elements

EPD Elements is the browser card-capture layer behind the epd.js browser SDK. These endpoints are authenticated with a publishable key and called by the SDK in the shopper's browser; you normally never call them directly.

The SDK boots from GET /elements/config, captures the card in a secure field, and exchanges it for a single-use card_token (cct_…) via POST /elements/tokens. Your backend then attaches that token to a customer with Add Payment Method using your secret key. Raw card data never touches your servers.

GET /elements/config

Get Elements bootstrap config

Returns the public config the EPD Elements SDK needs to mount its secure card field: tenant identity, mode, and the public field key. Authenticated with a publishable key.

You normally do not call this directly; the SDK does it on EPD(publishableKey).

Responses

200 Bootstrap config.
FieldTypeDescription
tenant_idrequired
string
Identifies the merchant the publishable key belongs to. The SDK stamps it on the captured card so the card can only be vaulted for this merchant.
e.g. "550e8400-e29b-41d4-a716-446655440000"
sandboxrequired
boolean
Whether the key is a test key (`epd_test_pk_`).
e.g. true
token_metadata_keyrequired
string
The field name under which the SDK records the merchant on the captured card. Used internally by the SDK.
e.g. "epd_connection_id"
runtime_public_keyrequired
string
Public key the SDK initialises the secure card field with. Public by design; rotate from the EPD side without a client change.
e.g. "key_prod_xxx"
401 Unauthorized. Authentication failed.
FieldTypeDescription
errorrequired
object
typerequired
enum
The type of error.
invalid_request_errorauthentication_errorauthorization_errorrate_limit_erroridempotency_errorprocessing_errorwebhook_error
coderequired
string
A short string identifying the specific error.
e.g. "validation_error"
messagerequired
string
A human-readable message providing details about the error.
e.g. "Request validation failed"
paramnullable
string
The parameter that caused the error, if applicable.
e.g. "email"
request_id
string
Unique request identifier for debugging.
e.g. "req_a1b2c3d4e5f67890abcdef0123456789"
field_errors
array[object]
Detailed field-level errors for validation failures.
POST /elements/tokens

Create a card-capture token

Exchanges a tokenized card from the secure field for an opaque, single-use card_token (cct_…) bound to the merchant. Authenticated with a publishable key.

The EPD Elements SDK calls this for you and returns the card_token. Send that token to Add Payment Method from your backend with your secret key.

A per-IP rate limit applies in addition to the per-merchant limit.

Request body required

FieldTypeDescription
runtime_tokenrequired
string
Token id produced by the secure card field, exchanged for an opaque `card_token`. The SDK supplies this for you.
e.g. "9f8c1b2a-3d4e-5f60-7182-93a4b5c6d7e8"

Responses

201 Card-capture token created.
FieldTypeDescription
card_tokenrequired
string
e.g. "cct_3f8a1c9e7b2d4a6f0e1c3b5d7f9a1c3e5b7d9f0a2c4e6b8d"
expires_inrequired
integer
Seconds until the token expires.
e.g. 900
400 Bad Request. The request was invalid or cannot be served.
FieldTypeDescription
errorrequired
object
typerequired
enum
The type of error.
invalid_request_errorauthentication_errorauthorization_errorrate_limit_erroridempotency_errorprocessing_errorwebhook_error
coderequired
string
A short string identifying the specific error.
e.g. "validation_error"
messagerequired
string
A human-readable message providing details about the error.
e.g. "Request validation failed"
paramnullable
string
The parameter that caused the error, if applicable.
e.g. "email"
request_id
string
Unique request identifier for debugging.
e.g. "req_a1b2c3d4e5f67890abcdef0123456789"
field_errors
array[object]
Detailed field-level errors for validation failures.
401 Unauthorized. Authentication failed.
FieldTypeDescription
errorrequired
object
typerequired
enum
The type of error.
invalid_request_errorauthentication_errorauthorization_errorrate_limit_erroridempotency_errorprocessing_errorwebhook_error
coderequired
string
A short string identifying the specific error.
e.g. "validation_error"
messagerequired
string
A human-readable message providing details about the error.
e.g. "Request validation failed"
paramnullable
string
The parameter that caused the error, if applicable.
e.g. "email"
request_id
string
Unique request identifier for debugging.
e.g. "req_a1b2c3d4e5f67890abcdef0123456789"
field_errors
array[object]
Detailed field-level errors for validation failures.
429 Too Many Requests. Rate limit exceeded.
FieldTypeDescription
errorrequired
object
typerequired
enum
The type of error.
invalid_request_errorauthentication_errorauthorization_errorrate_limit_erroridempotency_errorprocessing_errorwebhook_error
coderequired
string
A short string identifying the specific error.
e.g. "validation_error"
messagerequired
string
A human-readable message providing details about the error.
e.g. "Request validation failed"
paramnullable
string
The parameter that caused the error, if applicable.
e.g. "email"
request_id
string
Unique request identifier for debugging.
e.g. "req_a1b2c3d4e5f67890abcdef0123456789"
field_errors
array[object]
Detailed field-level errors for validation failures.