Skip to main content
GET
Get a payment instruction

Authorizations

Authorization
string
header
required

JWT bearer token. Include as Authorization: Bearer <token>. See the Authentication guide for how to obtain one.

Headers

X-Trace-Version
string

API version. Omit to use the default version.

Example:

"1"

Path Parameters

beneficiaryId
string<uuid>
required

UUID of the beneficiary.

paymentInstructionId
string<uuid>
required

UUID of the payment instruction.

Response

Payment instruction details.

A payment instruction on a beneficiary. Use address.rail to discriminate routing details — for beneficiary payment instructions it is one of PIX_KEY, PIX_BANK_INSTRUCTION, or CRYPTO.

id
string<uuid>
required
read-only
Example:

"c3d4e5f6-a7b8-9012-cdef-1234567890ab"

asset
enum<string>
required

ISO 4217 currency code or stablecoin ticker. The maximum decimal scale of an AmountValue paired with this asset depends on the asset:

Requests accept only these three assets. Any other asset fails with 400 INVALID_DATA (INVALID_ENUM).

Available options:
BRL,
USDT,
USDC
Example:

"BRL"

currentState
object
required

The payment instruction's current state. Carries a status, a reason (null when the status needs no justification), and the time the state was entered.

address
PIX key · object
required

A payment route, discriminated by rail. Beneficiary payment instructions emit one of PIX_KEY, PIX_BANK_INSTRUCTION, or CRYPTO; other rails appear in operation responses.

createdAt
string<date-time>
required
read-only
Example:

"2026-04-14T10:30:00.0000Z"

documents
Document · object[]
required
read-only

Compliance documents you have uploaded for the instruction. Empty until you upload one. This is what you sent — to know what is still wanted, read requirements.

requirements
object
required

What compliance last asked of you for this instruction. It reflects the latest request of the compliance analysis, so it can lag the analysis by a few seconds, like currentState and the BENEFICIARY_INSTRUCTION_ACTION_REQUIRED webhook. Every response that carries the instruction returns the same value, including the 201 that adds an instruction. All four groups are empty for an instruction whose review has not started, has not been read yet or has already been decided.

Example:
custodyDetail
object | null

Custody arrangement for the instruction. Present only for the CRYPTO rail; null for all other rails.