> ## Documentation Index > Fetch the complete documentation index at: https://docs.tracefinance.com/llms.txt > Use this file to discover all available pages before exploring further. # Get a payment instruction > Retrieves one payment instruction of a beneficiary, including its review status. ## OpenAPI ````yaml apis/fx-payment/openapi.yml GET /v1/beneficiaries/{beneficiaryId}/payment-instructions/{paymentInstructionId} openapi: 3.1.1 info: title: Trace Finance Payments API version: 1.0.0 description: > API for deposits, withdrawals, swaps, and beneficiary management on the Trace Finance platform. servers: - url: https://api.sandbox.tracefinance.com description: Sandbox security: - bearerAuth: [] tags: - name: Operations description: >- Create deposits, withdrawals, and swaps. Query operation status and history. - name: Reports description: Generate aggregated views of operations across a time window. - name: Beneficiaries description: >- Manage external beneficiaries and their payment instructions for withdrawals. - name: Payment instructions description: Add or remove payment instructions on an existing beneficiary. paths: /v1/beneficiaries/{beneficiaryId}/payment-instructions/{paymentInstructionId}: get: tags: - Payment instructions summary: Get a payment instruction description: > Retrieves one payment instruction of a beneficiary, in the same shape it has in `paymentInstructions` of [Get a beneficiary](/api-reference/fx-payment/beneficiaries/get-beneficiary). Use it to read the instruction's review status: `currentState.status` moves from `PENDING_REVIEW` to `APPROVED` or `REJECTED`, and `requirements` shows what compliance is still waiting on. It is the lighter way to poll one instruction when you cannot subscribe to webhooks, which the [Register a beneficiary](/journeys/register-beneficiary) journey recommends. Returns `404` when the beneficiary does not exist for the authenticated customer, or when the instruction is not on that beneficiary. operationId: getPaymentInstruction parameters: - $ref: '#/components/parameters/BeneficiaryId' - $ref: '#/components/parameters/PaymentInstructionId' - $ref: '#/components/parameters/TraceVersion' responses: '200': description: Payment instruction details. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/PaymentInstructionResponse' examples: pendingReview: summary: PIX instruction waiting for the review value: id: 00000000-0000-4000-8000-000000000002 asset: BRL currentState: status: PENDING_REVIEW createdAt: '2026-04-14T10:30:00Z' address: rail: PIX_KEY dictKeyType: CPF dictKey: '12345678901' createdAt: '2026-04-14T10:30:00Z' documents: [] requirements: currentlyDue: [] pendingVerification: [] errors: [] satisfied: [] custodyDetail: null documentOwed: summary: Crypto instruction waiting for a custody attestation value: id: 00000000-0000-4000-8000-000000000003 asset: USDT currentState: status: PENDING_REVIEW createdAt: '2026-04-14T10:30:00Z' address: rail: CRYPTO network: ETHEREUM address: '0xAbC0000000000000000000000000000000000001' createdAt: '2026-04-14T10:30:00Z' documents: [] requirements: currentlyDue: - type: BENEFICIARY_DOCUMENT documentType: CUSTODY_ATTESTATION anyOf: - CUSTODY_ATTESTATION pendingVerification: [] errors: [] satisfied: [] custodyDetail: null '400': description: >- Validation error: `beneficiaryId` or `paymentInstructionId` is not a UUID. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidPaymentInstructionUuid: summary: paymentInstructionId is not a UUID value: code: INVALID_DATA message: Object contains invalid data details: errors: - code: INVALID_UUID message: '''not-a-uuid'' cannot be converted to UUID' field: path:paymentInstructionId params: {} invalidBeneficiaryUuid: summary: beneficiaryId is not a UUID value: code: INVALID_DATA message: Object contains invalid data details: errors: - code: INVALID_UUID message: '''not-a-uuid'' cannot be converted to UUID' field: path:beneficiaryId params: {} '401': $ref: '#/components/responses/UnauthorizedError' '404': description: >- Beneficiary not found for the authenticated customer, or payment instruction not on the beneficiary. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: beneficiaryNotFound: summary: Beneficiary does not exist for the authenticated customer value: code: RESOURCE_NOT_FOUND message: >- Beneficiary with given parameters [id:00000000-0000-4000-8000-000000000001] not found details: resource: Beneficiary parameters: id: 00000000-0000-4000-8000-000000000001 paymentInstructionNotFound: summary: Payment instruction does not exist on the beneficiary value: code: RESOURCE_NOT_FOUND message: >- PaymentInstruction with given parameters [id:00000000-0000-4000-8000-000000000002] not found details: resource: PaymentInstruction parameters: id: 00000000-0000-4000-8000-000000000002 components: parameters: BeneficiaryId: name: beneficiaryId in: path required: true description: UUID of the beneficiary. schema: type: string format: uuid PaymentInstructionId: name: paymentInstructionId in: path required: true description: UUID of the payment instruction. schema: type: string format: uuid TraceVersion: name: X-Trace-Version in: header required: false description: API version. Omit to use the default version. schema: type: string example: '1' headers: RequestId: description: >- Unique request identifier emitted on every response. Reference it when contacting Trace Finance support so we can trace the request end-to-end. See [Errors](/guides/principles/errors). schema: type: string format: uuid schemas: PaymentInstructionResponse: type: object description: >- 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`. properties: id: type: string format: uuid example: pi-a1b2c3d4-5e6f-7890-abcd-ef1234567890 readOnly: true asset: $ref: '#/components/schemas/Asset' currentState: $ref: '#/components/schemas/InstructionState' address: $ref: '#/components/schemas/FinancialAddress' custodyDetail: oneOf: - $ref: '#/components/schemas/CustodyDetail' - type: 'null' description: >- Custody arrangement for the instruction. Present only for the `CRYPTO` rail; `null` for all other rails. createdAt: type: string format: date-time example: '2026-04-14T10:30:00Z' readOnly: true documents: type: array description: >- 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`. items: $ref: '#/components/schemas/BeneficiaryDocumentResponse' readOnly: true requirements: allOf: - $ref: '#/components/schemas/Requirements' description: >- What compliance is waiting on for this instruction, read live at request time. All four groups are empty for an instruction whose review has not started or has already been decided. readOnly: true required: - id - asset - currentState - address - createdAt - documents - requirements ErrorResponse: type: object properties: code: type: string description: Machine-readable error code. message: type: string description: Human-readable description. details: type: object additionalProperties: true required: - code - message Asset: type: string enum: - BRL - USDT - USDC description: > ISO 4217 currency code or stablecoin ticker. The maximum decimal scale of an `AmountValue` paired with this asset depends on the asset: | Asset | Decimals | |---|---| | BRL | 2 | | USDT | 6 | | USDC | 6 | example: BRL InstructionState: type: object description: >- A single entry in a payment instruction's state history. Carries a status, optional reason (present only for `REJECTED`), and the time the state was entered. properties: status: $ref: '#/components/schemas/InstructionStatus' reason: $ref: '#/components/schemas/Reason' description: >- Justification for entering this status (e.g., why an instruction was `REJECTED`, or which document is being asked for on `ACTION_REQUIRED`). Present for `REJECTED` and `ACTION_REQUIRED`; omitted for `PENDING_REVIEW` and `APPROVED`. createdAt: type: string format: date-time description: Time the instruction entered this status. required: - status - createdAt FinancialAddress: description: >- 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. oneOf: - $ref: '#/components/schemas/PixKeyAddress' - $ref: '#/components/schemas/PixBankInstructionAddress' - $ref: '#/components/schemas/PixStaticQrCodeAddress' - $ref: '#/components/schemas/BoletoAddress' - $ref: '#/components/schemas/CryptoWalletAddress' discriminator: propertyName: rail mapping: PIX_KEY: '#/components/schemas/PixKeyAddress' PIX_BANK_INSTRUCTION: '#/components/schemas/PixBankInstructionAddress' PIX_STATIC_QR_CODE: '#/components/schemas/PixStaticQrCodeAddress' BOLETO: '#/components/schemas/BoletoAddress' CRYPTO: '#/components/schemas/CryptoWalletAddress' CustodyDetail: type: object description: >- Custody arrangement for a crypto payment instruction. Optional; when present, all three fields are required. Applies to the `CRYPTO` rail only. Required (together with the custody attestation document) only when the wallet is not custodied by Trace. properties: purpose: type: string description: Purpose of the wallet or its transfers. example: Treasury settlement custody: type: string description: Who custodies the wallet. example: Coinbase Custody counterparty: type: string description: Counterparty on the other side of the arrangement. example: Acme VASP Ltd required: - purpose - custody - counterparty BeneficiaryDocumentResponse: title: Document type: object description: >- A compliance document attached to a payment instruction. One document per type: re-uploading the same type replaces the file under review, keeping `referenceId` and increasing `version`. properties: referenceId: type: string description: >- Identifier of the document. Stable across re-uploads of the same document type, so it always points at the same reviewable document. example: doc-a1b2c3d4-5e6f-7890-abcd-ef1234567890 readOnly: true type: $ref: '#/components/schemas/DocumentType' version: type: integer minimum: 1 description: >- Which file of this document is currently under compliance review. Starts at `1` and increases by one on every re-upload of the same type. Previous versions are retained by compliance. example: 1 readOnly: true currentState: allOf: - $ref: '#/components/schemas/DocumentState' description: >- Whether compliance is waiting on you for **this** document. Read this, not the instruction status, to know which file to replace. readOnly: true required: - referenceId - type - version - currentState Requirements: type: object description: >- What compliance is waiting on, grouped by what you have to do about it. The same shape is used for beneficiary payment instructions and for operations. Every group is always present; an empty one means there is nothing in that state. properties: currentlyDue: type: array description: Compliance is waiting on you to send these. items: $ref: '#/components/schemas/DocumentRequirement' pendingVerification: type: array description: You sent these and compliance is reviewing them. Nothing to do. items: $ref: '#/components/schemas/DocumentRequirement' errors: type: array description: >- These came back — sent, then refused or asked for again. `reason` says why. Send a new file for the same requirement. items: $ref: '#/components/schemas/DocumentRequirement' satisfied: type: array description: These are settled. Nothing to do. items: $ref: '#/components/schemas/DocumentRequirement' required: - currentlyDue - pendingVerification - errors - satisfied example: currentlyDue: - type: BENEFICIARY_DOCUMENT documentType: CUSTODY_ATTESTATION anyOf: - CUSTODY_ATTESTATION pendingVerification: [] errors: [] satisfied: [] InstructionStatus: type: string enum: - PENDING_REVIEW - ACTION_REQUIRED - APPROVED - REJECTED description: > Compliance review status of a payment instruction. New instructions start in `PENDING_REVIEW` and transition asynchronously to `APPROVED` or `REJECTED`. `ACTION_REQUIRED` means the review is waiting on **you**: compliance asked for another document, and `currentState.reason` says what for. Upload it with the instruction as the document `holder` and the instruction returns to `PENDING_REVIEW` on its own. Unlike `REJECTED`, this is not final — the same instruction can still be approved. Compliance can ask for more than one document, and it can ask for one you have never sent. `requirements` is the complete answer to *what is missing*: everything in `currentlyDue` and `errors` is still owed. `documents[].currentState` only covers files you already uploaded, so it can be empty while the instruction is `ACTION_REQUIRED`. The instruction returns to `PENDING_REVIEW` on its own once nothing is owed, so replacing one file does not necessarily end the wait. example: APPROVED Reason: type: object description: >- Machine- and human-readable explanation. Returned inside an `OperationState` entry when a status transition requires justification (e.g., `FAILED`). properties: code: type: string description: Machine-readable code. example: INSUFFICIENT_BALANCE message: type: string description: Human-readable description. example: Insufficient balance for the requested operation details: type: object additionalProperties: true description: Free-form context relevant to the reason. required: - code - message - details PixKeyAddress: title: PIX key type: object description: PIX route via DICT key. properties: rail: type: string enum: - PIX_KEY dictKeyType: $ref: '#/components/schemas/PixKeyType' dictKey: type: string description: DICT key value. example: john@example.com required: - rail - dictKeyType - dictKey PixBankInstructionAddress: title: PIX bank instruction type: object description: PIX route via bank-account details (no DICT key). properties: rail: type: string enum: - PIX_BANK_INSTRUCTION bank: $ref: '#/components/schemas/Bank' branch: type: string description: Branch number. example: '0001' accountNumber: type: string description: Account number with check digit. example: '123456' required: - rail - bank - branch - accountNumber PixStaticQrCodeAddress: title: PIX static QR code type: object description: PIX route via static QR code payload. properties: rail: type: string enum: - PIX_STATIC_QR_CODE qrCode: type: string description: PIX QR code payload (EMV-encoded BR Code). example: 00020126580014br.gov.bcb.pix... required: - rail - qrCode BoletoAddress: title: Boleto type: object description: Boleto route. properties: rail: type: string enum: - BOLETO barcode: type: string description: Boleto barcode (digitable line). example: 23793.38128 60800.000003 00000.000400 1 84340000012345 dueDate: type: string format: date-time description: Last day on which the boleto can be paid. example: '2026-05-15T23:59:59Z' required: - rail - barcode - dueDate CryptoWalletAddress: title: Crypto wallet type: object description: Crypto-wallet route. properties: rail: type: string enum: - CRYPTO network: type: string description: Blockchain network (e.g., `ETHEREUM`, `TRON`, `SOLANA`). example: ETHEREUM address: type: string description: Wallet address on `network`. example: '0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18' required: - rail - network - address DocumentType: type: string description: >- Type of compliance document. Beneficiary document upload supports only `CUSTODY_ATTESTATION`, which proves a crypto wallet's custody arrangement. enum: - CUSTODY_ATTESTATION example: CUSTODY_ATTESTATION DocumentState: type: object description: >- Review state of a single document. An instruction is `ACTION_REQUIRED` while any of its documents is — so with two documents asked for, replacing one leaves the instruction waiting on the other. properties: status: $ref: '#/components/schemas/DocumentStatus' reason: allOf: - $ref: '#/components/schemas/DocumentReason' description: >- Says the document is being asked for again. Present only for `ACTION_REQUIRED`. It does not carry the reviewer's own words — for what compliance actually said, read `requirements.errors[].reason` on the instruction. createdAt: type: string format: date-time example: '2026-04-14T10:30:00Z' required: - status - createdAt DocumentRequirement: type: object description: >- One thing compliance wants. The group it sits in says what state it is in, so the item does not repeat it. properties: type: type: string description: >- What the requirement is attached to: `BENEFICIARY_DOCUMENT` for a payment instruction, `OPERATION_DOCUMENT` for an operation. enum: - BENEFICIARY_DOCUMENT - OPERATION_DOCUMENT example: BENEFICIARY_DOCUMENT documentType: type: string description: >- What compliance asked for. Usually a single document type, but it can name a **family** of documents — `IDENTITY_VERIFICATION`, for example — in which case `anyOf` lists the ones that satisfy it. example: IDENTITY_VERIFICATION anyOf: type: array description: >- The document types that answer this requirement. **Any one of them settles it** — you do not send all of them. For a requirement naming a single document this holds exactly that one, so you can always read `anyOf` and ignore whether a family was asked for. items: type: string example: - PASSPORT - ID_CARD - DRIVER_LICENSE - RESIDENCE_PERMIT reason: allOf: - $ref: '#/components/schemas/DocumentReason' description: >- Why this requirement is open. Present when compliance explained itself, typically on `errors`. required: - type - documentType - anyOf PixKeyType: type: string enum: - CPF - CNPJ - EMAIL - PHONE - RANDOM description: PIX key category. `RANDOM` is a random key issued by the central bank. example: CPF Bank: type: object description: >- Bank reference. Resolved server-side from the COMPE code provided in the request. properties: code: type: string description: COMPE code (3-digit Brazilian bank code, may be sent unpadded). example: '001' name: type: string description: Registered bank name. example: BANCO DO BRASIL S.A. ispbCode: type: - string - 'null' description: >- ISPB code (8-digit Brazilian payment-system identifier). `null` when the bank is not registered with an ISPB. example: '00000000' required: - code - name - ispbCode DocumentStatus: type: string enum: - PENDING_REVIEW - ACTION_REQUIRED description: > Review state of one document. `PENDING_REVIEW` means it is with compliance; `ACTION_REQUIRED` means they asked you to replace it and `reason` says why. Uploading a new version of that document returns it to `PENDING_REVIEW`. example: ACTION_REQUIRED DocumentReason: type: - object - 'null' description: >- Machine- and human-readable explanation attached to a compliance document ask. properties: code: type: string example: DOCUMENT_REQUESTED message: type: string example: The file is not legible responses: UnauthorizedError: description: Missing or invalid authentication token. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidToken: $ref: '#/components/examples/InvalidToken' expiredToken: $ref: '#/components/examples/ExpiredToken' examples: InvalidToken: summary: Bearer token is invalid or malformed value: code: INVALID_ACCESS_TOKEN message: Invalid access token details: {} ExpiredToken: summary: Bearer token has expired value: code: EXPIRED_ACCESS_TOKEN message: Expired access token details: {} securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT bearer token. Include as `Authorization: Bearer `. See the [Authentication](/guides/authentication) guide for how to obtain one. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.