Skip to main content
POST

Authorizations

​
x-api-key
string
header
required

API key for service-to-service or merchant authentication.

Headers

​
x-correlation-id
string<uuid>

Unique identifier for request tracing. Generated by the client or server if not provided.

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
x-idempotency-key
string<uuid>

Unique key for idempotent request processing. Duplicate requests with the same key are safely ignored.

Example:

"baf6a8e2-0c89-46ef-9ca5-faa65b99bcd5"

Body

application/json

Instrument creation data

Request body for creating a new payment instrument

​
holder_id
string
required

Holder ID (customer or beneficiary)

Example:

"holder_123456789"

​
payment_method
required

Credit or debit card

Allowed value: "card"
Example:

"card"

​
holder_type
required

End customer

Allowed value: "CUSTOMER"
Example:

"CUSTOMER"

​
business_account_id
string<uuid>

Business account that owns this instrument. Used only when the request carries no x-merchant-id header — that header always wins — and only where hierarchy targeting is enabled for the environment.

Example:

"3f9a1c72-8d4e-4f61-9b2a-5c7e0d8a1b34"

​
on_behalf_of
string<uuid>

Business account this instrument is created on behalf of. When set, the instrument is owned by this account and the authenticated business_account_id is recorded as the acting account. Ignored when the legacy x-merchant-id header is supplied.

Example:

"7c2e5b91-6a3f-4d82-9e14-2b6d0f3a8c57"

​
pan_data
object

PAN (Primary Account Number) data for card tokenization

​
data
string

encrypted instrument data (e.g., encrypted JWE for Card, ApplePay token, GooglePay token, ... etc.)

​
agreement
object

Card-on-file agreement details for recurring or unscheduled transactions

​
future_usage

Unscheduled recurring card-on-file transaction

Allowed value: "unscheduled_card_on_file"
Example:

"unscheduled_card_on_file"

Response

Instrument created successfully.

Response returned after creating a new instrument

​
id
string<uuid>
required

Unique instrument identifier

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
created_at
string<date-time>
required

Timestamp when the instrument was created

Example:

"2024-01-01T00:00:00.000Z"

​
merchant_id
string
required

Merchant that owns the instrument

Example:

"merch_123456789"

​
holder_id
string
required

Holder ID associated with the instrument

Example:

"holder_123456789"

​
payment_method
required

Credit or debit card

Allowed value: "card"
Example:

"card"

​
holder_type
required

End customer

Allowed value: "CUSTOMER"
Example:

"CUSTOMER"

​
future_usage

Stored for future merchant-initiated use without a fixed schedule

Allowed value: "unscheduled_card_on_file"
Example:

"unscheduled_card_on_file"