Payment instruments

A payment instrument is a stored account or card that money moves to or from - 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 three places:

• On the way in - when you create a transfer, you describe the destination in payment_method.details.
• On the way out - a TransferView returns the resolved destination as its payment_instrument object.
• On transactions, orders and webhooks - the same payment_instrument object reports the card a payment ran on, or the destination of a transfer. See Instruments on transactions, orders and webhooks.

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.
holder_address	object	Holder postal address (line1, line2, city, state, postal_code, country), when one was supplied.

Fields without a value are omitted from a returned instrument.

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_brand	string	Card brand in lowercase, e.g. visa.
last4_digits	string	Last four digits of the card number. The full number is never returned.
bin	string	The card's bank identification number (first six to eight digits).
card_funding	string	How the card draws funds: credit, debit, prepaid, or unknown when the BIN could not be classified.
card_product	string	The card product tier in lowercase, e.g. platinum, gold, world. Omitted when unknown.
issuer_name	string	Name of the issuing bank. Omitted when unknown.

For a card, the common holder_name is the cardholder name as it was entered with the card. It is omitted when none was captured.

A card destination is addressed by its card_token, which you supply in payment_method.details when you create the transfer. The token and the card's expiry are not returned on an instrument.

Instruments on transactions, orders and webhooks

Besides transfers, the payment_instrument object is returned wherever a transaction is reported, so you can show the card on an invoice or recognise it when you look a payment up later:

Where	Field	When it is set
GET /v1/transactions/{id} and the transaction search	payment_instrument	On every attempt that ran on a stored instrument, including failed ones.
GET /v1/orders/{id} and the order search	payment_instrument	Once the order has succeeded: it is the instrument of the order's final transaction. A pending or failed order carries none.
Transaction webhooks	data.payment_instrument	On the same transactions as the API, at the time the event is emitted.

The object is present only when Orchestr holds the instrument:

• Card payments collected through our card fields or the server-to-server card API carry a card instrument with card_brand, last4_digits, the BIN-derived bin, card_funding, card_product and issuer_name, and the cardholder name in holder_name.
• Transfers carry their destination instrument.
• Redirect methods (iDEAL, PayPal and similar), and card payments where the customer enters the card on a provider-hosted page, carry no instrument: the field is absent.

Example, a card payment:

"payment_instrument": {
  "id": "pi_8a7b6c5d",
  "type": "card",
  "country_code": "US",
  "holder_name": "Jane Doe",
  "card_brand": "visa",
  "last4_digits": "4242",
  "bin": "42424242",
  "card_funding": "credit",
  "card_product": "platinum",
  "issuer_name": "Commonwealth Bank"
}

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.
• Webhook event types - the payloads that carry payment_instrument.
• The full API Reference for the PaymentInstrument model.