CreateInstrumentRequest

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

Show child attributes

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

Show child attributes

future_usage

Unscheduled recurring card-on-file transaction

Allowed value: "unscheduled_card_on_file"

Example:

"unscheduled_card_on_file"

{ "holder_id": "holder_123456789", "payment_method": "card", "holder_type": "CUSTOMER", "business_account_id": "3f9a1c72-8d4e-4f61-9b2a-5c7e0d8a1b34", "on_behalf_of": "7c2e5b91-6a3f-4d82-9e14-2b6d0f3a8c57", "data": "<string>", "agreement": { "reference": "custom-reference", "initial_transaction_reference": "transaction-reference-xxx" }, "future_usage": "unscheduled_card_on_file" }

Account Settlement

Payment Acceptance

Tokenization