> ## Documentation Index > Fetch the complete documentation index at: https://docs.kirafin.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get a payout > Retrieve the full, enriched detail of a single payout you own, by its `payout_id` (the transfer UUID returned at creation and by `GET /v1/payouts`). Works for payouts from every source — API payouts and virtual-account settlement/payout flows. The response is a bare JSON object (no `{ message, data }` wrapper). Notable fields: - `status` — the client-facing status. A payout that hit a terminal error surfaces as `"FAILED"` (it aligns with the `payout.failed` webhook); other values are `CREATED`, `KYT_PENDING` (a Know-Your-Transaction compliance screen, non-terminal), `PENDING`, `PROCESSING`, `COMPLETED`, `CANCELLED`, `IN_REVIEW`. - `origin` — `"api"`, `"payout"`, or `"deposit"`. - `from_amount`/`from_currency` and `to_amount`/`to_currency` — decimal strings; `fee` is the derived difference (or `null` when currencies differ). - `payment_method` — lowercased recipient rail (`wire`, `wallet`, `ach`). - `txn_hash` (crypto), `reference_number` (the sending bank's tracking reference on any fiat rail — an IMAD, an ACH trace number, or a UETR), and `provider_reference` when available. `uetr` is still returned for wire payouts but is deprecated in favour of `reference_number`. - `sender` and `recipient` — bank account numbers and CLABEs are masked to the last 4 digits (`****1234`). - `events[]` — a client-facing audit trail of status changes. - `extra_info.supporting_documents[].url` — short-lived (10-minute) pre-signed download links. - `extra_info.nature_of_payment` — the payout reason supplied at creation (`vendor`, `pobo`, `first_party`, `spot_3p`, `spot_1p`, `related_entities`, or `other`), echoed back unchanged. - `quotation` — present only when the payout was priced by the itemized quotation engine; it is the same object returned by `POST /v1/quotations`. **Errors:** `404` when no payout matches the id; `403` when the payout belongs to a different client. **Example response (200):** ```json { "payout_id": "550e8400-e29b-41d4-a716-446655440000", "user_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "recipient_id": "6ba7b811-9dad-11d1-80b4-00c04fd430c8", "quote_id": "6ba7b812-9dad-11d1-80b4-00c04fd430c8", "reference": "INV-2026-0042", "memo": "April consulting services", "origin": "payout", "from_amount": "1000.00", "from_currency": "USD", "to_amount": "997.50", "to_currency": "USD", "fee": "2.50", "payment_method": "wire", "txn_hash": null, "uetr": "a1b2c3d4-1111-2222-3333-444455556666", "reference_number": "a1b2c3d4-1111-2222-3333-444455556666", "provider_reference": "provider-tx-7788", "status": "COMPLETED", "extra_info": { "nature_of_payment": "vendor", "supporting_documents": [ { "type": "invoice", "url": "https://files.balampay.com/...signed...", "description": "Invoice PDF" } ] }, "metadata": { "order_id": "ord_12345" }, "sender": { "name": "Acme Holdings LLC", "company_name": "Acme Holdings LLC", "country": "US", "bank_name": "Example Bank, N.A.", "bank_account": "****6789" }, "recipient": { "name": "Jane Doe", "company_name": null, "country": "MX", "account_type": "WIRE", "bank_name": "BBVA Mexico", "account_number": "****4321", "routing_number": "021000021", "account_details": { "bank_name": "BBVA Mexico", "address": "Av. Reforma 123, CDMX", "account_number": "****4321", "bank_code": "012", "swift_bic": "BCMRMXMM" } }, "events": [ { "event_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "CREATED", "message": "Payout created", "created_at": "2026-06-25T14:00:00.000Z" }, { "event_id": "7c9e6679-7425-40de-944b-e07fc1f90ae8", "status": "COMPLETED", "message": "Payout settled", "created_at": "2026-06-25T14:05:00.000Z" } ], "created_at": "2026-06-25T14:00:00.000Z", "updated_at": "2026-06-25T14:05:00.000Z" } ``` {/* version-stamp:start — generated by scripts/stamp-versions.ts, do not edit */} Stable since **2025-01-01** — unchanged in **2026-04-14**. {/* version-stamp:end */} ## OpenAPI ````yaml /openapi/kira-api.2026-04-14.json get /v1/payouts/{payout_id} openapi: 3.1.0 info: title: Kira API version: '2026-04-14' description: >- REST API for users, KYC/KYB verification, virtual accounts, payouts, recipients, and webhooks. Every request requires an `x-api-key` header and a bearer access token (see Authentication). Pin your account to version `2026-04-14` before integrating. contact: name: Kira API Support email: support@kirafin.ai servers: - url: https://api.balampay.com description: Production - url: https://api.balampay.com/sandbox description: Sandbox security: - bearerAuth: [] apiKeyAuth: [] tags: - name: Authentication - name: Versioning - name: Users - name: Virtual Accounts - name: Quotations - name: Payouts - name: Recipients - name: Reference paths: /v1/payouts/{payout_id}: get: tags: - Payouts summary: Get a payout description: >- Retrieve the full, enriched detail of a single payout you own, by its `payout_id` (the transfer UUID returned at creation and by `GET /v1/payouts`). Works for payouts from every source — API payouts and virtual-account settlement/payout flows. The response is a bare JSON object (no `{ message, data }` wrapper). Notable fields: - `status` — the client-facing status. A payout that hit a terminal error surfaces as `"FAILED"` (it aligns with the `payout.failed` webhook); other values are `CREATED`, `KYT_PENDING` (a Know-Your-Transaction compliance screen, non-terminal), `PENDING`, `PROCESSING`, `COMPLETED`, `CANCELLED`, `IN_REVIEW`. - `origin` — `"api"`, `"payout"`, or `"deposit"`. - `from_amount`/`from_currency` and `to_amount`/`to_currency` — decimal strings; `fee` is the derived difference (or `null` when currencies differ). - `payment_method` — lowercased recipient rail (`wire`, `wallet`, `ach`). - `txn_hash` (crypto), `reference_number` (the sending bank's tracking reference on any fiat rail — an IMAD, an ACH trace number, or a UETR), and `provider_reference` when available. `uetr` is still returned for wire payouts but is deprecated in favour of `reference_number`. - `sender` and `recipient` — bank account numbers and CLABEs are masked to the last 4 digits (`****1234`). - `events[]` — a client-facing audit trail of status changes. - `extra_info.supporting_documents[].url` — short-lived (10-minute) pre-signed download links. - `extra_info.nature_of_payment` — the payout reason supplied at creation (`vendor`, `pobo`, `first_party`, `spot_3p`, `spot_1p`, `related_entities`, or `other`), echoed back unchanged. - `quotation` — present only when the payout was priced by the itemized quotation engine; it is the same object returned by `POST /v1/quotations`. **Errors:** `404` when no payout matches the id; `403` when the payout belongs to a different client. **Example response (200):** ```json { "payout_id": "550e8400-e29b-41d4-a716-446655440000", "user_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "recipient_id": "6ba7b811-9dad-11d1-80b4-00c04fd430c8", "quote_id": "6ba7b812-9dad-11d1-80b4-00c04fd430c8", "reference": "INV-2026-0042", "memo": "April consulting services", "origin": "payout", "from_amount": "1000.00", "from_currency": "USD", "to_amount": "997.50", "to_currency": "USD", "fee": "2.50", "payment_method": "wire", "txn_hash": null, "uetr": "a1b2c3d4-1111-2222-3333-444455556666", "reference_number": "a1b2c3d4-1111-2222-3333-444455556666", "provider_reference": "provider-tx-7788", "status": "COMPLETED", "extra_info": { "nature_of_payment": "vendor", "supporting_documents": [ { "type": "invoice", "url": "https://files.balampay.com/...signed...", "description": "Invoice PDF" } ] }, "metadata": { "order_id": "ord_12345" }, "sender": { "name": "Acme Holdings LLC", "company_name": "Acme Holdings LLC", "country": "US", "bank_name": "Example Bank, N.A.", "bank_account": "****6789" }, "recipient": { "name": "Jane Doe", "company_name": null, "country": "MX", "account_type": "WIRE", "bank_name": "BBVA Mexico", "account_number": "****4321", "routing_number": "021000021", "account_details": { "bank_name": "BBVA Mexico", "address": "Av. Reforma 123, CDMX", "account_number": "****4321", "bank_code": "012", "swift_bic": "BCMRMXMM" } }, "events": [ { "event_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "status": "CREATED", "message": "Payout created", "created_at": "2026-06-25T14:00:00.000Z" }, { "event_id": "7c9e6679-7425-40de-944b-e07fc1f90ae8", "status": "COMPLETED", "message": "Payout settled", "created_at": "2026-06-25T14:05:00.000Z" } ], "created_at": "2026-06-25T14:00:00.000Z", "updated_at": "2026-06-25T14:05:00.000Z" } ``` operationId: get_v1-payouts-payout-id parameters: - in: path name: payout_id required: true schema: type: string format: uuid description: Payout UUID. - in: header name: X-Api-Version required: false description: >- Optional. The date-versioned API version to apply for this request (e.g. `2026-04-14`). When sent it always wins, even over your pinned account default. When omitted, the API uses your account's pinned version if set, otherwise a baseline default. schema: type: string example: '2026-04-14' responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/PayoutDetailResponse' '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- Forbidden — the payout belongs to a different client (`PAYOUT_ACCESS_DENIED`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: >- Not found — no payout with this id (`PAYOUT_NOT_FOUND`). Unlike users, recipients, and virtual accounts, payout ids are **not** format-pre-validated: a malformed (non-UUID) id also returns `404`, not `400`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] apiKeyAuth: [] components: schemas: PayoutDetailResponse: type: object description: >- Full enriched detail of a single payout (a bare object, not wrapped in an envelope). See the `GET /v1/payouts/{payout_id}` operation description for a complete example and field-by-field notes. properties: payout_id: type: string format: uuid user_id: type: string format: uuid recipient_id: type: - string - 'null' format: uuid quote_id: type: - string - 'null' format: uuid description: >- The quote this payout was priced against. Populated on every virtual-account payout — settlement always reserves a quote, even when you did not explicitly reserve one via `POST .../payout/preview` with `create_quote: true` (unlike the preview response's `quote_id`, which appears only when a quote was requested). reference: type: - string - 'null' description: >- Your own reference string from the payout create request, echoed back unchanged. Sending `reference: "my-ref-123"` on create returned `reference: "my-ref-123"` on the payout detail. `null` when none was supplied. memo: type: - string - 'null' description: >- The customer-supplied memo from the create request (`extra_info.memo`), surfaced at top level. Sending `extra_info: {memo: "pay for services"}` on create returned top-level `memo: "pay for services"` on the payout detail. `null` when no memo was supplied. origin: type: string enum: - api - payout - deposit description: >- How this payment record originated. Enum is exactly `deposit` | `payout` | `api` (a bad value on the list endpoint's `?origin=` filter is rejected with 400 echoing this list). `payout` = a payout initiated from a virtual account (confirmed on every payout created). `deposit` = the inbound funding/settlement leg of a virtual account. `api` = a payout created directly through the API, not tied to a virtual account. from_amount: type: string description: >- Decimal string. The amount on the SOURCE/funding side of the payout, denominated in `from_currency`. `"100.00"` on a crypto-funded ($100.00 USDC) payout. from_currency: type: string description: >- ISO-4217 currency code (or stablecoin ticker) of the source/funding side (`from_amount`). `"USD"` for a fiat-funded payout, `"USDC"` for a crypto-funded payout (`mode: "CRYPTO"`) — NOT always USD. to_amount: type: string description: >- Decimal string. The amount on the DESTINATION side — what the recipient receives after fees/FX, denominated in `to_currency`. May differ in currency from `from_amount` — a payout with `from_currency: "USDC"` returned `to_amount: "86.69"`, `to_currency: "USD"`. to_currency: type: - string - 'null' description: >- ISO-4217 currency code (or stablecoin ticker) of the destination side (`to_amount`) — the currency the recipient is paid in. `"USD"` on a crypto-funded payout with no saved recipient (settles back to a fiat leg). fee: type: - string - 'null' description: >- Derived `from_amount` − `to_amount`; null when the currencies differ. payment_method: type: - string - 'null' description: 'Lowercased recipient rail: wire, wallet, ach.' txn_hash: type: - string - 'null' description: Present for crypto payouts. uetr: type: - string - 'null' description: >- **Deprecated — use `reference_number`.** Present for wire payouts. Still populated, and scheduled for removal; migrate to `reference_number`, which reports the equivalent value on every rail. deprecated: true reference_number: type: - string - 'null' description: >- The tracking reference the sending bank assigned to this payout, in whatever form the rail uses: an IMAD for Fedwire (`20260807MFP00407000001`), a trace number for ACH (`122245530000175`), or a UETR (`cdf55f20-1290-4f43-8a54-00cbe812c30a`) on rails whose bank reports one. Quote it to the receiving bank to trace the payment. `null` until the payment has actually been sent — a payout still being created, reviewed, or processing has no reference yet — and `null` for crypto payouts, which have a `txn_hash` instead. provider_reference: type: - string - 'null' description: >- The downstream payout provider's own reference/identifier for this payout. `null` on a payout still awaiting its crypto deposit (`status: "CREATED"`). status: type: string description: >- Client-facing status (UPPERCASE): CREATED, KYT_PENDING, PENDING, PROCESSING, COMPLETED, FAILED, CANCELLED, IN_REVIEW. extra_info: type: - object - 'null' additionalProperties: true description: >- Free-form object carrying create-time extras and derived record-keeping data. Keys observed on a crypto payout: `memo`, `invoice_number` (nested under `extra_info.extra_info`), `nature_of_payment`, `customer_reference`, `virtualAccountId`, `paymentType`, `payoutMode`, `depositWallet` ({walletId, address, network, currency}), and the fee breakdown under `extra_info.fees`. Exact keys are provider/mode-shaped and vary by payout type. metadata: type: object additionalProperties: true description: >- Your own key/value object attached at payout create time and returned verbatim. `metadata: {order_id: "abc123"}` sent on create was echoed back unchanged. `{}` when you set no keys. sender: type: object properties: name: type: - string - 'null' company_name: type: - string - 'null' country: type: - string - 'null' description: >- The sender's (paying user's) country. An ISO 3166-1 alpha-3 code (e.g. `"MEX"`) — NOT alpha-2. bank_name: type: - string - 'null' bank_account: type: - string - 'null' description: Masked to the last 4 digits (`****1234`). description: >- The party funding/initiating the payout — your end-user / virtual-account owner who is paying. `company_name`/`country` come from that user; `bank_name`/`bank_account` are populated for virtual-account-sourced payouts (e.g. `bank_name: "SLOVAK_SAVINGS_BANK"`, `bank_account: "****7748"` — masked to the last 4 digits). recipient: type: object properties: name: type: - string - 'null' company_name: type: - string - 'null' country: type: - string - 'null' description: >- The recipient's country. Format follows `sender.country` (ISO 3166-1 alpha-3). `null` when the recipient is unresolved. account_type: type: - string - 'null' description: >- The recipient's payout rail, mirroring the values documented on `RecipientResponse.account_type` (`ACH`, `WIRE`, `WALLET`). Reads the literal string `"UNKNOWN"` when the recipient can't be resolved (e.g. a crypto payout with no saved recipient). bank_name: type: - string - 'null' account_number: type: - string - 'null' description: Masked to the last 4 digits. routing_number: type: - string - 'null' account_details: type: object additionalProperties: true description: >- Rail-specific account fields; keys depend on `account_type`. `{}` when the recipient is unresolved (`account_type: "UNKNOWN"`). description: >- The payee. When the recipient can't be resolved (e.g. a crypto payout with no saved recipient), every field is `null` and `account_type` reads the literal string `"UNKNOWN"`. events: type: array description: Client-facing audit trail of status changes. items: type: object properties: event_id: type: string status: type: string message: type: - string - 'null' created_at: type: string required: - event_id - status - created_at quotation: type: object additionalProperties: true description: >- Present only when the payout was priced by the itemized quotation engine; the same object returned by `POST /v1/quotations`. created_at: type: string updated_at: type: string required: - payout_id - user_id - status - origin - from_amount - from_currency - created_at - updated_at ErrorResponse: type: object properties: message: type: string code: type: string statusCode: type: number error: type: string timestamp: type: string path: type: string details: {} required: - message securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: Access token from `POST /auth` (the `data.access_token` value). apiKeyAuth: type: apiKey in: header name: x-api-key description: API key issued by Kira. Required on every request, including `/auth`. ````