{ "openapi": "3.0.0", "info": { "title": "Infini Fiat Payout API", "version": "0.4.0", "description": "The Fiat Payout API lets an organization quote, create, and query direct USD bank payouts from its Infini USD balance to a third-party bank account.\n\nAll endpoints use the `/v2/payouts` prefix. Requests require [HMAC-SHA256 authentication](/docs/en/4-authorization) and an API key with the relevant payout permission.\n\n`POST /v2/payouts` does not enter the dashboard approval workflow. Infini performs final authorization, compliance, quote, destination, limit, and available-balance checks and then starts payout execution immediately. Bank settlement is asynchronous, so a successful create response normally has `status=processing`; it does not guarantee that the receiving bank account has already been credited." }, "servers": [ { "url": "https://openapi.infini.money", "description": "Production" }, { "url": "https://openapi-sandbox.infini.money", "description": "Sandbox" } ], "tags": [ { "name": "Quotes", "description": "Time-limited payout pricing and destination validation" }, { "name": "Payouts", "description": "Direct fiat payout execution and status" } ], "paths": { "/v2/payouts/quotes": { "post": { "operationId": "createFiatPayoutQuote", "summary": "Create a payout quote", "description": "Validates one bank destination and returns a time-limited payout quote. Requires `payout.write` permission.\n\nThe destination is submitted inline because this release does not expose a separate recipient resource. Infini binds a normalized, immutable destination snapshot to `quote_id`. The payout create request cannot replace or modify it.\n\nThe first release supports only these amount and fee-responsibility combinations:\n\n- `amount_mode=send` with `fee_paid_by=BENEFICIARY`: fees are deducted internally. `amount` fixes `sending_amount`; `transfer_fee_amount = sending_amount × fee_rate_decimal`; and `receiving_amount = sending_amount - transfer_fee_amount - bank_fee_amount`. For `amount=1000.00`, rate `0.001`, and bank fee `50.00`, the recipient receives `949.00`.\n- `amount_mode=receive` with `fee_paid_by=PAYER`: fees are deducted externally. `amount` fixes `receiving_amount`; `transfer_fee_amount = sending_amount × fee_rate_decimal`; and `sending_amount = receiving_amount + transfer_fee_amount + bank_fee_amount`. For `amount=1000.00`, rate `0.001`, and bank fee `50.00`, the source balance is debited `1051.05`.\n\nIn `receive` mode, Infini grosses up `sending_amount` until the recipient amount remains exact after all fees.\n\nChanging `fee_paid_by` changes the calculation and requires a new quote. The accepted `quote_id` locks the fee responsibility and both calculated amounts used by the payout.\n\nThe quote step performs preliminary destination, route, amount, compliance, and limit checks. It does not reserve balance, approve a payout, create a payout, or guarantee execution. `POST /v2/payouts` repeats all execution-critical checks against current state.", "tags": [ "Quotes" ], "parameters": [ { "$ref": "#/components/parameters/DateHeader" }, { "$ref": "#/components/parameters/AuthorizationHeader" }, { "$ref": "#/components/parameters/DigestHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQuoteRequest" }, "example": { "amount": "1000.00", "amount_mode": "receive", "fee_paid_by": "PAYER", "source_currency": "USD", "destination_currency": "USD", "destination_country": "US", "payout_type": "swift", "destination": { "type": "bank_account", "account_holder_type": "business", "account_holder_name": "Acme Supplies LLC", "bank_country": "US", "bank_name": "Example Bank", "account_number": "9876543210", "swift_code": "BOFAUS3NXXX", "address": { "line1": "123 Market Street", "line2": "Suite 500", "city": "New York", "state": "NY", "postal_code": "10001", "country": "US" } } } } } }, "responses": { "200": { "description": "Time-limited payout quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteEnvelope" }, "example": { "code": 0, "message": "", "data": { "quote_id": "poq_01JQ90B8S5VJ6R3T7F1M2C4N9X", "provider": "sgb", "payout_type": "swift", "source_currency": "USD", "destination_currency": "USD", "destination_country": "US", "amount_mode": "receive", "fee_paid_by": "PAYER", "sending_amount": "1051.05", "receiving_amount": "1000.00", "transfer_fee_amount": "1.05", "bank_fee_amount": "50.00", "fee_rate_decimal": "0.001", "rate": "1", "billing": { "currency": "USD", "transfer_fee": "1.05", "fx_fee": "0.00", "rail_fee": "50.00", "total_fee": "51.05", "fee_lines": [ { "type": "transfer_fee", "amount": "1.05", "currency": "USD", "rate": "0.001" }, { "type": "rail_fee", "amount": "50.00", "currency": "USD", "rate": "1" } ] }, "destination": { "type": "bank_account", "account_holder_type": "business", "account_holder_name": "Acme Supplies LLC", "bank_country": "US", "bank_name": "Example Bank", "account_number_masked": "******3210", "swift_code": "BOFAUS3NXXX" }, "expires_at": 1786586700 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL (HMAC)", "source": "curl -i -X POST \\\n '{{INFINI_BASE_URL}}/v2/payouts/quotes' \\\n -H 'Content-Type: application/json' \\\n -H 'Date: ' \\\n -H 'Digest: SHA-256=' \\\n -H 'Authorization: Signature keyId=\"{{INFINI_KEY_ID}}\",algorithm=\"hmac-sha256\",headers=\"@request-target date\",signature=\"\"' \\\n -d '{\n \"amount\": \"1000.00\",\n \"amount_mode\": \"receive\",\n \"fee_paid_by\": \"PAYER\",\n \"source_currency\": \"USD\",\n \"destination_currency\": \"USD\",\n \"destination_country\": \"US\",\n \"payout_type\": \"swift\",\n \"destination\": {\n \"type\": \"bank_account\",\n \"account_holder_type\": \"business\",\n \"account_holder_name\": \"Acme Supplies LLC\",\n \"bank_country\": \"US\",\n \"bank_name\": \"Example Bank\",\n \"account_number\": \"9876543210\",\n \"swift_code\": \"BOFAUS3NXXX\",\n \"address\": {\n \"line1\": \"123 Market Street\",\n \"line2\": \"Suite 500\",\n \"city\": \"New York\",\n \"state\": \"NY\",\n \"postal_code\": \"10001\",\n \"country\": \"US\"\n }\n }\n }'" } ] } }, "/v2/payouts": { "post": { "operationId": "createFiatPayout", "summary": "Create a fiat payout", "description": "Creates and immediately starts a payout using a valid quote. Requires `payout.write` permission. The payout does not enter the dashboard approval workflow.\n\n`quote_id` binds the provider, destination snapshot, source and destination currencies, payout rail, amount mode, fee responsibility, exchange rate, amounts, and fee breakdown. Do not repeat those fields in this request.\n\nThis operation performs the authoritative pre-execution checks, including API-key ownership and permissions, quote ownership and expiry, request-to-quote consistency, account and destination validation, compliance controls, limits, available balance, execution-provider availability, and idempotency.\n\n`client_reference_id` must uniquely identify one logical payout within the authenticated organization. Retrying the same business request returns the existing payout with `is_duplicate=true`. Reusing the value with different request data returns a conflict.\n\nA successful response means the payout was accepted and bank execution started. It does not mean the receiving bank has credited the account. Use `GET /v2/payouts/{payout_id}` to obtain the latest state.\n\nOnly one payout submission per organization can enter execution at a time. A concurrent submission is rejected with `108015 payout_submission_in_progress` before the quote is consumed, a payout is created, or the balance is debited. Retry after a short randomized delay and keep the same `client_reference_id` for the same logical payout.", "tags": [ "Payouts" ], "parameters": [ { "$ref": "#/components/parameters/DateHeader" }, { "$ref": "#/components/parameters/AuthorizationHeader" }, { "$ref": "#/components/parameters/DigestHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePayoutRequest" }, "example": { "client_reference_id": "payout_20260730_0001", "quote_id": "poq_01JQ90B8S5VJ6R3T7F1M2C4N9X", "purpose_code": "goods_and_services", "statement_reference": "INV-2026-0730" } } } }, "responses": { "200": { "description": "Payout created or an idempotent existing payout returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutEnvelope" }, "example": { "code": 0, "message": "", "data": { "payout_id": "fpo_01JQ90GQJTC5P7B2D8N6R4K1MX", "client_reference_id": "payout_20260730_0001", "quote_id": "poq_01JQ90B8S5VJ6R3T7F1M2C4N9X", "provider": "sgb", "status": "processing", "payout_type": "swift", "source_currency": "USD", "destination_currency": "USD", "destination_country": "US", "amount_mode": "receive", "fee_paid_by": "PAYER", "sending_amount": "1051.05", "receiving_amount": "1000.00", "transfer_fee_amount": "1.05", "bank_fee_amount": "50.00", "fee_rate_decimal": "0.001", "rate": "1", "billing": { "currency": "USD", "transfer_fee": "1.05", "fx_fee": "0.00", "rail_fee": "50.00", "total_fee": "51.05", "fee_lines": [ { "type": "transfer_fee", "amount": "1.05", "currency": "USD", "rate": "0.001" }, { "type": "rail_fee", "amount": "50.00", "currency": "USD", "rate": "1" } ] }, "destination": { "type": "bank_account", "account_holder_type": "business", "account_holder_name": "Acme Supplies LLC", "bank_country": "US", "bank_name": "Example Bank", "account_number_masked": "******3210", "swift_code": "BOFAUS3NXXX" }, "purpose_code": "goods_and_services", "statement_reference": "INV-2026-0730", "bank_reference": null, "failure": null, "return": null, "is_duplicate": false, "created_at": 1786587000, "updated_at": 1786587001, "completed_at": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL (HMAC)", "source": "curl -i -X POST \\\n '{{INFINI_BASE_URL}}/v2/payouts' \\\n -H 'Content-Type: application/json' \\\n -H 'Date: ' \\\n -H 'Digest: SHA-256=' \\\n -H 'Authorization: Signature keyId=\"{{INFINI_KEY_ID}}\",algorithm=\"hmac-sha256\",headers=\"@request-target date\",signature=\"\"' \\\n -d '{\n \"client_reference_id\": \"payout_20260730_0001\",\n \"quote_id\": \"poq_01JQ90B8S5VJ6R3T7F1M2C4N9X\",\n \"purpose_code\": \"goods_and_services\",\n \"statement_reference\": \"INV-2026-0730\"\n }'" } ] } }, "/v2/payouts/status/batch": { "post": { "operationId": "batchGetFiatPayoutStatuses", "summary": "List fiat payout statuses", "description": "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.\n\nResults are ordered by creation time descending and use page-based pagination. `page` defaults to `1`; `page_size` defaults to `20` and cannot exceed `100`.\n\nUse this endpoint for periodic time-window reconciliation. Use `GET /v2/payouts/{payout_id}` when retrieving one known payout.", "tags": [ "Payouts" ], "parameters": [ { "$ref": "#/components/parameters/DateHeader" }, { "$ref": "#/components/parameters/AuthorizationHeader" }, { "$ref": "#/components/parameters/DigestHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchPayoutStatusRequest" }, "example": { "start_time": 1786500000, "end_time": 1786599999, "page": 1, "page_size": 20 } } } }, "responses": { "200": { "description": "Payout statuses in creation-time descending order with pagination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchPayoutStatusEnvelope" }, "example": { "code": 0, "message": "", "data": { "payouts": [ { "payout_id": "fpo_01JQ90GQJTC5P7B2D8N6R4K1MX", "client_reference_id": "payout_20260730_0001", "quote_id": "poq_01JQ90B8S5VJ6R3T7F1M2C4N9X", "provider": "sgb", "status": "completed", "payout_type": "swift", "source_currency": "USD", "destination_currency": "USD", "destination_country": "US", "amount_mode": "receive", "fee_paid_by": "PAYER", "sending_amount": "1051.05", "receiving_amount": "1000.00", "transfer_fee_amount": "1.05", "bank_fee_amount": "50.00", "fee_rate_decimal": "0.001", "rate": "1", "billing": { "currency": "USD", "transfer_fee": "1.05", "fx_fee": "0.00", "rail_fee": "50.00", "total_fee": "51.05", "fee_lines": [ { "type": "transfer_fee", "amount": "1.05", "currency": "USD", "rate": "0.001" }, { "type": "rail_fee", "amount": "50.00", "currency": "USD", "rate": "1" } ] }, "destination": { "type": "bank_account", "account_holder_type": "business", "account_holder_name": "Acme Supplies LLC", "bank_country": "US", "bank_name": "Example Bank", "account_number_masked": "******3210", "swift_code": "BOFAUS3NXXX" }, "purpose_code": "goods_and_services", "statement_reference": "INV-2026-0730", "bank_reference": "RMTO2084957259539812352", "failure": null, "return": null, "created_at": 1786587000, "updated_at": 1786587871, "completed_at": 1786587871 } ], "total": 1, "page": 1, "page_size": 20, "total_pages": 1 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL (HMAC)", "source": "curl -i -X POST \\\n '{{INFINI_BASE_URL}}/v2/payouts/status/batch' \\\n -H 'Content-Type: application/json' \\\n -H 'Date: ' \\\n -H 'Digest: SHA-256=' \\\n -H 'Authorization: Signature keyId=\"{{INFINI_KEY_ID}}\",algorithm=\"hmac-sha256\",headers=\"@request-target date\",signature=\"\"' \\\n -d '{\n \"start_time\": 1786500000,\n \"end_time\": 1786599999,\n \"page\": 1,\n \"page_size\": 20\n }'" } ] } }, "/v2/payouts/{payout_id}": { "get": { "operationId": "getFiatPayout", "summary": "Get a fiat payout", "description": "Returns the latest payout state for the authenticated organization. Requires `payout.read` permission.\n\n`processing` means execution is still in progress. `completed` means the payout completed successfully. A receiving bank can still reject and return a previously completed transfer; the original payout remains `completed`, while the optional `return` object describes the bank return and compensating refund. `failed` means the payout failed before successful bank completion.", "tags": [ "Payouts" ], "parameters": [ { "$ref": "#/components/parameters/PayoutId" }, { "$ref": "#/components/parameters/DateHeader" }, { "$ref": "#/components/parameters/AuthorizationHeader" } ], "responses": { "200": { "description": "Current payout state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutEnvelope" }, "examples": { "processing": { "summary": "Processing payout", "value": { "code": 0, "message": "", "data": { "payout_id": "fpo_01JQ90GQJTC5P7B2D8N6R4K1MX", "client_reference_id": "payout_20260730_0001", "quote_id": "poq_01JQ90B8S5VJ6R3T7F1M2C4N9X", "provider": "sgb", "status": "processing", "payout_type": "swift", "source_currency": "USD", "destination_currency": "USD", "destination_country": "US", "amount_mode": "receive", "fee_paid_by": "PAYER", "sending_amount": "1051.05", "receiving_amount": "1000.00", "transfer_fee_amount": "1.05", "bank_fee_amount": "50.00", "fee_rate_decimal": "0.001", "rate": "1", "billing": { "currency": "USD", "transfer_fee": "1.05", "fx_fee": "0.00", "rail_fee": "50.00", "total_fee": "51.05", "fee_lines": [ { "type": "transfer_fee", "amount": "1.05", "currency": "USD", "rate": "0.001" }, { "type": "rail_fee", "amount": "50.00", "currency": "USD", "rate": "1" } ] }, "destination": { "type": "bank_account", "account_holder_type": "business", "account_holder_name": "Acme Supplies LLC", "bank_country": "US", "bank_name": "Example Bank", "account_number_masked": "******3210", "swift_code": "BOFAUS3NXXX" }, "purpose_code": "goods_and_services", "statement_reference": "INV-2026-0730", "bank_reference": null, "failure": null, "return": null, "is_duplicate": false, "created_at": 1786587000, "updated_at": 1786587001, "completed_at": null } } }, "completed": { "summary": "Completed payout", "value": { "code": 0, "message": "", "data": { "payout_id": "fpo_01JQ90GQJTC5P7B2D8N6R4K1MX", "client_reference_id": "payout_20260730_0001", "quote_id": "poq_01JQ90B8S5VJ6R3T7F1M2C4N9X", "provider": "sgb", "status": "completed", "payout_type": "swift", "source_currency": "USD", "destination_currency": "USD", "destination_country": "US", "amount_mode": "receive", "fee_paid_by": "PAYER", "sending_amount": "1051.05", "receiving_amount": "1000.00", "transfer_fee_amount": "1.05", "bank_fee_amount": "50.00", "fee_rate_decimal": "0.001", "rate": "1", "billing": { "currency": "USD", "transfer_fee": "1.05", "fx_fee": "0.00", "rail_fee": "50.00", "total_fee": "51.05", "fee_lines": [ { "type": "transfer_fee", "amount": "1.05", "currency": "USD", "rate": "0.001" }, { "type": "rail_fee", "amount": "50.00", "currency": "USD", "rate": "1" } ] }, "destination": { "type": "bank_account", "account_holder_type": "business", "account_holder_name": "Acme Supplies LLC", "bank_country": "US", "bank_name": "Example Bank", "account_number_masked": "******3210", "swift_code": "BOFAUS3NXXX" }, "purpose_code": "goods_and_services", "statement_reference": "INV-2026-0730", "bank_reference": "RMTO2084957259539812352", "failure": null, "return": null, "is_duplicate": false, "created_at": 1786587000, "updated_at": 1786587871, "completed_at": 1786587871 } } }, "bank_returned": { "summary": "Completed payout later returned by the receiving bank", "value": { "code": 0, "message": "", "data": { "payout_id": "fpo_01JQ90GQJTC5P7B2D8N6R4K1MX", "client_reference_id": "payout_20260730_0001", "quote_id": "poq_01JQ90B8S5VJ6R3T7F1M2C4N9X", "provider": "sgb", "status": "completed", "payout_type": "swift", "source_currency": "USD", "destination_currency": "USD", "destination_country": "US", "amount_mode": "receive", "fee_paid_by": "PAYER", "sending_amount": "1051.05", "receiving_amount": "1000.00", "transfer_fee_amount": "1.05", "bank_fee_amount": "50.00", "fee_rate_decimal": "0.001", "rate": "1", "billing": { "currency": "USD", "transfer_fee": "1.05", "fx_fee": "0.00", "rail_fee": "50.00", "total_fee": "51.05", "fee_lines": [ { "type": "transfer_fee", "amount": "1.05", "currency": "USD", "rate": "0.001" }, { "type": "rail_fee", "amount": "50.00", "currency": "USD", "rate": "1" } ] }, "destination": { "type": "bank_account", "account_holder_type": "business", "account_holder_name": "Acme Supplies LLC", "bank_country": "US", "bank_name": "Example Bank", "account_number_masked": "******3210", "swift_code": "BOFAUS3NXXX" }, "purpose_code": "goods_and_services", "statement_reference": "INV-2026-0730", "bank_reference": "RMTO2084957259539812352", "failure": null, "return": { "status": "refunded", "reason_code": "recipient_bank_rejected", "reason": "Beneficiary bank rejected the transfer", "returned_amount": "1000.00", "refund_amount": "1000.00", "retained_fee": "51.05", "currency": "USD", "returned_at": 1786674271 }, "is_duplicate": false, "created_at": 1786587000, "updated_at": 1786674271, "completed_at": 1786587871 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL (HMAC)", "source": "curl -i -X GET \\\n '{{INFINI_BASE_URL}}/v2/payouts/fpo_01JQ90GQJTC5P7B2D8N6R4K1MX' \\\n -H 'Date: ' \\\n -H 'Authorization: Signature keyId=\"{{INFINI_KEY_ID}}\",algorithm=\"hmac-sha256\",headers=\"@request-target date\",signature=\"\"'" } ] } } }, "components": { "parameters": { "DateHeader": { "name": "Date", "in": "header", "required": false, "description": "GMT server time, e.g. Tue, 21 Jan 2025 12:00:00 GMT. Required on the wire; the Try it signer injects it automatically.", "schema": { "type": "string", "example": "Tue, 30 Jul 2026 08:50:00 GMT" } }, "AuthorizationHeader": { "name": "Authorization", "in": "header", "required": false, "description": "HMAC-SHA256 `Signature` header. Required on the wire; the Try it signer injects it automatically. See the [Authentication](/docs/en/4-authorization) guide.", "schema": { "type": "string", "example": "Signature keyId=\"key_example\",algorithm=\"hmac-sha256\",headers=\"@request-target date\",signature=\"\"" } }, "DigestHeader": { "name": "Digest", "in": "header", "required": false, "description": "SHA-256 digest required on the wire when a body is present; the Try it signer injects it automatically.", "schema": { "type": "string", "example": "SHA-256=" } }, "PayoutId": { "name": "payout_id", "in": "path", "required": true, "description": "Infini fiat payout ID.", "schema": { "type": "string", "example": "fpo_01JQ90GQJTC5P7B2D8N6R4K1MX" } } }, "responses": { "BadRequest": { "description": "Request syntax or field validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "code": 30013, "message": "amount must be a positive decimal string", "data": { "error": "invalid_parameter", "field": "amount", "retryable": false } } } } }, "Unauthorized": { "description": "HMAC gateway validation or application authentication failed", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "$ref": "#/components/schemas/GatewayError" } ] }, "examples": { "gatewayAuthenticationFailed": { "summary": "Gateway could not validate the signed request", "value": { "message": "client request can't be validated" } }, "applicationAuthenticationFailed": { "summary": "Application authentication context is invalid", "value": { "code": 401, "message": "Unauthorized", "data": { "error": "authentication_failed", "field": null, "retryable": false } } } } } } }, "Forbidden": { "description": "API key permission, IP whitelist, or organization eligibility rejected the request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "$ref": "#/components/schemas/GatewayError" } ] }, "examples": { "permissionDenied": { "summary": "Payout access denied by permission or network policy", "value": { "code": 403, "message": "Payout access is denied", "data": { "error": "permission_denied", "field": null, "retryable": false } } }, "payoutSourceAccountNotFound": { "summary": "Organization does not have a USD payout account", "value": { "code": 108010, "message": "USD payout account is not available for this organization", "data": { "error": "payout_source_account_not_found", "field": null, "retryable": false } } } } } } }, "NotFound": { "description": "Resource was not found for the authenticated organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "payoutNotFound": { "summary": "Payout does not exist for the authenticated organization", "value": { "code": 404, "message": "Payout does not exist", "data": { "error": "resource_not_found", "field": "payout_id", "retryable": false } } }, "quoteNotFound": { "summary": "Quote does not exist for the authenticated organization", "value": { "code": 404, "message": "Quote does not exist", "data": { "error": "resource_not_found", "field": "quote_id", "retryable": false } } } } } } }, "Conflict": { "description": "The request conflicts with idempotency, quote state, or another payout submission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "idempotencyConflict": { "summary": "Idempotency reference reused with different request data", "value": { "code": 108012, "message": "client_reference_id was already used for a different request", "data": { "error": "idempotency_conflict", "field": "client_reference_id", "retryable": false } } }, "quoteAlreadyUsed": { "summary": "Quote has already been consumed", "value": { "code": 108013, "message": "Quote has already been used", "data": { "error": "quote_already_used", "field": "quote_id", "retryable": false } } }, "quoteNotActive": { "summary": "Quote is not active", "value": { "code": 108014, "message": "Quote is not active", "data": { "error": "quote_not_active", "field": "quote_id", "retryable": false } } }, "submissionInProgress": { "summary": "Another payout submission is in progress for the organization", "value": { "code": 108015, "message": "Another payout submission is in progress. Please retry shortly.", "data": { "error": "payout_submission_in_progress", "field": null, "retryable": true } } }, "payoutSourceAccountInvalid": { "summary": "USD payout account configuration is inconsistent", "value": { "code": 108011, "message": "USD payout account configuration is invalid. Contact support.", "data": { "error": "payout_source_account_invalid", "field": null, "retryable": false } } } } } } }, "UnprocessableEntity": { "description": "Request is syntactically valid but cannot pass payout eligibility or execution checks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "invalidFeeMode": { "summary": "Invalid fee mode", "value": { "code": 108001, "message": "amount_mode and fee_paid_by are not supported together", "data": { "error": "invalid_fee_mode", "field": "fee_paid_by", "retryable": false } } }, "quoteExpired": { "summary": "Quote expired", "value": { "code": 108002, "message": "Quote has expired", "data": { "error": "quote_expired", "field": "quote_id", "retryable": true } } }, "quoteUnavailable": { "summary": "Quote is temporarily unavailable", "value": { "code": 108003, "message": "Payout quote is temporarily unavailable", "data": { "error": "quote_unavailable", "field": null, "retryable": true } } }, "amountExceedsLimit": { "summary": "Amount exceeds the supported limit", "value": { "code": 108004, "message": "Payout amount exceeds the supported limit", "data": { "error": "amount_exceeds_limit", "field": "amount", "retryable": false } } }, "amountTooSmall": { "summary": "Amount is below the supported minimum", "value": { "code": 108005, "message": "Payout sending amount must be greater than 100 USD", "data": { "error": "amount_too_small", "field": "amount", "retryable": false } } }, "insufficientBalance": { "summary": "Insufficient balance", "value": { "code": 108006, "message": "Insufficient payout balance", "data": { "error": "insufficient_balance", "field": "amount", "retryable": false } } }, "dailyLimitExceeded": { "summary": "Amount would exceed the account's shared daily withdrawal limit", "value": { "code": 108007, "message": "Payout would exceed the account's daily withdrawal limit", "data": { "error": "daily_limit_exceeded", "field": "amount", "retryable": false } } } } } } }, "ServiceUnavailable": { "description": "Payout execution service or provider liquidity is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "code": 108009, "message": "Payout service is temporarily unavailable. Please try again later.", "data": { "error": "payout_service_unavailable", "field": null, "retryable": true } } } } }, "InternalError": { "description": "An unexpected internal error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "code": 500, "message": "An error occurred internally", "data": { "error": "internal_error", "field": null, "retryable": true } } } } } }, "schemas": { "StandardEnvelope": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "enum": [ 0 ], "description": "Business code. `0` means success.", "example": 0 }, "message": { "type": "string", "description": "Response message.", "example": "" } } }, "ErrorEnvelope": { "type": "object", "required": [ "code", "message", "data" ], "properties": { "code": { "type": "integer", "minimum": 1, "description": "Stable non-zero business error code. Fiat Payout-specific errors use the reserved 108001-108099 range.", "example": 108002 }, "message": { "type": "string", "description": "Human-readable error details for troubleshooting, not program control.", "example": "Quote has expired" }, "data": { "$ref": "#/components/schemas/ErrorData" } } }, "ErrorData": { "type": "object", "required": [ "error", "field", "retryable" ], "properties": { "error": { "type": "string", "description": "Stable machine-readable error identifier.", "example": "quote_expired" }, "field": { "type": "string", "nullable": true, "description": "Request field related to the error, when applicable.", "example": "quote_id" }, "retryable": { "type": "boolean", "description": "Whether retrying after correcting transient state can succeed.", "example": true } } }, "GatewayError": { "type": "object", "additionalProperties": false, "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Gateway validation error.", "example": "client request can't be validated" } } }, "CreateQuoteRequest": { "type": "object", "additionalProperties": false, "required": [ "amount", "amount_mode", "fee_paid_by", "source_currency", "destination_currency", "destination_country", "payout_type", "destination" ], "properties": { "amount": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,2})?$", "description": "Positive USD amount expressed according to `amount_mode`.", "example": "1000.00" }, "amount_mode": { "type": "string", "enum": [ "send", "receive" ], "description": "Side fixed by `amount`. `send` is the source-account debit; `receive` is the recipient amount.", "example": "receive" }, "fee_paid_by": { "type": "string", "enum": [ "PAYER", "BENEFICIARY" ], "description": "Fee responsibility and calculation input. `PAYER` applies fees externally; `BENEFICIARY` deducts fees internally. The first release accepts `receive` with `PAYER`, or `send` with `BENEFICIARY`.", "example": "PAYER" }, "source_currency": { "type": "string", "enum": [ "USD" ], "description": "Organization balance currency. The first release supports USD only.", "example": "USD" }, "destination_currency": { "type": "string", "enum": [ "USD" ], "description": "Currency delivered to the recipient. Payout quotes currently support USD only.", "example": "USD" }, "destination_country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Destination country as an ISO 3166-1 alpha-2 code.", "example": "US" }, "payout_type": { "type": "string", "enum": [ "swift" ], "description": "Payout rail. The current release supports SWIFT only.", "example": "swift" }, "destination": { "$ref": "#/components/schemas/BankDestinationInput" } } }, "BankDestinationInput": { "type": "object", "additionalProperties": false, "required": [ "type", "account_holder_type", "account_holder_name", "bank_country", "bank_name", "account_number", "swift_code" ], "properties": { "type": { "type": "string", "enum": [ "bank_account" ], "description": "Destination type.", "example": "bank_account" }, "account_holder_type": { "type": "string", "enum": [ "individual", "business" ], "description": "Legal type of the bank-account holder.", "example": "business" }, "account_holder_name": { "type": "string", "minLength": 1, "maxLength": 140, "description": "Full legal name registered on the bank account.", "example": "Acme Supplies LLC" }, "bank_country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Bank country as an ISO 3166-1 alpha-2 code.", "example": "US" }, "bank_name": { "type": "string", "minLength": 1, "maxLength": 140, "description": "Receiving bank's legal name.", "example": "Example Bank" }, "account_number": { "type": "string", "minLength": 4, "maxLength": 34, "writeOnly": true, "description": "Receiving bank account number.", "example": "9876543210" }, "swift_code": { "type": "string", "pattern": "^[A-Z0-9]{8}([A-Z0-9]{3})?$", "description": "Receiving bank SWIFT/BIC code.", "example": "BOFAUS3NXXX" }, "address": { "$ref": "#/components/schemas/PostalAddress" } } }, "PostalAddress": { "type": "object", "additionalProperties": false, "required": [ "line1", "city", "postal_code", "country" ], "properties": { "line1": { "type": "string", "description": "Primary street address.", "example": "123 Market Street" }, "line2": { "type": "string", "nullable": true, "description": "Secondary address details.", "example": "Suite 500" }, "city": { "type": "string", "description": "City or locality.", "example": "New York" }, "state": { "type": "string", "nullable": true, "description": "State, province, or region.", "example": "NY" }, "postal_code": { "type": "string", "description": "Postal or ZIP code.", "example": "10001" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Address country as an ISO 3166-1 alpha-2 code.", "example": "US" } } }, "BankDestinationView": { "type": "object", "required": [ "type", "account_holder_type", "account_holder_name", "bank_country", "bank_name", "account_number_masked", "swift_code" ], "properties": { "type": { "type": "string", "enum": [ "bank_account" ], "description": "Destination type.", "example": "bank_account" }, "account_holder_type": { "type": "string", "enum": [ "individual", "business" ], "description": "Legal type of the bank-account holder.", "example": "business" }, "account_holder_name": { "type": "string", "description": "Full legal name registered on the bank account.", "example": "Acme Supplies LLC" }, "bank_country": { "type": "string", "description": "Bank country as an ISO 3166-1 alpha-2 code.", "example": "US" }, "bank_name": { "type": "string", "description": "Receiving bank's legal name.", "example": "Example Bank" }, "account_number_masked": { "type": "string", "description": "Masked account number. Raw account details are never returned.", "example": "******3210" }, "swift_code": { "type": "string", "description": "Receiving bank SWIFT/BIC code.", "example": "BOFAUS3NXXX" } } }, "FeeLine": { "type": "object", "additionalProperties": false, "required": [ "type", "amount", "currency", "rate" ], "properties": { "type": { "type": "string", "enum": [ "transfer_fee", "fx_fee", "rail_fee" ], "description": "Fee component type.", "example": "transfer_fee" }, "amount": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,2})?$", "description": "Fee component amount in `currency`.", "example": "1.05" }, "currency": { "type": "string", "enum": [ "USD" ], "description": "Fee component currency.", "example": "USD" }, "rate": { "type": "string", "description": "Decimal rate used for this fee line, or `1` for a fixed rail fee.", "example": "0.001" } } }, "BillingBreakdown": { "type": "object", "additionalProperties": false, "required": [ "currency", "transfer_fee", "fx_fee", "rail_fee", "total_fee", "fee_lines" ], "properties": { "currency": { "type": "string", "enum": [ "USD" ], "description": "Currency used by all billing amounts.", "example": "USD" }, "transfer_fee": { "type": "string", "description": "Infini service fee for processing the payout. It does not include any bank or rail fee.", "example": "1.05" }, "fx_fee": { "type": "string", "description": "Foreign-exchange fee. It is `0.00` for the current USD-to-USD route.", "example": "0.00" }, "rail_fee": { "type": "string", "description": "Banking fee associated with the selected bank and payout rail.", "example": "50.00" }, "total_fee": { "type": "string", "description": "Sum of all fee components in the billing breakdown.", "example": "51.05" }, "fee_lines": { "type": "array", "description": "Itemized fee components used for reconciliation.", "items": { "$ref": "#/components/schemas/FeeLine" } } } }, "Quote": { "type": "object", "required": [ "quote_id", "provider", "payout_type", "source_currency", "destination_currency", "destination_country", "amount_mode", "fee_paid_by", "sending_amount", "receiving_amount", "transfer_fee_amount", "bank_fee_amount", "fee_rate_decimal", "rate", "billing", "destination", "expires_at" ], "properties": { "quote_id": { "type": "string", "description": "Time-limited payout quote ID.", "example": "poq_01JQ90B8S5VJ6R3T7F1M2C4N9X" }, "provider": { "type": "string", "enum": [ "sgb" ], "readOnly": true, "description": "Read-only execution provider identifier.", "example": "sgb" }, "payout_type": { "type": "string", "enum": [ "swift" ], "description": "Payout rail bound to the quote.", "example": "swift" }, "source_currency": { "type": "string", "enum": [ "USD" ], "description": "Organization balance currency.", "example": "USD" }, "destination_currency": { "type": "string", "enum": [ "USD" ], "description": "Currency delivered to the recipient.", "example": "USD" }, "destination_country": { "type": "string", "description": "Destination country as an ISO 3166-1 alpha-2 code.", "example": "US" }, "amount_mode": { "type": "string", "enum": [ "send", "receive" ], "description": "Side fixed by the quote request.", "example": "receive" }, "fee_paid_by": { "type": "string", "enum": [ "PAYER", "BENEFICIARY" ], "description": "Party responsible for payout fees. `PAYER` means external deduction; `BENEFICIARY` means internal deduction.", "example": "PAYER" }, "sending_amount": { "type": "string", "description": "Total amount debited from the organization's source balance. Use this as the outgoing amount for reconciliation.", "example": "1051.05" }, "receiving_amount": { "type": "string", "description": "Amount delivered to the recipient.", "example": "1000.00" }, "transfer_fee_amount": { "type": "string", "description": "Infini service fee for processing the payout. It excludes any bank or rail fee and equals `billing.transfer_fee`.", "example": "1.05" }, "bank_fee_amount": { "type": "string", "description": "Banking fee associated with the selected bank and payout rail, such as SWIFT, ACH, or wire. This equals `billing.rail_fee`.", "example": "50.00" }, "fee_rate_decimal": { "type": "string", "description": "Decimal transfer-fee rate applied to the quote.", "example": "0.001" }, "rate": { "type": "string", "description": "Destination-currency units per one source-currency unit.", "example": "1" }, "billing": { "$ref": "#/components/schemas/BillingBreakdown" }, "destination": { "$ref": "#/components/schemas/BankDestinationView" }, "expires_at": { "type": "integer", "format": "int64", "description": "Quote expiry time as Unix seconds.", "example": 1786586700 } } }, "QuoteEnvelope": { "allOf": [ { "$ref": "#/components/schemas/StandardEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Quote" } } } ] }, "CreatePayoutRequest": { "type": "object", "additionalProperties": false, "required": [ "client_reference_id", "quote_id", "purpose_code" ], "properties": { "client_reference_id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9._-]+$", "description": "Merchant-scoped idempotency and reconciliation reference for one logical payout.", "example": "payout_20260730_0001" }, "quote_id": { "type": "string", "description": "Unexpired quote owned by the authenticated organization. It binds the destination, amounts, fee responsibility, provider, rail, and pricing.", "example": "poq_01JQ90B8S5VJ6R3T7F1M2C4N9X" }, "purpose_code": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Business purpose code accepted for the payout corridor.", "example": "goods_and_services" }, "statement_reference": { "type": "string", "minLength": 1, "maxLength": 35, "description": "Reference displayed to the recipient when supported by the bank rail.", "example": "INV-2026-0730" } } }, "BatchPayoutStatusRequest": { "type": "object", "additionalProperties": false, "required": [ "start_time", "end_time" ], "properties": { "start_time": { "type": "integer", "format": "int64", "minimum": 1, "description": "Inclusive payout creation start time as Unix seconds.", "example": 1786500000 }, "end_time": { "type": "integer", "format": "int64", "minimum": 1, "description": "Inclusive payout creation end time as Unix seconds. Must be greater than or equal to `start_time`.", "example": 1786599999 }, "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number.", "example": 1 }, "page_size": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Number of payouts per page.", "example": 20 } } }, "PayoutStatusItem": { "type": "object", "additionalProperties": false, "required": [ "payout_id", "client_reference_id", "quote_id", "provider", "status", "payout_type", "source_currency", "destination_currency", "destination_country", "amount_mode", "fee_paid_by", "sending_amount", "receiving_amount", "transfer_fee_amount", "bank_fee_amount", "fee_rate_decimal", "rate", "billing", "destination", "purpose_code", "statement_reference", "bank_reference", "failure", "return", "created_at", "updated_at", "completed_at" ], "properties": { "payout_id": { "type": "string", "description": "Infini fiat payout ID.", "example": "fpo_01JQ90GQJTC5P7B2D8N6R4K1MX" }, "client_reference_id": { "type": "string", "description": "Merchant-provided payout reconciliation reference.", "example": "payout_20260730_0001" }, "quote_id": { "type": "string", "description": "Quote used to create the payout.", "example": "poq_01JQ90B8S5VJ6R3T7F1M2C4N9X" }, "provider": { "type": "string", "enum": [ "sgb" ], "readOnly": true, "description": "Execution provider selected by Infini.", "example": "sgb" }, "status": { "type": "string", "enum": [ "processing", "completed", "failed" ], "description": "Current payout lifecycle state.", "example": "completed" }, "payout_type": { "type": "string", "enum": [ "swift" ], "description": "Payout rail bound by the quote.", "example": "swift" }, "source_currency": { "type": "string", "enum": [ "USD" ], "description": "Organization balance currency.", "example": "USD" }, "destination_currency": { "type": "string", "enum": [ "USD" ], "description": "Currency delivered to the recipient.", "example": "USD" }, "destination_country": { "type": "string", "description": "Destination country as an ISO 3166-1 alpha-2 code.", "example": "US" }, "amount_mode": { "type": "string", "enum": [ "send", "receive" ], "description": "Side fixed by the accepted quote.", "example": "receive" }, "fee_paid_by": { "type": "string", "enum": [ "PAYER", "BENEFICIARY" ], "description": "Party responsible for payout fees.", "example": "PAYER" }, "sending_amount": { "type": "string", "description": "Actual total source-balance debit.", "example": "1051.05" }, "receiving_amount": { "type": "string", "description": "Amount delivered to the recipient.", "example": "1000.00" }, "transfer_fee_amount": { "type": "string", "description": "Infini service fee frozen by the quote.", "example": "1.05" }, "bank_fee_amount": { "type": "string", "description": "Banking fee frozen by the quote.", "example": "50.00" }, "fee_rate_decimal": { "type": "string", "description": "Decimal transfer-fee rate frozen by the quote.", "example": "0.001" }, "rate": { "type": "string", "description": "Exchange rate frozen by the quote.", "example": "1" }, "billing": { "$ref": "#/components/schemas/BillingBreakdown" }, "destination": { "$ref": "#/components/schemas/BankDestinationView" }, "purpose_code": { "type": "string", "description": "Business purpose supplied at creation.", "example": "goods_and_services" }, "statement_reference": { "type": "string", "nullable": true, "description": "Recipient-facing reference when supported.", "example": "INV-2026-0730" }, "bank_reference": { "type": "string", "nullable": true, "description": "Bank transfer reference when available.", "example": "RMTO2084957259539812352" }, "failure": { "$ref": "#/components/schemas/Failure" }, "return": { "$ref": "#/components/schemas/PayoutReturn" }, "created_at": { "type": "integer", "format": "int64", "description": "Payout creation time as Unix seconds.", "example": 1786587000 }, "updated_at": { "type": "integer", "format": "int64", "description": "Payout last-update time as Unix seconds.", "example": 1786587871 }, "completed_at": { "type": "integer", "format": "int64", "nullable": true, "description": "Payout completion time as Unix seconds when available.", "example": 1786587871 } } }, "BatchPayoutStatusEnvelope": { "allOf": [ { "$ref": "#/components/schemas/StandardEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "payouts", "total", "page", "page_size", "total_pages" ], "properties": { "payouts": { "type": "array", "description": "Payout statuses ordered by creation time descending.", "items": { "$ref": "#/components/schemas/PayoutStatusItem" } }, "total": { "type": "integer", "format": "int64", "description": "Total number of payouts matching the time range.", "example": 1 }, "page": { "type": "integer", "description": "Current page number.", "example": 1 }, "page_size": { "type": "integer", "description": "Requested page size.", "example": 20 }, "total_pages": { "type": "integer", "description": "Total number of pages.", "example": 1 } } } } } ] }, "Payout": { "type": "object", "required": [ "payout_id", "client_reference_id", "quote_id", "provider", "status", "payout_type", "source_currency", "destination_currency", "destination_country", "amount_mode", "fee_paid_by", "sending_amount", "receiving_amount", "transfer_fee_amount", "bank_fee_amount", "fee_rate_decimal", "rate", "billing", "destination", "purpose_code", "statement_reference", "bank_reference", "failure", "return", "is_duplicate", "created_at", "updated_at", "completed_at" ], "properties": { "payout_id": { "type": "string", "description": "Infini fiat payout ID.", "example": "fpo_01JQ90GQJTC5P7B2D8N6R4K1MX" }, "client_reference_id": { "type": "string", "description": "Merchant-provided payout reconciliation reference.", "example": "payout_20260730_0001" }, "quote_id": { "type": "string", "description": "Quote used to create the payout.", "example": "poq_01JQ90B8S5VJ6R3T7F1M2C4N9X" }, "provider": { "type": "string", "enum": [ "sgb" ], "readOnly": true, "description": "Execution provider selected by Infini.", "example": "sgb" }, "status": { "type": "string", "enum": [ "processing", "completed", "failed" ], "description": "Current payout lifecycle state. A receiving-bank return does not change a completed payout's status; inspect the `return` object for the compensating refund. API payouts have no approval-pending state.", "example": "processing" }, "payout_type": { "type": "string", "enum": [ "swift" ], "description": "Payout rail bound by the quote.", "example": "swift" }, "source_currency": { "type": "string", "enum": [ "USD" ], "description": "Organization balance currency.", "example": "USD" }, "destination_currency": { "type": "string", "enum": [ "USD" ], "description": "Currency delivered to the recipient.", "example": "USD" }, "destination_country": { "type": "string", "description": "Destination country as an ISO 3166-1 alpha-2 code.", "example": "US" }, "amount_mode": { "type": "string", "enum": [ "send", "receive" ], "description": "Side fixed by the accepted quote.", "example": "receive" }, "fee_paid_by": { "type": "string", "enum": [ "PAYER", "BENEFICIARY" ], "description": "Party responsible for payout fees. `PAYER` means external deduction; `BENEFICIARY` means internal deduction. Persisted for statement reconciliation.", "example": "PAYER" }, "sending_amount": { "type": "string", "description": "Actual total source-balance debit. This is also the authoritative outgoing statement amount.", "example": "1051.05" }, "receiving_amount": { "type": "string", "description": "Amount delivered to the recipient.", "example": "1000.00" }, "transfer_fee_amount": { "type": "string", "description": "Infini service fee frozen by the quote. It excludes any bank or rail fee.", "example": "1.05" }, "bank_fee_amount": { "type": "string", "description": "Banking fee for the selected bank and payout rail frozen by the quote. Rail examples include SWIFT, ACH, and wire.", "example": "50.00" }, "fee_rate_decimal": { "type": "string", "description": "Decimal transfer-fee rate frozen by the quote.", "example": "0.001" }, "rate": { "type": "string", "description": "Exchange rate frozen by the quote.", "example": "1" }, "billing": { "$ref": "#/components/schemas/BillingBreakdown" }, "destination": { "$ref": "#/components/schemas/BankDestinationView" }, "purpose_code": { "type": "string", "description": "Business purpose supplied at creation.", "example": "goods_and_services" }, "statement_reference": { "type": "string", "nullable": true, "description": "Recipient-facing reference when supported.", "example": "INV-2026-0730" }, "bank_reference": { "type": "string", "nullable": true, "description": "Bank transfer reference when available.", "example": "RMTO2084957259539812352" }, "failure": { "$ref": "#/components/schemas/Failure" }, "return": { "$ref": "#/components/schemas/PayoutReturn" }, "is_duplicate": { "type": "boolean", "description": "Whether this response was produced by an idempotent create retry.", "example": false }, "created_at": { "type": "integer", "format": "int64", "description": "Payout creation time as Unix seconds.", "example": 1786587000 }, "updated_at": { "type": "integer", "format": "int64", "description": "Payout last-update time as Unix seconds.", "example": 1786587001 }, "completed_at": { "type": "integer", "format": "int64", "nullable": true, "description": "Time the banking partner reported payout completion, as Unix seconds.", "example": 1786587871 } } }, "Failure": { "type": "object", "nullable": true, "description": "Failure details when the payout could not be completed; otherwise null.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable payout failure code.", "example": "payout_failed" }, "message": { "type": "string", "description": "Human-readable payout failure details.", "example": "The payout could not be completed" } } }, "PayoutReturn": { "type": "object", "nullable": true, "additionalProperties": false, "description": "Compensating refund created after a receiving bank returns a completed payout; otherwise null. The original payout remains `completed`.", "required": [ "status", "reason_code", "reason", "returned_amount", "refund_amount", "retained_fee", "currency", "returned_at" ], "properties": { "status": { "type": "string", "enum": [ "refunded" ], "description": "Settlement state of the compensating refund.", "example": "refunded" }, "reason_code": { "type": "string", "enum": [ "recipient_bank_rejected" ], "description": "Stable machine-readable reason for the bank return.", "example": "recipient_bank_rejected" }, "reason": { "type": "string", "description": "Human-readable bank-return reason when supplied by the banking partner.", "example": "Beneficiary bank rejected the transfer" }, "returned_amount": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,2})?$", "description": "Amount the banking partner reported as returned.", "example": "1000.00" }, "refund_amount": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,2})?$", "description": "Amount actually credited back to the organization's balance after retained fees.", "example": "1000.00" }, "retained_fee": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,2})?$", "description": "Original payout fee retained and not included in `refund_amount`.", "example": "51.05" }, "currency": { "type": "string", "enum": [ "USD" ], "description": "Currency of the return, refund, and retained-fee amounts.", "example": "USD" }, "returned_at": { "type": "integer", "format": "int64", "description": "Time the compensating refund was recorded, as Unix seconds.", "example": 1786674271 } } }, "PayoutEnvelope": { "allOf": [ { "$ref": "#/components/schemas/StandardEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Payout" } } } ] } }, "securitySchemes": { "InfiniHmac": { "type": "http", "scheme": "basic", "description": "Sandbox API **Key** (keyId) and **Secret** from the Infini dashboard." } } }, "security": [ { "InfiniHmac": [] } ] }