Payment instruments
A payment instrument is a destination that can receive funds — a bank account, a digital wallet, an on-chain crypto wallet, a real-time-payment alias, or a card. Instruments appear in the Merchant API in two places:
- On the way in — when you create a transfer, you describe the destination in
payment_method.details. - On the way out — a
TransferViewreturns the resolved destination as itspayment_instrumentobject.
A payout has no instrument fields of its own: it reuses the instrument of the original payment you reference, so you never re-supply account details for a payout.
Instrument types
The type field selects the instrument kind and determines which fields are populated. Values are
lowercase on the wire.
type | Destination |
|---|---|
bank_account | A bank account (IBAN or account number + routing details). |
wallet | A digital wallet such as Skrill, PayPal, or GCash. Addressed by holder_email / holder_phone. |
crypto_wallet | An on-chain wallet address. |
real_time_payment | A real-time-payment alias (e.g. a Pix key, phone, PayID, or VPA). |
card | A tokenized destination card. |
Common fields
Every instrument, whatever its type, may carry these:
| Field | Type | Description |
|---|---|---|
id | string | The stored instrument identifier (pi_...), on returned instruments. |
type | string | One of the values above. |
country_code | string | ISO 3166-1 alpha-2 country code. |
holder_name | string | Full name of the account/instrument holder. |
holder_email | string | Holder email. |
holder_phone | string | Holder phone (also the recipient address for digital wallets). |
document_id | string | Holder tax/identity document number, where the rail requires it. |
Fields by type
Beyond the common fields, each type adds its own. When creating a transfer these go inside
payment_method.details; on a returned payment_instrument they appear at the top level. Which
fields are required depends on the payment method, country, and provider.
bank_account
| Field | Type | Description |
|---|---|---|
iban | string | Account IBAN. |
account_number | string | Account number, where IBAN is not used. |
bic_swift | string | BIC / SWIFT code. |
bank_code | string | National bank/sort code. |
branch_code | string | Branch code, where applicable. |
bank_name | string | Name of the bank. |
account_type | string | e.g. checking or savings. |
wallet
No exclusive fields — the recipient is identified by the common holder_email / holder_phone.
Which wallet it is comes from the transfer's payment_method.code.
crypto_wallet
| Field | Type | Description |
|---|---|---|
wallet_address | string | The on-chain destination address. |
real_time_payment
| Field | Type | Description |
|---|---|---|
account_reference | string | The RTP alias — a Pix key, phone number, PayID, or VPA. |
card
| Field | Type | Description |
|---|---|---|
card_token | string | Tokenized destination card reference. Required for a card destination. |
card_brand | string | Card brand, e.g. visa. |
card_exp_month | integer | Expiry month. |
card_exp_year | integer | Expiry year. |
last4_digits | string | Last four digits of the card number. |
Request-side details
When you create a transfer, payment_method.details accepts the union of the fields above plus a few
holder attributes some rails require — first_name, middle_name, last_name, date_of_birth,
bank_address, and holder_address. Supply only what the destination needs; unused fields are
ignored. See the PaymentMethodDetails schema for the full list.
Next steps
- Transfers — create a transfer to one of these instruments.
- The full API Reference for the
PaymentInstrumentmodel.