--- title: "List fiat payout statuses" method: POST path: "/v2/payouts/status/batch" tags: ["Payouts"] --- # List fiat payout statuses `POST /v2/payouts/status/batch` ## Request - Base URL: `https://openapi.infini.money` - URL: `https://openapi.infini.money/v2/payouts/status/batch` - Auth: API key in header `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) Returns fiat payouts owned by the authenticated organization whose creation time falls within the inclusive `start_time` and `end_time` range. Requires `payout.read` permission. Results are ordered by creation time descending and use page-based pagination. `page` defaults to `1`; `page_size` defaults to `20` and cannot exceed `100`. Use this endpoint for periodic time-window reconciliation. Use `GET /v2/payouts/{payout_id}` when retrieving one known payout. ## Headers - `X-API-Key-ID` string, required - `X-API-Timestamp` string, required - `X-API-Nonce` string, required - `Digest` string, required - `Authorization` string, required ## Request body - BatchPayoutStatusRequest - `start_time` integer, required: Inclusive payout creation start time as Unix seconds. - `end_time` integer, required: Inclusive payout creation end time as Unix seconds. Must be greater than or equal to `start_time`. - `page` integer: Page number. - `page_size` integer: Number of payouts per page. ## Response `200` Payout statuses in creation-time descending order with pagination - BatchPayoutStatusEnvelope - `code` 0, required: Business code. `0` means success. - `message` string, required: Response message. - `data` object, required - `payouts` PayoutStatusItem[], required: Payout statuses ordered by creation time descending. - `payout_id` string, required: Infini fiat payout ID. - `client_reference_id` string, required: Merchant-provided payout reconciliation reference. - `quote_id` string, required: Quote used to create the payout. - `provider` 'sgb', required: Execution provider selected by Infini. - `status` 'processing' | 'completed' | 'failed', required: Current payout lifecycle state. - `payout_type` 'swift', required: Payout rail bound by the quote. - `source_currency` 'USD', required: Organization balance currency. - `destination_currency` 'USD', required: Currency delivered to the recipient. - `destination_country` string, required: Destination country as an ISO 3166-1 alpha-2 code. - `amount_mode` 'send' | 'receive', required: Side fixed by the accepted quote. - `fee_paid_by` 'PAYER' | 'BENEFICIARY', required: Party responsible for payout fees. - `sending_amount` string, required: Actual total source-balance debit. - `receiving_amount` string, required: Amount delivered to the recipient. - `transfer_fee_amount` string, required: Infini service fee frozen by the quote. - `bank_fee_amount` string, required: Banking fee frozen by the quote. - `fee_rate_decimal` string, required: Decimal transfer-fee rate frozen by the quote. - `rate` string, required: Exchange rate frozen by the quote. - `billing` BillingBreakdown, required - `currency` 'USD', required: Currency used by all billing amounts. - `transfer_fee` string, required: Infini service fee for processing the payout. It does not include any bank or rail fee. - `fx_fee` string, required: Foreign-exchange fee. It is `0.00` for the current USD-to-USD route. - `rail_fee` string, required: Banking fee associated with the selected bank and payout rail. - `total_fee` string, required: Sum of all fee components in the billing breakdown. - `fee_lines` FeeLine[], required: Itemized fee components used for reconciliation. - `type` 'transfer_fee' | 'fx_fee' | 'rail_fee', required: Fee component type. - `amount` string, required: Fee component amount in `currency`. - `currency` 'USD', required: Fee component currency. - `rate` string, required: Decimal rate used for this fee line, or `1` for a fixed rail fee. - `destination` BankDestinationView, required - `type` 'bank_account', required: Destination type. - `account_holder_type` 'individual' | 'business', required: Legal type of the bank-account holder. - `account_holder_name` string, required: Full legal name registered on the bank account. - `bank_country` string, required: Bank country as an ISO 3166-1 alpha-2 code. - `bank_name` string, required: Receiving bank's legal name. - `account_number_masked` string, required: Masked account number. Raw account details are never returned. - `swift_code` string, required: Receiving bank SWIFT/BIC code. - `purpose_code` string, required: Business purpose supplied at creation. - `statement_reference` string, nullable, required: Recipient-facing reference when supported. - `bank_reference` string, nullable, required: Bank transfer reference when available. - `failure` Failure, nullable, required: Failure details when the payout could not be completed; otherwise null. - `code` string, required: Stable machine-readable payout failure code. - `message` string, required: Human-readable payout failure details. - `return` PayoutReturn, nullable, required: Compensating refund created after a receiving bank returns a completed payout; otherwise null. The original payout remains `completed`. - `status` 'refunded', required: Settlement state of the compensating refund. - `reason_code` 'recipient_bank_rejected', required: Stable machine-readable reason for the bank return. - `reason` string, required: Human-readable bank-return reason when supplied by the banking partner. - `returned_amount` string, required: Amount the banking partner reported as returned. - `refund_amount` string, required: Amount actually credited back to the organization's balance after retained fees. - `retained_fee` string, required: Original payout fee retained and not included in `refund_amount`. - `currency` 'USD', required: Currency of the return, refund, and retained-fee amounts. - `returned_at` integer, required: Time the compensating refund was recorded, as Unix seconds. - `created_at` integer, required: Payout creation time as Unix seconds. - `updated_at` integer, required: Payout last-update time as Unix seconds. - `completed_at` integer, nullable, required: Payout completion time as Unix seconds when available. - `total` integer, required: Total number of payouts matching the time range. - `page` integer, required: Current page number. - `page_size` integer, required: Requested page size. - `total_pages` integer, required: Total number of pages. ## Other responses - `400`: Request syntax or field validation failed - `401`: Authentication failed: invalid/disabled credential, signature, timestamp, nonce or digest. - `403`: Authenticated credential lacks permission or the client IP is not allowed. - `500`: An unexpected internal error occurred ## Changes - **2026-10-23** `25c3ff16936d`: 7 breaking, 1 warning - added the new required `header` request parameter `X-API-Key-ID` - added the new required `header` request parameter `X-API-Nonce` - added the new required `header` request parameter `X-API-Timestamp` - the `header` request parameter `Authorization` became required - …4 more - **2026-08-25** `b24d213661e9`: 3 breaking, 1 warning, 34 info - added the new required request property `end_time` - added the new required request property `start_time` - the `allOf[subschema #2]/data/payouts/items/` response's property type changed from no type to `object` for status `200` - removed the request property `payout_ids` - …34 more - **2026-08-25** `239598a803f5`: 1 info - endpoint added [Operation history](https://skmtc.dev/infini/apis/infini-fiat-payout-api/changes/v2/payouts/status/batch/post.md) --- [API](https://skmtc.dev/infini/apis/infini-fiat-payout-api.md) - [All operations](https://skmtc.dev/infini/apis/infini-fiat-payout-api/llms.txt) - [OpenAPI document](https://skmtc.dev/infini/apis/infini-fiat-payout-api/revisions/25c3ff16936d?raw)