{"openapi":"3.1.0","info":{"title":"Overview of OpenFX v3 APIs","description":"OpenFX provides a robust and secure API suite engineered for high performance and reliability, enabling programmatic access to real-time market data, trade execution, and money movement functionalities. This guide will walk through the step-by-step process of deposits, quoting, trading, settlements and monitoring using OpenFX APIs.","version":"v3","termsOfService":"https://www.openfx.com/terms","contact":{"name":"OpenFX Support","email":"support@openfx.com","url":"https://www.openfx.com"}},"servers":[{"url":"https://api.openfx.com/v3","description":"OpenFX API Server"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"CryptoDestination":{"type":"object","properties":{"address":{"type":"string","examples":["0x2205844f0b80798F0e187c260753191eb668a495"],"description":"On-chain destination address. Format varies by chain."}},"required":["address"]},"SwiftDestination":{"type":"object","properties":{"accountName":{"type":"string","examples":["RedEnvelope Inc."],"description":"Beneficiary name on the account."},"accountNumber":{"type":"string","examples":["123456789"],"description":"Account number, IBAN, CLABE, CBU — format varies by rail."},"bankName":{"type":"string","examples":["Zand Bank"],"description":"Beneficiary bank name."},"memo":{"type":"string","description":"Payment reference / memo string. Optional."},"businessName":{"type":"string","description":"Business name when distinct from accountName."},"bankAddress":{"type":"string","description":"Deprecated — populated for legacy rows. Prefer `bankDetails` going forward."},"bankDetails":{"type":"object","properties":{"bankName":{"type":"string"},"addressLineOne":{"type":"string"},"addressLineTwo":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string"},"accountType":{"type":"string"}},"description":"Beneficiary bank address details (bankName, city, country, etc.). Subset of fields per rail."},"contactDetails":{"type":"object","properties":{"addressLineOne":{"type":"string"},"addressLineTwo":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"}},"description":"Beneficiary contact / address details. Subset of fields per rail; PSE/ACH also include email+phone."},"meta":{"type":"object","additionalProperties":{},"description":"Rail- or currency-specific extras. Examples: `meta.intermediaryBankDetails` (USD/SWIFT), `meta.leiCode` (GBP), `meta.pixKey` (BRL/PIX), `meta.taxId`+`meta.bankCode` (COP/PSE+ACH)."},"swiftCode":{"type":"string","examples":["DEUTDEFF"],"description":"BIC / SWIFT code of the beneficiary bank."}},"required":["accountName","accountNumber","bankName","swiftCode"]},"FedwireDestination":{"type":"object","properties":{"accountName":{"type":"string","examples":["RedEnvelope Inc."],"description":"Beneficiary name on the account."},"accountNumber":{"type":"string","examples":["123456789"],"description":"Account number, IBAN, CLABE, CBU — format varies by rail."},"bankName":{"type":"string","examples":["Zand Bank"],"description":"Beneficiary bank name."},"memo":{"type":"string","description":"Payment reference / memo string. Optional."},"businessName":{"type":"string","description":"Business name when distinct from accountName."},"bankAddress":{"type":"string","description":"Deprecated — populated for legacy rows. Prefer `bankDetails` going forward."},"bankDetails":{"type":"object","properties":{"bankName":{"type":"string"},"addressLineOne":{"type":"string"},"addressLineTwo":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string"},"accountType":{"type":"string"}},"description":"Beneficiary bank address details (bankName, city, country, etc.). Subset of fields per rail."},"contactDetails":{"type":"object","properties":{"addressLineOne":{"type":"string"},"addressLineTwo":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"}},"description":"Beneficiary contact / address details. Subset of fields per rail; PSE/ACH also include email+phone."},"meta":{"type":"object","additionalProperties":{},"description":"Rail- or currency-specific extras. Examples: `meta.intermediaryBankDetails` (USD/SWIFT), `meta.leiCode` (GBP), `meta.pixKey` (BRL/PIX), `meta.taxId`+`meta.bankCode` (COP/PSE+ACH)."},"routingNumber":{"type":"string","examples":["021000021"],"description":"ABA / Fedwire routing number."}},"required":["accountName","accountNumber","bankName","routingNumber"]},"FpsDestination":{"type":"object","properties":{"accountName":{"type":"string","examples":["RedEnvelope Inc."],"description":"Beneficiary name on the account."},"accountNumber":{"type":"string","examples":["123456789"],"description":"Account number, IBAN, CLABE, CBU — format varies by rail."},"bankName":{"type":"string","examples":["Zand Bank"],"description":"Beneficiary bank name."},"memo":{"type":"string","description":"Payment reference / memo string. Optional."},"businessName":{"type":"string","description":"Business name when distinct from accountName."},"bankAddress":{"type":"string","description":"Deprecated — populated for legacy rows. Prefer `bankDetails` going forward."},"bankDetails":{"type":"object","properties":{"bankName":{"type":"string"},"addressLineOne":{"type":"string"},"addressLineTwo":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string"},"accountType":{"type":"string"}},"description":"Beneficiary bank address details (bankName, city, country, etc.). Subset of fields per rail."},"contactDetails":{"type":"object","properties":{"addressLineOne":{"type":"string"},"addressLineTwo":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"}},"description":"Beneficiary contact / address details. Subset of fields per rail; PSE/ACH also include email+phone."},"meta":{"type":"object","additionalProperties":{},"description":"Rail- or currency-specific extras. Examples: `meta.intermediaryBankDetails` (USD/SWIFT), `meta.leiCode` (GBP), `meta.pixKey` (BRL/PIX), `meta.taxId`+`meta.bankCode` (COP/PSE+ACH)."},"ukSortCode":{"type":"string","examples":["20-00-00"],"description":"UK sort code."}},"required":["accountName","accountNumber","bankName","ukSortCode"]},"LocalRailDestination":{"type":"object","properties":{"accountName":{"type":"string","examples":["RedEnvelope Inc."],"description":"Beneficiary name on the account."},"accountNumber":{"type":"string","examples":["123456789"],"description":"Account number, IBAN, CLABE, CBU — format varies by rail."},"bankName":{"type":"string","examples":["Zand Bank"],"description":"Beneficiary bank name."},"memo":{"type":"string","description":"Payment reference / memo string. Optional."},"businessName":{"type":"string","description":"Business name when distinct from accountName."},"bankAddress":{"type":"string","description":"Deprecated — populated for legacy rows. Prefer `bankDetails` going forward."},"bankDetails":{"type":"object","properties":{"bankName":{"type":"string"},"addressLineOne":{"type":"string"},"addressLineTwo":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string"},"accountType":{"type":"string"}},"description":"Beneficiary bank address details (bankName, city, country, etc.). Subset of fields per rail."},"contactDetails":{"type":"object","properties":{"addressLineOne":{"type":"string"},"addressLineTwo":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"}},"description":"Beneficiary contact / address details. Subset of fields per rail; PSE/ACH also include email+phone."},"meta":{"type":"object","additionalProperties":{},"description":"Rail- or currency-specific extras. Examples: `meta.intermediaryBankDetails` (USD/SWIFT), `meta.leiCode` (GBP), `meta.pixKey` (BRL/PIX), `meta.taxId`+`meta.bankCode` (COP/PSE+ACH)."}},"required":["accountName","accountNumber","bankName"]}}},"security":[{"bearerAuth":[]}],"tags":[{"name":"FX","description":"Core FX endpoints for market data, balances, the quote-then-trade workflow, deposits, and withdrawals."},{"name":"MarketData","description":"This endpoint retrieves a complete list of all tradable fiat and stablecoin currency pairs on the OpenFX platform."},{"name":"Balances","description":"The Balance endpoints enable real-time tracking and management of currency holdings within an account."},{"name":"Trade","description":"The Trade APIs facilitate programmatic currency exchange through a quote-then-trade workflow, ensuring price transparency and guaranteed execution at quoted rates."},{"name":"Deposits","description":"Deposit endpoints enable secure funding of trading accounts across multiple supported currencies and methods."},{"name":"Withdrawals","description":"The Withdrawal API facilitates secure fund withdrawals for both fiat and stablecoins."}],"paths":{"/fx/balances":{"get":{"responses":{"200":{"description":"success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"aggregate":{"type":"object","properties":{"currency":{"type":"string","examples":["USD"],"description":"Currency the aggregate amount below is denominated in (always USD today)."},"withdrawableBalance":{"type":"string","examples":["85000.00"],"description":"Org-wide net equity converted to `currency` — the ceiling on what can actually be withdrawn across all currencies. Never negative; `0` when the org's net position is negative."}},"required":["currency","withdrawableBalance"],"description":"Net equity across all currencies held by the org, converted to USD."},"balances":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string","examples":["USD"],"description":"Currency symbol of this balance row."},"withdrawableBalance":{"type":"string","examples":["50000.00"],"description":"Amount immediately available to withdraw or trade in `currency`. Never negative — `0` when `totalBalance` is negative."},"totalBalance":{"type":"string","examples":["60000.00","-1200.50"],"description":"Total ledger balance in `currency`, including amounts reserved for pending withdrawals/trades. May be negative when the org owes a settlement."}},"required":["currency","withdrawableBalance","totalBalance"]},"description":"One row per currency the org holds."}},"required":["aggregate","balances"]}},"required":["data"]},"examples":{"default_example":{"value":{"data":{"aggregate":{"currency":"USD","withdrawableBalance":"85000.00"},"balances":[{"currency":"USD","withdrawableBalance":"50000.00","totalBalance":"60000.00"},{"currency":"USDC","withdrawableBalance":"25000.00","totalBalance":"25000.00"},{"currency":"EUR","withdrawableBalance":"0","totalBalance":"-1200.50"}]}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"VALIDATION_BODY_FAILED","type":"VALIDATION_ERROR","message":"Request body failed validation. See details.issues for field-level errors, or details.firstIssuePath for the most common single-field case.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"fx_list_balances","summary":"List balances","tags":["FX"],"description":"Check how much money is available across all currencies held in the account. Returns real-time balances including available and total amounts per currency. Use this before initiating a trade to confirm sufficient funds, before initiating a withdrawal to check available amounts, or for end-of-day reconciliation. Returns one balance row per currency held by your organization. `withdrawableBalance` is the amount immediately available to withdraw or trade; `totalBalance` is the full ledger balance (may exceed `withdrawableBalance` when amounts are reserved for pending withdrawals or trades). `totalBalance` may be negative when the org owes a settlement, in which case `withdrawableBalance` is `0`. The `aggregate` block carries org-wide net equity in USD — the ceiling on what can actually be withdrawn across all currencies. No pagination — balances are naturally bounded to one row per currency."}},"/fx/exposures":{"get":{"responses":{"200":{"description":"success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"aggregate":{"type":"object","properties":{"currency":{"type":"string","examples":["USD"],"description":"Currency the aggregate amounts below are denominated in (always USD today)."},"limitAmount":{"type":"string","examples":["50000.00"],"description":"Total credit line extended to the org."},"usedAmount":{"type":"string","examples":["1200.00"],"description":"Amount currently drawn against the credit line (settlable-now + settlable-later exposure)."},"availableAmount":{"type":"string","examples":["48800.00"],"description":"Remaining credit line available (`limitAmount` minus `usedAmount`). Can be negative if the org's open exposure currently exceeds its credit limit (e.g. after a limit reduction)."},"usageBreakdown":{"type":"object","properties":{"settlableNow":{"type":"string","examples":["800.00"],"description":"Total exposure across all currencies from trades that are `READY_TO_SETTLE`."},"settlableLater":{"type":"string","examples":["400.00"],"description":"Total exposure across all currencies from trades still `LOCKED`."}},"required":["settlableNow","settlableLater"]}},"required":["currency","limitAmount","usedAmount","availableAmount","usageBreakdown"],"description":"Org-wide exposure, converted to USD."},"currencyExposures":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string","examples":["USD"],"description":"ISO currency code."},"exposureAmount":{"type":"string","examples":["1200.00"],"description":"Native-currency exposure held against this currency (settlable-now + settlable-later)."},"usageBreakdown":{"type":"object","properties":{"settlableNow":{"type":"object","properties":{"amount":{"type":"string","examples":["800.00"],"description":"Native-currency exposure from trades that are `READY_TO_SETTLE`."}},"required":["amount"]},"settlableLater":{"type":"object","properties":{"amount":{"type":"string","examples":["400.00"],"description":"Native-currency exposure from trades still `LOCKED` (settlement window hasn't opened yet)."}},"required":["amount"]}},"required":["settlableNow","settlableLater"]}},"required":["currency","exposureAmount","usageBreakdown"]},"description":"Per-currency breakdown of open exposure."}},"required":["aggregate","currencyExposures"]}},"required":["data"]},"examples":{"default_example":{"value":{"data":{"aggregate":{"currency":"USD","limitAmount":"50000.00","usedAmount":"1200.00","availableAmount":"48800.00","usageBreakdown":{"settlableNow":"800.00","settlableLater":"400.00"}},"currencyExposures":[{"currency":"USD","exposureAmount":"1200.00","usageBreakdown":{"settlableNow":{"amount":"800.00"},"settlableLater":{"amount":"400.00"}}}]}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"VALIDATION_BODY_FAILED","type":"VALIDATION_ERROR","message":"Request body failed validation. See details.issues for field-level errors, or details.firstIssuePath for the most common single-field case.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}},"exposure_not_enabled_example":{"value":{"error":{"code":"EXPOSURE_NOT_ENABLED","type":"AUTHORIZATION_ERROR","message":"No exposure limit configured for your account.","details":{}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"fx_get_exposure","summary":"Get exposure summary","tags":["FX"],"description":"Get the authenticated org's credit exposure summary — how much of the org's credit line is currently committed to unsettled FX trades, broken down by currency and by settlement stage. No request body, no query or path parameters; the org is resolved from the authenticated API key."}},"/fx/pairs":{"get":{"responses":{"200":{"description":"success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"pairs":{"type":"array","items":{"type":"object","properties":{"buyCurrency":{"type":"string","examples":["USDC"],"description":"Currency the user buys in this market."},"sellCurrency":{"type":"string","examples":["USD"],"description":"Currency the user sells in this market."},"minTradeAmount":{"type":"string","examples":["100"],"description":"Minimum trade amount, denominated in the `sellCurrency`."},"maxTradeAmount":{"type":"string","examples":["100000000"],"description":"Maximum trade amount, denominated in the `sellCurrency`."}},"required":["buyCurrency","sellCurrency","minTradeAmount","maxTradeAmount"]},"description":"Tradable currency pairs available to your organization. Limits are scoped to the `sellCurrency`, so each underlying pair is enumerated in both directions."}},"required":["pairs"]}},"required":["data"]},"examples":{"default_example":{"value":{"data":{"pairs":[{"buyCurrency":"USDC","sellCurrency":"USD","minTradeAmount":"100","maxTradeAmount":"100000000"},{"buyCurrency":"USD","sellCurrency":"USDC","minTradeAmount":"100","maxTradeAmount":"10000000"}]}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"VALIDATION_BODY_FAILED","type":"VALIDATION_ERROR","message":"Request body failed validation. See details.issues for field-level errors, or details.firstIssuePath for the most common single-field case.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"fx_get_pairs","summary":"List available currency pairs","tags":["FX"],"description":"Find out which currency pairs are available for you to trade on the platform, including trading limits, supported directions, and minimum/maximum amounts. Call this before generating a quote to confirm a pair is tradable and to check constraints. Limits are scoped to sellCurrency, so each underlying pair is returned in both directions (e.g. USD→USDC and USDC→USD)."}},"/fx/quotes":{"post":{"responses":{"200":{"description":"success","headers":{"Idempotency-Replayed":{"description":"`true` when the response was served from the idempotency cache (replay of a prior request with the same Idempotency-Key and same request payload); `false` for a freshly executed request. Always present on idempotent endpoints.","schema":{"type":"string","enum":["true","false"]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","const":"quote","example":"quote","description":"Resource type."},"id":{"type":"string","examples":["qte_3FfGK34vwMvVFDedyb2nkf"]},"buyCurrency":{"type":"string","examples":["USDC"]},"sellCurrency":{"type":"string","examples":["USD"]},"buyAmount":{"type":"string","examples":["1000"],"description":"Present when the quote was requested in `buyCurrency` terms."},"sellAmount":{"type":"string","examples":["1000"],"description":"Present when the quote was requested in `sellCurrency` terms."},"quoteAmount":{"type":"string","examples":["999.8000000079984"]},"createdAt":{"type":"string","examples":["2026-03-22T12:00:00.000Z"],"description":"RFC 3339 timestamp at which the quote was created."},"expiresAt":{"type":["string","null"],"examples":["2026-03-22T12:03:00.000Z"],"description":"RFC 3339 timestamp at which the quote expires."},"settlementWindow":{"type":"string","enum":["IMMEDIATE","T0","T1","T2"],"examples":["T0"],"description":"Settlement window for the resulting trade."}},"required":["object","id","buyCurrency","sellCurrency","quoteAmount","createdAt","expiresAt"]}},"required":["data"]},"examples":{"default_example":{"value":{"data":{"object":"quote","id":"qte_3FfGK34vwMvVFDedyb2nkf","buyCurrency":"USDC","sellCurrency":"USD","buyAmount":"1000","quoteAmount":"999.8000000079984","createdAt":"2026-03-22T12:00:00.000Z","expiresAt":"2026-03-22T12:00:03.000Z","settlementWindow":"T0"}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"VALIDATION_BODY_FAILED","type":"VALIDATION_ERROR","message":"Request body failed validation. See details.issues for field-level errors, or details.firstIssuePath for the most common single-field case.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"409":{"description":"Conflict","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"IDEMPOTENCY_IN_FLIGHT","type":"CONFLICT","message":"Another request with this idempotency key is currently processing. Wait for some time and retry with the same key.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"fx_create_quote","summary":"Generate quote","tags":["FX"],"x-idempotency-ttl-seconds":1800,"description":"Lock in a guaranteed exchange rate for a specific currency pair and amount. Returns a quote ID and rate valid until the RFC 3339 timestamp returned in `expiresAt` (driven by your `quoteForSeconds`). Default quote validity is 3 seconds. You must call this before executing a trade as you can't trade without a valid quote. Use this when you want to preview the rate, fees, and converted amount before committing.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255,"pattern":"^[a-zA-Z0-9_-]{1,255}$","examples":["123e4567-e89b-12d3-a456-426614174000"]},"description":"Unique key to ensure idempotent requests. Valid for 30 minutes."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"buyAmount":{"type":"string","pattern":"^(?=.*[1-9])\\d+(\\.\\d+)?$","examples":["1000"],"description":"Amount to buy, denominated in `buyCurrency`. Mutually exclusive with `sellAmount`."},"sellAmount":{"type":"string","pattern":"^(?=.*[1-9])\\d+(\\.\\d+)?$","examples":["1000"],"description":"Amount to sell, denominated in `sellCurrency`. Mutually exclusive with `buyAmount`."},"buyCurrency":{"type":"string","minLength":1,"examples":["USDC"],"description":"Currency to buy. Must be uppercase (e.g. `USDC`)."},"sellCurrency":{"type":"string","minLength":1,"examples":["USD"],"description":"Currency to sell. Must be uppercase (e.g. `USD`)."},"quoteForSeconds":{"type":"number","enum":[3,15,30,45,60],"examples":[3],"description":"Requested quote expiry validity in seconds.","default":3},"settlementWindow":{"type":"string","enum":["IMMEDIATE","T0","T1","T2"],"examples":["T0"],"description":"Settlement window for the resulting trade. Defaults to `T0` when omitted."}},"required":["buyCurrency","sellCurrency"],"additionalProperties":false}}}}}},"/fx/trades":{"get":{"responses":{"200":{"description":"success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"trade","example":"trade","description":"Resource type."},"id":{"type":"string","examples":["tde_5W7guYdHT24JFnRQrZN9y8"],"description":"Unique identifier for the trade."},"quoteId":{"type":"string","examples":["qte_TmHeAhdFLes63uGgDjcJRx"],"description":"ID of the quote this trade was executed against."},"buyCurrency":{"type":"string","examples":["USDC"],"description":"Currency the user bought."},"sellCurrency":{"type":"string","examples":["USD"],"description":"Currency the user sold."},"buyAmount":{"type":"string","examples":["1000"],"description":"Present when the trade was specified in `buyCurrency` terms."},"sellAmount":{"type":"string","examples":["1000"],"description":"Present when the trade was specified in `sellCurrency` terms."},"executedAmount":{"type":"string","examples":["999.8"],"description":"Final amount received in the counter-currency."},"status":{"type":"string","examples":["EXECUTED"],"description":"Lifecycle state of the trade."},"clientReferenceId":{"type":["string","null"],"examples":["order-123",null],"description":"Optional client-supplied reference for the trade, or null when unset."},"createdAt":{"type":"string","examples":["2026-03-22T12:00:00.000Z"],"description":"RFC 3339 timestamp at which the trade was created."},"settlementWindow":{"type":["string","null"],"enum":["IMMEDIATE","T0","T1","T2"],"examples":["T0"],"description":"Settlement window the trade settles in."},"settlementStartTime":{"type":["string","null"],"examples":["2026-03-22T12:04:00.000Z"],"description":"RFC 3339 timestamp at which settlement started, or null."}},"required":["object","id","quoteId","buyCurrency","sellCurrency","executedAmount","status","clientReferenceId","createdAt","settlementWindow","settlementStartTime"]}},"pagination":{"type":"object","properties":{"limit":{"type":"number","examples":[25],"description":"Page size used for this request."},"hasNext":{"type":"boolean","examples":[true],"description":"Whether more results exist after this page."},"nextCursor":{"type":["string","null"],"description":"Cursor pointing to the last item on this page. Pass as `startingAfter` to fetch the next page."},"hasPrev":{"type":"boolean","examples":[false],"description":"Whether results exist before this page."},"prevCursor":{"type":["string","null"],"description":"Cursor pointing to the first item on this page. Pass as `endingBefore` to fetch the previous page."}},"required":["limit","hasNext","nextCursor","hasPrev","prevCursor"]}},"required":["data","pagination"]},"examples":{"default_example":{"value":{"data":[{"object":"trade","id":"tde_6SATV6VSUdBTttHWBmCYjD","quoteId":"qte_TmHeAhdFLes63uGgDjcJRx","buyCurrency":"USD","sellCurrency":"USDC","buyAmount":"100","executedAmount":"99.8","status":"EXECUTED","clientReferenceId":null,"createdAt":"2026-03-22T12:00:05.000Z","settlementWindow":"T0","settlementStartTime":null}],"pagination":{"limit":25,"hasNext":true,"nextCursor":"eyJjcmVhdGVkQXQiOi4uLn0","hasPrev":false,"prevCursor":null}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"VALIDATION_BODY_FAILED","type":"VALIDATION_ERROR","message":"Request body failed validation. See details.issues for field-level errors, or details.firstIssuePath for the most common single-field case.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"fx_list_trades","summary":"List trades","tags":["FX"],"description":"Retrieve a list of all executed trades, including completed, pending, and settled transactions. Use this for trade history, reconciliation, reporting, or when you want to view your recent trading activity. Cursor-paginated list of trades for your organization, newest first. Use `startingAfter` to fetch the next page and `endingBefore` to fetch the previous page. The two cursors are mutually exclusive.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Items per page (max 100, default 25)."},{"name":"startingAfter","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor to fetch the next page. Use the `nextCursor` from a previous response."},{"name":"endingBefore","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor to fetch the previous page. Use the `prevCursor` from a previous response."}]},"post":{"responses":{"200":{"description":"success","headers":{"Idempotency-Replayed":{"description":"`true` when the response was served from the idempotency cache (replay of a prior request with the same Idempotency-Key and same request payload); `false` for a freshly executed request. Always present on idempotent endpoints.","schema":{"type":"string","enum":["true","false"]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","const":"trade","example":"trade","description":"Resource type."},"id":{"type":"string","examples":["tde_5W7guYdHT24JFnRQrZN9y8"],"description":"Unique identifier for the trade."},"quoteId":{"type":"string","examples":["qte_TmHeAhdFLes63uGgDjcJRx"],"description":"ID of the quote this trade was executed against."},"buyCurrency":{"type":"string","examples":["USDC"],"description":"Currency the user bought."},"sellCurrency":{"type":"string","examples":["USD"],"description":"Currency the user sold."},"buyAmount":{"type":"string","examples":["1000"],"description":"Present when the trade was specified in `buyCurrency` terms."},"sellAmount":{"type":"string","examples":["1000"],"description":"Present when the trade was specified in `sellCurrency` terms."},"executedAmount":{"type":"string","examples":["999.8"],"description":"Final amount received in the counter-currency."},"status":{"type":"string","examples":["EXECUTED"],"description":"Lifecycle state of the trade."},"clientReferenceId":{"type":["string","null"],"examples":["order-123",null],"description":"Optional client-supplied reference for the trade, or null when unset."},"createdAt":{"type":"string","examples":["2026-03-22T12:00:00.000Z"],"description":"RFC 3339 timestamp at which the trade was created."},"settlementWindow":{"type":["string","null"],"enum":["IMMEDIATE","T0","T1","T2"],"examples":["T0"],"description":"Settlement window the trade settles in."},"settlementStartTime":{"type":["string","null"],"examples":["2026-03-22T12:04:00.000Z"],"description":"RFC 3339 timestamp at which settlement started, or null."}},"required":["object","id","quoteId","buyCurrency","sellCurrency","executedAmount","status","clientReferenceId","createdAt","settlementWindow","settlementStartTime"]}},"required":["data"]},"examples":{"default_example":{"value":{"data":{"object":"trade","id":"tde_6SATV6VSUdBTttHWBmCYjD","quoteId":"qte_TmHeAhdFLes63uGgDjcJRx","buyCurrency":"USD","sellCurrency":"USDC","buyAmount":"100","executedAmount":"99.8","status":"EXECUTED","clientReferenceId":null,"createdAt":"2026-03-22T12:00:05.000Z","settlementWindow":"T0","settlementStartTime":null}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"VALIDATION_BODY_FAILED","type":"VALIDATION_ERROR","message":"Request body failed validation. See details.issues for field-level errors, or details.firstIssuePath for the most common single-field case.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"409":{"description":"Conflict","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"IDEMPOTENCY_IN_FLIGHT","type":"CONFLICT","message":"Another request with this idempotency key is currently processing. Wait for some time and retry with the same key.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"fx_create_trade","summary":"Execute trade","tags":["FX"],"x-idempotency-ttl-seconds":86400,"description":"Execute a currency exchange using a valid quote ID. This is the only way to convert between currencies on the platform. Use this when you have reviewed a quote and want to proceed with the exchange. Requires a quote ID from fx_create_quote.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255,"pattern":"^[a-zA-Z0-9_-]{1,255}$","examples":["123e4567-e89b-12d3-a456-426614174000"]},"description":"Unique key to ensure idempotent requests. Valid for 24 hours."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"quoteId":{"type":"string","minLength":1,"example":"qte_TmHeAhdFLes63uGgDjcJRx","description":"ID of the quote to execute the trade against."},"clientReferenceId":{"type":"string","maxLength":255,"examples":["order-123"],"description":"Optional client-supplied reference for the trade, up to 255 characters after trimming."}},"required":["quoteId"],"additionalProperties":false}}}}}},"/fx/withdrawals":{"post":{"responses":{"200":{"description":"success","headers":{"Idempotency-Replayed":{"description":"`true` when the response was served from the idempotency cache (replay of a prior request with the same Idempotency-Key and same request payload); `false` for a freshly executed request. Always present on idempotent endpoints.","schema":{"type":"string","enum":["true","false"]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","const":"withdrawal","example":"withdrawal","description":"Resource type."},"id":{"type":"string","examples":["wtd_6SATV6VSUdBTttHWBmCYjD"],"description":"Unique identifier for the withdrawal."},"currency":{"type":"string","examples":["USDC"],"description":"Currency of the withdrawal."},"assetType":{"type":"string","enum":["CRYPTO","FIAT"],"examples":["CRYPTO"],"description":"Asset class: `CRYPTO` for on-chain, `FIAT` for bank rails."},"withdrawalAmount":{"type":"string","examples":["1000.00"],"description":"Amount being withdrawn, in `currency`."},"status":{"type":"string","examples":["COMPLETED"],"description":"Lifecycle state of the withdrawal at the moment of response."},"network":{"type":["string","null"],"examples":["ETHEREUM"],"description":"Network the crypto withdrawal settled over; `null` for fiat withdrawals."},"withdrawalAccountId":{"type":"string","examples":["wac_NDqQ9LmcUASpnHR6CTvdkk"],"description":"ID of the destination withdrawal account used."},"estimatedCompletionAt":{"type":["string","null"],"examples":["2026-03-22T12:05:00.000Z"],"description":"RFC 3339 timestamp at which the withdrawal is expected to settle. `null` if the upstream has no ETA yet."},"paymentDetails":{"type":["object","null"],"additionalProperties":{"type":"object","additionalProperties":{}},"description":"Network-specific identifiers populated once the withdrawal reaches a terminal state. Keyed by transferType (e.g. `{ \"FEDWIRE\": { \"imad\": \"...\", \"omad\": \"...\" } }`). Returned in the response only for fiat withdrawals (`null` on initial POST until terminal); omitted entirely for crypto."},"actorId":{"type":"string","examples":["usr_7m4VsfRw4pGrS76WYj5tnx"],"description":"ID of the actor that initiated the withdrawal. Masked to a fixed placeholder when the actor is an internal (OpenFX / RedEnvelope) operator."},"actorEmail":{"type":"string","examples":["client-user@example.co"],"description":"Email of the actor that initiated the withdrawal. Masked to a fixed placeholder when the actor is an internal (OpenFX / RedEnvelope) operator."},"createdAt":{"type":"string","examples":["2026-03-22T12:00:00.000Z"],"description":"RFC 3339 timestamp at which the withdrawal was created."},"metadata":{"type":["object","null"],"propertyNames":{"type":"string","minLength":1,"maxLength":40},"additionalProperties":{"type":"string","maxLength":500},"description":"Optional client-owned metadata bag (string keys → string values). Echoed back verbatim on a successful response. Limits: at most 50 keys, keys up to 40 characters, values up to 500 characters, and at most 8192 bytes when serialized.","examples":[{"requestId":"client-generated-correlation-id"}]}},"required":["object","id","currency","assetType","withdrawalAmount","status","network","withdrawalAccountId","estimatedCompletionAt","actorId","actorEmail","createdAt"]}},"required":["data"]},"examples":{"crypto_example":{"summary":"Crypto withdrawal","value":{"data":{"object":"withdrawal","id":"wtd_6SATV6VSUdBTttHWBmCYjD","currency":"USDC","withdrawalAmount":"1000.00","status":"COMPLETED","assetType":"CRYPTO","network":"ETHEREUM","withdrawalAccountId":"wac_NDqQ9LmcUASpnHR6CTvdkk","metadata":{"requestId":"client-generated-correlation-id"},"estimatedCompletionAt":"2026-03-22T12:05:00.000Z","actorId":"usr_7m4VsfRw4pGrS76WYj5tnx","actorEmail":"client-user@example.co","createdAt":"2026-03-22T12:00:00.000Z"}}},"fiat_example":{"summary":"Fiat withdrawal (FEDWIRE)","value":{"data":{"object":"withdrawal","id":"wtd_8YPy9cT9R7QjMLMgnFDNsE","currency":"USD","withdrawalAmount":"5000.00","status":"COMPLETED","assetType":"FIAT","network":null,"withdrawalAccountId":"wac_UXpWaK83GJwYb8BUySn841","estimatedCompletionAt":"2026-03-23T17:00:00.000Z","metadata":{"requestId":"client-generated-correlation-id"},"paymentDetails":{"FEDWIRE":{"imad":"20260322ABC00318000742","omad":"20260322XYZ0041800293847561NQ0785"}},"actorId":"usr_7m4VsfRw4pGrS76WYj5tnx","actorEmail":"client-user@example.co","createdAt":"2026-03-22T12:00:00.000Z"}}}}}}},"400":{"description":"Bad request — typically a validation, balance, or address-state issue","content":{"application/json":{"examples":{"insufficient_balance":{"summary":"Insufficient balance","value":{"error":{"code":"WITHDRAWAL_INSUFFICIENT_BALANCE","type":"VALIDATION_ERROR","message":"Insufficient balance for this withdrawal.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"address_not_active":{"summary":"Withdrawal account not active or verified","value":{"error":{"code":"WITHDRAWAL_ADDRESS_NOT_VERIFIED","type":"VALIDATION_ERROR","message":"The withdrawal account is not active or verified.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"404":{"description":"Withdrawal account not found","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"WITHDRAWAL_ADDRESS_NOT_FOUND","type":"NOT_FOUND","message":"The requested withdrawal account was not found.","retryStrategy":"TERMINAL","details":{}}}}}}}},"409":{"description":"Conflict","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"IDEMPOTENCY_IN_FLIGHT","type":"CONFLICT","message":"Another request with this idempotency key is currently processing. Wait for some time and retry with the same key.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"fx_create_withdrawal","summary":"Create withdrawal","tags":["FX"],"x-idempotency-ttl-seconds":604800,"description":"Initiate a withdrawal from your OpenFX balance to a previously-registered withdrawal account. Replaces v2's separate `POST /v2/brokerage/:orgId/withdrawal` (crypto) and `POST /v2/brokerage/:orgId/fiat_withdrawal` (fiat) — server dispatches based on `currency`.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255,"pattern":"^[a-zA-Z0-9_-]{1,255}$","examples":["123e4567-e89b-12d3-a456-426614174000"]},"description":"Unique key to ensure idempotent requests. Valid for 7 days."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string","enum":["USDT","USDC","EURC","EUROP","USD","AED","GBP","EUR","AUD","MXN","BRL","PHP","ARS","COP","INR","CHF","IDR","NOK","PLN","SGD","ZAR","DKK","HKD","SEK"],"examples":["USDC"],"description":"Currency to withdraw. Server dispatches crypto (USDT/USDC/EURC) vs fiat based on the value — single union, not separate endpoints."},"withdrawalAmount":{"type":"string","pattern":"^(?=.*[1-9])\\d+(\\.\\d+)?$","examples":["1000.00"],"description":"Amount to withdraw, in the requested currency, as a positive decimal string."},"withdrawalAccountId":{"type":"string","minLength":1,"example":"wac_NDqQ9LmcUASpnHR6CTvdkk","description":"ID of the destination withdrawal account (crypto address or fiat bank account) on file for this org."},"metadata":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":40},"additionalProperties":{"type":"string","maxLength":500},"description":"Optional client-owned metadata bag (string keys → string values). Echoed back verbatim on a successful response. Limits: at most 50 keys, keys up to 40 characters, values up to 500 characters, and at most 8192 bytes when serialized.","examples":[{"requestId":"client-generated-correlation-id"}]}},"required":["currency","withdrawalAmount","withdrawalAccountId"],"additionalProperties":false}}}}},"get":{"responses":{"200":{"description":"success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"withdrawal","example":"withdrawal","description":"Resource type."},"id":{"type":"string","examples":["wtd_6SATV6VSUdBTttHWBmCYjD"],"description":"Unique identifier for the withdrawal."},"currency":{"type":"string","examples":["USDC"],"description":"Currency of the withdrawal."},"assetType":{"type":"string","enum":["CRYPTO","FIAT"],"examples":["CRYPTO"],"description":"Asset class: `CRYPTO` for on-chain, `FIAT` for bank rails."},"withdrawalAmount":{"type":"string","examples":["1000.00"],"description":"Amount withdrawn, in `currency`."},"status":{"type":"string","examples":["COMPLETED"],"description":"Lifecycle state of the withdrawal."},"network":{"type":["string","null"],"examples":["ETHEREUM"],"description":"Network the crypto withdrawal settled over; `null` for fiat withdrawals."},"withdrawalAccountId":{"type":["string","null"],"examples":["wac_NDqQ9LmcUASpnHR6CTvdkk"],"description":"ID of the destination withdrawal account used. `null` if no account is on record for the withdrawal."},"transactionHash":{"type":["string","null"],"examples":["0xdef456..."],"description":"On-chain transaction hash for crypto withdrawals once broadcast. `null` for fiat or before the chain leg lands."},"paymentDetails":{"type":["object","null"],"additionalProperties":{"type":"object","additionalProperties":{}},"description":"Network-specific identifiers populated once the withdrawal reaches a terminal state. Keyed by transferType (e.g. `{ \"FEDWIRE\": { \"imad\": \"...\", \"omad\": \"...\" } }`). Returned in the response only for fiat withdrawals; omitted entirely for crypto."},"actorId":{"type":"string","examples":["usr_7m4VsfRw4pGrS76WYj5tnx"],"description":"ID of the actor that initiated the withdrawal. Masked to a fixed placeholder when the actor is an internal (OpenFX / RedEnvelope) operator."},"actorEmail":{"type":"string","examples":["client-user@example.co"],"description":"Email of the actor that initiated the withdrawal. Masked to a fixed placeholder when the actor is an internal (OpenFX / RedEnvelope) operator."},"createdAt":{"type":"string","examples":["2026-03-22T12:00:00.000Z"],"description":"RFC 3339 timestamp at which the withdrawal was created."},"metadata":{"type":["object","null"],"propertyNames":{"type":"string","minLength":1,"maxLength":40},"additionalProperties":{"type":"string","maxLength":500},"description":"Optional client-owned metadata bag (string keys → string values). Echoed back verbatim on a successful response. Limits: at most 50 keys, keys up to 40 characters, values up to 500 characters, and at most 8192 bytes when serialized.","examples":[{"requestId":"client-generated-correlation-id"}]}},"required":["object","id","currency","assetType","withdrawalAmount","status","network","withdrawalAccountId","transactionHash","actorId","actorEmail","createdAt"]}},"pagination":{"type":"object","properties":{"limit":{"type":"number","examples":[25],"description":"Page size used for this request."},"hasNext":{"type":"boolean","examples":[true],"description":"Whether more results exist after this page."},"nextCursor":{"type":["string","null"],"description":"Cursor pointing to the last item on this page. Pass as `startingAfter` to fetch the next page."},"hasPrev":{"type":"boolean","examples":[false],"description":"Whether results exist before this page."},"prevCursor":{"type":["string","null"],"description":"Cursor pointing to the first item on this page. Pass as `endingBefore` to fetch the previous page."}},"required":["limit","hasNext","nextCursor","hasPrev","prevCursor"]}},"required":["data","pagination"]},"examples":{"default_example":{"value":{"data":[{"object":"withdrawal","id":"wtd_6SATV6VSUdBTttHWBmCYjD","currency":"USDC","withdrawalAmount":"1000.00","status":"COMPLETED","assetType":"CRYPTO","network":"ETHEREUM","withdrawalAccountId":"wac_NDqQ9LmcUASpnHR6CTvdkk","transactionHash":"0xdef456...","createdAt":"2026-03-22T12:00:00.000Z","metadata":{"clientId":"123e4567-e89b-12d3-a456-426614174000"}},{"object":"withdrawal","id":"wtd_8YPy9cT9R7QjMLMgnFDNsE","currency":"USD","withdrawalAmount":"5000.00","status":"COMPLETED","assetType":"FIAT","network":null,"withdrawalAccountId":"wac_UXpWaK83GJwYb8BUySn841","transactionHash":null,"paymentDetails":{"FEDWIRE":{"imad":"20260322ABC00318000742","omad":"20260322XYZ0041800293847561NQ0785"}},"createdAt":"2026-03-22T11:00:00.000Z","metadata":null}],"pagination":{"limit":25,"hasNext":true,"nextCursor":"eyJjcmVhdGVkQXQiOi...","hasPrev":false,"prevCursor":null}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"VALIDATION_BODY_FAILED","type":"VALIDATION_ERROR","message":"Request body failed validation. See details.issues for field-level errors, or details.firstIssuePath for the most common single-field case.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"fx_list_withdrawals","summary":"List withdrawals","tags":["FX"],"description":"Retrieve a history of all outgoing withdrawals, both fiat and stablecoin, from the account. Use this to track pending withdrawals, reconcile outgoing payments against bank or blockchain records, or generate a withdrawal history report. Cursor-paginated list of withdrawals (crypto + fiat) for your organization, newest first. Use `startingAfter` to fetch the next page and `endingBefore` to fetch the previous page. The two cursors are mutually exclusive.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Items per page (max 100, default 25)."},{"name":"startingAfter","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor to fetch the next page. Use the `nextCursor` from a previous response."},{"name":"endingBefore","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor to fetch the previous page. Use the `prevCursor` from a previous response."}]}},"/fx/trades/{id}":{"get":{"responses":{"200":{"description":"success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","const":"trade","example":"trade","description":"Resource type."},"id":{"type":"string","examples":["tde_5W7guYdHT24JFnRQrZN9y8"],"description":"Unique identifier for the trade."},"quoteId":{"type":"string","examples":["qte_TmHeAhdFLes63uGgDjcJRx"],"description":"ID of the quote this trade was executed against."},"buyCurrency":{"type":"string","examples":["USDC"],"description":"Currency the user bought."},"sellCurrency":{"type":"string","examples":["USD"],"description":"Currency the user sold."},"buyAmount":{"type":"string","examples":["1000"],"description":"Present when the trade was specified in `buyCurrency` terms."},"sellAmount":{"type":"string","examples":["1000"],"description":"Present when the trade was specified in `sellCurrency` terms."},"executedAmount":{"type":"string","examples":["999.8"],"description":"Final amount received in the counter-currency."},"status":{"type":"string","examples":["EXECUTED"],"description":"Lifecycle state of the trade."},"clientReferenceId":{"type":["string","null"],"examples":["order-123",null],"description":"Optional client-supplied reference for the trade, or null when unset."},"createdAt":{"type":"string","examples":["2026-03-22T12:00:00.000Z"],"description":"RFC 3339 timestamp at which the trade was created."},"settlementWindow":{"type":["string","null"],"enum":["IMMEDIATE","T0","T1","T2"],"examples":["T0"],"description":"Settlement window the trade settles in."},"settlementStartTime":{"type":["string","null"],"examples":["2026-03-22T12:04:00.000Z"],"description":"RFC 3339 timestamp at which settlement started, or null."}},"required":["object","id","quoteId","buyCurrency","sellCurrency","executedAmount","status","clientReferenceId","createdAt","settlementWindow","settlementStartTime"]}},"required":["data"]},"examples":{"default_example":{"value":{"data":{"object":"trade","id":"tde_5W7guYdHT24JFnRQrZN9y8","quoteId":"qte_TmHeAhdFLes63uGgDjcJRx","buyCurrency":"USDC","sellCurrency":"USD","buyAmount":"1000","executedAmount":"999.8","status":"EXECUTED","clientReferenceId":null,"createdAt":"2026-03-22T11:59:55.000Z","settlementWindow":"T0","settlementStartTime":"2026-03-22T12:04:00.000Z"}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"VALIDATION_BODY_FAILED","type":"VALIDATION_ERROR","message":"Request body failed validation. See details.issues for field-level errors, or details.firstIssuePath for the most common single-field case.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"404":{"description":"Trade not found","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"TRADE_NOT_FOUND","type":"NOT_FOUND","message":"The requested trade was not found.","retryStrategy":"TERMINAL","details":{}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"fx_get_trade","summary":"Get trade by ID","tags":["FX"],"description":"Retrieve details of a previously executed trade by its unique identifier. Returns the executed amount, currency pair, and execution timestamp. Use this to verify a trade executed correctly, check whether settlement is complete, or retrieve details for a specific transaction reference.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","examples":["tde_5W7guYdHT24JFnRQrZN9y8"]},"description":"Unique identifier of the trade to fetch."}]}},"/fx/trades/{id}/settle":{"post":{"responses":{"200":{"description":"success","headers":{"Idempotency-Replayed":{"description":"`true` when the response was served from the idempotency cache; `false` for a freshly settled request.","schema":{"type":"string","enum":["true","false"]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","const":"trade","example":"trade","description":"Resource type."},"id":{"type":"string","examples":["tde_5W7guYdHT24JFnRQrZN9y8"],"description":"Unique identifier for the trade."},"quoteId":{"type":"string","examples":["qte_TmHeAhdFLes63uGgDjcJRx"],"description":"ID of the quote this trade was executed against."},"buyCurrency":{"type":"string","examples":["USDC"],"description":"Currency the user bought."},"sellCurrency":{"type":"string","examples":["USD"],"description":"Currency the user sold."},"buyAmount":{"type":"string","examples":["1000"],"description":"Present when the trade was specified in `buyCurrency` terms."},"sellAmount":{"type":"string","examples":["1000"],"description":"Present when the trade was specified in `sellCurrency` terms."},"executedAmount":{"type":"string","examples":["999.8"],"description":"Final amount received in the counter-currency."},"status":{"type":"string","examples":["EXECUTED"],"description":"Lifecycle state of the trade."},"clientReferenceId":{"type":["string","null"],"examples":["order-123"],"description":"Client-supplied reference for the trade, if any."},"createdAt":{"type":"string","examples":["2026-03-22T12:00:00.000Z"],"description":"RFC 3339 timestamp at which the trade was created."},"settlementWindow":{"type":["string","null"],"enum":["IMMEDIATE","T0","T1","T2"],"examples":["T0"],"description":"Settlement window the trade settles in."},"settlementStartTime":{"type":["string","null"],"examples":["2026-03-22T12:04:00.000Z"],"description":"RFC 3339 timestamp at which settlement started, or null."},"settledAt":{"type":["string","null"],"examples":["2026-03-22T12:05:00.000Z"],"description":"RFC 3339 timestamp at which the trade settled, or null until settled."}},"required":["object","id","quoteId","buyCurrency","sellCurrency","executedAmount","status","clientReferenceId","createdAt","settlementWindow","settlementStartTime","settledAt"]}},"required":["data"]},"examples":{"default_example":{"value":{"data":{"object":"trade","id":"tde_5W7guYdHT24JFnRQrZN9y8","quoteId":"qte_TmHeAhdFLes63uGgDjcJRx","buyCurrency":"USDC","sellCurrency":"USD","sellAmount":"1000","executedAmount":"999.8","status":"EXECUTED","createdAt":"2026-03-22T12:00:00.000Z","settlementWindow":"T0","clientReferenceId":"order-123","settledAt":"2026-03-22T12:05:00.000Z","settlementStartTime":"2026-03-22T12:04:00.000Z"}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"VALIDATION_BODY_FAILED","type":"VALIDATION_ERROR","message":"Request body failed validation. See details.issues for field-level errors, or details.firstIssuePath for the most common single-field case.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"404":{"description":"Trade not found","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"TRADE_NOT_FOUND","type":"NOT_FOUND","message":"The requested trade was not found.","retryStrategy":"TERMINAL","details":{}}}}}}}},"409":{"description":"Conflict","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"IDEMPOTENCY_IN_FLIGHT","type":"CONFLICT","message":"Another request with this idempotency key is currently processing. Wait for some time and retry with the same key.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"fx_settle_trade","summary":"Settle trade","tags":["FX"],"x-idempotency-ttl-seconds":86400,"description":"Settle a manual trade that is ready to settle. Use this to finalize a trade whose settlement is performed manually. The trade must be a manual trade in a settleable state.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","examples":["tde_5W7guYdHT24JFnRQrZN9y8"]},"description":"Unique identifier of the trade to settle."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255,"pattern":"^[a-zA-Z0-9_-]{1,255}$","examples":["123e4567-e89b-12d3-a456-426614174000"]},"description":"Unique key to ensure idempotent requests. Valid for 24 hours."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}}}},"/fx/trades/{id}/reverse-quote":{"post":{"responses":{"200":{"description":"success","headers":{"Idempotency-Replayed":{"description":"`true` when served from the idempotency cache; `false` for a fresh reversal quote.","schema":{"type":"string","enum":["true","false"]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","const":"quote","example":"quote","description":"Resource type."},"id":{"type":"string","examples":["qte_3FfGK34vwMvVFDedyb2nkf"],"description":"Reversal quote identifier."},"buyCurrency":{"type":"string","examples":["USDC"],"description":"Currency bought by the reversal."},"sellCurrency":{"type":"string","examples":["USD"],"description":"Currency sold by the reversal."},"buyAmount":{"type":"string","examples":["122.9385076875"],"description":"Present when the surfaced leg is the buy side."},"sellAmount":{"type":"string","examples":["122.96925"],"description":"Present when the surfaced leg is the sell side."},"quoteAmount":{"type":"string","examples":["122.9385076875"],"description":"The counter leg of the reversal quote."},"expiresAt":{"type":"string","examples":["2026-07-02T03:06:35.017Z"],"description":"RFC 3339 timestamp at which the reversal quote expires."},"createdAt":{"type":"string","examples":["2026-07-02T03:06:20.017Z"],"description":"RFC 3339 timestamp at which the reversal quote was created."},"reversalDetails":{"type":"object","properties":{"direction":{"type":"string","enum":["DEBIT","CREDIT"],"examples":["DEBIT"],"description":"Direction of the differential against the account: DEBIT (charged) or CREDIT (refunded)."},"differentialAmount":{"type":"string","examples":["2.5"],"description":"Unsigned magnitude of the differential, in `currency`. The sign is carried by `direction`."},"currency":{"type":"string","examples":["USD"],"description":"Currency the differential is denominated in."}},"required":["direction","differentialAmount","currency"]}},"required":["object","id","buyCurrency","sellCurrency","quoteAmount","expiresAt","createdAt","reversalDetails"]}},"required":["data"]},"examples":{"default_example":{"value":{"data":{"object":"quote","id":"qte_8tq1QB8NboFWEJS7bLebAg","buyCurrency":"USDC","sellCurrency":"USD","sellAmount":"122.96925","quoteAmount":"122.9385076875","expiresAt":"2026-07-02T03:06:35.017Z","createdAt":"2026-07-02T03:06:20.017Z","reversalDetails":{"direction":"DEBIT","differentialAmount":"0.0614923125","currency":"USDC"}}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"VALIDATION_BODY_FAILED","type":"VALIDATION_ERROR","message":"Request body failed validation. See details.issues for field-level errors, or details.firstIssuePath for the most common single-field case.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"404":{"description":"Trade not found","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"TRADE_NOT_FOUND","type":"NOT_FOUND","message":"The requested trade was not found.","retryStrategy":"TERMINAL","details":{}}}}}}}},"409":{"description":"Conflict","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"IDEMPOTENCY_IN_FLIGHT","type":"CONFLICT","message":"Another request with this idempotency key is currently processing. Wait for some time and retry with the same key.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"fx_create_reversal_quote","summary":"Create reversal quote","tags":["FX"],"x-idempotency-ttl-seconds":1800,"description":"Generate a reversal quote for a previously executed trade. Returns a preview of the differential (the gain or loss from unwinding the trade at the current rate). Execute the reversal with fx_reverse_trade using the returned quote ID before it expires.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","examples":["tde_5W7guYdHT24JFnRQrZN9y8"]},"description":"Unique identifier of the trade to reverse."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255,"pattern":"^[a-zA-Z0-9_-]{1,255}$","examples":["123e4567-e89b-12d3-a456-426614174000"]},"description":"Unique key to ensure idempotent requests. Valid for 30 minutes."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"quoteForSeconds":{"type":"number","enum":[3,15,30,45,60],"examples":[15],"description":"Requested reversal-quote validity in seconds."}},"additionalProperties":false}}}}}},"/fx/trades/{id}/reverse":{"post":{"responses":{"200":{"description":"success","headers":{"Idempotency-Replayed":{"description":"`true` when served from the idempotency cache; `false` for a freshly executed reversal.","schema":{"type":"string","enum":["true","false"]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","const":"trade","example":"trade","description":"Resource type."},"id":{"type":"string","examples":["tde_5W7guYdHT24JFnRQrZN9y8"],"description":"Unique identifier for the trade."},"quoteId":{"type":"string","examples":["qte_TmHeAhdFLes63uGgDjcJRx"],"description":"ID of the quote this trade was executed against."},"buyCurrency":{"type":"string","examples":["USDC"],"description":"Currency the user bought."},"sellCurrency":{"type":"string","examples":["USD"],"description":"Currency the user sold."},"buyAmount":{"type":"string","examples":["1000"],"description":"Present when the trade was specified in `buyCurrency` terms."},"sellAmount":{"type":"string","examples":["1000"],"description":"Present when the trade was specified in `sellCurrency` terms."},"executedAmount":{"type":"string","examples":["999.8"],"description":"Final amount received in the counter-currency."},"status":{"type":"string","examples":["EXECUTED"],"description":"Lifecycle state of the trade."},"clientReferenceId":{"type":["string","null"],"examples":["order-123-reversal"],"description":"Client-supplied reference for the reversal, if any."},"createdAt":{"type":"string","examples":["2026-03-22T12:00:00.000Z"],"description":"RFC 3339 timestamp at which the trade was created."},"settlementWindow":{"type":["string","null"],"enum":["IMMEDIATE","T0","T1","T2"],"examples":["T0"],"description":"Settlement window the trade settles in."},"settlementStartTime":{"type":["string","null"],"examples":["2026-03-22T12:04:00.000Z"],"description":"RFC 3339 timestamp at which settlement started, or null."},"originalTradeId":{"type":"string","examples":["tde_5W7guYdHT24JFnRQrZN9y8"],"description":"ID of the original trade this reversal unwinds."},"reversalDetails":{"type":"object","properties":{"direction":{"type":"string","enum":["DEBIT","CREDIT"],"examples":["DEBIT"],"description":"Direction of the differential against the account: DEBIT (charged) or CREDIT (refunded)."},"differentialAmount":{"type":"string","examples":["2.5"],"description":"Unsigned magnitude of the differential, in `currency`. The sign is carried by `direction`."},"currency":{"type":"string","examples":["USD"],"description":"Currency the differential is denominated in."}},"required":["direction","differentialAmount","currency"]}},"required":["object","id","quoteId","buyCurrency","sellCurrency","executedAmount","status","clientReferenceId","createdAt","settlementWindow","settlementStartTime","originalTradeId","reversalDetails"]}},"required":["data"]},"examples":{"default_example":{"value":{"data":{"object":"trade","id":"tde_6SATV6VSUdBTttHWBmCYjD","quoteId":"qte_TmHeAhdFLes63uGgDjcJRx","buyCurrency":"USDC","sellCurrency":"USD","sellAmount":"1000","executedAmount":"999.8","status":"EXECUTED","createdAt":"2026-03-22T12:00:05.000Z","settlementWindow":"T0","settlementStartTime":null,"clientReferenceId":"order-123-reversal","originalTradeId":"tde_8XvH7fKH8hcFyopFF2PFas","reversalDetails":{"direction":"DEBIT","differentialAmount":"2.5","currency":"USD"}}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"VALIDATION_BODY_FAILED","type":"VALIDATION_ERROR","message":"Request body failed validation. See details.issues for field-level errors, or details.firstIssuePath for the most common single-field case.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"404":{"description":"Trade or quote not found","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"TRADE_NOT_FOUND","type":"NOT_FOUND","message":"The requested trade was not found.","retryStrategy":"TERMINAL","details":{}}}}}}}},"409":{"description":"Conflict","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"IDEMPOTENCY_IN_FLIGHT","type":"CONFLICT","message":"Another request with this idempotency key is currently processing. Wait for some time and retry with the same key.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"fx_reverse_trade","summary":"Reverse trade","tags":["FX"],"x-idempotency-ttl-seconds":86400,"description":"Execute a reversal of a previously executed trade against a reversal quote from fx_create_reversal_quote. Unwinds the original trade at the quoted rate, applying the differential. The reversal quote must be valid (not expired or already used).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","examples":["tde_8XvH7fKH8hcFyopFF2PFas"]},"description":"Unique identifier of the original trade to reverse."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255,"pattern":"^[a-zA-Z0-9_-]{1,255}$","examples":["123e4567-e89b-12d3-a456-426614174000"]},"description":"Unique key to ensure idempotent requests. Valid for 24 hours."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"quoteId":{"type":"string","minLength":1,"example":"qte_TmHeAhdFLes63uGgDjcJRx","description":"ID of the reversal quote to execute the reversal against."},"clientReferenceId":{"type":"string","examples":["order-123-reversal"],"description":"Optional client-supplied reference for the reversal."}},"required":["quoteId"],"additionalProperties":false}}}}}},"/fx/quotes/{id}":{"get":{"responses":{"200":{"description":"success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","const":"quote","example":"quote","description":"Resource type."},"id":{"type":"string","examples":["qte_3FfGK34vwMvVFDedyb2nkf"]},"buyCurrency":{"type":"string","examples":["USDC"]},"sellCurrency":{"type":"string","examples":["USD"]},"buyAmount":{"type":"string","examples":["1000"],"description":"Present when the quote was requested in `buyCurrency` terms."},"sellAmount":{"type":"string","examples":["1000"],"description":"Present when the quote was requested in `sellCurrency` terms."},"quoteAmount":{"type":"string","examples":["999.8000000079984"]},"createdAt":{"type":"string","examples":["2026-03-22T12:00:00.000Z"],"description":"RFC 3339 timestamp at which the quote was created."},"expiresAt":{"type":["string","null"],"examples":["2026-03-22T12:03:00.000Z"],"description":"RFC 3339 timestamp at which the quote expires."},"settlementWindow":{"type":"string","enum":["IMMEDIATE","T0","T1","T2"],"examples":["T0"],"description":"Settlement window for the resulting trade."},"status":{"type":"string","enum":["ACTIVE","EXPIRED","CONSUMED"],"examples":["ACTIVE"]}},"required":["object","id","buyCurrency","sellCurrency","quoteAmount","createdAt","expiresAt","status"]}},"required":["data"]},"examples":{"default_example":{"value":{"data":{"object":"quote","id":"qte_3FfGK34vwMvVFDedyb2nkf","buyCurrency":"USD","sellCurrency":"USDC","buyAmount":"1000","quoteAmount":"999.8000000079984","expiresAt":"2026-03-22T12:03:00.000Z","createdAt":"2026-03-22T12:02:57.000Z","status":"ACTIVE"}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"VALIDATION_BODY_FAILED","type":"VALIDATION_ERROR","message":"Request body failed validation. See details.issues for field-level errors, or details.firstIssuePath for the most common single-field case.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"404":{"description":"Quote not found","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"QUOTE_NOT_FOUND","type":"NOT_FOUND","message":"The requested quote was not found.","retryStrategy":"TERMINAL","details":{}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"fx_get_quote","summary":"Get quote by id","tags":["FX"],"description":"Check the details and status of a previously generated quote in the last 2 days, including whether it is still valid or has expired. Use this when you need to confirm a quote's validity before attempting execution.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","examples":["qte_3FfGK34vwMvVFDedyb2nkf"]},"description":"ID of the quote to fetch."}]}},"/fx/withdrawal-accounts":{"get":{"responses":{"200":{"description":"success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"withdrawalAccount","example":"withdrawalAccount","description":"Resource type."},"id":{"type":"string","examples":["wac_5mQnQqDsbVx3A5n4AmtmkR"],"description":"Unique identifier for the withdrawal account."},"assetType":{"type":"string","enum":["CRYPTO","FIAT"],"examples":["CRYPTO"],"description":"`CRYPTO` for on-chain addresses, `FIAT` for bank accounts."},"network":{"type":["string","null"],"examples":["ETHEREUM"],"description":"Chain the on-chain address settles over (UPPER_SNAKE_CASE, e.g. \"ETHEREUM\"). `null` for fiat accounts."},"rail":{"type":["string","null"],"examples":["SWIFT"],"description":"Fiat payment rail (UPPER_SNAKE_CASE) — determines the `destination` shape. One of SWIFT, SEPA, FEDWIRE, FPS, UAEFTS, NPP, PESONET, SPEI, PIX, PSE, ACH, TRANSFERENCIA_3_0, ACH/WIRE, CUBIX, BLINC, COELSA, SNP. `null` for crypto accounts, which carry `network` instead."},"displayName":{"type":["string","null"],"examples":["ETH USDC Wallet"],"description":"Caller-supplied display name. Maps to `name` for crypto and `nickname` (falling back to `accountName`) for fiat."},"currency":{"type":"string","examples":["USDC"],"description":"Currency symbol. Independent of rail — e.g. SWIFT applies to USD/EUR/GBP/AED."},"status":{"type":"string","enum":["PENDING","ACTIVE","ARCHIVED","REJECTED","DEACTIVATED","ADDITIONAL_ACTION_NEEDED"],"examples":["ACTIVE"],"description":"Lifecycle status of the account."},"verified":{"type":["boolean","null"],"examples":[true],"description":"Whether the account has cleared verification. `null` when the upstream verification state is not set (mirrors the stored value; matches v2)."},"creatorId":{"type":["string","null"],"examples":["usr_HMHpSX6QBbtQsVzRg1eaAF"],"description":"User ID that created the account. `null` only for legacy crypto rows."},"destination":{"anyOf":[{"$ref":"#/components/schemas/CryptoDestination"},{"$ref":"#/components/schemas/SwiftDestination"},{"$ref":"#/components/schemas/FedwireDestination"},{"$ref":"#/components/schemas/FpsDestination"},{"$ref":"#/components/schemas/LocalRailDestination"}],"description":"Rail-specific destination details. Shape is determined by `rail` — see the anatomy examples for each rail."},"createdAt":{"type":"string","examples":["2026-03-22T12:00:00.000Z"],"description":"RFC 3339 timestamp at which the account was created."},"updatedAt":{"type":"string","examples":["2026-03-22T12:00:00.000Z"],"description":"RFC 3339 timestamp at which the account was last updated."}},"required":["object","id","assetType","network","rail","displayName","currency","status","verified","creatorId","destination","createdAt","updatedAt"]}},"pagination":{"type":"object","properties":{"limit":{"type":"number","examples":[25],"description":"Page size used for this request."},"hasNext":{"type":"boolean","examples":[true],"description":"Whether more results exist after this page."},"nextCursor":{"type":["string","null"],"description":"Cursor pointing to the last item on this page. Pass as `startingAfter` to fetch the next page."},"hasPrev":{"type":"boolean","examples":[false],"description":"Whether results exist before this page."},"prevCursor":{"type":["string","null"],"description":"Cursor pointing to the first item on this page. Pass as `endingBefore` to fetch the previous page."}},"required":["limit","hasNext","nextCursor","hasPrev","prevCursor"]}},"required":["data","pagination"]},"examples":{"mixed_rails":{"summary":"Mixed list — one crypto + one fiat row","value":{"data":[{"object":"withdrawalAccount","id":"wac_5mQnQqDsbVx3A5n4AmtmkR","assetType":"CRYPTO","network":"ETHEREUM","rail":null,"displayName":"ETH USDC Treasury","currency":"USDC","status":"ACTIVE","verified":true,"creatorId":"usr_HMHpSX6QBbtQsVzRg1eaAF","destination":{"address":"0x2205844f0b80798F0e187c260753191eb668a495"},"createdAt":"2026-03-22T12:00:00.000Z","updatedAt":"2026-03-22T12:00:00.000Z"},{"object":"withdrawalAccount","id":"wac_TgWiiyTjcj2GMmNNhdGtw8","assetType":"FIAT","network":null,"rail":"FEDWIRE","displayName":"Ops USD payroll","currency":"USD","status":"ACTIVE","verified":true,"creatorId":"usr_HMHpSX6QBbtQsVzRg1eaAF","destination":{"accountName":"RedEnvelope Inc.","accountNumber":"123456789","bankName":"Zand Bank","routingNumber":"021000021","bankDetails":{"bankAddress":"270 Park Ave, New York, NY 10017"},"contactDetails":{"addressLineOne":"548 Market St","city":"San Francisco","state":"CA","postalCode":"94104","country":"US"},"meta":{"taxId":"84-1234567"}},"createdAt":"2026-03-20T08:00:00.000Z","updatedAt":"2026-03-20T08:00:00.000Z"}],"pagination":{"limit":25,"hasNext":false,"nextCursor":null,"hasPrev":false,"prevCursor":null}}},"usd_swift_with_intermediary":{"summary":"USD/SWIFT — intermediary bank lives in meta","value":{"data":[{"object":"withdrawalAccount","id":"wac_JaAf8vzg5Dj95u5RUQVFkA","assetType":"FIAT","network":null,"rail":"SWIFT","displayName":"USD SWIFT (intermediary)","currency":"USD","status":"ACTIVE","verified":true,"creatorId":"usr_HMHpSX6QBbtQsVzRg1eaAF","destination":{"accountName":"RedEnvelope Inc.","accountNumber":"987654321","bankName":"Standard Chartered","swiftCode":"SCBLAEAD","meta":{"intermediaryBankDetails":{"bankName":"JPMorgan Chase","swiftCode":"CHASUS33","routingNumber":"021000021"}}},"createdAt":"2026-03-18T09:00:00.000Z","updatedAt":"2026-03-18T09:00:00.000Z"}],"pagination":{"limit":25,"hasNext":false,"nextCursor":null,"hasPrev":false,"prevCursor":null}}},"eur_sepa":{"summary":"EUR/SEPA — same shape as SWIFT","value":{"data":[{"object":"withdrawalAccount","id":"wac_Dh1qygS1gyno5NidpRe1KU","assetType":"FIAT","network":null,"rail":"SEPA","displayName":"EUR vendor","currency":"EUR","status":"ACTIVE","verified":true,"creatorId":"usr_HMHpSX6QBbtQsVzRg1eaAF","destination":{"accountName":"Acme GmbH","accountNumber":"DE89370400440532013000","bankName":"Deutsche Bank","swiftCode":"DEUTDEFF"},"createdAt":"2026-03-19T10:00:00.000Z","updatedAt":"2026-03-19T10:00:00.000Z"}],"pagination":{"limit":25,"hasNext":false,"nextCursor":null,"hasPrev":false,"prevCursor":null}}},"gbp_fps":{"summary":"GBP/FPS — ukSortCode + optional leiCode","value":{"data":[{"object":"withdrawalAccount","id":"wac_LgPmGnpufNDyVcWSshjj7V","assetType":"FIAT","network":null,"rail":"FPS","displayName":"GBP payroll","currency":"GBP","status":"ACTIVE","verified":true,"creatorId":"usr_HMHpSX6QBbtQsVzRg1eaAF","destination":{"accountName":"RedEnvelope UK Ltd","accountNumber":"12345678","bankName":"Barclays","ukSortCode":"20-00-00","meta":{"leiCode":"213800XYZABCDEF12345"}},"createdAt":"2026-03-17T14:00:00.000Z","updatedAt":"2026-03-17T14:00:00.000Z"}],"pagination":{"limit":25,"hasNext":false,"nextCursor":null,"hasPrev":false,"prevCursor":null}}},"brl_pix":{"summary":"BRL/PIX — pixKey + taxId in meta","value":{"data":[{"object":"withdrawalAccount","id":"wac_Lp2rkaCWr2EoatdxYBn6Ta","assetType":"FIAT","network":null,"rail":"PIX","displayName":"BRL vendor","currency":"BRL","status":"ACTIVE","verified":true,"creatorId":"usr_HMHpSX6QBbtQsVzRg1eaAF","destination":{"accountName":"Fornecedor LTDA","accountNumber":"00012345","bankName":"Banco do Brasil","meta":{"pixKey":"00.123.456/0001-99","taxId":"00.123.456/0001-99","bankCode":"001"}},"createdAt":"2026-03-16T11:00:00.000Z","updatedAt":"2026-03-16T11:00:00.000Z"}],"pagination":{"limit":25,"hasNext":false,"nextCursor":null,"hasPrev":false,"prevCursor":null}}},"cop_ach":{"summary":"COP/ACH — taxId+bankCode in meta, accountType in bankDetails, email+phone in contactDetails","value":{"data":[{"object":"withdrawalAccount","id":"wac_NvGNR6ADnWU53Li99vLwn1","assetType":"FIAT","network":null,"rail":"ACH","displayName":"COP supplier","currency":"COP","status":"ACTIVE","verified":true,"creatorId":"usr_HMHpSX6QBbtQsVzRg1eaAF","destination":{"accountName":"Proveedor S.A.S.","accountNumber":"1234567890","bankName":"Bancolombia","bankDetails":{"accountType":"checking"},"contactDetails":{"email":"ops@proveedor.co","phone":"+57 1 234 5678","addressLineOne":"Cra 7 # 12-34","city":"Bogotá","country":"CO"},"meta":{"taxId":"900123456-1","bankCode":"007"}},"createdAt":"2026-03-15T09:00:00.000Z","updatedAt":"2026-03-15T09:00:00.000Z"}],"pagination":{"limit":25,"hasNext":false,"nextCursor":null,"hasPrev":false,"prevCursor":null}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"VALIDATION_BODY_FAILED","type":"VALIDATION_ERROR","message":"Request body failed validation. See details.issues for field-level errors, or details.firstIssuePath for the most common single-field case.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"fx_list_withdrawal_accounts","summary":"List withdrawal accounts","tags":["FX"],"description":"List all pre-approved accounts where funds can be sent, including bank accounts for fiat and wallet addresses for stablecoins. Use this to view available withdrawal options before initiating a withdrawal, or to look up a specific account ID required by fx_create_withdrawal. Cursor-paginated list of withdrawal accounts (crypto + fiat) for your organization, newest first. Crypto accounts carry `network` (the chain) with a null `rail`; fiat accounts carry `rail` (the bank rail) with a null `network`. The `rail` field determines the shape of `destination` (same rail across currencies yields the same shape). Use `assetType`, `network`, `rail`, `currency`, `status`, or `verified` to filter.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Items per page (max 100, default 25)."},{"name":"startingAfter","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor to fetch the next page. Use the `nextCursor` from a previous response."},{"name":"endingBefore","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor to fetch the previous page. Use the `prevCursor` from a previous response."},{"name":"assetType","in":"query","required":false,"schema":{"type":"string","enum":["CRYPTO","FIAT"]},"description":"Restrict results to CRYPTO or FIAT accounts (asset class). Omit to return both."},{"name":"verified","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]},"description":"Filter by verification state."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","active","archived","rejected","deactivated","additional_action_needed"]},"description":"Filter by account lifecycle status."},{"name":"currency","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by currency symbol. Must be uppercase (e.g. `USDC`, `USD`)."},{"name":"network","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by chain name. Must be uppercase (e.g. `ETHEREUM`). Implicitly excludes fiat accounts; combining it with `assetType=FIAT` returns 400."},{"name":"rail","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by fiat rail (e.g. `SWIFT`, `FEDWIRE`). Implicitly excludes crypto accounts; combining it with `assetType=CRYPTO` returns 400."}]}},"/fx/withdrawals/{id}":{"get":{"responses":{"200":{"description":"success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","const":"withdrawal","example":"withdrawal","description":"Resource type."},"id":{"type":"string","examples":["wtd_6SATV6VSUdBTttHWBmCYjD"],"description":"Unique identifier for the withdrawal."},"currency":{"type":"string","examples":["USDC"],"description":"Currency of the withdrawal."},"assetType":{"type":"string","enum":["CRYPTO","FIAT"],"examples":["CRYPTO"],"description":"Asset class: `CRYPTO` for on-chain, `FIAT` for bank rails."},"withdrawalAmount":{"type":"string","examples":["1000.00"],"description":"Amount withdrawn, in `currency`."},"status":{"type":"string","examples":["COMPLETED"],"description":"Lifecycle state of the withdrawal."},"network":{"type":["string","null"],"examples":["ETHEREUM"],"description":"Network the crypto withdrawal settled over; `null` for fiat withdrawals."},"withdrawalAccountId":{"type":["string","null"],"examples":["wac_NDqQ9LmcUASpnHR6CTvdkk"],"description":"ID of the destination withdrawal account used. `null` if no account is on record for the withdrawal."},"transactionHash":{"type":["string","null"],"examples":["0xdef456..."],"description":"On-chain transaction hash for crypto withdrawals once broadcast. `null` for fiat or before the chain leg lands."},"paymentDetails":{"type":["object","null"],"additionalProperties":{"type":"object","additionalProperties":{}},"description":"Network-specific identifiers populated once the withdrawal reaches a terminal state. Keyed by transferType (e.g. `{ \"FEDWIRE\": { \"imad\": \"...\", \"omad\": \"...\" } }`). Returned in the response only for fiat withdrawals; omitted entirely for crypto."},"actorId":{"type":"string","examples":["usr_7m4VsfRw4pGrS76WYj5tnx"],"description":"ID of the actor that initiated the withdrawal. Masked to a fixed placeholder when the actor is an internal (OpenFX / RedEnvelope) operator."},"actorEmail":{"type":"string","examples":["client-user@example.co"],"description":"Email of the actor that initiated the withdrawal. Masked to a fixed placeholder when the actor is an internal (OpenFX / RedEnvelope) operator."},"createdAt":{"type":"string","examples":["2026-03-22T12:00:00.000Z"],"description":"RFC 3339 timestamp at which the withdrawal was created."},"metadata":{"type":["object","null"],"propertyNames":{"type":"string","minLength":1,"maxLength":40},"additionalProperties":{"type":"string","maxLength":500},"description":"Optional client-owned metadata bag (string keys → string values). Echoed back verbatim on a successful response. Limits: at most 50 keys, keys up to 40 characters, values up to 500 characters, and at most 8192 bytes when serialized.","examples":[{"requestId":"client-generated-correlation-id"}]}},"required":["object","id","currency","assetType","withdrawalAmount","status","network","withdrawalAccountId","transactionHash","actorId","actorEmail","createdAt"]}},"required":["data"]},"examples":{"default_example":{"value":{"data":{"object":"withdrawal","id":"wtd_6SATV6VSUdBTttHWBmCYjD","currency":"USDC","withdrawalAmount":"1000.00","status":"COMPLETED","assetType":"CRYPTO","network":"ETHEREUM","withdrawalAccountId":"wac_NDqQ9LmcUASpnHR6CTvdkk","transactionHash":"0xdef456...","createdAt":"2026-03-22T12:00:00.000Z","metadata":{"key":"value"}}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"VALIDATION_BODY_FAILED","type":"VALIDATION_ERROR","message":"Request body failed validation. See details.issues for field-level errors, or details.firstIssuePath for the most common single-field case.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"404":{"description":"Withdrawal not found","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"WITHDRAWAL_NOT_FOUND","type":"NOT_FOUND","message":"The requested withdrawal was not found.","retryStrategy":"TERMINAL","details":{}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"fx_get_withdrawal","summary":"Get withdrawal by ID","tags":["FX"],"description":"Fetch a single withdrawal (crypto or fiat) by its ID. Returns the same row shape as the list endpoint. Get full details of a specific withdrawal including amount, currency, destination, status, and timestamp. Use this to check whether a withdrawal has been processed, completed, or failed, or to retrieve the blockchain transaction hash or bank reference for a specific payout.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","examples":["wtd_6SATV6VSUdBTttHWBmCYjD"]},"description":"Unique identifier of the withdrawal to fetch."}]}},"/fx/deposits":{"get":{"responses":{"200":{"description":"success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"deposit","example":"deposit","description":"Resource type."},"id":{"type":"string","examples":["dpt_EA9vbVngB76PmMibCiMNPb"],"description":"Unique identifier for the deposit."},"currency":{"type":"string","examples":["USDC"],"description":"Currency of the deposit."},"assetType":{"type":"string","enum":["CRYPTO","FIAT"],"examples":["CRYPTO"],"description":"Asset class: `CRYPTO` for on-chain, `FIAT` for bank rails."},"depositAmount":{"type":"string","examples":["5000.00"],"description":"Deposited amount as a decimal string."},"status":{"type":"string","examples":["COMPLETED"],"description":"Lifecycle state of the deposit at the moment of response."},"network":{"type":["string","null"],"examples":["ETHEREUM"],"description":"Settlement network for crypto deposits (canonical form, e.g. `ETHEREUM`); `null` for fiat deposits."},"transactionHash":{"type":["string","null"],"examples":["0xabc123..."],"description":"On-chain transaction hash for crypto deposits, `null` otherwise."},"referenceId":{"type":["string","null"],"examples":["INV-2026-0001"],"description":"External reference id supplied by the customer, if any."},"memo":{"type":["string","null"],"examples":[null],"description":"Optional memo line provided with the deposit."},"paymentDetails":{"type":["object","null"],"examples":[{"FEDWIRE":{"imad":"20260517KLR00318000742","omad":"20261103GHP0041800293847561NQ0785"}}],"description":"Payment-rail-specific identifiers (e.g. FEDWIRE IMAD/OMAD). Outer key is the transferType. Returned in the response only for fiat deposits; `null` for crypto deposits and any deposit without rail metadata."},"createdAt":{"type":"string","examples":["2026-03-22T11:50:00.000Z"],"description":"RFC 3339 timestamp at which the deposit was created."}},"required":["object","id","currency","assetType","depositAmount","status","network","transactionHash","referenceId","memo","createdAt"]}},"pagination":{"type":"object","properties":{"limit":{"type":"number","examples":[25],"description":"Page size used for this request."},"hasNext":{"type":"boolean","examples":[true],"description":"Whether more results exist after this page."},"nextCursor":{"type":["string","null"],"description":"Cursor pointing to the last item on this page. Pass as `startingAfter` to fetch the next page."},"hasPrev":{"type":"boolean","examples":[false],"description":"Whether results exist before this page."},"prevCursor":{"type":["string","null"],"description":"Cursor pointing to the first item on this page. Pass as `endingBefore` to fetch the previous page."}},"required":["limit","hasNext","nextCursor","hasPrev","prevCursor"]}},"required":["data","pagination"]},"examples":{"default_example":{"value":{"data":[{"object":"deposit","id":"dpt_EA9vbVngB76PmMibCiMNPb","currency":"USDC","depositAmount":"5000.00","status":"COMPLETED","assetType":"CRYPTO","network":"ETHEREUM","transactionHash":"0xabc123...","referenceId":"INV-2026-0001","memo":null,"createdAt":"2026-03-22T11:50:00.000Z"},{"object":"deposit","id":"dpt_GGNnm66gppS3syB6J4irne","currency":"USD","depositAmount":"10000.00","status":"COMPLETED","assetType":"FIAT","network":null,"transactionHash":null,"referenceId":"WIRE-2026-0042","memo":null,"paymentDetails":{"FEDWIRE":{"imad":"20260517KLR00318000742","omad":"20261103GHP0041800293847561NQ0785"}},"createdAt":"2026-03-22T10:00:00.000Z"}],"pagination":{"limit":25,"hasNext":true,"nextCursor":"eyJjcmVhdGVkQXQiOi4uLn0","hasPrev":false,"prevCursor":null}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"VALIDATION_BODY_FAILED","type":"VALIDATION_ERROR","message":"Request body failed validation. See details.issues for field-level errors, or details.firstIssuePath for the most common single-field case.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"fx_list_deposits","summary":"List deposits","tags":["FX"],"description":"Retrieve a history of all incoming deposits, both fiat and stablecoin, into the account. Use this to confirm whether an expected deposit has arrived, to reconcile incoming funds against bank or blockchain records, or to generate a funding history report. Supports cursor pagination and filtering by currency.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Items per page (max 100, default 25)."},{"name":"startingAfter","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor to fetch the next page. Use the `nextCursor` from a previous response."},{"name":"endingBefore","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor to fetch the previous page. Use the `prevCursor` from a previous response."},{"name":"currency","in":"query","required":false,"schema":{"type":"string","enum":["USD","AED","GBP","EUR","AUD","MXN","BRL","PHP","ARS","COP","INR","CHF","IDR","NOK","PLN","SGD","ZAR","DKK","HKD","SEK","USDT","USDC","EURC","EUROP"]},"description":"Filter deposits by a supported currency code (e.g. `USDC`, `USD`)."}]}},"/fx/deposits/{id}":{"get":{"responses":{"200":{"description":"success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","const":"deposit","example":"deposit","description":"Resource type."},"id":{"type":"string","examples":["dpt_EA9vbVngB76PmMibCiMNPb"],"description":"Unique identifier for the deposit."},"currency":{"type":"string","examples":["USDC"],"description":"Currency of the deposit."},"assetType":{"type":"string","enum":["CRYPTO","FIAT"],"examples":["CRYPTO"],"description":"Asset class: `CRYPTO` for on-chain, `FIAT` for bank rails."},"depositAmount":{"type":"string","examples":["5000.00"],"description":"Deposited amount as a decimal string."},"status":{"type":"string","examples":["COMPLETED"],"description":"Lifecycle state of the deposit at the moment of response."},"network":{"type":["string","null"],"examples":["ETHEREUM"],"description":"Settlement network for crypto deposits (canonical form, e.g. `ETHEREUM`); `null` for fiat deposits."},"transactionHash":{"type":["string","null"],"examples":["0xabc123..."],"description":"On-chain transaction hash for crypto deposits, `null` otherwise."},"referenceId":{"type":["string","null"],"examples":["INV-2026-0001"],"description":"External reference id supplied by the customer, if any."},"memo":{"type":["string","null"],"examples":[null],"description":"Optional memo line provided with the deposit."},"paymentDetails":{"type":["object","null"],"examples":[{"FEDWIRE":{"imad":"20260517KLR00318000742","omad":"20261103GHP0041800293847561NQ0785"}}],"description":"Payment-rail-specific identifiers (e.g. FEDWIRE IMAD/OMAD). Outer key is the transferType. Returned in the response only for fiat deposits; `null` for crypto deposits and any deposit without rail metadata."},"createdAt":{"type":"string","examples":["2026-03-22T11:50:00.000Z"],"description":"RFC 3339 timestamp at which the deposit was created."}},"required":["object","id","currency","assetType","depositAmount","status","network","transactionHash","referenceId","memo","createdAt"]}},"required":["data"]},"examples":{"default_example":{"value":{"data":{"object":"deposit","id":"dpt_EA9vbVngB76PmMibCiMNPb","currency":"USDC","depositAmount":"5000.00","status":"COMPLETED","assetType":"CRYPTO","network":"ETHEREUM","transactionHash":"0xabc123...","referenceId":"INV-2026-0001","memo":null,"createdAt":"2026-03-22T11:50:00.000Z"}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"VALIDATION_BODY_FAILED","type":"VALIDATION_ERROR","message":"Request body failed validation. See details.issues for field-level errors, or details.firstIssuePath for the most common single-field case.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"404":{"description":"Deposit not found","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"DEPOSIT_NOT_FOUND","type":"NOT_FOUND","message":"The requested deposit was not found.","retryStrategy":"TERMINAL","details":{}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"fx_get_deposit","summary":"Get deposit by ID","tags":["FX"],"description":"Retrieve details of a single deposit for fiat or stablecoin, by its unique identifier. Use this to confirm whether a specific deposit has arrived, to reconcile a known reference against bank or blockchain records, or to inspect payment-rail metadata (e.g. FEDWIRE IMAD/OMAD).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","examples":["dpt_EA9vbVngB76PmMibCiMNPb"]},"description":"Unique identifier of the deposit to fetch."}]}},"/display-ids":{"get":{"responses":{"200":{"description":"success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":{"type":"object","properties":{"id":{"type":"string","example":"2c011d8b-1822-4d1c-9b16-414aaf2b2de4"},"object":{"type":"string","example":"trade"}},"required":["id","object"]},"example":{"tde_5W7guYdHT24JFnRQrZN9y8":{"id":"24753ee0-c3e9-4268-a48f-0cef3559f17f","object":"trade"},"qte_TmHeAhdFLes63uGgDjcJRx":{"id":"d8bc9618-2830-1822-9ae2-414aaf2b2de3","object":"quote"}}}},"required":["data"]},"examples":{"default_example":{"value":{"data":{"tde_5W7guYdHT24JFnRQrZN9y8":{"id":"24753ee0-c3e9-4268-a48f-0cef3559f17f","object":"trade"},"qte_TmHeAhdFLes63uGgDjcJRx":{"id":"d8bc9618-2830-1822-9ae2-414aaf2b2de3","object":"quote"}}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"VALIDATION_BODY_FAILED","type":"VALIDATION_ERROR","message":"Request body failed validation. See details.issues for field-level errors, or details.firstIssuePath for the most common single-field case.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"examples":{"default_example":{"value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"lookup_display_ids","summary":"Resolve readable IDs to UUIDs","description":"Batch-resolve typed IDs (e.g. `tde_…`, `qte_…`) to their underlying UUID and object type. All-or-nothing: any malformed ID, or more than the cap, fails the whole request.","parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string"},"description":"Typed IDs to resolve, as a comma-separated list and/or repeated `ids` params (max 50 per request; duplicates count toward the limit and collapse to one key in the response)."}]}},"/payments/payout-quotes":{"post":{"responses":{"200":{"description":"success","headers":{"Idempotency-Replayed":{"description":"`true` when the response was served from the idempotency cache; `false` for a freshly executed request.","schema":{"type":"string","enum":["true","false"]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","const":"payoutQuote","examples":["payoutQuote"],"description":"The type of object represented, a fixed discriminator. Always `\"payoutQuote\"` for this resource."},"id":{"type":"string","pattern":"^pytqte_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"pytqte_7RJWhvQBQPEjJmki5fhBbo","description":"Quote identifier."},"financialAccountId":{"type":"string","pattern":"^finacc_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"finacc_eUzeSQF9ZY6q4x8AhBskUf","description":"Financial account debited."},"receiver":{"type":"object","properties":{"accountId":{"type":"string","pattern":"^acc_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"acc_h82pJGF9p7kpzb6eU326EF","description":"The account being paid, derived from the payout address."},"payoutAddressId":{"type":"string","pattern":"^pytadd_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"pytadd_NJAEqN76R7PwPfHt3oWb8R","description":"The payout address the funds are credited to."}},"required":["accountId","payoutAddressId"],"additionalProperties":false},"rail":{"type":"string","enum":["SEPA","SWIFT","IMPS","NEFT","RTGS"],"examples":["IMPS"],"description":"Rail selected for the payout, based on which the fee is calculated."},"sendAmount":{"type":"string","pattern":"^[0-9]+\\.[0-9]{6}$","examples":["1000.000000"],"description":"Total debited on the send side: `fxRates.convertedAmount` plus `fees.totalAmount`."},"sendCurrency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["USD"],"description":"Currency of the send leg, always the financial account's currency."},"receiveAmount":{"type":"string","pattern":"^[0-9]+(\\.[0-9]{1,8})?$","examples":["83450.00"],"description":"Amount delivered on the receive side."},"receiveCurrency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["INR"],"description":"Currency of the receive leg."},"fees":{"type":"object","properties":{"totalAmount":{"type":"string","pattern":"^[0-9]+\\.[0-9]{6}$","examples":["3.000000"],"description":"Total of the fee components, added on top of `fxRates.convertedAmount` to make `sendAmount`."},"currency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["USD"],"description":"Currency of `totalAmount`."},"components":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["NETWORK_FEE","SWIFT_FEE","RESIDENT_DISCOUNT"],"examples":["NETWORK_FEE"],"description":"Kind of fee charged on top of the conversion. A `SWIFT_FEE` is a flat charge beside the `NETWORK_FEE` on a payout whose `rail` is `SWIFT`; a `RESIDENT_DISCOUNT` carries a negative `amount`."},"amount":{"type":"string","pattern":"^-?[0-9]+\\.[0-9]{6}$","examples":["5.000000"],"description":"What this component comes to. Negative for a discount such as `RESIDENT_DISCOUNT`."},"currency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["USD"],"description":"Currency of this component's `amount`."}},"required":["type","amount","currency"],"additionalProperties":false},"description":"Itemised breakdown. The components sum to `totalAmount`."}},"required":["totalAmount","currency","components"],"additionalProperties":false},"fixedSide":{"type":"string","enum":["SEND","RECEIVE"],"examples":["SEND"],"description":"Which leg is held exact. Derived from whichever amount the request provided: `sendAmount` gives `SEND`, `receiveAmount` gives `RECEIVE`."},"fxRates":{"type":"object","properties":{"client":{"type":"string","pattern":"^[0-9]+(\\.[0-9]{1,16})?$","examples":["1.10165"],"description":"Rate applied, in units of `sendCurrency` per unit of `receiveCurrency`. Conversion costs are already priced in."},"convertedAmount":{"type":"string","pattern":"^[0-9]+\\.[0-9]{6}$","examples":["110.165000"],"description":"What the receive leg comes to in `sendCurrency` at `client`, before the payout-leg fees."},"expiresAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:33:00.000Z"],"description":"When this rate expires. Omitted on a like-for-like quote, where no rate is locked."}},"required":["client","convertedAmount"],"additionalProperties":false},"sender":{"type":"object","properties":{"accountId":{"type":"string","pattern":"^acc_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"acc_Zf2cDnimbTFVeJtx1qtBmU","description":"Referenced account."}},"required":["accountId"],"additionalProperties":false},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own key/value pairs, echoed back verbatim."},"createdAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"Creation timestamp."}},"required":["object","id","financialAccountId","receiver","sendAmount","sendCurrency","receiveAmount","receiveCurrency","fees","fixedSide","fxRates","createdAt"],"additionalProperties":false}},"required":["data"]},"examples":{"default_example":{"summary":"USD → INR quote, send side fixed","value":{"data":{"object":"payoutQuote","id":"pytqte_7RJWhvQBQPEjJmki5fhBbo","financialAccountId":"finacc_eUzeSQF9ZY6q4x8AhBskUf","receiver":{"accountId":"acc_h82pJGF9p7kpzb6eU326EF","payoutAddressId":"pytadd_NJAEqN76R7PwPfHt3oWb8R"},"rail":"IMPS","sendAmount":"1000.000000","sendCurrency":"USD","receiveAmount":"83450.00","receiveCurrency":"INR","fees":{"totalAmount":"3.000000","currency":"USD","components":[{"type":"NETWORK_FEE","amount":"3.000000","currency":"USD"}]},"fixedSide":"SEND","fxRates":{"client":"83.6835","convertedAmount":"997.000000","expiresAt":"2026-06-04T10:31:00.000Z"},"createdAt":"2026-06-04T10:30:00.000Z"}}}}}}},"400":{"description":"The request failed validation, has an invalid Content-Type, the Idempotency-Key is malformed, or the gateway context was missing.","content":{"application/json":{"examples":{"validation_body_failed":{"summary":"Request body failed validation. See details.issues for field-level errors, or details.firstIssuePath for the most common single-field case.","value":{"error":{"code":"VALIDATION_BODY_FAILED","type":"VALIDATION_ERROR","message":"Request body failed validation. See details.issues for field-level errors, or details.firstIssuePath for the most common single-field case.","retryStrategy":"FIX_AND_RESUBMIT","details":{"issues":[{"path":"/identity/individual/lastName","code":"invalid_type","message":"Required","expected":"string","received":"undefined"},{"path":"/identity/individual/documents/0/type","code":"invalid_enum_value","message":"is not a supported document type","expected":"PASSPORT|NATIONAL_ID|DRIVERS_LICENSE|SSN|RESIDENCE_PERMIT","received":"LIBRARY_CARD"},{"path":"/identity/individual/residentialAddress/country","code":"custom","message":"is not an ISO 3166-1 alpha-2 country code (the United Kingdom is GB)","received":"UK"}],"firstIssuePath":"/identity/individual/lastName"}}}},"validation_content_type":{"summary":"Content-Type must be application/json.","value":{"error":{"code":"VALIDATION_CONTENT_TYPE","type":"VALIDATION_ERROR","message":"Content-Type must be application/json.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"idempotency_key_invalid":{"summary":"Idempotency-Key is malformed. Generate a new key matching the documented pattern and retry with that new key.","value":{"error":{"code":"IDEMPOTENCY_KEY_INVALID","type":"VALIDATION_ERROR","message":"Idempotency-Key is malformed. Generate a new key matching the documented pattern and retry with that new key.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"missing_request_context":{"summary":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","value":{"error":{"code":"MISSING_REQUEST_CONTEXT","type":"VALIDATION_ERROR","message":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"invalid_organization":{"summary":"The organization identifier on the request is malformed. Send the request through the documented gateway.","value":{"error":{"code":"INVALID_ORGANIZATION","type":"VALIDATION_ERROR","message":"The organization identifier on the request is malformed. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"The request is not authenticated.","content":{"application/json":{"examples":{"auth_token_missing":{"summary":"The Authorization header is missing. Provide a Bearer JWT.","value":{"error":{"code":"AUTH_TOKEN_MISSING","type":"AUTHENTICATION_ERROR","message":"The Authorization header is missing. Provide a Bearer JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid":{"summary":"Authorization token is invalid. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_expired":{"summary":"Authorization token has expired. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_EXPIRED","type":"AUTHENTICATION_ERROR","message":"Authorization token has expired. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid_config":{"summary":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","value":{"error":{"code":"AUTH_TOKEN_INVALID_CONFIG","type":"AUTHENTICATION_ERROR","message":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","retryStrategy":"TERMINAL","details":{}}}},"auth_api_key_invalid":{"summary":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","value":{"error":{"code":"AUTH_API_KEY_INVALID","type":"AUTHENTICATION_ERROR","message":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"The API key may not perform this operation.","content":{"application/json":{"examples":{"auth_insufficient_scope":{"summary":"The API key is missing the scope required for this operation.","value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"404":{"description":"A referenced resource does not exist in this org.","content":{"application/json":{"examples":{"account_not_found":{"summary":"No account with that id in this org.","value":{"error":{"code":"ACCOUNT_NOT_FOUND","type":"NOT_FOUND","message":"No account with that id in this org.","retryStrategy":"TERMINAL","details":{}}}},"financial_account_not_found":{"summary":"No financial account with that id in this org.","value":{"error":{"code":"FINANCIAL_ACCOUNT_NOT_FOUND","type":"NOT_FOUND","message":"No financial account with that id in this org.","retryStrategy":"TERMINAL","details":{}}}},"payout_address_not_found":{"summary":"No payout address with that id in this org.","value":{"error":{"code":"PAYOUT_ADDRESS_NOT_FOUND","type":"NOT_FOUND","message":"No payout address with that id in this org.","retryStrategy":"TERMINAL","details":{}}}}}}}},"409":{"description":"The request conflicts with current state, or with an in-flight request using the same key.","content":{"application/json":{"examples":{"idempotency_in_flight":{"summary":"Another request with this idempotency key is currently processing. Wait for some time and retry with the same key.","value":{"error":{"code":"IDEMPOTENCY_IN_FLIGHT","type":"CONFLICT","message":"Another request with this idempotency key is currently processing. Wait for some time and retry with the same key.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}},"account_archived":{"summary":"The account is archived and cannot take new work.","value":{"error":{"code":"ACCOUNT_ARCHIVED","type":"CONFLICT","message":"The account is archived and cannot take new work.","retryStrategy":"TERMINAL","details":{"accountId":"acc_h82pJGF9p7kpzb6eU326EF"}}}},"account_not_active":{"summary":"The account's standing does not allow this operation.","value":{"error":{"code":"ACCOUNT_NOT_ACTIVE","type":"CONFLICT","message":"The account's standing does not allow this operation.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{"accountId":"acc_h82pJGF9p7kpzb6eU326EF","status":"REJECTED"}}}},"agreements_not_active":{"summary":"Required agreements for this account are not active.","value":{"error":{"code":"AGREEMENTS_NOT_ACTIVE","type":"CONFLICT","message":"Required agreements for this account are not active.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}},"agreements_pending":{"summary":"Required agreements for this account are still pending.","value":{"error":{"code":"AGREEMENTS_PENDING","type":"CONFLICT","message":"Required agreements for this account are still pending.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}},"beneficiary_details_missing":{"summary":"A detail the receiving institution requires for this payout is missing from the destination payout address. Supply it on the address, then retry.","value":{"error":{"code":"BENEFICIARY_DETAILS_MISSING","type":"CONFLICT","message":"A detail the receiving institution requires for this payout is missing from the destination payout address. Supply it on the address, then retry.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}},"capability_not_active":{"summary":"The beneficiary does not hold an active capability this payout requires. Complete the capability setup and retry.","value":{"error":{"code":"CAPABILITY_NOT_ACTIVE","type":"CONFLICT","message":"The beneficiary does not hold an active capability this payout requires. Complete the capability setup and retry.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{"accountId":"acc_h82pJGF9p7kpzb6eU326EF","required":{"grant":"RECEIVE_PAYOUTS","currency":"INR","repatriability":"NON_REPATRIABLE"},"capabilityId":"cap_Ce3AJmB1WMUZmkD9mMKVx","status":"PENDING"}}}},"kyc_required":{"summary":"The account needs identity verification before this payout can be created.","value":{"error":{"code":"KYC_REQUIRED","type":"CONFLICT","message":"The account needs identity verification before this payout can be created.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}},"payout_address_archived":{"summary":"This payout address was archived by the client and can no longer be paid. Create the payout to a different address.","value":{"error":{"code":"PAYOUT_ADDRESS_ARCHIVED","type":"CONFLICT","message":"This payout address was archived by the client and can no longer be paid. Create the payout to a different address.","retryStrategy":"TERMINAL","details":{}}}},"payout_address_rejected":{"summary":"This payout address is rejected and cannot be paid.","value":{"error":{"code":"PAYOUT_ADDRESS_REJECTED","type":"CONFLICT","message":"This payout address is rejected and cannot be paid.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}},"payout_not_enabled":{"summary":"Payouts are not enabled for this organization.","value":{"error":{"code":"PAYOUT_NOT_ENABLED","type":"CONFLICT","message":"Payouts are not enabled for this organization.","retryStrategy":"TERMINAL","details":{}}}},"quote_temporarily_unavailable":{"summary":"Quoting is temporarily unavailable for the requested currencies. Retry shortly.","value":{"error":{"code":"QUOTE_TEMPORARILY_UNAVAILABLE","type":"CONFLICT","message":"Quoting is temporarily unavailable for the requested currencies. Retry shortly.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}},"422":{"description":"A business rule was tripped by the request's own values, or the key was replayed with a different body.","content":{"application/json":{"examples":{"idempotency_mismatch":{"summary":"This idempotency key was previously seen with a different request body. Use a new key for a new request, or resubmit the original body verbatim.","value":{"error":{"code":"IDEMPOTENCY_MISMATCH","type":"CONFLICT","message":"This idempotency key was previously seen with a different request body. Use a new key for a new request, or resubmit the original body verbatim.","retryStrategy":"FIX_AND_RESUBMIT","details":{"originalRequestHash":"sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"}}}},"amount_out_of_range":{"summary":"The amount is outside the permitted range for payouts to this destination. See details.issues for the violating amount and its bound, then adjust the amount and resubmit.","value":{"error":{"code":"AMOUNT_OUT_OF_RANGE","type":"VALIDATION_ERROR","message":"The amount is outside the permitted range for payouts to this destination. See details.issues for the violating amount and its bound, then adjust the amount and resubmit.","retryStrategy":"FIX_AND_RESUBMIT","details":{"issues":[{"path":"/receiveAmount","code":"amount_below_minimum","message":"receiveAmount 50.00 INR is below the 100.00 INR minimum for this payout destination"}],"firstIssuePath":"/receiveAmount","amount":"50.00","minimum":"100.00","currency":"INR"}}}},"financial_account_currency_mismatch":{"summary":"The financial account's currency does not match the send currency for this payout.","value":{"error":{"code":"FINANCIAL_ACCOUNT_CURRENCY_MISMATCH","type":"VALIDATION_ERROR","message":"The financial account's currency does not match the send currency for this payout.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"identity_requirement_unmet":{"summary":"A requested capability needs more identity information than the account has supplied. details names each capability and its unmet requirements.","value":{"error":{"code":"IDENTITY_REQUIREMENT_UNMET","type":"VALIDATION_ERROR","message":"A requested capability needs more identity information than the account has supplied. details names each capability and its unmet requirements.","retryStrategy":"FIX_AND_RESUBMIT","details":{"issues":[{"path":"/identity/individual/nationality","code":"invalid_type","message":"Required","expected":"string","received":"undefined"},{"path":"/identity/individual/residentialAddress/country","code":"invalid_type","message":"Required","expected":"string","received":"undefined"}],"firstIssuePath":"/identity/individual/nationality"}}}},"quote_rail_unavailable":{"summary":"No rail is available for the requested corridor.","value":{"error":{"code":"QUOTE_RAIL_UNAVAILABLE","type":"VALIDATION_ERROR","message":"No rail is available for the requested corridor.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"quote_rejected":{"summary":"A quote is not available for the requested currencies or amount.","value":{"error":{"code":"QUOTE_REJECTED","type":"VALIDATION_ERROR","message":"A quote is not available for the requested currencies or amount.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"quote_send_currency_unavailable":{"summary":"The requested send currency is not available for this corridor.","value":{"error":{"code":"QUOTE_SEND_CURRENCY_UNAVAILABLE","type":"VALIDATION_ERROR","message":"The requested send currency is not available for this corridor.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"sender_account_required":{"summary":"This payout requires a sender account, but none was named. Provide sender and resubmit.","value":{"error":{"code":"SENDER_ACCOUNT_REQUIRED","type":"VALIDATION_ERROR","message":"This payout requires a sender account, but none was named. Provide sender and resubmit.","retryStrategy":"FIX_AND_RESUBMIT","details":{"issues":[{"path":"/sender","code":"invalid_type","message":"Required","expected":"object","received":"undefined"}],"firstIssuePath":"/sender"}}}}}}}},"428":{"description":"The Idempotency-Key header is required for this endpoint.","content":{"application/json":{"examples":{"idempotency_key_missing":{"summary":"The Idempotency-Key header is required for this endpoint.","value":{"error":{"code":"IDEMPOTENCY_KEY_MISSING","type":"VALIDATION_ERROR","message":"The Idempotency-Key header is required for this endpoint.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"429":{"description":"The API key has exceeded its request rate limit.","content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"This API key has exceeded its request rate limit for the current window.","value":{"error":{"code":"RATE_LIMIT_EXCEEDED","type":"RATE_LIMITED","message":"This API key has exceeded its request rate limit for the current window.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}},"500":{"description":"An unexpected internal error occurred.","content":{"application/json":{"examples":{"internal_error":{"summary":"An unexpected internal error occurred. Contact support with the trace ID.","value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"createPayoutQuote","summary":"Create payment quote","tags":["Payouts"],"description":"Price a payout without committing to it. Returns an immutable, time-bounded snapshot of the rate and fees, held until `fxRates.expiresAt`. Provide exactly one of `sendAmount` or `receiveAmount`; the other is derived and `fixedSide` records which one you fixed. Pass the returned `id` as `quoteId` on POST /v3/payments/payouts to apply this exact pricing — applying an expired quote is rejected with 409 QUOTE_EXPIRED. Creating a quote moves no funds.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","format":"uuid","example":"123e4567-e89b-12d3-a456-426614174000"},"description":"Unique key to ensure idempotent requests. UUID v4 recommended."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"financialAccountId":{"type":"string","example":"finacc_eUzeSQF9ZY6q4x8AhBskUf","description":"Financial account debited. One of the accounts from GET /v3/common/financial-accounts."},"receiver":{"type":"object","properties":{"payoutAddressId":{"type":"string","example":"pytadd_NJAEqN76R7PwPfHt3oWb8R","description":"The payout address the funds are credited to."}},"required":["payoutAddressId"],"additionalProperties":false},"sendAmount":{"type":"string","pattern":"^[0-9]+(\\.[0-9]{1,8})?$","examples":["1000.00"],"description":"Total to debit, fees included. Provide exactly one of `sendAmount` / `receiveAmount`."},"receiveAmount":{"type":"string","pattern":"^[0-9]+(\\.[0-9]{1,8})?$","examples":["83450.00"],"description":"Amount to deliver on the receive side. Provide exactly one of `sendAmount` / `receiveAmount`."},"receiveCurrency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["INR"],"description":"Currency to send to the receiver. Must be supported by the selected payout address."},"quoteForSeconds":{"type":"integer","examples":[60],"description":"How long the resulting quote's price is held, in seconds. Omit to default to 60, or your organization's configured hold when one is set."},"metadata":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":40},"additionalProperties":{"type":"string","maxLength":500},"description":"Optional client-owned metadata bag (string keys → string values). Echoed back verbatim on a successful response. Limits: at most 50 keys, keys up to 40 characters, values up to 500 characters, and at most 8192 bytes when serialized.","examples":[{"requestId":"client-generated-correlation-id"}]},"sender":{"type":"object","properties":{"accountId":{"type":"string","example":"acc_Zf2cDnimbTFVeJtx1qtBmU","description":"Referenced account."}},"required":["accountId"],"additionalProperties":false}},"required":["receiver","receiveCurrency"],"additionalProperties":false}}}}}},"/payments/payouts":{"post":{"responses":{"200":{"description":"success","headers":{"Idempotency-Replayed":{"description":"`true` when the response was served from the idempotency cache; `false` for a freshly executed request.","schema":{"type":"string","enum":["true","false"]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","const":"payout","examples":["payout"],"description":"The type of object represented, a fixed discriminator. Always `\"payout\"` for this resource."},"id":{"type":"string","pattern":"^pyt_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"pyt_GBWRJhmcFkMvrr4Fu3tMSJ","description":"Payout identifier."},"financialAccountId":{"type":"string","pattern":"^finacc_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"finacc_eUzeSQF9ZY6q4x8AhBskUf","description":"Financial account debited."},"receiver":{"type":"object","properties":{"accountId":{"type":"string","pattern":"^acc_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"acc_h82pJGF9p7kpzb6eU326EF","description":"The account being paid, derived from the payout address."},"payoutAddressId":{"type":"string","pattern":"^pytadd_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"pytadd_NJAEqN76R7PwPfHt3oWb8R","description":"The payout address the funds are credited to."}},"required":["accountId","payoutAddressId"],"additionalProperties":false},"rail":{"type":"string","enum":["SEPA","SWIFT","IMPS","NEFT","RTGS"],"examples":["IMPS"],"description":"Settlement rail selected; always present once resolved."},"sendAmount":{"type":"string","pattern":"^[0-9]+\\.[0-9]{6}$","examples":["1000.000000"],"description":"Total debited on the send side."},"sendCurrency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["USD"],"description":"Currency of the send leg."},"receiveAmount":{"type":"string","pattern":"^[0-9]+(\\.[0-9]{1,8})?$","examples":["83450.00"],"description":"Amount delivered on the receive side."},"receiveCurrency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["INR"],"description":"Currency of the receive leg."},"fees":{"type":"object","properties":{"totalAmount":{"type":"string","pattern":"^[0-9]+\\.[0-9]{6}$","examples":["3.000000"],"description":"Total of the fee components, added on top of `fxRates.convertedAmount` to make `sendAmount`."},"currency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["USD"],"description":"Currency of `totalAmount`."},"components":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["NETWORK_FEE","SWIFT_FEE","RESIDENT_DISCOUNT"],"examples":["NETWORK_FEE"],"description":"Kind of fee charged on top of the conversion. A `SWIFT_FEE` is a flat charge beside the `NETWORK_FEE` on a payout whose `rail` is `SWIFT`; a `RESIDENT_DISCOUNT` carries a negative `amount`."},"amount":{"type":"string","pattern":"^-?[0-9]+\\.[0-9]{6}$","examples":["5.000000"],"description":"What this component comes to. Negative for a discount such as `RESIDENT_DISCOUNT`."},"currency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["USD"],"description":"Currency of this component's `amount`."}},"required":["type","amount","currency"],"additionalProperties":false},"description":"Itemised breakdown. The components sum to `totalAmount`."}},"required":["totalAmount","currency","components"],"additionalProperties":false},"fixedSide":{"type":"string","enum":["SEND","RECEIVE"],"examples":["SEND"],"description":"Which leg is held exact. Derived from whichever amount the request provided: `sendAmount` gives `SEND`, `receiveAmount` gives `RECEIVE`."},"fxRates":{"type":"object","properties":{"client":{"type":"string","pattern":"^[0-9]+(\\.[0-9]{1,16})?$","examples":["1.10165"],"description":"Rate applied, in units of `sendCurrency` per unit of `receiveCurrency`. Conversion costs are already priced in."},"convertedAmount":{"type":"string","pattern":"^[0-9]+\\.[0-9]{6}$","examples":["110.165000"],"description":"What the receive leg comes to in `sendCurrency` at `client`, before the payout-leg fees."},"expiresAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:33:00.000Z"],"description":"When this rate expires. Omitted on a like-for-like quote, where no rate is locked."}},"required":["client","convertedAmount"],"additionalProperties":false},"status":{"type":"string","enum":["REQUIRES_CONFIRMATION","ACCEPTED","PROCESSING","IN_REVIEW","PROCESSED","RETURNED","FAILED","CANCELLED","EXPIRED"],"examples":["PROCESSED"],"description":"Lifecycle state. `REQUIRES_CONFIRMATION`, `ACCEPTED`, `PROCESSING` and `IN_REVIEW` are in flight. `RETURNED`, `FAILED`, `CANCELLED` and `EXPIRED` are terminal. `PROCESSED` is the success state and the only outcome that is not terminal — a late return can still move it to `RETURNED`."},"sender":{"type":"object","properties":{"accountId":{"type":"string","pattern":"^acc_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"acc_Zf2cDnimbTFVeJtx1qtBmU","description":"Referenced account."}},"required":["accountId"],"additionalProperties":false,"description":"The sender, distinct from the account being paid named in `receiver`."},"settlementTraceId":{"type":"object","properties":{"status":{"type":"string","enum":["PENDING","AVAILABLE","UNSUPPORTED"],"examples":["AVAILABLE"],"description":"Whether a trace reference has been reported, is still pending, or the rail issues none."},"key":{"type":["string","null"],"enum":["END_TO_END_IDENTIFIER","RETRIEVAL_REFERENCE_NUMBER","UNIQUE_TRANSACTION_REFERENCE","UNIQUE_END_TO_END_TRANSACTION_REFERENCE"],"examples":["RETRIEVAL_REFERENCE_NUMBER"],"description":"Null until `rail` resolves, and where that rail issues nothing traceable."},"value":{"type":["string","null"],"examples":["402612345678"],"description":"The reference itself. Null until `status` is `AVAILABLE`, never a placeholder."}},"required":["status","key","value"],"additionalProperties":false},"receiverMemo":{"type":"string","examples":["Invoice INV-2026-0412"],"description":"Free-text memo to the receiver, where the rail carries one."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own key/value pairs, echoed back verbatim."},"confirmations":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"QUOTE"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"ACCOUNT_HOLDER_NAME"},"mode":{"type":"string","enum":["SEPA_VOP","IMPS_PENNY_DROP"],"examples":["IMPS_PENNY_DROP"],"description":"How the account holder name was checked."},"result":{"type":"string","examples":["MATCH"],"description":"Outcome of the name check. Not constrained to a closed set: the upstream types this as a free string, so a new verdict must not fail response validation."},"providedName":{"type":"string","examples":["Nadia Holdings Pvt Ltd"],"description":"The name submitted for comparison, frozen as it stood when the act ran."},"registeredName":{"type":["string","null"],"examples":["Nadia Holdings Private Limited"],"description":"The name the receiving institution holds. Null where the scheme returned none."},"createdAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"When the act started."},"verifiedAt":{"type":["string","null"],"format":"date-time","examples":["2026-06-04T10:35:12.000Z"],"description":"When it resolved. Null while `PENDING`."},"expiresAt":{"type":["string","null"],"format":"date-time","examples":["2026-12-04T10:35:12.000Z"],"description":"When the result goes stale, or null."}},"required":["type","mode","result","providedName","registeredName","createdAt","verifiedAt","expiresAt"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"RECEIVE_AMOUNT_DEDUCTIONS"}},"required":["type"],"additionalProperties":false}]},"description":"What the caller must accept before funds move. Complete in the create response, and it survives confirmation rather than draining."},"failure":{"type":["object","null"],"properties":{"code":{"type":"string","examples":["INSUFFICIENT_FUNDS"],"description":"Why the payout failed after acceptance. Branch on this, never on `message`. Not a closed enum on the wire — the upstream may add a code before this service knows about it."},"message":{"type":"string","examples":["Insufficient funds in the financial account when the debit was attempted after acceptance."],"description":"Human-readable failure detail."}},"required":["code","message"],"additionalProperties":false,"description":"Why this payout failed. Null unless `status` is FAILED."},"return":{"type":["object","null"],"properties":{"reasonCode":{"type":"string","examples":["AC04"],"description":"The reason code the scheme reported, such as SEPA `AC04`. Free-form: the scheme owns the values."},"amount":{"type":"string","pattern":"^[0-9]+\\.[0-9]{6}$","examples":["1000.000000"],"description":"Amount credited back."},"currency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["USD"],"description":"Currency of the returned `amount`."},"returnedAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"When the return was credited back."}},"required":["reasonCode","amount","currency","returnedAt"],"additionalProperties":false,"description":"How much came back, and when. Null unless `status` is RETURNED."},"createdAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:05.000Z"],"description":"Creation timestamp."},"updatedAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:05.000Z"],"description":"Last-update timestamp."},"processedAt":{"type":["string","null"],"format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"When the payout reached PROCESSED."}},"required":["object","id","financialAccountId","receiver","sendAmount","sendCurrency","receiveAmount","receiveCurrency","fees","fixedSide","fxRates","status","settlementTraceId","confirmations","failure","return","createdAt","updatedAt","processedAt"],"additionalProperties":false}},"required":["data"]},"examples":{"default_example":{"summary":"Awaiting confirmation","value":{"data":{"object":"payout","id":"pyt_GBWRJhmcFkMvrr4Fu3tMSJ","financialAccountId":"finacc_eUzeSQF9ZY6q4x8AhBskUf","receiver":{"accountId":"acc_h82pJGF9p7kpzb6eU326EF","payoutAddressId":"pytadd_NJAEqN76R7PwPfHt3oWb8R"},"rail":"IMPS","sendAmount":"1000.000000","sendCurrency":"USD","receiveAmount":"83450.00","receiveCurrency":"INR","fees":{"totalAmount":"3.000000","currency":"USD","components":[{"type":"NETWORK_FEE","amount":"3.000000","currency":"USD"}]},"fixedSide":"SEND","fxRates":{"client":"83.6835","convertedAmount":"997.000000","expiresAt":"2026-06-04T10:31:00.000Z"},"status":"REQUIRES_CONFIRMATION","settlementTraceId":{"status":"PENDING","key":null,"value":null},"receiverMemo":"Invoice INV-2026-0412","metadata":{"invoiceId":"INV-2026-0412"},"confirmations":[{"type":"QUOTE"}],"failure":null,"return":null,"createdAt":"2026-06-04T10:30:05.000Z","updatedAt":"2026-06-04T10:30:05.000Z","processedAt":null}}}}}}},"400":{"description":"The request failed validation, has an invalid Content-Type, the Idempotency-Key is malformed, or the gateway context was missing.","content":{"application/json":{"examples":{"validation_body_failed":{"summary":"Request body failed validation. See details.issues for field-level errors, or details.firstIssuePath for the most common single-field case.","value":{"error":{"code":"VALIDATION_BODY_FAILED","type":"VALIDATION_ERROR","message":"Request body failed validation. See details.issues for field-level errors, or details.firstIssuePath for the most common single-field case.","retryStrategy":"FIX_AND_RESUBMIT","details":{"issues":[{"path":"/identity/individual/lastName","code":"invalid_type","message":"Required","expected":"string","received":"undefined"},{"path":"/identity/individual/documents/0/type","code":"invalid_enum_value","message":"is not a supported document type","expected":"PASSPORT|NATIONAL_ID|DRIVERS_LICENSE|SSN|RESIDENCE_PERMIT","received":"LIBRARY_CARD"},{"path":"/identity/individual/residentialAddress/country","code":"custom","message":"is not an ISO 3166-1 alpha-2 country code (the United Kingdom is GB)","received":"UK"}],"firstIssuePath":"/identity/individual/lastName"}}}},"validation_content_type":{"summary":"Content-Type must be application/json.","value":{"error":{"code":"VALIDATION_CONTENT_TYPE","type":"VALIDATION_ERROR","message":"Content-Type must be application/json.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"idempotency_key_invalid":{"summary":"Idempotency-Key is malformed. Generate a new key matching the documented pattern and retry with that new key.","value":{"error":{"code":"IDEMPOTENCY_KEY_INVALID","type":"VALIDATION_ERROR","message":"Idempotency-Key is malformed. Generate a new key matching the documented pattern and retry with that new key.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"missing_request_context":{"summary":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","value":{"error":{"code":"MISSING_REQUEST_CONTEXT","type":"VALIDATION_ERROR","message":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"invalid_organization":{"summary":"The organization identifier on the request is malformed. Send the request through the documented gateway.","value":{"error":{"code":"INVALID_ORGANIZATION","type":"VALIDATION_ERROR","message":"The organization identifier on the request is malformed. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"receiver_memo_invalid":{"summary":"The receiver memo is not accepted by the selected rail.","value":{"error":{"code":"RECEIVER_MEMO_INVALID","type":"VALIDATION_ERROR","message":"The receiver memo is not accepted by the selected rail.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"The request is not authenticated.","content":{"application/json":{"examples":{"auth_token_missing":{"summary":"The Authorization header is missing. Provide a Bearer JWT.","value":{"error":{"code":"AUTH_TOKEN_MISSING","type":"AUTHENTICATION_ERROR","message":"The Authorization header is missing. Provide a Bearer JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid":{"summary":"Authorization token is invalid. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_expired":{"summary":"Authorization token has expired. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_EXPIRED","type":"AUTHENTICATION_ERROR","message":"Authorization token has expired. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid_config":{"summary":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","value":{"error":{"code":"AUTH_TOKEN_INVALID_CONFIG","type":"AUTHENTICATION_ERROR","message":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","retryStrategy":"TERMINAL","details":{}}}},"auth_api_key_invalid":{"summary":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","value":{"error":{"code":"AUTH_API_KEY_INVALID","type":"AUTHENTICATION_ERROR","message":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"The API key may not perform this operation.","content":{"application/json":{"examples":{"auth_insufficient_scope":{"summary":"The API key is missing the scope required for this operation.","value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"404":{"description":"A referenced resource does not exist in this org.","content":{"application/json":{"examples":{"account_not_found":{"summary":"No account with that id in this org.","value":{"error":{"code":"ACCOUNT_NOT_FOUND","type":"NOT_FOUND","message":"No account with that id in this org.","retryStrategy":"TERMINAL","details":{}}}},"financial_account_not_found":{"summary":"No financial account with that id in this org.","value":{"error":{"code":"FINANCIAL_ACCOUNT_NOT_FOUND","type":"NOT_FOUND","message":"No financial account with that id in this org.","retryStrategy":"TERMINAL","details":{}}}},"payout_address_not_found":{"summary":"No payout address with that id in this org.","value":{"error":{"code":"PAYOUT_ADDRESS_NOT_FOUND","type":"NOT_FOUND","message":"No payout address with that id in this org.","retryStrategy":"TERMINAL","details":{}}}},"quote_not_found":{"summary":"The requested quote was not found.","value":{"error":{"code":"QUOTE_NOT_FOUND","type":"NOT_FOUND","message":"The requested quote was not found.","retryStrategy":"TERMINAL","details":{}}}}}}}},"409":{"description":"The request conflicts with current state, or with an in-flight request using the same key.","content":{"application/json":{"examples":{"idempotency_in_flight":{"summary":"Another request with this idempotency key is currently processing. Wait for some time and retry with the same key.","value":{"error":{"code":"IDEMPOTENCY_IN_FLIGHT","type":"CONFLICT","message":"Another request with this idempotency key is currently processing. Wait for some time and retry with the same key.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}},"account_archived":{"summary":"The account is archived and cannot take new work.","value":{"error":{"code":"ACCOUNT_ARCHIVED","type":"CONFLICT","message":"The account is archived and cannot take new work.","retryStrategy":"TERMINAL","details":{"accountId":"acc_h82pJGF9p7kpzb6eU326EF"}}}},"account_holder_mismatch":{"summary":"The receiving-side account holder name check on the destination payout address returned a blocking result, so the payout was not created.","value":{"error":{"code":"ACCOUNT_HOLDER_MISMATCH","type":"CONFLICT","message":"The receiving-side account holder name check on the destination payout address returned a blocking result, so the payout was not created.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}},"account_not_active":{"summary":"The account's standing does not allow this operation.","value":{"error":{"code":"ACCOUNT_NOT_ACTIVE","type":"CONFLICT","message":"The account's standing does not allow this operation.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{"accountId":"acc_h82pJGF9p7kpzb6eU326EF","status":"REJECTED"}}}},"agreements_not_active":{"summary":"Required agreements for this account are not active.","value":{"error":{"code":"AGREEMENTS_NOT_ACTIVE","type":"CONFLICT","message":"Required agreements for this account are not active.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}},"agreements_pending":{"summary":"Required agreements for this account are still pending.","value":{"error":{"code":"AGREEMENTS_PENDING","type":"CONFLICT","message":"Required agreements for this account are still pending.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}},"beneficiary_details_missing":{"summary":"A detail the receiving institution requires for this payout is missing from the destination payout address. Supply it on the address, then retry.","value":{"error":{"code":"BENEFICIARY_DETAILS_MISSING","type":"CONFLICT","message":"A detail the receiving institution requires for this payout is missing from the destination payout address. Supply it on the address, then retry.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}},"capability_not_active":{"summary":"The beneficiary does not hold an active capability this payout requires. Complete the capability setup and retry.","value":{"error":{"code":"CAPABILITY_NOT_ACTIVE","type":"CONFLICT","message":"The beneficiary does not hold an active capability this payout requires. Complete the capability setup and retry.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{"accountId":"acc_h82pJGF9p7kpzb6eU326EF","required":{"grant":"RECEIVE_PAYOUTS","currency":"INR","repatriability":"NON_REPATRIABLE"},"capabilityId":"cap_Ce3AJmB1WMUZmkD9mMKVx","status":"PENDING"}}}},"insufficient_funds":{"summary":"The financial account does not hold enough funds for this payout.","value":{"error":{"code":"INSUFFICIENT_FUNDS","type":"CONFLICT","message":"The financial account does not hold enough funds for this payout.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{"financialAccountId":"finacc_eUzeSQF9ZY6q4x8AhBskUf"}}}},"kyc_required":{"summary":"The account needs identity verification before this payout can be created.","value":{"error":{"code":"KYC_REQUIRED","type":"CONFLICT","message":"The account needs identity verification before this payout can be created.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}},"payout_address_archived":{"summary":"This payout address was archived by the client and can no longer be paid. Create the payout to a different address.","value":{"error":{"code":"PAYOUT_ADDRESS_ARCHIVED","type":"CONFLICT","message":"This payout address was archived by the client and can no longer be paid. Create the payout to a different address.","retryStrategy":"TERMINAL","details":{}}}},"payout_address_rejected":{"summary":"This payout address is rejected and cannot be paid.","value":{"error":{"code":"PAYOUT_ADDRESS_REJECTED","type":"CONFLICT","message":"This payout address is rejected and cannot be paid.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}},"payout_address_verification_failed":{"summary":"Verification of the payout address failed, so the payout was not created.","value":{"error":{"code":"PAYOUT_ADDRESS_VERIFICATION_FAILED","type":"CONFLICT","message":"Verification of the payout address failed, so the payout was not created.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}},"payout_not_enabled":{"summary":"Payouts are not enabled for this organization.","value":{"error":{"code":"PAYOUT_NOT_ENABLED","type":"CONFLICT","message":"Payouts are not enabled for this organization.","retryStrategy":"TERMINAL","details":{}}}},"payout_temporarily_unavailable":{"summary":"Payouts are temporarily unavailable. Retry shortly with the same Idempotency-Key.","value":{"error":{"code":"PAYOUT_TEMPORARILY_UNAVAILABLE","type":"CONFLICT","message":"Payouts are temporarily unavailable. Retry shortly with the same Idempotency-Key.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}},"quote_already_consumed":{"summary":"This quote has already been used by a previous trade. Request a fresh quote.","value":{"error":{"code":"QUOTE_ALREADY_CONSUMED","type":"CONFLICT","message":"This quote has already been used by a previous trade. Request a fresh quote.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"quote_expired":{"summary":"The quoted rate has expired. Request a new quote.","value":{"error":{"code":"QUOTE_EXPIRED","type":"CONFLICT","message":"The quoted rate has expired. Request a new quote.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"quote_temporarily_unavailable":{"summary":"Quoting is temporarily unavailable for the requested currencies. Retry shortly.","value":{"error":{"code":"QUOTE_TEMPORARILY_UNAVAILABLE","type":"CONFLICT","message":"Quoting is temporarily unavailable for the requested currencies. Retry shortly.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}},"422":{"description":"A business rule was tripped by the request's own values, or the key was replayed with a different body.","content":{"application/json":{"examples":{"idempotency_mismatch":{"summary":"This idempotency key was previously seen with a different request body. Use a new key for a new request, or resubmit the original body verbatim.","value":{"error":{"code":"IDEMPOTENCY_MISMATCH","type":"CONFLICT","message":"This idempotency key was previously seen with a different request body. Use a new key for a new request, or resubmit the original body verbatim.","retryStrategy":"FIX_AND_RESUBMIT","details":{"originalRequestHash":"sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"}}}},"amount_out_of_range":{"summary":"The amount is outside the permitted range for payouts to this destination. See details.issues for the violating amount and its bound, then adjust the amount and resubmit.","value":{"error":{"code":"AMOUNT_OUT_OF_RANGE","type":"VALIDATION_ERROR","message":"The amount is outside the permitted range for payouts to this destination. See details.issues for the violating amount and its bound, then adjust the amount and resubmit.","retryStrategy":"FIX_AND_RESUBMIT","details":{"issues":[{"path":"/receiveAmount","code":"amount_below_minimum","message":"receiveAmount 50.00 INR is below the 100.00 INR minimum for this payout destination"}],"firstIssuePath":"/receiveAmount","amount":"50.00","minimum":"100.00","currency":"INR"}}}},"currency_not_supported":{"summary":"The requested receiveCurrency cannot be delivered to this destination on any rail. Pick a supported currency for this payout address, or pay a different address.","value":{"error":{"code":"CURRENCY_NOT_SUPPORTED","type":"VALIDATION_ERROR","message":"The requested receiveCurrency cannot be delivered to this destination on any rail. Pick a supported currency for this payout address, or pay a different address.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"financial_account_currency_mismatch":{"summary":"The financial account's currency does not match the send currency for this payout.","value":{"error":{"code":"FINANCIAL_ACCOUNT_CURRENCY_MISMATCH","type":"VALIDATION_ERROR","message":"The financial account's currency does not match the send currency for this payout.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"identity_requirement_unmet":{"summary":"A requested capability needs more identity information than the account has supplied. details names each capability and its unmet requirements.","value":{"error":{"code":"IDENTITY_REQUIREMENT_UNMET","type":"VALIDATION_ERROR","message":"A requested capability needs more identity information than the account has supplied. details names each capability and its unmet requirements.","retryStrategy":"FIX_AND_RESUBMIT","details":{"issues":[{"path":"/identity/individual/nationality","code":"invalid_type","message":"Required","expected":"string","received":"undefined"},{"path":"/identity/individual/residentialAddress/country","code":"invalid_type","message":"Required","expected":"string","received":"undefined"}],"firstIssuePath":"/identity/individual/nationality"}}}},"quote_rejected":{"summary":"A quote is not available for the requested currencies or amount.","value":{"error":{"code":"QUOTE_REJECTED","type":"VALIDATION_ERROR","message":"A quote is not available for the requested currencies or amount.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"quote_send_currency_unavailable":{"summary":"The requested send currency is not available for this corridor.","value":{"error":{"code":"QUOTE_SEND_CURRENCY_UNAVAILABLE","type":"VALIDATION_ERROR","message":"The requested send currency is not available for this corridor.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"sender_account_required":{"summary":"This payout requires a sender account, but none was named. Provide sender and resubmit.","value":{"error":{"code":"SENDER_ACCOUNT_REQUIRED","type":"VALIDATION_ERROR","message":"This payout requires a sender account, but none was named. Provide sender and resubmit.","retryStrategy":"FIX_AND_RESUBMIT","details":{"issues":[{"path":"/sender","code":"invalid_type","message":"Required","expected":"object","received":"undefined"}],"firstIssuePath":"/sender"}}}}}}}},"428":{"description":"The Idempotency-Key header is required for this endpoint.","content":{"application/json":{"examples":{"idempotency_key_missing":{"summary":"The Idempotency-Key header is required for this endpoint.","value":{"error":{"code":"IDEMPOTENCY_KEY_MISSING","type":"VALIDATION_ERROR","message":"The Idempotency-Key header is required for this endpoint.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"429":{"description":"The API key has exceeded its request rate limit.","content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"This API key has exceeded its request rate limit for the current window.","value":{"error":{"code":"RATE_LIMIT_EXCEEDED","type":"RATE_LIMITED","message":"This API key has exceeded its request rate limit for the current window.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}},"500":{"description":"An unexpected internal error occurred.","content":{"application/json":{"examples":{"internal_error":{"summary":"An unexpected internal error occurred. Contact support with the trace ID.","value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"createPayout","summary":"Create payout","tags":["Payouts"],"description":"Create a payout, debiting a financial account and crediting the receiving account's payout address. Two variants, selected by `type`: `FROM_QUOTE` applies a prior quote's locked-in rate and routing, and `INLINE` prices the payout in this call. The payout is created in `REQUIRES_CONFIRMATION` with no funds moved — `confirmations[]` lists everything the caller must accept, and POST /v3/payments/payouts/{payoutId}/confirm acknowledges all of it atomically.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255,"pattern":"^[a-zA-Z0-9_-]{1,255}$","example":"123e4567-e89b-12d3-a456-426614174000"},"description":"Unique key to ensure idempotent requests — 1-255 characters: alphanumerics, hyphens, underscores. UUID v4 recommended."}],"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"FROM_QUOTE"},"quoteId":{"type":"string","example":"pytqte_7RJWhvQBQPEjJmki5fhBbo","description":"Prior quote whose rate, rail, and routing are applied as-is."},"receiverMemo":{"type":"string","examples":["Invoice INV-2026-0412"],"description":"Free-text memo to the receiver, where the rail carries one."},"metadata":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":40},"additionalProperties":{"type":"string","maxLength":500},"description":"Optional client-owned metadata bag (string keys → string values). Echoed back verbatim on a successful response. Limits: at most 50 keys, keys up to 40 characters, values up to 500 characters, and at most 8192 bytes when serialized.","examples":[{"requestId":"client-generated-correlation-id"}]}},"required":["type","quoteId"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"INLINE"},"financialAccountId":{"type":"string","example":"finacc_eUzeSQF9ZY6q4x8AhBskUf","description":"Financial account debited."},"receiver":{"type":"object","properties":{"payoutAddressId":{"type":"string","example":"pytadd_NJAEqN76R7PwPfHt3oWb8R","description":"The payout address the funds are credited to."}},"required":["payoutAddressId"],"additionalProperties":false},"sendAmount":{"type":"string","pattern":"^[0-9]+(\\.[0-9]{1,8})?$","examples":["10000.00"],"description":"Total to debit, fees included. Provide exactly one of `sendAmount` / `receiveAmount`."},"receiveAmount":{"type":"string","pattern":"^[0-9]+(\\.[0-9]{1,8})?$","examples":["83450.00"],"description":"Amount to deliver on the receive side. Provide exactly one of `sendAmount` / `receiveAmount`."},"receiveCurrency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["INR"],"description":"Currency to deliver on the receive side."},"quoteForSeconds":{"type":"integer","examples":[60],"description":"How long the resulting quote's price is held, in seconds. Omit to default to 60, or your organization's configured hold when one is set."},"receiverMemo":{"type":"string","examples":["Invoice INV-2026-0412"],"description":"Free-text memo to the receiver, where the rail carries one."},"metadata":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":40},"additionalProperties":{"type":"string","maxLength":500},"description":"Optional client-owned metadata bag (string keys → string values). Echoed back verbatim on a successful response. Limits: at most 50 keys, keys up to 40 characters, values up to 500 characters, and at most 8192 bytes when serialized.","examples":[{"requestId":"client-generated-correlation-id"}]},"sender":{"type":"object","properties":{"accountId":{"type":"string","example":"acc_Zf2cDnimbTFVeJtx1qtBmU","description":"Referenced account."}},"required":["accountId"],"additionalProperties":false}},"required":["type","receiver","receiveCurrency"],"additionalProperties":false}]}}}}},"get":{"responses":{"200":{"description":"A page of payouts.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"payout","examples":["payout"],"description":"The type of object represented, a fixed discriminator. Always `\"payout\"` for this resource."},"id":{"type":"string","pattern":"^pyt_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"pyt_GBWRJhmcFkMvrr4Fu3tMSJ","description":"Payout identifier."},"financialAccountId":{"type":"string","pattern":"^finacc_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"finacc_eUzeSQF9ZY6q4x8AhBskUf","description":"Financial account debited."},"receiver":{"type":"object","properties":{"accountId":{"type":"string","pattern":"^acc_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"acc_h82pJGF9p7kpzb6eU326EF","description":"The account being paid, derived from the payout address."},"payoutAddressId":{"type":"string","pattern":"^pytadd_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"pytadd_NJAEqN76R7PwPfHt3oWb8R","description":"The payout address the funds are credited to."}},"required":["accountId","payoutAddressId"],"additionalProperties":false},"rail":{"type":"string","enum":["SEPA","SWIFT","IMPS","NEFT","RTGS"],"examples":["IMPS"],"description":"Settlement rail selected; always present once resolved."},"sendAmount":{"type":"string","pattern":"^[0-9]+\\.[0-9]{6}$","examples":["1000.000000"],"description":"Total debited on the send side."},"sendCurrency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["USD"],"description":"Currency of the send leg."},"receiveAmount":{"type":"string","pattern":"^[0-9]+(\\.[0-9]{1,8})?$","examples":["83450.00"],"description":"Amount delivered on the receive side."},"receiveCurrency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["INR"],"description":"Currency of the receive leg."},"fees":{"type":"object","properties":{"totalAmount":{"type":"string","pattern":"^[0-9]+\\.[0-9]{6}$","examples":["3.000000"],"description":"Total of the fee components, added on top of `fxRates.convertedAmount` to make `sendAmount`."},"currency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["USD"],"description":"Currency of `totalAmount`."},"components":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["NETWORK_FEE","SWIFT_FEE","RESIDENT_DISCOUNT"],"examples":["NETWORK_FEE"],"description":"Kind of fee charged on top of the conversion. A `SWIFT_FEE` is a flat charge beside the `NETWORK_FEE` on a payout whose `rail` is `SWIFT`; a `RESIDENT_DISCOUNT` carries a negative `amount`."},"amount":{"type":"string","pattern":"^-?[0-9]+\\.[0-9]{6}$","examples":["5.000000"],"description":"What this component comes to. Negative for a discount such as `RESIDENT_DISCOUNT`."},"currency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["USD"],"description":"Currency of this component's `amount`."}},"required":["type","amount","currency"],"additionalProperties":false},"description":"Itemised breakdown. The components sum to `totalAmount`."}},"required":["totalAmount","currency","components"],"additionalProperties":false},"fixedSide":{"type":"string","enum":["SEND","RECEIVE"],"examples":["SEND"],"description":"Which leg is held exact. Derived from whichever amount the request provided: `sendAmount` gives `SEND`, `receiveAmount` gives `RECEIVE`."},"fxRates":{"type":"object","properties":{"client":{"type":"string","pattern":"^[0-9]+(\\.[0-9]{1,16})?$","examples":["1.10165"],"description":"Rate applied, in units of `sendCurrency` per unit of `receiveCurrency`. Conversion costs are already priced in."},"convertedAmount":{"type":"string","pattern":"^[0-9]+\\.[0-9]{6}$","examples":["110.165000"],"description":"What the receive leg comes to in `sendCurrency` at `client`, before the payout-leg fees."},"expiresAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:33:00.000Z"],"description":"When this rate expires. Omitted on a like-for-like quote, where no rate is locked."}},"required":["client","convertedAmount"],"additionalProperties":false},"status":{"type":"string","enum":["REQUIRES_CONFIRMATION","ACCEPTED","PROCESSING","IN_REVIEW","PROCESSED","RETURNED","FAILED","CANCELLED","EXPIRED"],"examples":["PROCESSED"],"description":"Lifecycle state. `REQUIRES_CONFIRMATION`, `ACCEPTED`, `PROCESSING` and `IN_REVIEW` are in flight. `RETURNED`, `FAILED`, `CANCELLED` and `EXPIRED` are terminal. `PROCESSED` is the success state and the only outcome that is not terminal — a late return can still move it to `RETURNED`."},"sender":{"type":"object","properties":{"accountId":{"type":"string","pattern":"^acc_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"acc_Zf2cDnimbTFVeJtx1qtBmU","description":"Referenced account."}},"required":["accountId"],"additionalProperties":false,"description":"The sender, distinct from the account being paid named in `receiver`."},"settlementTraceId":{"type":"object","properties":{"status":{"type":"string","enum":["PENDING","AVAILABLE","UNSUPPORTED"],"examples":["AVAILABLE"],"description":"Whether a trace reference has been reported, is still pending, or the rail issues none."},"key":{"type":["string","null"],"enum":["END_TO_END_IDENTIFIER","RETRIEVAL_REFERENCE_NUMBER","UNIQUE_TRANSACTION_REFERENCE","UNIQUE_END_TO_END_TRANSACTION_REFERENCE"],"examples":["RETRIEVAL_REFERENCE_NUMBER"],"description":"Null until `rail` resolves, and where that rail issues nothing traceable."},"value":{"type":["string","null"],"examples":["402612345678"],"description":"The reference itself. Null until `status` is `AVAILABLE`, never a placeholder."}},"required":["status","key","value"],"additionalProperties":false},"receiverMemo":{"type":"string","examples":["Invoice INV-2026-0412"],"description":"Free-text memo to the receiver, where the rail carries one."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own key/value pairs, echoed back verbatim."},"confirmations":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"QUOTE"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"ACCOUNT_HOLDER_NAME"},"mode":{"type":"string","enum":["SEPA_VOP","IMPS_PENNY_DROP"],"examples":["IMPS_PENNY_DROP"],"description":"How the account holder name was checked."},"result":{"type":"string","examples":["MATCH"],"description":"Outcome of the name check. Not constrained to a closed set: the upstream types this as a free string, so a new verdict must not fail response validation."},"providedName":{"type":"string","examples":["Nadia Holdings Pvt Ltd"],"description":"The name submitted for comparison, frozen as it stood when the act ran."},"registeredName":{"type":["string","null"],"examples":["Nadia Holdings Private Limited"],"description":"The name the receiving institution holds. Null where the scheme returned none."},"createdAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"When the act started."},"verifiedAt":{"type":["string","null"],"format":"date-time","examples":["2026-06-04T10:35:12.000Z"],"description":"When it resolved. Null while `PENDING`."},"expiresAt":{"type":["string","null"],"format":"date-time","examples":["2026-12-04T10:35:12.000Z"],"description":"When the result goes stale, or null."}},"required":["type","mode","result","providedName","registeredName","createdAt","verifiedAt","expiresAt"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"RECEIVE_AMOUNT_DEDUCTIONS"}},"required":["type"],"additionalProperties":false}]},"description":"What the caller must accept before funds move. Complete in the create response, and it survives confirmation rather than draining."},"failure":{"type":["object","null"],"properties":{"code":{"type":"string","examples":["INSUFFICIENT_FUNDS"],"description":"Why the payout failed after acceptance. Branch on this, never on `message`. Not a closed enum on the wire — the upstream may add a code before this service knows about it."},"message":{"type":"string","examples":["Insufficient funds in the financial account when the debit was attempted after acceptance."],"description":"Human-readable failure detail."}},"required":["code","message"],"additionalProperties":false,"description":"Why this payout failed. Null unless `status` is FAILED."},"return":{"type":["object","null"],"properties":{"reasonCode":{"type":"string","examples":["AC04"],"description":"The reason code the scheme reported, such as SEPA `AC04`. Free-form: the scheme owns the values."},"amount":{"type":"string","pattern":"^[0-9]+\\.[0-9]{6}$","examples":["1000.000000"],"description":"Amount credited back."},"currency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["USD"],"description":"Currency of the returned `amount`."},"returnedAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"When the return was credited back."}},"required":["reasonCode","amount","currency","returnedAt"],"additionalProperties":false,"description":"How much came back, and when. Null unless `status` is RETURNED."},"createdAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:05.000Z"],"description":"Creation timestamp."},"updatedAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:05.000Z"],"description":"Last-update timestamp."},"processedAt":{"type":["string","null"],"format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"When the payout reached PROCESSED."}},"required":["object","id","financialAccountId","receiver","sendAmount","sendCurrency","receiveAmount","receiveCurrency","fees","fixedSide","fxRates","status","settlementTraceId","confirmations","failure","return","createdAt","updatedAt","processedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"limit":{"type":"number","examples":[25],"description":"Page size used for this request."},"hasNext":{"type":"boolean","examples":[true],"description":"Whether more results exist after this page."},"nextCursor":{"type":["string","null"],"description":"Cursor pointing to the last item on this page. Pass as `startingAfter` to fetch the next page."},"hasPrev":{"type":"boolean","examples":[false],"description":"Whether results exist before this page."},"prevCursor":{"type":["string","null"],"description":"Cursor pointing to the first item on this page. Pass as `endingBefore` to fetch the previous page."}},"required":["limit","hasNext","nextCursor","hasPrev","prevCursor"]}},"required":["data","pagination"]},"examples":{"default_example":{"value":{"data":[{"object":"payout","id":"pyt_GBWRJhmcFkMvrr4Fu3tMSJ","financialAccountId":"finacc_eUzeSQF9ZY6q4x8AhBskUf","receiver":{"accountId":"acc_h82pJGF9p7kpzb6eU326EF","payoutAddressId":"pytadd_NJAEqN76R7PwPfHt3oWb8R"},"rail":"IMPS","sendAmount":"1000.000000","sendCurrency":"USD","receiveAmount":"83450.00","receiveCurrency":"INR","fees":{"totalAmount":"3.000000","currency":"USD","components":[{"type":"NETWORK_FEE","amount":"3.000000","currency":"USD"}]},"fixedSide":"SEND","fxRates":{"client":"83.6835","convertedAmount":"997.000000","expiresAt":"2026-06-04T10:31:00.000Z"},"status":"PROCESSED","settlementTraceId":{"status":"AVAILABLE","key":"RETRIEVAL_REFERENCE_NUMBER","value":"402612345678"},"receiverMemo":"Invoice INV-2026-0412","metadata":{"invoiceId":"INV-2026-0412"},"confirmations":[{"type":"QUOTE"}],"failure":null,"return":null,"createdAt":"2026-06-04T10:30:05.000Z","updatedAt":"2026-06-04T10:32:10.000Z","processedAt":"2026-06-04T10:32:10.000Z"}],"pagination":{"limit":25,"hasNext":false,"nextCursor":null,"hasPrev":false,"prevCursor":null}}}}}}},"400":{"description":"The request failed validation, or the gateway context was missing.","content":{"application/json":{"examples":{"validation_query_failed":{"summary":"Query parameters failed validation.","value":{"error":{"code":"VALIDATION_QUERY_FAILED","type":"VALIDATION_ERROR","message":"Query parameters failed validation.","retryStrategy":"FIX_AND_RESUBMIT","details":{"issues":[{"path":"/receiveCurrency","code":"invalid_type","message":"Required","expected":"string","received":"undefined"}],"firstIssuePath":"/receiveCurrency"}}}},"missing_request_context":{"summary":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","value":{"error":{"code":"MISSING_REQUEST_CONTEXT","type":"VALIDATION_ERROR","message":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"invalid_organization":{"summary":"The organization identifier on the request is malformed. Send the request through the documented gateway.","value":{"error":{"code":"INVALID_ORGANIZATION","type":"VALIDATION_ERROR","message":"The organization identifier on the request is malformed. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"The request is not authenticated.","content":{"application/json":{"examples":{"auth_token_missing":{"summary":"The Authorization header is missing. Provide a Bearer JWT.","value":{"error":{"code":"AUTH_TOKEN_MISSING","type":"AUTHENTICATION_ERROR","message":"The Authorization header is missing. Provide a Bearer JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid":{"summary":"Authorization token is invalid. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_expired":{"summary":"Authorization token has expired. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_EXPIRED","type":"AUTHENTICATION_ERROR","message":"Authorization token has expired. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid_config":{"summary":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","value":{"error":{"code":"AUTH_TOKEN_INVALID_CONFIG","type":"AUTHENTICATION_ERROR","message":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","retryStrategy":"TERMINAL","details":{}}}},"auth_api_key_invalid":{"summary":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","value":{"error":{"code":"AUTH_API_KEY_INVALID","type":"AUTHENTICATION_ERROR","message":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"The API key may not perform this operation.","content":{"application/json":{"examples":{"auth_insufficient_scope":{"summary":"The API key is missing the scope required for this operation.","value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"429":{"description":"The API key has exceeded its request rate limit.","content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"This API key has exceeded its request rate limit for the current window.","value":{"error":{"code":"RATE_LIMIT_EXCEEDED","type":"RATE_LIMITED","message":"This API key has exceeded its request rate limit for the current window.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}},"500":{"description":"An unexpected internal error occurred.","content":{"application/json":{"examples":{"internal_error":{"summary":"An unexpected internal error occurred. Contact support with the trace ID.","value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"listPayouts","summary":"List payouts","tags":["Payouts"],"description":"Cursor-paginated list of payouts for the caller's organization, newest first by `createdAt`. Each element is a full payout, not a summary row.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size. Default 25, max 100."},{"name":"startingAfter","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor for the next (older) page. Mutually exclusive with `endingBefore`."},{"name":"endingBefore","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor for the previous (newer) page. Mutually exclusive with `startingAfter`."}]}},"/payments/payouts/{payoutId}":{"get":{"responses":{"200":{"description":"success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","const":"payout","examples":["payout"],"description":"The type of object represented, a fixed discriminator. Always `\"payout\"` for this resource."},"id":{"type":"string","pattern":"^pyt_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"pyt_GBWRJhmcFkMvrr4Fu3tMSJ","description":"Payout identifier."},"financialAccountId":{"type":"string","pattern":"^finacc_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"finacc_eUzeSQF9ZY6q4x8AhBskUf","description":"Financial account debited."},"receiver":{"type":"object","properties":{"accountId":{"type":"string","pattern":"^acc_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"acc_h82pJGF9p7kpzb6eU326EF","description":"The account being paid, derived from the payout address."},"payoutAddressId":{"type":"string","pattern":"^pytadd_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"pytadd_NJAEqN76R7PwPfHt3oWb8R","description":"The payout address the funds are credited to."}},"required":["accountId","payoutAddressId"],"additionalProperties":false},"rail":{"type":"string","enum":["SEPA","SWIFT","IMPS","NEFT","RTGS"],"examples":["IMPS"],"description":"Settlement rail selected; always present once resolved."},"sendAmount":{"type":"string","pattern":"^[0-9]+\\.[0-9]{6}$","examples":["1000.000000"],"description":"Total debited on the send side."},"sendCurrency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["USD"],"description":"Currency of the send leg."},"receiveAmount":{"type":"string","pattern":"^[0-9]+(\\.[0-9]{1,8})?$","examples":["83450.00"],"description":"Amount delivered on the receive side."},"receiveCurrency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["INR"],"description":"Currency of the receive leg."},"fees":{"type":"object","properties":{"totalAmount":{"type":"string","pattern":"^[0-9]+\\.[0-9]{6}$","examples":["3.000000"],"description":"Total of the fee components, added on top of `fxRates.convertedAmount` to make `sendAmount`."},"currency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["USD"],"description":"Currency of `totalAmount`."},"components":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["NETWORK_FEE","SWIFT_FEE","RESIDENT_DISCOUNT"],"examples":["NETWORK_FEE"],"description":"Kind of fee charged on top of the conversion. A `SWIFT_FEE` is a flat charge beside the `NETWORK_FEE` on a payout whose `rail` is `SWIFT`; a `RESIDENT_DISCOUNT` carries a negative `amount`."},"amount":{"type":"string","pattern":"^-?[0-9]+\\.[0-9]{6}$","examples":["5.000000"],"description":"What this component comes to. Negative for a discount such as `RESIDENT_DISCOUNT`."},"currency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["USD"],"description":"Currency of this component's `amount`."}},"required":["type","amount","currency"],"additionalProperties":false},"description":"Itemised breakdown. The components sum to `totalAmount`."}},"required":["totalAmount","currency","components"],"additionalProperties":false},"fixedSide":{"type":"string","enum":["SEND","RECEIVE"],"examples":["SEND"],"description":"Which leg is held exact. Derived from whichever amount the request provided: `sendAmount` gives `SEND`, `receiveAmount` gives `RECEIVE`."},"fxRates":{"type":"object","properties":{"client":{"type":"string","pattern":"^[0-9]+(\\.[0-9]{1,16})?$","examples":["1.10165"],"description":"Rate applied, in units of `sendCurrency` per unit of `receiveCurrency`. Conversion costs are already priced in."},"convertedAmount":{"type":"string","pattern":"^[0-9]+\\.[0-9]{6}$","examples":["110.165000"],"description":"What the receive leg comes to in `sendCurrency` at `client`, before the payout-leg fees."},"expiresAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:33:00.000Z"],"description":"When this rate expires. Omitted on a like-for-like quote, where no rate is locked."}},"required":["client","convertedAmount"],"additionalProperties":false},"status":{"type":"string","enum":["REQUIRES_CONFIRMATION","ACCEPTED","PROCESSING","IN_REVIEW","PROCESSED","RETURNED","FAILED","CANCELLED","EXPIRED"],"examples":["PROCESSED"],"description":"Lifecycle state. `REQUIRES_CONFIRMATION`, `ACCEPTED`, `PROCESSING` and `IN_REVIEW` are in flight. `RETURNED`, `FAILED`, `CANCELLED` and `EXPIRED` are terminal. `PROCESSED` is the success state and the only outcome that is not terminal — a late return can still move it to `RETURNED`."},"sender":{"type":"object","properties":{"accountId":{"type":"string","pattern":"^acc_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"acc_Zf2cDnimbTFVeJtx1qtBmU","description":"Referenced account."}},"required":["accountId"],"additionalProperties":false,"description":"The sender, distinct from the account being paid named in `receiver`."},"settlementTraceId":{"type":"object","properties":{"status":{"type":"string","enum":["PENDING","AVAILABLE","UNSUPPORTED"],"examples":["AVAILABLE"],"description":"Whether a trace reference has been reported, is still pending, or the rail issues none."},"key":{"type":["string","null"],"enum":["END_TO_END_IDENTIFIER","RETRIEVAL_REFERENCE_NUMBER","UNIQUE_TRANSACTION_REFERENCE","UNIQUE_END_TO_END_TRANSACTION_REFERENCE"],"examples":["RETRIEVAL_REFERENCE_NUMBER"],"description":"Null until `rail` resolves, and where that rail issues nothing traceable."},"value":{"type":["string","null"],"examples":["402612345678"],"description":"The reference itself. Null until `status` is `AVAILABLE`, never a placeholder."}},"required":["status","key","value"],"additionalProperties":false},"receiverMemo":{"type":"string","examples":["Invoice INV-2026-0412"],"description":"Free-text memo to the receiver, where the rail carries one."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own key/value pairs, echoed back verbatim."},"confirmations":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"QUOTE"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"ACCOUNT_HOLDER_NAME"},"mode":{"type":"string","enum":["SEPA_VOP","IMPS_PENNY_DROP"],"examples":["IMPS_PENNY_DROP"],"description":"How the account holder name was checked."},"result":{"type":"string","examples":["MATCH"],"description":"Outcome of the name check. Not constrained to a closed set: the upstream types this as a free string, so a new verdict must not fail response validation."},"providedName":{"type":"string","examples":["Nadia Holdings Pvt Ltd"],"description":"The name submitted for comparison, frozen as it stood when the act ran."},"registeredName":{"type":["string","null"],"examples":["Nadia Holdings Private Limited"],"description":"The name the receiving institution holds. Null where the scheme returned none."},"createdAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"When the act started."},"verifiedAt":{"type":["string","null"],"format":"date-time","examples":["2026-06-04T10:35:12.000Z"],"description":"When it resolved. Null while `PENDING`."},"expiresAt":{"type":["string","null"],"format":"date-time","examples":["2026-12-04T10:35:12.000Z"],"description":"When the result goes stale, or null."}},"required":["type","mode","result","providedName","registeredName","createdAt","verifiedAt","expiresAt"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"RECEIVE_AMOUNT_DEDUCTIONS"}},"required":["type"],"additionalProperties":false}]},"description":"What the caller must accept before funds move. Complete in the create response, and it survives confirmation rather than draining."},"failure":{"type":["object","null"],"properties":{"code":{"type":"string","examples":["INSUFFICIENT_FUNDS"],"description":"Why the payout failed after acceptance. Branch on this, never on `message`. Not a closed enum on the wire — the upstream may add a code before this service knows about it."},"message":{"type":"string","examples":["Insufficient funds in the financial account when the debit was attempted after acceptance."],"description":"Human-readable failure detail."}},"required":["code","message"],"additionalProperties":false,"description":"Why this payout failed. Null unless `status` is FAILED."},"return":{"type":["object","null"],"properties":{"reasonCode":{"type":"string","examples":["AC04"],"description":"The reason code the scheme reported, such as SEPA `AC04`. Free-form: the scheme owns the values."},"amount":{"type":"string","pattern":"^[0-9]+\\.[0-9]{6}$","examples":["1000.000000"],"description":"Amount credited back."},"currency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["USD"],"description":"Currency of the returned `amount`."},"returnedAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"When the return was credited back."}},"required":["reasonCode","amount","currency","returnedAt"],"additionalProperties":false,"description":"How much came back, and when. Null unless `status` is RETURNED."},"createdAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:05.000Z"],"description":"Creation timestamp."},"updatedAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:05.000Z"],"description":"Last-update timestamp."},"processedAt":{"type":["string","null"],"format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"When the payout reached PROCESSED."}},"required":["object","id","financialAccountId","receiver","sendAmount","sendCurrency","receiveAmount","receiveCurrency","fees","fixedSide","fxRates","status","settlementTraceId","confirmations","failure","return","createdAt","updatedAt","processedAt"],"additionalProperties":false}},"required":["data"]},"examples":{"default_example":{"summary":"Settled payout","value":{"data":{"object":"payout","id":"pyt_GBWRJhmcFkMvrr4Fu3tMSJ","financialAccountId":"finacc_eUzeSQF9ZY6q4x8AhBskUf","receiver":{"accountId":"acc_h82pJGF9p7kpzb6eU326EF","payoutAddressId":"pytadd_NJAEqN76R7PwPfHt3oWb8R"},"rail":"IMPS","sendAmount":"1000.000000","sendCurrency":"USD","receiveAmount":"83450.00","receiveCurrency":"INR","fees":{"totalAmount":"3.000000","currency":"USD","components":[{"type":"NETWORK_FEE","amount":"3.000000","currency":"USD"}]},"fixedSide":"SEND","fxRates":{"client":"83.6835","convertedAmount":"997.000000","expiresAt":"2026-06-04T10:31:00.000Z"},"status":"PROCESSED","settlementTraceId":{"status":"AVAILABLE","key":"RETRIEVAL_REFERENCE_NUMBER","value":"402612345678"},"receiverMemo":"Invoice INV-2026-0412","metadata":{"invoiceId":"INV-2026-0412"},"confirmations":[{"type":"QUOTE"}],"failure":null,"return":null,"createdAt":"2026-06-04T10:30:05.000Z","updatedAt":"2026-06-04T10:32:10.000Z","processedAt":"2026-06-04T10:32:10.000Z"}}}}}}},"400":{"description":"The request failed validation, or the gateway context was missing.","content":{"application/json":{"examples":{"validation_path_failed":{"summary":"URL path parameters failed validation.","value":{"error":{"code":"VALIDATION_PATH_FAILED","type":"VALIDATION_ERROR","message":"URL path parameters failed validation.","retryStrategy":"FIX_AND_RESUBMIT","details":{"issues":[{"path":"/payoutId","code":"invalid_string","message":"is not a well-formed payout id"}],"firstIssuePath":"/payoutId"}}}},"missing_request_context":{"summary":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","value":{"error":{"code":"MISSING_REQUEST_CONTEXT","type":"VALIDATION_ERROR","message":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"invalid_organization":{"summary":"The organization identifier on the request is malformed. Send the request through the documented gateway.","value":{"error":{"code":"INVALID_ORGANIZATION","type":"VALIDATION_ERROR","message":"The organization identifier on the request is malformed. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"The request is not authenticated.","content":{"application/json":{"examples":{"auth_token_missing":{"summary":"The Authorization header is missing. Provide a Bearer JWT.","value":{"error":{"code":"AUTH_TOKEN_MISSING","type":"AUTHENTICATION_ERROR","message":"The Authorization header is missing. Provide a Bearer JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid":{"summary":"Authorization token is invalid. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_expired":{"summary":"Authorization token has expired. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_EXPIRED","type":"AUTHENTICATION_ERROR","message":"Authorization token has expired. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid_config":{"summary":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","value":{"error":{"code":"AUTH_TOKEN_INVALID_CONFIG","type":"AUTHENTICATION_ERROR","message":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","retryStrategy":"TERMINAL","details":{}}}},"auth_api_key_invalid":{"summary":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","value":{"error":{"code":"AUTH_API_KEY_INVALID","type":"AUTHENTICATION_ERROR","message":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"The API key may not perform this operation.","content":{"application/json":{"examples":{"auth_insufficient_scope":{"summary":"The API key is missing the scope required for this operation.","value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"404":{"description":"The requested resource does not exist in this org.","content":{"application/json":{"examples":{"payout_not_found":{"summary":"No payout with that id in this org.","value":{"error":{"code":"PAYOUT_NOT_FOUND","type":"NOT_FOUND","message":"No payout with that id in this org.","retryStrategy":"TERMINAL","details":{}}}}}}}},"429":{"description":"The API key has exceeded its request rate limit.","content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"This API key has exceeded its request rate limit for the current window.","value":{"error":{"code":"RATE_LIMIT_EXCEEDED","type":"RATE_LIMITED","message":"This API key has exceeded its request rate limit for the current window.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}},"500":{"description":"An unexpected internal error occurred.","content":{"application/json":{"examples":{"internal_error":{"summary":"An unexpected internal error occurred. Contact support with the trace ID.","value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"getPayout","summary":"Get payout by ID","tags":["Payouts"],"description":"Retrieve a single payout by its identifier. Use this to poll a payout's `status`, read the `settlementTraceId` once the rail reports one, or inspect `failure` / `return` on a payout that did not settle cleanly.","parameters":[{"name":"payoutId","in":"path","required":true,"schema":{"type":"string","examples":["pyt_GBWRJhmcFkMvrr4Fu3tMSJ"]},"description":"Unique identifier of the payout."}]}},"/payments/payouts/{payoutId}/confirm":{"post":{"responses":{"200":{"description":"success","headers":{"Idempotency-Replayed":{"description":"`true` when the response was served from the idempotency cache; `false` for a freshly executed request.","schema":{"type":"string","enum":["true","false"]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","const":"payout","examples":["payout"],"description":"The type of object represented, a fixed discriminator. Always `\"payout\"` for this resource."},"id":{"type":"string","pattern":"^pyt_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"pyt_GBWRJhmcFkMvrr4Fu3tMSJ","description":"Payout identifier."},"financialAccountId":{"type":"string","pattern":"^finacc_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"finacc_eUzeSQF9ZY6q4x8AhBskUf","description":"Financial account debited."},"receiver":{"type":"object","properties":{"accountId":{"type":"string","pattern":"^acc_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"acc_h82pJGF9p7kpzb6eU326EF","description":"The account being paid, derived from the payout address."},"payoutAddressId":{"type":"string","pattern":"^pytadd_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"pytadd_NJAEqN76R7PwPfHt3oWb8R","description":"The payout address the funds are credited to."}},"required":["accountId","payoutAddressId"],"additionalProperties":false},"rail":{"type":"string","enum":["SEPA","SWIFT","IMPS","NEFT","RTGS"],"examples":["IMPS"],"description":"Settlement rail selected; always present once resolved."},"sendAmount":{"type":"string","pattern":"^[0-9]+\\.[0-9]{6}$","examples":["1000.000000"],"description":"Total debited on the send side."},"sendCurrency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["USD"],"description":"Currency of the send leg."},"receiveAmount":{"type":"string","pattern":"^[0-9]+(\\.[0-9]{1,8})?$","examples":["83450.00"],"description":"Amount delivered on the receive side."},"receiveCurrency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["INR"],"description":"Currency of the receive leg."},"fees":{"type":"object","properties":{"totalAmount":{"type":"string","pattern":"^[0-9]+\\.[0-9]{6}$","examples":["3.000000"],"description":"Total of the fee components, added on top of `fxRates.convertedAmount` to make `sendAmount`."},"currency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["USD"],"description":"Currency of `totalAmount`."},"components":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["NETWORK_FEE","SWIFT_FEE","RESIDENT_DISCOUNT"],"examples":["NETWORK_FEE"],"description":"Kind of fee charged on top of the conversion. A `SWIFT_FEE` is a flat charge beside the `NETWORK_FEE` on a payout whose `rail` is `SWIFT`; a `RESIDENT_DISCOUNT` carries a negative `amount`."},"amount":{"type":"string","pattern":"^-?[0-9]+\\.[0-9]{6}$","examples":["5.000000"],"description":"What this component comes to. Negative for a discount such as `RESIDENT_DISCOUNT`."},"currency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["USD"],"description":"Currency of this component's `amount`."}},"required":["type","amount","currency"],"additionalProperties":false},"description":"Itemised breakdown. The components sum to `totalAmount`."}},"required":["totalAmount","currency","components"],"additionalProperties":false},"fixedSide":{"type":"string","enum":["SEND","RECEIVE"],"examples":["SEND"],"description":"Which leg is held exact. Derived from whichever amount the request provided: `sendAmount` gives `SEND`, `receiveAmount` gives `RECEIVE`."},"fxRates":{"type":"object","properties":{"client":{"type":"string","pattern":"^[0-9]+(\\.[0-9]{1,16})?$","examples":["1.10165"],"description":"Rate applied, in units of `sendCurrency` per unit of `receiveCurrency`. Conversion costs are already priced in."},"convertedAmount":{"type":"string","pattern":"^[0-9]+\\.[0-9]{6}$","examples":["110.165000"],"description":"What the receive leg comes to in `sendCurrency` at `client`, before the payout-leg fees."},"expiresAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:33:00.000Z"],"description":"When this rate expires. Omitted on a like-for-like quote, where no rate is locked."}},"required":["client","convertedAmount"],"additionalProperties":false},"status":{"type":"string","enum":["REQUIRES_CONFIRMATION","ACCEPTED","PROCESSING","IN_REVIEW","PROCESSED","RETURNED","FAILED","CANCELLED","EXPIRED"],"examples":["PROCESSED"],"description":"Lifecycle state. `REQUIRES_CONFIRMATION`, `ACCEPTED`, `PROCESSING` and `IN_REVIEW` are in flight. `RETURNED`, `FAILED`, `CANCELLED` and `EXPIRED` are terminal. `PROCESSED` is the success state and the only outcome that is not terminal — a late return can still move it to `RETURNED`."},"sender":{"type":"object","properties":{"accountId":{"type":"string","pattern":"^acc_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"acc_Zf2cDnimbTFVeJtx1qtBmU","description":"Referenced account."}},"required":["accountId"],"additionalProperties":false,"description":"The sender, distinct from the account being paid named in `receiver`."},"settlementTraceId":{"type":"object","properties":{"status":{"type":"string","enum":["PENDING","AVAILABLE","UNSUPPORTED"],"examples":["AVAILABLE"],"description":"Whether a trace reference has been reported, is still pending, or the rail issues none."},"key":{"type":["string","null"],"enum":["END_TO_END_IDENTIFIER","RETRIEVAL_REFERENCE_NUMBER","UNIQUE_TRANSACTION_REFERENCE","UNIQUE_END_TO_END_TRANSACTION_REFERENCE"],"examples":["RETRIEVAL_REFERENCE_NUMBER"],"description":"Null until `rail` resolves, and where that rail issues nothing traceable."},"value":{"type":["string","null"],"examples":["402612345678"],"description":"The reference itself. Null until `status` is `AVAILABLE`, never a placeholder."}},"required":["status","key","value"],"additionalProperties":false},"receiverMemo":{"type":"string","examples":["Invoice INV-2026-0412"],"description":"Free-text memo to the receiver, where the rail carries one."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own key/value pairs, echoed back verbatim."},"confirmations":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"QUOTE"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"ACCOUNT_HOLDER_NAME"},"mode":{"type":"string","enum":["SEPA_VOP","IMPS_PENNY_DROP"],"examples":["IMPS_PENNY_DROP"],"description":"How the account holder name was checked."},"result":{"type":"string","examples":["MATCH"],"description":"Outcome of the name check. Not constrained to a closed set: the upstream types this as a free string, so a new verdict must not fail response validation."},"providedName":{"type":"string","examples":["Nadia Holdings Pvt Ltd"],"description":"The name submitted for comparison, frozen as it stood when the act ran."},"registeredName":{"type":["string","null"],"examples":["Nadia Holdings Private Limited"],"description":"The name the receiving institution holds. Null where the scheme returned none."},"createdAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"When the act started."},"verifiedAt":{"type":["string","null"],"format":"date-time","examples":["2026-06-04T10:35:12.000Z"],"description":"When it resolved. Null while `PENDING`."},"expiresAt":{"type":["string","null"],"format":"date-time","examples":["2026-12-04T10:35:12.000Z"],"description":"When the result goes stale, or null."}},"required":["type","mode","result","providedName","registeredName","createdAt","verifiedAt","expiresAt"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"RECEIVE_AMOUNT_DEDUCTIONS"}},"required":["type"],"additionalProperties":false}]},"description":"What the caller must accept before funds move. Complete in the create response, and it survives confirmation rather than draining."},"failure":{"type":["object","null"],"properties":{"code":{"type":"string","examples":["INSUFFICIENT_FUNDS"],"description":"Why the payout failed after acceptance. Branch on this, never on `message`. Not a closed enum on the wire — the upstream may add a code before this service knows about it."},"message":{"type":"string","examples":["Insufficient funds in the financial account when the debit was attempted after acceptance."],"description":"Human-readable failure detail."}},"required":["code","message"],"additionalProperties":false,"description":"Why this payout failed. Null unless `status` is FAILED."},"return":{"type":["object","null"],"properties":{"reasonCode":{"type":"string","examples":["AC04"],"description":"The reason code the scheme reported, such as SEPA `AC04`. Free-form: the scheme owns the values."},"amount":{"type":"string","pattern":"^[0-9]+\\.[0-9]{6}$","examples":["1000.000000"],"description":"Amount credited back."},"currency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["USD"],"description":"Currency of the returned `amount`."},"returnedAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"When the return was credited back."}},"required":["reasonCode","amount","currency","returnedAt"],"additionalProperties":false,"description":"How much came back, and when. Null unless `status` is RETURNED."},"createdAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:05.000Z"],"description":"Creation timestamp."},"updatedAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:05.000Z"],"description":"Last-update timestamp."},"processedAt":{"type":["string","null"],"format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"When the payout reached PROCESSED."}},"required":["object","id","financialAccountId","receiver","sendAmount","sendCurrency","receiveAmount","receiveCurrency","fees","fixedSide","fxRates","status","settlementTraceId","confirmations","failure","return","createdAt","updatedAt","processedAt"],"additionalProperties":false}},"required":["data"]},"examples":{"default_example":{"summary":"Confirmed and accepted","value":{"data":{"object":"payout","id":"pyt_GBWRJhmcFkMvrr4Fu3tMSJ","financialAccountId":"finacc_eUzeSQF9ZY6q4x8AhBskUf","receiver":{"accountId":"acc_h82pJGF9p7kpzb6eU326EF","payoutAddressId":"pytadd_NJAEqN76R7PwPfHt3oWb8R"},"rail":"IMPS","sendAmount":"1000.000000","sendCurrency":"USD","receiveAmount":"83450.00","receiveCurrency":"INR","fees":{"totalAmount":"3.000000","currency":"USD","components":[{"type":"NETWORK_FEE","amount":"3.000000","currency":"USD"}]},"fixedSide":"SEND","fxRates":{"client":"83.6835","convertedAmount":"997.000000","expiresAt":"2026-06-04T10:31:00.000Z"},"status":"ACCEPTED","settlementTraceId":{"status":"PENDING","key":null,"value":null},"receiverMemo":"Invoice INV-2026-0412","metadata":{"invoiceId":"INV-2026-0412"},"confirmations":[{"type":"QUOTE"}],"failure":null,"return":null,"createdAt":"2026-06-04T10:30:05.000Z","updatedAt":"2026-06-04T10:30:20.000Z","processedAt":null}}}}}}},"400":{"description":"The request failed validation, has an invalid Content-Type, the Idempotency-Key is malformed, or the gateway context was missing.","content":{"application/json":{"examples":{"validation_path_failed":{"summary":"URL path parameters failed validation.","value":{"error":{"code":"VALIDATION_PATH_FAILED","type":"VALIDATION_ERROR","message":"URL path parameters failed validation.","retryStrategy":"FIX_AND_RESUBMIT","details":{"issues":[{"path":"/payoutId","code":"invalid_string","message":"is not a well-formed payout id"}],"firstIssuePath":"/payoutId"}}}},"validation_content_type":{"summary":"Content-Type must be application/json.","value":{"error":{"code":"VALIDATION_CONTENT_TYPE","type":"VALIDATION_ERROR","message":"Content-Type must be application/json.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"idempotency_key_invalid":{"summary":"Idempotency-Key is malformed. Generate a new key matching the documented pattern and retry with that new key.","value":{"error":{"code":"IDEMPOTENCY_KEY_INVALID","type":"VALIDATION_ERROR","message":"Idempotency-Key is malformed. Generate a new key matching the documented pattern and retry with that new key.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"missing_request_context":{"summary":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","value":{"error":{"code":"MISSING_REQUEST_CONTEXT","type":"VALIDATION_ERROR","message":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"invalid_organization":{"summary":"The organization identifier on the request is malformed. Send the request through the documented gateway.","value":{"error":{"code":"INVALID_ORGANIZATION","type":"VALIDATION_ERROR","message":"The organization identifier on the request is malformed. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"The request is not authenticated.","content":{"application/json":{"examples":{"auth_token_missing":{"summary":"The Authorization header is missing. Provide a Bearer JWT.","value":{"error":{"code":"AUTH_TOKEN_MISSING","type":"AUTHENTICATION_ERROR","message":"The Authorization header is missing. Provide a Bearer JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid":{"summary":"Authorization token is invalid. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_expired":{"summary":"Authorization token has expired. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_EXPIRED","type":"AUTHENTICATION_ERROR","message":"Authorization token has expired. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid_config":{"summary":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","value":{"error":{"code":"AUTH_TOKEN_INVALID_CONFIG","type":"AUTHENTICATION_ERROR","message":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","retryStrategy":"TERMINAL","details":{}}}},"auth_api_key_invalid":{"summary":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","value":{"error":{"code":"AUTH_API_KEY_INVALID","type":"AUTHENTICATION_ERROR","message":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"The API key may not perform this operation.","content":{"application/json":{"examples":{"auth_insufficient_scope":{"summary":"The API key is missing the scope required for this operation.","value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"404":{"description":"A referenced resource does not exist in this org.","content":{"application/json":{"examples":{"payout_not_found":{"summary":"No payout with that id in this org.","value":{"error":{"code":"PAYOUT_NOT_FOUND","type":"NOT_FOUND","message":"No payout with that id in this org.","retryStrategy":"TERMINAL","details":{}}}}}}}},"409":{"description":"The request conflicts with current state, or with an in-flight request using the same key.","content":{"application/json":{"examples":{"idempotency_in_flight":{"summary":"Another request with this idempotency key is currently processing. Wait for some time and retry with the same key.","value":{"error":{"code":"IDEMPOTENCY_IN_FLIGHT","type":"CONFLICT","message":"Another request with this idempotency key is currently processing. Wait for some time and retry with the same key.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}},"insufficient_funds":{"summary":"The financial account does not hold enough funds for this payout.","value":{"error":{"code":"INSUFFICIENT_FUNDS","type":"CONFLICT","message":"The financial account does not hold enough funds for this payout.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{"financialAccountId":"finacc_eUzeSQF9ZY6q4x8AhBskUf"}}}},"payout_confirmation_not_allowed":{"summary":"This payout is not awaiting confirmation, so it can no longer be confirmed.","value":{"error":{"code":"PAYOUT_CONFIRMATION_NOT_ALLOWED","type":"CONFLICT","message":"This payout is not awaiting confirmation, so it can no longer be confirmed.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}},"payout_temporarily_unavailable":{"summary":"Payouts are temporarily unavailable. Retry shortly with the same Idempotency-Key.","value":{"error":{"code":"PAYOUT_TEMPORARILY_UNAVAILABLE","type":"CONFLICT","message":"Payouts are temporarily unavailable. Retry shortly with the same Idempotency-Key.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}},"422":{"description":"A business rule was tripped by the request's own values, or the key was replayed with a different body.","content":{"application/json":{"examples":{"idempotency_mismatch":{"summary":"This idempotency key was previously seen with a different request body. Use a new key for a new request, or resubmit the original body verbatim.","value":{"error":{"code":"IDEMPOTENCY_MISMATCH","type":"CONFLICT","message":"This idempotency key was previously seen with a different request body. Use a new key for a new request, or resubmit the original body verbatim.","retryStrategy":"FIX_AND_RESUBMIT","details":{"originalRequestHash":"sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"}}}}}}}},"428":{"description":"The Idempotency-Key header is required for this endpoint.","content":{"application/json":{"examples":{"idempotency_key_missing":{"summary":"The Idempotency-Key header is required for this endpoint.","value":{"error":{"code":"IDEMPOTENCY_KEY_MISSING","type":"VALIDATION_ERROR","message":"The Idempotency-Key header is required for this endpoint.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"429":{"description":"The API key has exceeded its request rate limit.","content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"This API key has exceeded its request rate limit for the current window.","value":{"error":{"code":"RATE_LIMIT_EXCEEDED","type":"RATE_LIMITED","message":"This API key has exceeded its request rate limit for the current window.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}},"500":{"description":"An unexpected internal error occurred.","content":{"application/json":{"examples":{"internal_error":{"summary":"An unexpected internal error occurred. Contact support with the trace ID.","value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"confirmPayout","summary":"Confirm payout","tags":["Payouts"],"description":"Acknowledge every entry in the payout's `confirmations[]` and release it for settlement. Acknowledgement is atomic — there is no per-entry confirm, so a caller who accepts the pricing but declines the account holder name should cancel and create another payout instead. The payout moves to `ACCEPTED` and `confirmations[]` is retained as the record of what was accepted.","parameters":[{"name":"payoutId","in":"path","required":true,"schema":{"type":"string","examples":["pyt_GBWRJhmcFkMvrr4Fu3tMSJ"]},"description":"Unique identifier of the payout."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255,"pattern":"^[a-zA-Z0-9_-]{1,255}$","example":"123e4567-e89b-12d3-a456-426614174000"},"description":"Unique key to ensure idempotent requests — 1-255 characters: alphanumerics, hyphens, underscores. UUID v4 recommended."}]}},"/payments/payouts/{payoutId}/cancel":{"post":{"responses":{"200":{"description":"success","headers":{"Idempotency-Replayed":{"description":"`true` when the response was served from the idempotency cache; `false` for a freshly executed request.","schema":{"type":"string","enum":["true","false"]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","const":"payout","examples":["payout"],"description":"The type of object represented, a fixed discriminator. Always `\"payout\"` for this resource."},"id":{"type":"string","pattern":"^pyt_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"pyt_GBWRJhmcFkMvrr4Fu3tMSJ","description":"Payout identifier."},"financialAccountId":{"type":"string","pattern":"^finacc_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"finacc_eUzeSQF9ZY6q4x8AhBskUf","description":"Financial account debited."},"receiver":{"type":"object","properties":{"accountId":{"type":"string","pattern":"^acc_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"acc_h82pJGF9p7kpzb6eU326EF","description":"The account being paid, derived from the payout address."},"payoutAddressId":{"type":"string","pattern":"^pytadd_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"pytadd_NJAEqN76R7PwPfHt3oWb8R","description":"The payout address the funds are credited to."}},"required":["accountId","payoutAddressId"],"additionalProperties":false},"rail":{"type":"string","enum":["SEPA","SWIFT","IMPS","NEFT","RTGS"],"examples":["IMPS"],"description":"Settlement rail selected; always present once resolved."},"sendAmount":{"type":"string","pattern":"^[0-9]+\\.[0-9]{6}$","examples":["1000.000000"],"description":"Total debited on the send side."},"sendCurrency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["USD"],"description":"Currency of the send leg."},"receiveAmount":{"type":"string","pattern":"^[0-9]+(\\.[0-9]{1,8})?$","examples":["83450.00"],"description":"Amount delivered on the receive side."},"receiveCurrency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["INR"],"description":"Currency of the receive leg."},"fees":{"type":"object","properties":{"totalAmount":{"type":"string","pattern":"^[0-9]+\\.[0-9]{6}$","examples":["3.000000"],"description":"Total of the fee components, added on top of `fxRates.convertedAmount` to make `sendAmount`."},"currency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["USD"],"description":"Currency of `totalAmount`."},"components":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["NETWORK_FEE","SWIFT_FEE","RESIDENT_DISCOUNT"],"examples":["NETWORK_FEE"],"description":"Kind of fee charged on top of the conversion. A `SWIFT_FEE` is a flat charge beside the `NETWORK_FEE` on a payout whose `rail` is `SWIFT`; a `RESIDENT_DISCOUNT` carries a negative `amount`."},"amount":{"type":"string","pattern":"^-?[0-9]+\\.[0-9]{6}$","examples":["5.000000"],"description":"What this component comes to. Negative for a discount such as `RESIDENT_DISCOUNT`."},"currency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["USD"],"description":"Currency of this component's `amount`."}},"required":["type","amount","currency"],"additionalProperties":false},"description":"Itemised breakdown. The components sum to `totalAmount`."}},"required":["totalAmount","currency","components"],"additionalProperties":false},"fixedSide":{"type":"string","enum":["SEND","RECEIVE"],"examples":["SEND"],"description":"Which leg is held exact. Derived from whichever amount the request provided: `sendAmount` gives `SEND`, `receiveAmount` gives `RECEIVE`."},"fxRates":{"type":"object","properties":{"client":{"type":"string","pattern":"^[0-9]+(\\.[0-9]{1,16})?$","examples":["1.10165"],"description":"Rate applied, in units of `sendCurrency` per unit of `receiveCurrency`. Conversion costs are already priced in."},"convertedAmount":{"type":"string","pattern":"^[0-9]+\\.[0-9]{6}$","examples":["110.165000"],"description":"What the receive leg comes to in `sendCurrency` at `client`, before the payout-leg fees."},"expiresAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:33:00.000Z"],"description":"When this rate expires. Omitted on a like-for-like quote, where no rate is locked."}},"required":["client","convertedAmount"],"additionalProperties":false},"status":{"type":"string","enum":["REQUIRES_CONFIRMATION","ACCEPTED","PROCESSING","IN_REVIEW","PROCESSED","RETURNED","FAILED","CANCELLED","EXPIRED"],"examples":["PROCESSED"],"description":"Lifecycle state. `REQUIRES_CONFIRMATION`, `ACCEPTED`, `PROCESSING` and `IN_REVIEW` are in flight. `RETURNED`, `FAILED`, `CANCELLED` and `EXPIRED` are terminal. `PROCESSED` is the success state and the only outcome that is not terminal — a late return can still move it to `RETURNED`."},"sender":{"type":"object","properties":{"accountId":{"type":"string","pattern":"^acc_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"acc_Zf2cDnimbTFVeJtx1qtBmU","description":"Referenced account."}},"required":["accountId"],"additionalProperties":false,"description":"The sender, distinct from the account being paid named in `receiver`."},"settlementTraceId":{"type":"object","properties":{"status":{"type":"string","enum":["PENDING","AVAILABLE","UNSUPPORTED"],"examples":["AVAILABLE"],"description":"Whether a trace reference has been reported, is still pending, or the rail issues none."},"key":{"type":["string","null"],"enum":["END_TO_END_IDENTIFIER","RETRIEVAL_REFERENCE_NUMBER","UNIQUE_TRANSACTION_REFERENCE","UNIQUE_END_TO_END_TRANSACTION_REFERENCE"],"examples":["RETRIEVAL_REFERENCE_NUMBER"],"description":"Null until `rail` resolves, and where that rail issues nothing traceable."},"value":{"type":["string","null"],"examples":["402612345678"],"description":"The reference itself. Null until `status` is `AVAILABLE`, never a placeholder."}},"required":["status","key","value"],"additionalProperties":false},"receiverMemo":{"type":"string","examples":["Invoice INV-2026-0412"],"description":"Free-text memo to the receiver, where the rail carries one."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own key/value pairs, echoed back verbatim."},"confirmations":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"QUOTE"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"ACCOUNT_HOLDER_NAME"},"mode":{"type":"string","enum":["SEPA_VOP","IMPS_PENNY_DROP"],"examples":["IMPS_PENNY_DROP"],"description":"How the account holder name was checked."},"result":{"type":"string","examples":["MATCH"],"description":"Outcome of the name check. Not constrained to a closed set: the upstream types this as a free string, so a new verdict must not fail response validation."},"providedName":{"type":"string","examples":["Nadia Holdings Pvt Ltd"],"description":"The name submitted for comparison, frozen as it stood when the act ran."},"registeredName":{"type":["string","null"],"examples":["Nadia Holdings Private Limited"],"description":"The name the receiving institution holds. Null where the scheme returned none."},"createdAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"When the act started."},"verifiedAt":{"type":["string","null"],"format":"date-time","examples":["2026-06-04T10:35:12.000Z"],"description":"When it resolved. Null while `PENDING`."},"expiresAt":{"type":["string","null"],"format":"date-time","examples":["2026-12-04T10:35:12.000Z"],"description":"When the result goes stale, or null."}},"required":["type","mode","result","providedName","registeredName","createdAt","verifiedAt","expiresAt"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"RECEIVE_AMOUNT_DEDUCTIONS"}},"required":["type"],"additionalProperties":false}]},"description":"What the caller must accept before funds move. Complete in the create response, and it survives confirmation rather than draining."},"failure":{"type":["object","null"],"properties":{"code":{"type":"string","examples":["INSUFFICIENT_FUNDS"],"description":"Why the payout failed after acceptance. Branch on this, never on `message`. Not a closed enum on the wire — the upstream may add a code before this service knows about it."},"message":{"type":"string","examples":["Insufficient funds in the financial account when the debit was attempted after acceptance."],"description":"Human-readable failure detail."}},"required":["code","message"],"additionalProperties":false,"description":"Why this payout failed. Null unless `status` is FAILED."},"return":{"type":["object","null"],"properties":{"reasonCode":{"type":"string","examples":["AC04"],"description":"The reason code the scheme reported, such as SEPA `AC04`. Free-form: the scheme owns the values."},"amount":{"type":"string","pattern":"^[0-9]+\\.[0-9]{6}$","examples":["1000.000000"],"description":"Amount credited back."},"currency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["USD"],"description":"Currency of the returned `amount`."},"returnedAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"When the return was credited back."}},"required":["reasonCode","amount","currency","returnedAt"],"additionalProperties":false,"description":"How much came back, and when. Null unless `status` is RETURNED."},"createdAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:05.000Z"],"description":"Creation timestamp."},"updatedAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:05.000Z"],"description":"Last-update timestamp."},"processedAt":{"type":["string","null"],"format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"When the payout reached PROCESSED."}},"required":["object","id","financialAccountId","receiver","sendAmount","sendCurrency","receiveAmount","receiveCurrency","fees","fixedSide","fxRates","status","settlementTraceId","confirmations","failure","return","createdAt","updatedAt","processedAt"],"additionalProperties":false}},"required":["data"]},"examples":{"default_example":{"summary":"Cancelled before confirmation","value":{"data":{"object":"payout","id":"pyt_GBWRJhmcFkMvrr4Fu3tMSJ","financialAccountId":"finacc_eUzeSQF9ZY6q4x8AhBskUf","receiver":{"accountId":"acc_h82pJGF9p7kpzb6eU326EF","payoutAddressId":"pytadd_NJAEqN76R7PwPfHt3oWb8R"},"rail":"IMPS","sendAmount":"1000.000000","sendCurrency":"USD","receiveAmount":"83450.00","receiveCurrency":"INR","fees":{"totalAmount":"3.000000","currency":"USD","components":[{"type":"NETWORK_FEE","amount":"3.000000","currency":"USD"}]},"fixedSide":"SEND","fxRates":{"client":"83.6835","convertedAmount":"997.000000","expiresAt":"2026-06-04T10:31:00.000Z"},"status":"CANCELLED","settlementTraceId":{"status":"PENDING","key":null,"value":null},"receiverMemo":"Invoice INV-2026-0412","metadata":{"invoiceId":"INV-2026-0412"},"confirmations":[{"type":"QUOTE"}],"failure":null,"return":null,"createdAt":"2026-06-04T10:30:05.000Z","updatedAt":"2026-06-04T10:30:25.000Z","processedAt":null}}}}}}},"400":{"description":"The request failed validation, has an invalid Content-Type, the Idempotency-Key is malformed, or the gateway context was missing.","content":{"application/json":{"examples":{"validation_path_failed":{"summary":"URL path parameters failed validation.","value":{"error":{"code":"VALIDATION_PATH_FAILED","type":"VALIDATION_ERROR","message":"URL path parameters failed validation.","retryStrategy":"FIX_AND_RESUBMIT","details":{"issues":[{"path":"/payoutId","code":"invalid_string","message":"is not a well-formed payout id"}],"firstIssuePath":"/payoutId"}}}},"validation_content_type":{"summary":"Content-Type must be application/json.","value":{"error":{"code":"VALIDATION_CONTENT_TYPE","type":"VALIDATION_ERROR","message":"Content-Type must be application/json.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"idempotency_key_invalid":{"summary":"Idempotency-Key is malformed. Generate a new key matching the documented pattern and retry with that new key.","value":{"error":{"code":"IDEMPOTENCY_KEY_INVALID","type":"VALIDATION_ERROR","message":"Idempotency-Key is malformed. Generate a new key matching the documented pattern and retry with that new key.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"missing_request_context":{"summary":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","value":{"error":{"code":"MISSING_REQUEST_CONTEXT","type":"VALIDATION_ERROR","message":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"invalid_organization":{"summary":"The organization identifier on the request is malformed. Send the request through the documented gateway.","value":{"error":{"code":"INVALID_ORGANIZATION","type":"VALIDATION_ERROR","message":"The organization identifier on the request is malformed. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"The request is not authenticated.","content":{"application/json":{"examples":{"auth_token_missing":{"summary":"The Authorization header is missing. Provide a Bearer JWT.","value":{"error":{"code":"AUTH_TOKEN_MISSING","type":"AUTHENTICATION_ERROR","message":"The Authorization header is missing. Provide a Bearer JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid":{"summary":"Authorization token is invalid. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_expired":{"summary":"Authorization token has expired. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_EXPIRED","type":"AUTHENTICATION_ERROR","message":"Authorization token has expired. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid_config":{"summary":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","value":{"error":{"code":"AUTH_TOKEN_INVALID_CONFIG","type":"AUTHENTICATION_ERROR","message":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","retryStrategy":"TERMINAL","details":{}}}},"auth_api_key_invalid":{"summary":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","value":{"error":{"code":"AUTH_API_KEY_INVALID","type":"AUTHENTICATION_ERROR","message":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"The API key may not perform this operation.","content":{"application/json":{"examples":{"auth_insufficient_scope":{"summary":"The API key is missing the scope required for this operation.","value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"404":{"description":"A referenced resource does not exist in this org.","content":{"application/json":{"examples":{"payout_not_found":{"summary":"No payout with that id in this org.","value":{"error":{"code":"PAYOUT_NOT_FOUND","type":"NOT_FOUND","message":"No payout with that id in this org.","retryStrategy":"TERMINAL","details":{}}}}}}}},"409":{"description":"The request conflicts with current state, or with an in-flight request using the same key.","content":{"application/json":{"examples":{"idempotency_in_flight":{"summary":"Another request with this idempotency key is currently processing. Wait for some time and retry with the same key.","value":{"error":{"code":"IDEMPOTENCY_IN_FLIGHT","type":"CONFLICT","message":"Another request with this idempotency key is currently processing. Wait for some time and retry with the same key.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}},"payout_cancellation_not_allowed":{"summary":"This payout is no longer cancellable.","value":{"error":{"code":"PAYOUT_CANCELLATION_NOT_ALLOWED","type":"CONFLICT","message":"This payout is no longer cancellable.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}},"422":{"description":"A business rule was tripped by the request's own values, or the key was replayed with a different body.","content":{"application/json":{"examples":{"idempotency_mismatch":{"summary":"This idempotency key was previously seen with a different request body. Use a new key for a new request, or resubmit the original body verbatim.","value":{"error":{"code":"IDEMPOTENCY_MISMATCH","type":"CONFLICT","message":"This idempotency key was previously seen with a different request body. Use a new key for a new request, or resubmit the original body verbatim.","retryStrategy":"FIX_AND_RESUBMIT","details":{"originalRequestHash":"sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"}}}}}}}},"428":{"description":"The Idempotency-Key header is required for this endpoint.","content":{"application/json":{"examples":{"idempotency_key_missing":{"summary":"The Idempotency-Key header is required for this endpoint.","value":{"error":{"code":"IDEMPOTENCY_KEY_MISSING","type":"VALIDATION_ERROR","message":"The Idempotency-Key header is required for this endpoint.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"429":{"description":"The API key has exceeded its request rate limit.","content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"This API key has exceeded its request rate limit for the current window.","value":{"error":{"code":"RATE_LIMIT_EXCEEDED","type":"RATE_LIMITED","message":"This API key has exceeded its request rate limit for the current window.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}},"500":{"description":"An unexpected internal error occurred.","content":{"application/json":{"examples":{"internal_error":{"summary":"An unexpected internal error occurred. Contact support with the trace ID.","value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"cancelPayout","summary":"Cancel payout","tags":["Payouts"],"description":"Decline a payout that is still awaiting confirmation. No funds have moved at this point, so cancelling is terminal and clean: the payout moves to `CANCELLED` and cannot be revived. This is how a caller declines an account holder name they do not accept — cancel, then create a replacement payout against a corrected payout address.","parameters":[{"name":"payoutId","in":"path","required":true,"schema":{"type":"string","examples":["pyt_GBWRJhmcFkMvrr4Fu3tMSJ"]},"description":"Unique identifier of the payout."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255,"pattern":"^[a-zA-Z0-9_-]{1,255}$","example":"123e4567-e89b-12d3-a456-426614174000"},"description":"Unique key to ensure idempotent requests — 1-255 characters: alphanumerics, hyphens, underscores. UUID v4 recommended."}]}},"/common/accounts":{"post":{"responses":{"200":{"description":"success","headers":{"Idempotency-Replayed":{"description":"`true` when the response was served from the idempotency cache; `false` for a freshly executed request.","schema":{"type":"string","enum":["true","false"]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","const":"account","examples":["account"],"description":"The type of object represented, a fixed discriminator. Always `\"account\"` for this resource."},"id":{"type":"string","pattern":"^acc_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"acc_h82pJGF9p7kpzb6eU326EF","description":"Account identifier."},"status":{"type":"string","enum":["PENDING","ACTIVE","REJECTED","REQUIRES_INFORMATION"],"examples":["ACTIVE"],"description":"The account's standing with OpenFX as a whole. Not a rollup of `capabilities` — each capability carries its own status. `ACTIVE` is the only status in which a payout can name the account."},"archivedAt":{"type":["string","null"],"format":"date-time","examples":["2026-07-01T09:00:00.000Z"],"description":"When the client retired this account, or null while it is live. Terminal once set."},"createdAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"Creation timestamp."},"updatedAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"Update timestamp."},"capabilities":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"accountCapability","examples":["accountCapability"],"description":"The type of object represented, a fixed discriminator. Always `\"accountCapability\"` for this resource."},"id":{"type":"string","pattern":"^cap_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"cap_Ce3AJmAmDGcJgTmTqgFVZ","description":"The catalog capability this account holds."},"status":{"type":"string","enum":["PENDING","ACTIVE","REJECTED","REQUIRES_INFORMATION"],"examples":["ACTIVE"],"description":"Whether this capability can currently back its activity on a payout. Born `PENDING`; settles by webhook, usually within a minute."},"hasActiveAddresses":{"type":["boolean","null"],"description":"Indicates whether the capability serves any payout addresses"},"details":{"type":"object","properties":{"grants":{"type":"array","items":{"type":"string"},"minItems":1,"examples":[["RECEIVE_PAYOUTS"]],"description":"What this capability lets the holding account do, at least one grant (e.g. `RECEIVE_PAYOUTS`, `SEND_PAYOUTS_TO_THIRD_PARTIES`). Append-only: tolerate a member you do not recognize."},"currencies":{"type":"array","items":{"type":"string","pattern":"^[A-Z0-9]{2,15}$"},"minItems":1,"examples":[["EUR"]],"description":"The currencies this capability covers. Absent where the coverage is currency-independent."},"repatriability":{"type":"array","items":{"type":"string"},"minItems":1,"examples":[["REPATRIABLE"]],"description":"The repatriability categories this capability covers (`REPATRIABLE` / `NON_REPATRIABLE`). Absent where the axis does not apply."}},"required":["grants"],"additionalProperties":false}},"required":["object","id","status","hasActiveAddresses","details"],"additionalProperties":false},"description":"The capabilities this account holds, one entry per capability it has been set up for. Grows via POST /v3/common/accounts/{accountId}/capabilities."},"identity":{"oneOf":[{"type":"object","properties":{"identityType":{"type":"string","const":"INDIVIDUAL"},"individual":{"type":"object","properties":{"firstName":{"type":"string","examples":["Nadia"],"description":"Given names, in the order the person writes them."},"lastName":{"type":"string","examples":["Mehta"],"description":"Family name. A person who goes by a single name puts the whole of it here."},"dateOfBirth":{"type":"string","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","examples":["1990-03-14"],"description":"The person's date of birth."},"nationality":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose nationality the person holds. Single-valued."},"email":{"type":"string","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\\.)+[A-Za-z]{2,}$","maxLength":255,"examples":["nadia.mehta@novalia.example"],"description":"The person's own email address."},"phoneNumber":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$","examples":["+919876543210"],"description":"The person's own phone number."},"residentialAddress":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"Where the person lives."},"taxInformation":{"type":"array","items":{"type":"object","properties":{"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose authority issued the identifier."},"taxIdNumber":{"type":"string","examples":["ABCDE1234F"],"description":"The identifier itself, as the issuing authority writes it, punctuation included."}},"required":["issuingCountry","taxIdNumber"],"additionalProperties":false},"description":"The tax identifiers this person holds, one entry per issuing country. An Indian PAN belongs here."},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["PASSPORT","NATIONAL_ID","DRIVERS_LICENSE","SSN","RESIDENCE_PERMIT"],"examples":["PASSPORT"],"description":"The kind of document a person holds."},"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country the document was issued in."}},"required":["type","issuingCountry"],"additionalProperties":false}}},"required":["lastName"],"additionalProperties":false}},"required":["identityType","individual"],"additionalProperties":false},{"type":"object","properties":{"identityType":{"type":"string","const":"ORGANIZATION"},"organization":{"type":"object","properties":{"legalName":{"type":"string","examples":["Novalia Handels GmbH"],"description":"The organization's name exactly as the register it is incorporated in records it, suffix included."},"doingBusinessAs":{"type":"string","examples":["Novalia"],"description":"The trading name the organization is known by, where that differs from the legal name."},"contactEmail":{"type":"string","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\\.)+[A-Za-z]{2,}$","maxLength":255,"examples":["treasury@novalia.example"],"description":"An address that reaches the organization; a channel into the company, not any one person's own."},"registrationNumber":{"type":"string","examples":["HRB 123456"],"description":"The organization's number in the public register it is incorporated in."},"dateOfIncorporation":{"type":"string","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","examples":["2014-09-01"],"description":"The date the organization was constituted."},"legalStructure":{"type":"string","enum":["PUBLIC_LISTED_COMPANY","PRIVATE_LIMITED","SOLE_TRADER","NON_PROFIT","GENERAL_PARTNERSHIP","LIMITED_PARTNERSHIP"],"examples":["PRIVATE_LIMITED"],"description":"The form an organization is constituted in."},"taxInformation":{"type":"array","items":{"type":"object","properties":{"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose authority issued the identifier."},"taxIdNumber":{"type":"string","examples":["ABCDE1234F"],"description":"The identifier itself, as the issuing authority writes it, punctuation included."}},"required":["issuingCountry","taxIdNumber"],"additionalProperties":false},"description":"The tax identifiers this organization holds, one entry per issuing country. A VAT number is one."},"registeredAddress":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"The registered office: the address on file in the register the organization is incorporated in."},"principalPlaceOfBusiness":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"Where the organization operates from, where that differs from the registered office."},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["REGISTRATION_DOCUMENT","CONSTITUTIONAL_DOCUMENT","PROOF_OF_OWNERSHIP","PROOF_OF_ADDRESS","PROOF_OF_TAX_INFORMATION"],"examples":["REGISTRATION_DOCUMENT"],"description":"The kind of document an organization holds."},"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country the document was issued in."}},"required":["type","issuingCountry"],"additionalProperties":false}},"associations":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"identityType":{"type":"string","const":"INDIVIDUAL"},"role":{"type":"string","enum":["UBO_THROUGH_OWNERSHIP","UBO_THROUGH_CONTROL","DIRECTOR","SIGNATORY","AUTHORIZED_REPRESENTATIVE"],"examples":["UBO_THROUGH_OWNERSHIP"],"description":"How a natural person is associated with an organization."},"individual":{"type":"object","properties":{"firstName":{"type":"string","examples":["Nadia"],"description":"Given names, in the order the person writes them."},"lastName":{"type":"string","examples":["Mehta"],"description":"Family name. A person who goes by a single name puts the whole of it here."},"dateOfBirth":{"type":"string","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","examples":["1990-03-14"],"description":"The person's date of birth."},"nationality":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose nationality the person holds. Single-valued."},"email":{"type":"string","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\\.)+[A-Za-z]{2,}$","maxLength":255,"examples":["nadia.mehta@novalia.example"],"description":"The person's own email address."},"phoneNumber":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$","examples":["+919876543210"],"description":"The person's own phone number."},"residentialAddress":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"Where the person lives."},"taxInformation":{"type":"array","items":{"type":"object","properties":{"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose authority issued the identifier."},"taxIdNumber":{"type":"string","examples":["ABCDE1234F"],"description":"The identifier itself, as the issuing authority writes it, punctuation included."}},"required":["issuingCountry","taxIdNumber"],"additionalProperties":false},"description":"The tax identifiers this person holds, one entry per issuing country. An Indian PAN belongs here."},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["PASSPORT","NATIONAL_ID","DRIVERS_LICENSE","SSN","RESIDENCE_PERMIT"],"examples":["PASSPORT"],"description":"The kind of document a person holds."},"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country the document was issued in."}},"required":["type","issuingCountry"],"additionalProperties":false}}},"required":["lastName"],"additionalProperties":false},"ownershipPercent":{"type":"number","minimum":0,"maximum":100,"examples":[40],"description":"The share of the organization this identity holds, as a percentage."}},"required":["identityType","role","individual"],"additionalProperties":false},{"type":"object","properties":{"identityType":{"type":"string","const":"ORGANIZATION"},"role":{"type":"string","enum":["ULTIMATE_PARENT_COMPANY"],"examples":["ULTIMATE_PARENT_COMPANY"],"description":"How an organization is associated with another organization."},"organization":{"type":"object","properties":{"legalName":{"type":"string","examples":["Novalia Handels GmbH"],"description":"The organization's name exactly as the register it is incorporated in records it, suffix included."},"doingBusinessAs":{"type":"string","examples":["Novalia"],"description":"The trading name the organization is known by, where that differs from the legal name."},"contactEmail":{"type":"string","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\\.)+[A-Za-z]{2,}$","maxLength":255,"examples":["treasury@novalia.example"],"description":"An address that reaches the organization; a channel into the company, not any one person's own."},"registrationNumber":{"type":"string","examples":["HRB 123456"],"description":"The organization's number in the public register it is incorporated in."},"dateOfIncorporation":{"type":"string","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","examples":["2014-09-01"],"description":"The date the organization was constituted."},"legalStructure":{"type":"string","enum":["PUBLIC_LISTED_COMPANY","PRIVATE_LIMITED","SOLE_TRADER","NON_PROFIT","GENERAL_PARTNERSHIP","LIMITED_PARTNERSHIP"],"examples":["PRIVATE_LIMITED"],"description":"The form an organization is constituted in."},"taxInformation":{"type":"array","items":{"type":"object","properties":{"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose authority issued the identifier."},"taxIdNumber":{"type":"string","examples":["ABCDE1234F"],"description":"The identifier itself, as the issuing authority writes it, punctuation included."}},"required":["issuingCountry","taxIdNumber"],"additionalProperties":false},"description":"The tax identifiers this organization holds, one entry per issuing country. A VAT number is one."},"registeredAddress":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"The registered office: the address on file in the register the organization is incorporated in."},"principalPlaceOfBusiness":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"Where the organization operates from, where that differs from the registered office."},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["REGISTRATION_DOCUMENT","CONSTITUTIONAL_DOCUMENT","PROOF_OF_OWNERSHIP","PROOF_OF_ADDRESS","PROOF_OF_TAX_INFORMATION"],"examples":["REGISTRATION_DOCUMENT"],"description":"The kind of document an organization holds."},"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country the document was issued in."}},"required":["type","issuingCountry"],"additionalProperties":false}}},"required":["legalName"],"additionalProperties":false},"ownershipPercent":{"type":"number","minimum":0,"maximum":100,"examples":[40],"description":"The share of the organization this identity holds, as a percentage."}},"required":["identityType","role","organization"],"additionalProperties":false}]}}},"required":["legalName"],"additionalProperties":false}},"required":["identityType","organization"],"additionalProperties":false}],"description":"Who the account is."},"label":{"type":"string","examples":["Novalia"],"description":"Freeform label to help you identify the account."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own key/value pairs, echoed back verbatim."}},"required":["object","id","status","archivedAt","createdAt","updatedAt","capabilities","identity"],"additionalProperties":false}},"required":["data"]},"examples":{"default_example":{"summary":"Organization account, EUR-receiving capability pending","value":{"data":{"object":"account","id":"acc_h82pJGF9p7kpzb6eU326EF","status":"ACTIVE","capabilities":[{"object":"accountCapability","id":"cap_Ce3AJmAmDGcJgTmTqgFVZ","status":"PENDING","hasActiveAddresses":false,"details":{"grants":["RECEIVE_PAYOUTS"],"currencies":["EUR"]}}],"identity":{"identityType":"ORGANIZATION","organization":{"legalName":"Novalia Handels GmbH","registeredAddress":{"country":"DE"}}},"archivedAt":null,"createdAt":"2026-06-04T10:30:00.000Z","updatedAt":"2026-06-04T10:30:00.000Z"}}}}}}},"400":{"description":"The request failed validation, has an invalid Content-Type, the Idempotency-Key is malformed, or the gateway context was missing.","content":{"application/json":{"examples":{"validation_body_failed":{"summary":"Request body failed validation. See details.issues for field-level errors, or details.firstIssuePath for the most common single-field case.","value":{"error":{"code":"VALIDATION_BODY_FAILED","type":"VALIDATION_ERROR","message":"Request body failed validation. See details.issues for field-level errors, or details.firstIssuePath for the most common single-field case.","retryStrategy":"FIX_AND_RESUBMIT","details":{"issues":[{"path":"/identity/individual/lastName","code":"invalid_type","message":"Required","expected":"string","received":"undefined"},{"path":"/identity/individual/documents/0/type","code":"invalid_enum_value","message":"is not a supported document type","expected":"PASSPORT|NATIONAL_ID|DRIVERS_LICENSE|SSN|RESIDENCE_PERMIT","received":"LIBRARY_CARD"},{"path":"/identity/individual/residentialAddress/country","code":"custom","message":"is not an ISO 3166-1 alpha-2 country code (the United Kingdom is GB)","received":"UK"}],"firstIssuePath":"/identity/individual/lastName"}}}},"validation_content_type":{"summary":"Content-Type must be application/json.","value":{"error":{"code":"VALIDATION_CONTENT_TYPE","type":"VALIDATION_ERROR","message":"Content-Type must be application/json.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"idempotency_key_invalid":{"summary":"Idempotency-Key is malformed. Generate a new key matching the documented pattern and retry with that new key.","value":{"error":{"code":"IDEMPOTENCY_KEY_INVALID","type":"VALIDATION_ERROR","message":"Idempotency-Key is malformed. Generate a new key matching the documented pattern and retry with that new key.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"missing_request_context":{"summary":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","value":{"error":{"code":"MISSING_REQUEST_CONTEXT","type":"VALIDATION_ERROR","message":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"invalid_organization":{"summary":"The organization identifier on the request is malformed. Send the request through the documented gateway.","value":{"error":{"code":"INVALID_ORGANIZATION","type":"VALIDATION_ERROR","message":"The organization identifier on the request is malformed. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"The request is not authenticated.","content":{"application/json":{"examples":{"auth_token_missing":{"summary":"The Authorization header is missing. Provide a Bearer JWT.","value":{"error":{"code":"AUTH_TOKEN_MISSING","type":"AUTHENTICATION_ERROR","message":"The Authorization header is missing. Provide a Bearer JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid":{"summary":"Authorization token is invalid. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_expired":{"summary":"Authorization token has expired. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_EXPIRED","type":"AUTHENTICATION_ERROR","message":"Authorization token has expired. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid_config":{"summary":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","value":{"error":{"code":"AUTH_TOKEN_INVALID_CONFIG","type":"AUTHENTICATION_ERROR","message":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","retryStrategy":"TERMINAL","details":{}}}},"auth_api_key_invalid":{"summary":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","value":{"error":{"code":"AUTH_API_KEY_INVALID","type":"AUTHENTICATION_ERROR","message":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"The API key may not perform this operation.","content":{"application/json":{"examples":{"auth_insufficient_scope":{"summary":"The API key is missing the scope required for this operation.","value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"409":{"description":"The request conflicts with current state, or with an in-flight request using the same key.","content":{"application/json":{"examples":{"idempotency_in_flight":{"summary":"Another request with this idempotency key is currently processing. Wait for some time and retry with the same key.","value":{"error":{"code":"IDEMPOTENCY_IN_FLIGHT","type":"CONFLICT","message":"Another request with this idempotency key is currently processing. Wait for some time and retry with the same key.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}},"422":{"description":"A business rule was tripped by the request's own values, or the key was replayed with a different body.","content":{"application/json":{"examples":{"idempotency_mismatch":{"summary":"This idempotency key was previously seen with a different request body. Use a new key for a new request, or resubmit the original body verbatim.","value":{"error":{"code":"IDEMPOTENCY_MISMATCH","type":"CONFLICT","message":"This idempotency key was previously seen with a different request body. Use a new key for a new request, or resubmit the original body verbatim.","retryStrategy":"FIX_AND_RESUBMIT","details":{"originalRequestHash":"sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"}}}},"capability_duplicate":{"summary":"The account already holds a cell for a requested capability, or the request names the same capability twice. details.capabilities lists the duplicates.","value":{"error":{"code":"CAPABILITY_DUPLICATE","type":"VALIDATION_ERROR","message":"The account already holds a cell for a requested capability, or the request names the same capability twice. details.capabilities lists the duplicates.","retryStrategy":"FIX_AND_RESUBMIT","details":{"duplicates":["cap_Ce3AJmB1WMUZmkD9mMKVx"]}}}},"identity_requirement_unmet":{"summary":"A requested capability needs more identity information than the account has supplied. details names each capability and its unmet requirements.","value":{"error":{"code":"IDENTITY_REQUIREMENT_UNMET","type":"VALIDATION_ERROR","message":"A requested capability needs more identity information than the account has supplied. details names each capability and its unmet requirements.","retryStrategy":"FIX_AND_RESUBMIT","details":{"issues":[{"path":"/identity/individual/nationality","code":"invalid_type","message":"Required","expected":"string","received":"undefined"},{"path":"/identity/individual/residentialAddress/country","code":"invalid_type","message":"Required","expected":"string","received":"undefined"}],"firstIssuePath":"/identity/individual/nationality"}}}}}}}},"428":{"description":"The Idempotency-Key header is required for this endpoint.","content":{"application/json":{"examples":{"idempotency_key_missing":{"summary":"The Idempotency-Key header is required for this endpoint.","value":{"error":{"code":"IDEMPOTENCY_KEY_MISSING","type":"VALIDATION_ERROR","message":"The Idempotency-Key header is required for this endpoint.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"429":{"description":"The API key has exceeded its request rate limit.","content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"This API key has exceeded its request rate limit for the current window.","value":{"error":{"code":"RATE_LIMIT_EXCEEDED","type":"RATE_LIMITED","message":"This API key has exceeded its request rate limit for the current window.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}},"500":{"description":"An unexpected internal error occurred.","content":{"application/json":{"examples":{"internal_error":{"summary":"An unexpected internal error occurred. Contact support with the trace ID.","value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"createAccount","summary":"Create an account","tags":["Accounts"],"description":"Create an account — the party you move money to or from: one identity, plus the capabilities it should be set up for. `capabilities` may be empty (a bare account is an identity container; request more later with POST /v3/common/accounts/{accountId}/capabilities). Every requested capability starts `PENDING` and settles by webhook, usually within a minute. An account holds no money with OpenFX: it is a party, not a balance.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255,"pattern":"^[a-zA-Z0-9_-]{1,255}$","example":"123e4567-e89b-12d3-a456-426614174000"},"description":"Unique key to ensure idempotent requests — 1-255 characters: alphanumerics, hyphens, underscores. UUID v4 recommended."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"capabilities":{"type":"array","items":{"type":"string","example":"cap_Ce3AJmAmDGcJgTmTqgFVZ","description":"A capability id from the capability catalog."},"description":"The capabilities to request for this account. May be empty: a bare account is an identity container, and more can be requested after creation. Every requested capability starts `PENDING`."},"identity":{"oneOf":[{"type":"object","properties":{"identityType":{"type":"string","const":"INDIVIDUAL"},"individual":{"type":"object","properties":{"firstName":{"type":"string","examples":["Nadia"],"description":"Given names, in the order the person writes them."},"lastName":{"type":"string","examples":["Mehta"],"description":"Family name. A person who goes by a single name puts the whole of it here."},"dateOfBirth":{"type":"string","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","examples":["1990-03-14"],"description":"The person's date of birth."},"nationality":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose nationality the person holds. Single-valued."},"email":{"type":"string","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\\.)+[A-Za-z]{2,}$","maxLength":255,"examples":["nadia.mehta@novalia.example"],"description":"The person's own email address."},"phoneNumber":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$","examples":["+919876543210"],"description":"The person's own phone number."},"residentialAddress":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"Where the person lives."},"taxInformation":{"type":"array","items":{"type":"object","properties":{"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose authority issued the identifier."},"taxIdNumber":{"type":"string","examples":["ABCDE1234F"],"description":"The identifier itself, as the issuing authority writes it, punctuation included."}},"required":["issuingCountry","taxIdNumber"],"additionalProperties":false},"description":"The tax identifiers this person holds, one entry per issuing country. An Indian PAN belongs here."},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["PASSPORT","NATIONAL_ID","DRIVERS_LICENSE","SSN","RESIDENCE_PERMIT"],"examples":["PASSPORT"],"description":"The kind of document a person holds."},"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country the document was issued in."},"number":{"type":"string","examples":["Z1234567"],"description":"The number printed on the document. Input-only: never returned on reads."}},"required":["type","issuingCountry","number"],"additionalProperties":false}}},"required":["lastName"],"additionalProperties":false}},"required":["identityType","individual"],"additionalProperties":false},{"type":"object","properties":{"identityType":{"type":"string","const":"ORGANIZATION"},"organization":{"type":"object","properties":{"legalName":{"type":"string","examples":["Novalia Handels GmbH"],"description":"The organization's name exactly as the register it is incorporated in records it, suffix included."},"doingBusinessAs":{"type":"string","examples":["Novalia"],"description":"The trading name the organization is known by, where that differs from the legal name."},"contactEmail":{"type":"string","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\\.)+[A-Za-z]{2,}$","maxLength":255,"examples":["treasury@novalia.example"],"description":"An address that reaches the organization; a channel into the company, not any one person's own."},"registrationNumber":{"type":"string","examples":["HRB 123456"],"description":"The organization's number in the public register it is incorporated in."},"dateOfIncorporation":{"type":"string","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","examples":["2014-09-01"],"description":"The date the organization was constituted."},"legalStructure":{"type":"string","enum":["PUBLIC_LISTED_COMPANY","PRIVATE_LIMITED","SOLE_TRADER","NON_PROFIT","GENERAL_PARTNERSHIP","LIMITED_PARTNERSHIP"],"examples":["PRIVATE_LIMITED"],"description":"The form an organization is constituted in."},"taxInformation":{"type":"array","items":{"type":"object","properties":{"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose authority issued the identifier."},"taxIdNumber":{"type":"string","examples":["ABCDE1234F"],"description":"The identifier itself, as the issuing authority writes it, punctuation included."}},"required":["issuingCountry","taxIdNumber"],"additionalProperties":false},"description":"The tax identifiers this organization holds, one entry per issuing country. A VAT number is one."},"registeredAddress":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"The registered office: the address on file in the register the organization is incorporated in."},"principalPlaceOfBusiness":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"Where the organization operates from, where that differs from the registered office."},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["REGISTRATION_DOCUMENT","CONSTITUTIONAL_DOCUMENT","PROOF_OF_OWNERSHIP","PROOF_OF_ADDRESS","PROOF_OF_TAX_INFORMATION"],"examples":["REGISTRATION_DOCUMENT"],"description":"The kind of document an organization holds."},"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country the document was issued in."},"number":{"type":"string","examples":["Z1234567"],"description":"The number printed on the document. Input-only: never returned on reads."}},"required":["type","issuingCountry","number"],"additionalProperties":false}},"associations":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"identityType":{"type":"string","const":"INDIVIDUAL"},"role":{"type":"string","enum":["UBO_THROUGH_OWNERSHIP","UBO_THROUGH_CONTROL","DIRECTOR","SIGNATORY","AUTHORIZED_REPRESENTATIVE"],"examples":["UBO_THROUGH_OWNERSHIP"],"description":"How a natural person is associated with an organization."},"individual":{"type":"object","properties":{"firstName":{"type":"string","examples":["Nadia"],"description":"Given names, in the order the person writes them."},"lastName":{"type":"string","examples":["Mehta"],"description":"Family name. A person who goes by a single name puts the whole of it here."},"dateOfBirth":{"type":"string","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","examples":["1990-03-14"],"description":"The person's date of birth."},"nationality":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose nationality the person holds. Single-valued."},"email":{"type":"string","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\\.)+[A-Za-z]{2,}$","maxLength":255,"examples":["nadia.mehta@novalia.example"],"description":"The person's own email address."},"phoneNumber":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$","examples":["+919876543210"],"description":"The person's own phone number."},"residentialAddress":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"Where the person lives."},"taxInformation":{"type":"array","items":{"type":"object","properties":{"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose authority issued the identifier."},"taxIdNumber":{"type":"string","examples":["ABCDE1234F"],"description":"The identifier itself, as the issuing authority writes it, punctuation included."}},"required":["issuingCountry","taxIdNumber"],"additionalProperties":false},"description":"The tax identifiers this person holds, one entry per issuing country. An Indian PAN belongs here."},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["PASSPORT","NATIONAL_ID","DRIVERS_LICENSE","SSN","RESIDENCE_PERMIT"],"examples":["PASSPORT"],"description":"The kind of document a person holds."},"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country the document was issued in."},"number":{"type":"string","examples":["Z1234567"],"description":"The number printed on the document. Input-only: never returned on reads."}},"required":["type","issuingCountry","number"],"additionalProperties":false}}},"required":["lastName"],"additionalProperties":false,"description":"Who this person is."},"ownershipPercent":{"type":"number","minimum":0,"maximum":100,"examples":[40],"description":"The share of the organization this identity holds, as a percentage."}},"required":["identityType","role","individual"],"additionalProperties":false},{"type":"object","properties":{"identityType":{"type":"string","const":"ORGANIZATION"},"role":{"type":"string","enum":["ULTIMATE_PARENT_COMPANY"],"examples":["ULTIMATE_PARENT_COMPANY"],"description":"How an organization is associated with another organization."},"organization":{"type":"object","properties":{"legalName":{"type":"string","examples":["Novalia Handels GmbH"],"description":"The organization's name exactly as the register it is incorporated in records it, suffix included."},"doingBusinessAs":{"type":"string","examples":["Novalia"],"description":"The trading name the organization is known by, where that differs from the legal name."},"contactEmail":{"type":"string","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\\.)+[A-Za-z]{2,}$","maxLength":255,"examples":["treasury@novalia.example"],"description":"An address that reaches the organization; a channel into the company, not any one person's own."},"registrationNumber":{"type":"string","examples":["HRB 123456"],"description":"The organization's number in the public register it is incorporated in."},"dateOfIncorporation":{"type":"string","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","examples":["2014-09-01"],"description":"The date the organization was constituted."},"legalStructure":{"type":"string","enum":["PUBLIC_LISTED_COMPANY","PRIVATE_LIMITED","SOLE_TRADER","NON_PROFIT","GENERAL_PARTNERSHIP","LIMITED_PARTNERSHIP"],"examples":["PRIVATE_LIMITED"],"description":"The form an organization is constituted in."},"taxInformation":{"type":"array","items":{"type":"object","properties":{"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose authority issued the identifier."},"taxIdNumber":{"type":"string","examples":["ABCDE1234F"],"description":"The identifier itself, as the issuing authority writes it, punctuation included."}},"required":["issuingCountry","taxIdNumber"],"additionalProperties":false},"description":"The tax identifiers this organization holds, one entry per issuing country. A VAT number is one."},"registeredAddress":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"The registered office: the address on file in the register the organization is incorporated in."},"principalPlaceOfBusiness":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"Where the organization operates from, where that differs from the registered office."},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["REGISTRATION_DOCUMENT","CONSTITUTIONAL_DOCUMENT","PROOF_OF_OWNERSHIP","PROOF_OF_ADDRESS","PROOF_OF_TAX_INFORMATION"],"examples":["REGISTRATION_DOCUMENT"],"description":"The kind of document an organization holds."},"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country the document was issued in."},"number":{"type":"string","examples":["Z1234567"],"description":"The number printed on the document. Input-only: never returned on reads."}},"required":["type","issuingCountry","number"],"additionalProperties":false}}},"required":["legalName"],"additionalProperties":false},"ownershipPercent":{"type":"number","minimum":0,"maximum":100,"examples":[40],"description":"The share of the organization this identity holds, as a percentage."}},"required":["identityType","role","organization"],"additionalProperties":false}]},"description":"The people and companies that own or control this organization, one entry each."}},"required":["legalName"],"additionalProperties":false}},"required":["identityType","organization"],"additionalProperties":false}],"description":"Who the account is."},"label":{"type":"string","examples":["Novalia"],"description":"Freeform label to help you identify the account. For a structured reference back to your own system, use `metadata`."},"metadata":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":40},"additionalProperties":{"type":"string","maxLength":500},"description":"Optional client-owned metadata bag (string keys → string values). Echoed back verbatim on a successful response. Limits: at most 50 keys, keys up to 40 characters, values up to 500 characters, and at most 8192 bytes when serialized.","examples":[{"requestId":"client-generated-correlation-id"}]}},"required":["identity"],"additionalProperties":false}}}}},"get":{"responses":{"200":{"description":"A page of accounts.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"account","examples":["account"],"description":"The type of object represented, a fixed discriminator. Always `\"account\"` for this resource."},"id":{"type":"string","pattern":"^acc_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"acc_h82pJGF9p7kpzb6eU326EF","description":"Account identifier."},"status":{"type":"string","enum":["PENDING","ACTIVE","REJECTED","REQUIRES_INFORMATION"],"examples":["ACTIVE"],"description":"The account's standing with OpenFX as a whole. Not a rollup of `capabilities` — each capability carries its own status. `ACTIVE` is the only status in which a payout can name the account."},"archivedAt":{"type":["string","null"],"format":"date-time","examples":["2026-07-01T09:00:00.000Z"],"description":"When the client retired this account, or null while it is live. Terminal once set."},"createdAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"Creation timestamp."},"updatedAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"Update timestamp."},"capabilities":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"accountCapability","examples":["accountCapability"],"description":"The type of object represented, a fixed discriminator. Always `\"accountCapability\"` for this resource."},"id":{"type":"string","pattern":"^cap_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"cap_Ce3AJmAmDGcJgTmTqgFVZ","description":"The catalog capability this account holds."},"status":{"type":"string","enum":["PENDING","ACTIVE","REJECTED","REQUIRES_INFORMATION"],"examples":["ACTIVE"],"description":"Whether this capability can currently back its activity on a payout. Born `PENDING`; settles by webhook, usually within a minute."},"hasActiveAddresses":{"type":["boolean","null"],"description":"Indicates whether the capability serves any payout addresses"},"details":{"type":"object","properties":{"grants":{"type":"array","items":{"type":"string"},"minItems":1,"examples":[["RECEIVE_PAYOUTS"]],"description":"What this capability lets the holding account do, at least one grant (e.g. `RECEIVE_PAYOUTS`, `SEND_PAYOUTS_TO_THIRD_PARTIES`). Append-only: tolerate a member you do not recognize."},"currencies":{"type":"array","items":{"type":"string","pattern":"^[A-Z0-9]{2,15}$"},"minItems":1,"examples":[["EUR"]],"description":"The currencies this capability covers. Absent where the coverage is currency-independent."},"repatriability":{"type":"array","items":{"type":"string"},"minItems":1,"examples":[["REPATRIABLE"]],"description":"The repatriability categories this capability covers (`REPATRIABLE` / `NON_REPATRIABLE`). Absent where the axis does not apply."}},"required":["grants"],"additionalProperties":false}},"required":["object","id","status","hasActiveAddresses","details"],"additionalProperties":false},"description":"The capabilities this account holds, one entry per capability it has been set up for. Grows via POST /v3/common/accounts/{accountId}/capabilities."},"identity":{"oneOf":[{"type":"object","properties":{"identityType":{"type":"string","const":"INDIVIDUAL"},"individual":{"type":"object","properties":{"firstName":{"type":"string","examples":["Nadia"],"description":"Given names, in the order the person writes them."},"lastName":{"type":"string","examples":["Mehta"],"description":"Family name. A person who goes by a single name puts the whole of it here."},"dateOfBirth":{"type":"string","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","examples":["1990-03-14"],"description":"The person's date of birth."},"nationality":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose nationality the person holds. Single-valued."},"email":{"type":"string","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\\.)+[A-Za-z]{2,}$","maxLength":255,"examples":["nadia.mehta@novalia.example"],"description":"The person's own email address."},"phoneNumber":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$","examples":["+919876543210"],"description":"The person's own phone number."},"residentialAddress":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"Where the person lives."},"taxInformation":{"type":"array","items":{"type":"object","properties":{"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose authority issued the identifier."},"taxIdNumber":{"type":"string","examples":["ABCDE1234F"],"description":"The identifier itself, as the issuing authority writes it, punctuation included."}},"required":["issuingCountry","taxIdNumber"],"additionalProperties":false},"description":"The tax identifiers this person holds, one entry per issuing country. An Indian PAN belongs here."},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["PASSPORT","NATIONAL_ID","DRIVERS_LICENSE","SSN","RESIDENCE_PERMIT"],"examples":["PASSPORT"],"description":"The kind of document a person holds."},"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country the document was issued in."}},"required":["type","issuingCountry"],"additionalProperties":false}}},"required":["lastName"],"additionalProperties":false}},"required":["identityType","individual"],"additionalProperties":false},{"type":"object","properties":{"identityType":{"type":"string","const":"ORGANIZATION"},"organization":{"type":"object","properties":{"legalName":{"type":"string","examples":["Novalia Handels GmbH"],"description":"The organization's name exactly as the register it is incorporated in records it, suffix included."},"doingBusinessAs":{"type":"string","examples":["Novalia"],"description":"The trading name the organization is known by, where that differs from the legal name."},"contactEmail":{"type":"string","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\\.)+[A-Za-z]{2,}$","maxLength":255,"examples":["treasury@novalia.example"],"description":"An address that reaches the organization; a channel into the company, not any one person's own."},"registrationNumber":{"type":"string","examples":["HRB 123456"],"description":"The organization's number in the public register it is incorporated in."},"dateOfIncorporation":{"type":"string","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","examples":["2014-09-01"],"description":"The date the organization was constituted."},"legalStructure":{"type":"string","enum":["PUBLIC_LISTED_COMPANY","PRIVATE_LIMITED","SOLE_TRADER","NON_PROFIT","GENERAL_PARTNERSHIP","LIMITED_PARTNERSHIP"],"examples":["PRIVATE_LIMITED"],"description":"The form an organization is constituted in."},"taxInformation":{"type":"array","items":{"type":"object","properties":{"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose authority issued the identifier."},"taxIdNumber":{"type":"string","examples":["ABCDE1234F"],"description":"The identifier itself, as the issuing authority writes it, punctuation included."}},"required":["issuingCountry","taxIdNumber"],"additionalProperties":false},"description":"The tax identifiers this organization holds, one entry per issuing country. A VAT number is one."},"registeredAddress":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"The registered office: the address on file in the register the organization is incorporated in."},"principalPlaceOfBusiness":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"Where the organization operates from, where that differs from the registered office."},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["REGISTRATION_DOCUMENT","CONSTITUTIONAL_DOCUMENT","PROOF_OF_OWNERSHIP","PROOF_OF_ADDRESS","PROOF_OF_TAX_INFORMATION"],"examples":["REGISTRATION_DOCUMENT"],"description":"The kind of document an organization holds."},"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country the document was issued in."}},"required":["type","issuingCountry"],"additionalProperties":false}},"associations":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"identityType":{"type":"string","const":"INDIVIDUAL"},"role":{"type":"string","enum":["UBO_THROUGH_OWNERSHIP","UBO_THROUGH_CONTROL","DIRECTOR","SIGNATORY","AUTHORIZED_REPRESENTATIVE"],"examples":["UBO_THROUGH_OWNERSHIP"],"description":"How a natural person is associated with an organization."},"individual":{"type":"object","properties":{"firstName":{"type":"string","examples":["Nadia"],"description":"Given names, in the order the person writes them."},"lastName":{"type":"string","examples":["Mehta"],"description":"Family name. A person who goes by a single name puts the whole of it here."},"dateOfBirth":{"type":"string","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","examples":["1990-03-14"],"description":"The person's date of birth."},"nationality":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose nationality the person holds. Single-valued."},"email":{"type":"string","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\\.)+[A-Za-z]{2,}$","maxLength":255,"examples":["nadia.mehta@novalia.example"],"description":"The person's own email address."},"phoneNumber":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$","examples":["+919876543210"],"description":"The person's own phone number."},"residentialAddress":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"Where the person lives."},"taxInformation":{"type":"array","items":{"type":"object","properties":{"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose authority issued the identifier."},"taxIdNumber":{"type":"string","examples":["ABCDE1234F"],"description":"The identifier itself, as the issuing authority writes it, punctuation included."}},"required":["issuingCountry","taxIdNumber"],"additionalProperties":false},"description":"The tax identifiers this person holds, one entry per issuing country. An Indian PAN belongs here."},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["PASSPORT","NATIONAL_ID","DRIVERS_LICENSE","SSN","RESIDENCE_PERMIT"],"examples":["PASSPORT"],"description":"The kind of document a person holds."},"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country the document was issued in."}},"required":["type","issuingCountry"],"additionalProperties":false}}},"required":["lastName"],"additionalProperties":false},"ownershipPercent":{"type":"number","minimum":0,"maximum":100,"examples":[40],"description":"The share of the organization this identity holds, as a percentage."}},"required":["identityType","role","individual"],"additionalProperties":false},{"type":"object","properties":{"identityType":{"type":"string","const":"ORGANIZATION"},"role":{"type":"string","enum":["ULTIMATE_PARENT_COMPANY"],"examples":["ULTIMATE_PARENT_COMPANY"],"description":"How an organization is associated with another organization."},"organization":{"type":"object","properties":{"legalName":{"type":"string","examples":["Novalia Handels GmbH"],"description":"The organization's name exactly as the register it is incorporated in records it, suffix included."},"doingBusinessAs":{"type":"string","examples":["Novalia"],"description":"The trading name the organization is known by, where that differs from the legal name."},"contactEmail":{"type":"string","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\\.)+[A-Za-z]{2,}$","maxLength":255,"examples":["treasury@novalia.example"],"description":"An address that reaches the organization; a channel into the company, not any one person's own."},"registrationNumber":{"type":"string","examples":["HRB 123456"],"description":"The organization's number in the public register it is incorporated in."},"dateOfIncorporation":{"type":"string","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","examples":["2014-09-01"],"description":"The date the organization was constituted."},"legalStructure":{"type":"string","enum":["PUBLIC_LISTED_COMPANY","PRIVATE_LIMITED","SOLE_TRADER","NON_PROFIT","GENERAL_PARTNERSHIP","LIMITED_PARTNERSHIP"],"examples":["PRIVATE_LIMITED"],"description":"The form an organization is constituted in."},"taxInformation":{"type":"array","items":{"type":"object","properties":{"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose authority issued the identifier."},"taxIdNumber":{"type":"string","examples":["ABCDE1234F"],"description":"The identifier itself, as the issuing authority writes it, punctuation included."}},"required":["issuingCountry","taxIdNumber"],"additionalProperties":false},"description":"The tax identifiers this organization holds, one entry per issuing country. A VAT number is one."},"registeredAddress":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"The registered office: the address on file in the register the organization is incorporated in."},"principalPlaceOfBusiness":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"Where the organization operates from, where that differs from the registered office."},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["REGISTRATION_DOCUMENT","CONSTITUTIONAL_DOCUMENT","PROOF_OF_OWNERSHIP","PROOF_OF_ADDRESS","PROOF_OF_TAX_INFORMATION"],"examples":["REGISTRATION_DOCUMENT"],"description":"The kind of document an organization holds."},"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country the document was issued in."}},"required":["type","issuingCountry"],"additionalProperties":false}}},"required":["legalName"],"additionalProperties":false},"ownershipPercent":{"type":"number","minimum":0,"maximum":100,"examples":[40],"description":"The share of the organization this identity holds, as a percentage."}},"required":["identityType","role","organization"],"additionalProperties":false}]}}},"required":["legalName"],"additionalProperties":false}},"required":["identityType","organization"],"additionalProperties":false}],"description":"Who the account is."},"label":{"type":"string","examples":["Novalia"],"description":"Freeform label to help you identify the account."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own key/value pairs, echoed back verbatim."}},"required":["object","id","status","archivedAt","createdAt","updatedAt","capabilities","identity"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"limit":{"type":"number","examples":[25],"description":"Page size used for this request."},"hasNext":{"type":"boolean","examples":[true],"description":"Whether more results exist after this page."},"nextCursor":{"type":["string","null"],"description":"Cursor pointing to the last item on this page. Pass as `startingAfter` to fetch the next page."},"hasPrev":{"type":"boolean","examples":[false],"description":"Whether results exist before this page."},"prevCursor":{"type":["string","null"],"description":"Cursor pointing to the first item on this page. Pass as `endingBefore` to fetch the previous page."}},"required":["limit","hasNext","nextCursor","hasPrev","prevCursor"]}},"required":["data","pagination"]},"examples":{"default_example":{"summary":"Single-row page","value":{"data":[{"object":"account","id":"acc_h82pJGF9p7kpzb6eU326EF","status":"ACTIVE","capabilities":[{"object":"accountCapability","id":"cap_Ce3AJmAmDGcJgTmTqgFVZ","status":"PENDING","hasActiveAddresses":false,"details":{"grants":["RECEIVE_PAYOUTS"],"currencies":["EUR"]}}],"identity":{"identityType":"ORGANIZATION","organization":{"legalName":"Novalia Handels GmbH","registeredAddress":{"country":"DE"}}},"archivedAt":null,"createdAt":"2026-06-04T10:30:00.000Z","updatedAt":"2026-06-04T10:30:00.000Z"}],"pagination":{"limit":25,"hasNext":false,"nextCursor":null,"hasPrev":false,"prevCursor":null}}}}}}},"400":{"description":"The request failed validation, or the gateway context was missing.","content":{"application/json":{"examples":{"validation_query_failed":{"summary":"Query parameters failed validation.","value":{"error":{"code":"VALIDATION_QUERY_FAILED","type":"VALIDATION_ERROR","message":"Query parameters failed validation.","retryStrategy":"FIX_AND_RESUBMIT","details":{"issues":[{"path":"/receiveCurrency","code":"invalid_type","message":"Required","expected":"string","received":"undefined"}],"firstIssuePath":"/receiveCurrency"}}}},"missing_request_context":{"summary":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","value":{"error":{"code":"MISSING_REQUEST_CONTEXT","type":"VALIDATION_ERROR","message":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"invalid_organization":{"summary":"The organization identifier on the request is malformed. Send the request through the documented gateway.","value":{"error":{"code":"INVALID_ORGANIZATION","type":"VALIDATION_ERROR","message":"The organization identifier on the request is malformed. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"The request is not authenticated.","content":{"application/json":{"examples":{"auth_token_missing":{"summary":"The Authorization header is missing. Provide a Bearer JWT.","value":{"error":{"code":"AUTH_TOKEN_MISSING","type":"AUTHENTICATION_ERROR","message":"The Authorization header is missing. Provide a Bearer JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid":{"summary":"Authorization token is invalid. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_expired":{"summary":"Authorization token has expired. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_EXPIRED","type":"AUTHENTICATION_ERROR","message":"Authorization token has expired. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid_config":{"summary":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","value":{"error":{"code":"AUTH_TOKEN_INVALID_CONFIG","type":"AUTHENTICATION_ERROR","message":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","retryStrategy":"TERMINAL","details":{}}}},"auth_api_key_invalid":{"summary":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","value":{"error":{"code":"AUTH_API_KEY_INVALID","type":"AUTHENTICATION_ERROR","message":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"The API key may not perform this operation.","content":{"application/json":{"examples":{"auth_insufficient_scope":{"summary":"The API key is missing the scope required for this operation.","value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"429":{"description":"The API key has exceeded its request rate limit.","content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"This API key has exceeded its request rate limit for the current window.","value":{"error":{"code":"RATE_LIMIT_EXCEEDED","type":"RATE_LIMITED","message":"This API key has exceeded its request rate limit for the current window.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}},"500":{"description":"An unexpected internal error occurred.","content":{"application/json":{"examples":{"internal_error":{"summary":"An unexpected internal error occurred. Contact support with the trace ID.","value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"listAccounts","summary":"List accounts","tags":["Accounts"],"description":"Cursor-paginated list of accounts, newest-first by `createdAt`. Archived accounts are hidden by default; pass `archived=true` to include them. The query parameters here are the only server-side filters.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size. Default 25, max 100."},{"name":"startingAfter","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor for the next (older) page. Mutually exclusive with `endingBefore`."},{"name":"endingBefore","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor for the previous (newer) page. Mutually exclusive with `startingAfter`."},{"name":"archived","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]},"description":"Whether to include archived accounts. Defaults to false."}]}},"/common/accounts/{accountId}":{"get":{"responses":{"200":{"description":"The requested account.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","const":"account","examples":["account"],"description":"The type of object represented, a fixed discriminator. Always `\"account\"` for this resource."},"id":{"type":"string","pattern":"^acc_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"acc_h82pJGF9p7kpzb6eU326EF","description":"Account identifier."},"status":{"type":"string","enum":["PENDING","ACTIVE","REJECTED","REQUIRES_INFORMATION"],"examples":["ACTIVE"],"description":"The account's standing with OpenFX as a whole. Not a rollup of `capabilities` — each capability carries its own status. `ACTIVE` is the only status in which a payout can name the account."},"archivedAt":{"type":["string","null"],"format":"date-time","examples":["2026-07-01T09:00:00.000Z"],"description":"When the client retired this account, or null while it is live. Terminal once set."},"createdAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"Creation timestamp."},"updatedAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"Update timestamp."},"capabilities":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"accountCapability","examples":["accountCapability"],"description":"The type of object represented, a fixed discriminator. Always `\"accountCapability\"` for this resource."},"id":{"type":"string","pattern":"^cap_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"cap_Ce3AJmAmDGcJgTmTqgFVZ","description":"The catalog capability this account holds."},"status":{"type":"string","enum":["PENDING","ACTIVE","REJECTED","REQUIRES_INFORMATION"],"examples":["ACTIVE"],"description":"Whether this capability can currently back its activity on a payout. Born `PENDING`; settles by webhook, usually within a minute."},"hasActiveAddresses":{"type":["boolean","null"],"description":"Indicates whether the capability serves any payout addresses"},"details":{"type":"object","properties":{"grants":{"type":"array","items":{"type":"string"},"minItems":1,"examples":[["RECEIVE_PAYOUTS"]],"description":"What this capability lets the holding account do, at least one grant (e.g. `RECEIVE_PAYOUTS`, `SEND_PAYOUTS_TO_THIRD_PARTIES`). Append-only: tolerate a member you do not recognize."},"currencies":{"type":"array","items":{"type":"string","pattern":"^[A-Z0-9]{2,15}$"},"minItems":1,"examples":[["EUR"]],"description":"The currencies this capability covers. Absent where the coverage is currency-independent."},"repatriability":{"type":"array","items":{"type":"string"},"minItems":1,"examples":[["REPATRIABLE"]],"description":"The repatriability categories this capability covers (`REPATRIABLE` / `NON_REPATRIABLE`). Absent where the axis does not apply."}},"required":["grants"],"additionalProperties":false}},"required":["object","id","status","hasActiveAddresses","details"],"additionalProperties":false},"description":"The capabilities this account holds, one entry per capability it has been set up for. Grows via POST /v3/common/accounts/{accountId}/capabilities."},"identity":{"oneOf":[{"type":"object","properties":{"identityType":{"type":"string","const":"INDIVIDUAL"},"individual":{"type":"object","properties":{"firstName":{"type":"string","examples":["Nadia"],"description":"Given names, in the order the person writes them."},"lastName":{"type":"string","examples":["Mehta"],"description":"Family name. A person who goes by a single name puts the whole of it here."},"dateOfBirth":{"type":"string","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","examples":["1990-03-14"],"description":"The person's date of birth."},"nationality":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose nationality the person holds. Single-valued."},"email":{"type":"string","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\\.)+[A-Za-z]{2,}$","maxLength":255,"examples":["nadia.mehta@novalia.example"],"description":"The person's own email address."},"phoneNumber":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$","examples":["+919876543210"],"description":"The person's own phone number."},"residentialAddress":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"Where the person lives."},"taxInformation":{"type":"array","items":{"type":"object","properties":{"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose authority issued the identifier."},"taxIdNumber":{"type":"string","examples":["ABCDE1234F"],"description":"The identifier itself, as the issuing authority writes it, punctuation included."}},"required":["issuingCountry","taxIdNumber"],"additionalProperties":false},"description":"The tax identifiers this person holds, one entry per issuing country. An Indian PAN belongs here."},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["PASSPORT","NATIONAL_ID","DRIVERS_LICENSE","SSN","RESIDENCE_PERMIT"],"examples":["PASSPORT"],"description":"The kind of document a person holds."},"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country the document was issued in."}},"required":["type","issuingCountry"],"additionalProperties":false}}},"required":["lastName"],"additionalProperties":false}},"required":["identityType","individual"],"additionalProperties":false},{"type":"object","properties":{"identityType":{"type":"string","const":"ORGANIZATION"},"organization":{"type":"object","properties":{"legalName":{"type":"string","examples":["Novalia Handels GmbH"],"description":"The organization's name exactly as the register it is incorporated in records it, suffix included."},"doingBusinessAs":{"type":"string","examples":["Novalia"],"description":"The trading name the organization is known by, where that differs from the legal name."},"contactEmail":{"type":"string","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\\.)+[A-Za-z]{2,}$","maxLength":255,"examples":["treasury@novalia.example"],"description":"An address that reaches the organization; a channel into the company, not any one person's own."},"registrationNumber":{"type":"string","examples":["HRB 123456"],"description":"The organization's number in the public register it is incorporated in."},"dateOfIncorporation":{"type":"string","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","examples":["2014-09-01"],"description":"The date the organization was constituted."},"legalStructure":{"type":"string","enum":["PUBLIC_LISTED_COMPANY","PRIVATE_LIMITED","SOLE_TRADER","NON_PROFIT","GENERAL_PARTNERSHIP","LIMITED_PARTNERSHIP"],"examples":["PRIVATE_LIMITED"],"description":"The form an organization is constituted in."},"taxInformation":{"type":"array","items":{"type":"object","properties":{"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose authority issued the identifier."},"taxIdNumber":{"type":"string","examples":["ABCDE1234F"],"description":"The identifier itself, as the issuing authority writes it, punctuation included."}},"required":["issuingCountry","taxIdNumber"],"additionalProperties":false},"description":"The tax identifiers this organization holds, one entry per issuing country. A VAT number is one."},"registeredAddress":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"The registered office: the address on file in the register the organization is incorporated in."},"principalPlaceOfBusiness":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"Where the organization operates from, where that differs from the registered office."},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["REGISTRATION_DOCUMENT","CONSTITUTIONAL_DOCUMENT","PROOF_OF_OWNERSHIP","PROOF_OF_ADDRESS","PROOF_OF_TAX_INFORMATION"],"examples":["REGISTRATION_DOCUMENT"],"description":"The kind of document an organization holds."},"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country the document was issued in."}},"required":["type","issuingCountry"],"additionalProperties":false}},"associations":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"identityType":{"type":"string","const":"INDIVIDUAL"},"role":{"type":"string","enum":["UBO_THROUGH_OWNERSHIP","UBO_THROUGH_CONTROL","DIRECTOR","SIGNATORY","AUTHORIZED_REPRESENTATIVE"],"examples":["UBO_THROUGH_OWNERSHIP"],"description":"How a natural person is associated with an organization."},"individual":{"type":"object","properties":{"firstName":{"type":"string","examples":["Nadia"],"description":"Given names, in the order the person writes them."},"lastName":{"type":"string","examples":["Mehta"],"description":"Family name. A person who goes by a single name puts the whole of it here."},"dateOfBirth":{"type":"string","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","examples":["1990-03-14"],"description":"The person's date of birth."},"nationality":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose nationality the person holds. Single-valued."},"email":{"type":"string","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\\.)+[A-Za-z]{2,}$","maxLength":255,"examples":["nadia.mehta@novalia.example"],"description":"The person's own email address."},"phoneNumber":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$","examples":["+919876543210"],"description":"The person's own phone number."},"residentialAddress":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"Where the person lives."},"taxInformation":{"type":"array","items":{"type":"object","properties":{"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose authority issued the identifier."},"taxIdNumber":{"type":"string","examples":["ABCDE1234F"],"description":"The identifier itself, as the issuing authority writes it, punctuation included."}},"required":["issuingCountry","taxIdNumber"],"additionalProperties":false},"description":"The tax identifiers this person holds, one entry per issuing country. An Indian PAN belongs here."},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["PASSPORT","NATIONAL_ID","DRIVERS_LICENSE","SSN","RESIDENCE_PERMIT"],"examples":["PASSPORT"],"description":"The kind of document a person holds."},"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country the document was issued in."}},"required":["type","issuingCountry"],"additionalProperties":false}}},"required":["lastName"],"additionalProperties":false},"ownershipPercent":{"type":"number","minimum":0,"maximum":100,"examples":[40],"description":"The share of the organization this identity holds, as a percentage."}},"required":["identityType","role","individual"],"additionalProperties":false},{"type":"object","properties":{"identityType":{"type":"string","const":"ORGANIZATION"},"role":{"type":"string","enum":["ULTIMATE_PARENT_COMPANY"],"examples":["ULTIMATE_PARENT_COMPANY"],"description":"How an organization is associated with another organization."},"organization":{"type":"object","properties":{"legalName":{"type":"string","examples":["Novalia Handels GmbH"],"description":"The organization's name exactly as the register it is incorporated in records it, suffix included."},"doingBusinessAs":{"type":"string","examples":["Novalia"],"description":"The trading name the organization is known by, where that differs from the legal name."},"contactEmail":{"type":"string","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\\.)+[A-Za-z]{2,}$","maxLength":255,"examples":["treasury@novalia.example"],"description":"An address that reaches the organization; a channel into the company, not any one person's own."},"registrationNumber":{"type":"string","examples":["HRB 123456"],"description":"The organization's number in the public register it is incorporated in."},"dateOfIncorporation":{"type":"string","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","examples":["2014-09-01"],"description":"The date the organization was constituted."},"legalStructure":{"type":"string","enum":["PUBLIC_LISTED_COMPANY","PRIVATE_LIMITED","SOLE_TRADER","NON_PROFIT","GENERAL_PARTNERSHIP","LIMITED_PARTNERSHIP"],"examples":["PRIVATE_LIMITED"],"description":"The form an organization is constituted in."},"taxInformation":{"type":"array","items":{"type":"object","properties":{"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose authority issued the identifier."},"taxIdNumber":{"type":"string","examples":["ABCDE1234F"],"description":"The identifier itself, as the issuing authority writes it, punctuation included."}},"required":["issuingCountry","taxIdNumber"],"additionalProperties":false},"description":"The tax identifiers this organization holds, one entry per issuing country. A VAT number is one."},"registeredAddress":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"The registered office: the address on file in the register the organization is incorporated in."},"principalPlaceOfBusiness":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"Where the organization operates from, where that differs from the registered office."},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["REGISTRATION_DOCUMENT","CONSTITUTIONAL_DOCUMENT","PROOF_OF_OWNERSHIP","PROOF_OF_ADDRESS","PROOF_OF_TAX_INFORMATION"],"examples":["REGISTRATION_DOCUMENT"],"description":"The kind of document an organization holds."},"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country the document was issued in."}},"required":["type","issuingCountry"],"additionalProperties":false}}},"required":["legalName"],"additionalProperties":false},"ownershipPercent":{"type":"number","minimum":0,"maximum":100,"examples":[40],"description":"The share of the organization this identity holds, as a percentage."}},"required":["identityType","role","organization"],"additionalProperties":false}]}}},"required":["legalName"],"additionalProperties":false}},"required":["identityType","organization"],"additionalProperties":false}],"description":"Who the account is."},"label":{"type":"string","examples":["Novalia"],"description":"Freeform label to help you identify the account."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own key/value pairs, echoed back verbatim."}},"required":["object","id","status","archivedAt","createdAt","updatedAt","capabilities","identity"],"additionalProperties":false}},"required":["data"]},"examples":{"default_example":{"summary":"Organization account","value":{"data":{"object":"account","id":"acc_h82pJGF9p7kpzb6eU326EF","status":"ACTIVE","capabilities":[{"object":"accountCapability","id":"cap_Ce3AJmAmDGcJgTmTqgFVZ","status":"PENDING","hasActiveAddresses":false,"details":{"grants":["RECEIVE_PAYOUTS"],"currencies":["EUR"]}}],"identity":{"identityType":"ORGANIZATION","organization":{"legalName":"Novalia Handels GmbH","registeredAddress":{"country":"DE"}}},"archivedAt":null,"createdAt":"2026-06-04T10:30:00.000Z","updatedAt":"2026-06-04T10:30:00.000Z"}}}}}}},"400":{"description":"The request failed validation, or the gateway context was missing.","content":{"application/json":{"examples":{"validation_path_failed":{"summary":"URL path parameters failed validation.","value":{"error":{"code":"VALIDATION_PATH_FAILED","type":"VALIDATION_ERROR","message":"URL path parameters failed validation.","retryStrategy":"FIX_AND_RESUBMIT","details":{"issues":[{"path":"/payoutId","code":"invalid_string","message":"is not a well-formed payout id"}],"firstIssuePath":"/payoutId"}}}},"missing_request_context":{"summary":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","value":{"error":{"code":"MISSING_REQUEST_CONTEXT","type":"VALIDATION_ERROR","message":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"invalid_organization":{"summary":"The organization identifier on the request is malformed. Send the request through the documented gateway.","value":{"error":{"code":"INVALID_ORGANIZATION","type":"VALIDATION_ERROR","message":"The organization identifier on the request is malformed. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"The request is not authenticated.","content":{"application/json":{"examples":{"auth_token_missing":{"summary":"The Authorization header is missing. Provide a Bearer JWT.","value":{"error":{"code":"AUTH_TOKEN_MISSING","type":"AUTHENTICATION_ERROR","message":"The Authorization header is missing. Provide a Bearer JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid":{"summary":"Authorization token is invalid. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_expired":{"summary":"Authorization token has expired. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_EXPIRED","type":"AUTHENTICATION_ERROR","message":"Authorization token has expired. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid_config":{"summary":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","value":{"error":{"code":"AUTH_TOKEN_INVALID_CONFIG","type":"AUTHENTICATION_ERROR","message":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","retryStrategy":"TERMINAL","details":{}}}},"auth_api_key_invalid":{"summary":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","value":{"error":{"code":"AUTH_API_KEY_INVALID","type":"AUTHENTICATION_ERROR","message":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"The API key may not perform this operation.","content":{"application/json":{"examples":{"auth_insufficient_scope":{"summary":"The API key is missing the scope required for this operation.","value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"404":{"description":"The requested resource does not exist in this org.","content":{"application/json":{"examples":{"account_not_found":{"summary":"No account with that id in this org.","value":{"error":{"code":"ACCOUNT_NOT_FOUND","type":"NOT_FOUND","message":"No account with that id in this org.","retryStrategy":"TERMINAL","details":{}}}}}}}},"429":{"description":"The API key has exceeded its request rate limit.","content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"This API key has exceeded its request rate limit for the current window.","value":{"error":{"code":"RATE_LIMIT_EXCEEDED","type":"RATE_LIMITED","message":"This API key has exceeded its request rate limit for the current window.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}},"500":{"description":"An unexpected internal error occurred.","content":{"application/json":{"examples":{"internal_error":{"summary":"An unexpected internal error occurred. Contact support with the trace ID.","value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"getAccount","summary":"Get an account by id","tags":["Accounts"],"description":"Retrieve a single account. Payout addresses are not embedded: fetch an account's destinations with GET /v3/payments/payout-addresses?accountId=, which is cursor-paginated and returns the full PayoutAddress shape.","parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string","examples":["acc_h82pJGF9p7kpzb6eU326EF"]},"description":"Account id (`acc_`)."}]}},"/common/accounts/{accountId}/archive":{"post":{"responses":{"200":{"description":"The archived account (`archivedAt` set).","headers":{"Idempotency-Replayed":{"description":"`true` when the response was served from the idempotency cache; `false` for a freshly executed request.","schema":{"type":"string","enum":["true","false"]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","const":"account","examples":["account"],"description":"The type of object represented, a fixed discriminator. Always `\"account\"` for this resource."},"id":{"type":"string","pattern":"^acc_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"acc_h82pJGF9p7kpzb6eU326EF","description":"Account identifier."},"status":{"type":"string","enum":["PENDING","ACTIVE","REJECTED","REQUIRES_INFORMATION"],"examples":["ACTIVE"],"description":"The account's standing with OpenFX as a whole. Not a rollup of `capabilities` — each capability carries its own status. `ACTIVE` is the only status in which a payout can name the account."},"archivedAt":{"type":["string","null"],"format":"date-time","examples":["2026-07-01T09:00:00.000Z"],"description":"When the client retired this account, or null while it is live. Terminal once set."},"createdAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"Creation timestamp."},"updatedAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"Update timestamp."},"capabilities":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"accountCapability","examples":["accountCapability"],"description":"The type of object represented, a fixed discriminator. Always `\"accountCapability\"` for this resource."},"id":{"type":"string","pattern":"^cap_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"cap_Ce3AJmAmDGcJgTmTqgFVZ","description":"The catalog capability this account holds."},"status":{"type":"string","enum":["PENDING","ACTIVE","REJECTED","REQUIRES_INFORMATION"],"examples":["ACTIVE"],"description":"Whether this capability can currently back its activity on a payout. Born `PENDING`; settles by webhook, usually within a minute."},"hasActiveAddresses":{"type":["boolean","null"],"description":"Indicates whether the capability serves any payout addresses"},"details":{"type":"object","properties":{"grants":{"type":"array","items":{"type":"string"},"minItems":1,"examples":[["RECEIVE_PAYOUTS"]],"description":"What this capability lets the holding account do, at least one grant (e.g. `RECEIVE_PAYOUTS`, `SEND_PAYOUTS_TO_THIRD_PARTIES`). Append-only: tolerate a member you do not recognize."},"currencies":{"type":"array","items":{"type":"string","pattern":"^[A-Z0-9]{2,15}$"},"minItems":1,"examples":[["EUR"]],"description":"The currencies this capability covers. Absent where the coverage is currency-independent."},"repatriability":{"type":"array","items":{"type":"string"},"minItems":1,"examples":[["REPATRIABLE"]],"description":"The repatriability categories this capability covers (`REPATRIABLE` / `NON_REPATRIABLE`). Absent where the axis does not apply."}},"required":["grants"],"additionalProperties":false}},"required":["object","id","status","hasActiveAddresses","details"],"additionalProperties":false},"description":"The capabilities this account holds, one entry per capability it has been set up for. Grows via POST /v3/common/accounts/{accountId}/capabilities."},"identity":{"oneOf":[{"type":"object","properties":{"identityType":{"type":"string","const":"INDIVIDUAL"},"individual":{"type":"object","properties":{"firstName":{"type":"string","examples":["Nadia"],"description":"Given names, in the order the person writes them."},"lastName":{"type":"string","examples":["Mehta"],"description":"Family name. A person who goes by a single name puts the whole of it here."},"dateOfBirth":{"type":"string","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","examples":["1990-03-14"],"description":"The person's date of birth."},"nationality":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose nationality the person holds. Single-valued."},"email":{"type":"string","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\\.)+[A-Za-z]{2,}$","maxLength":255,"examples":["nadia.mehta@novalia.example"],"description":"The person's own email address."},"phoneNumber":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$","examples":["+919876543210"],"description":"The person's own phone number."},"residentialAddress":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"Where the person lives."},"taxInformation":{"type":"array","items":{"type":"object","properties":{"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose authority issued the identifier."},"taxIdNumber":{"type":"string","examples":["ABCDE1234F"],"description":"The identifier itself, as the issuing authority writes it, punctuation included."}},"required":["issuingCountry","taxIdNumber"],"additionalProperties":false},"description":"The tax identifiers this person holds, one entry per issuing country. An Indian PAN belongs here."},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["PASSPORT","NATIONAL_ID","DRIVERS_LICENSE","SSN","RESIDENCE_PERMIT"],"examples":["PASSPORT"],"description":"The kind of document a person holds."},"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country the document was issued in."}},"required":["type","issuingCountry"],"additionalProperties":false}}},"required":["lastName"],"additionalProperties":false}},"required":["identityType","individual"],"additionalProperties":false},{"type":"object","properties":{"identityType":{"type":"string","const":"ORGANIZATION"},"organization":{"type":"object","properties":{"legalName":{"type":"string","examples":["Novalia Handels GmbH"],"description":"The organization's name exactly as the register it is incorporated in records it, suffix included."},"doingBusinessAs":{"type":"string","examples":["Novalia"],"description":"The trading name the organization is known by, where that differs from the legal name."},"contactEmail":{"type":"string","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\\.)+[A-Za-z]{2,}$","maxLength":255,"examples":["treasury@novalia.example"],"description":"An address that reaches the organization; a channel into the company, not any one person's own."},"registrationNumber":{"type":"string","examples":["HRB 123456"],"description":"The organization's number in the public register it is incorporated in."},"dateOfIncorporation":{"type":"string","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","examples":["2014-09-01"],"description":"The date the organization was constituted."},"legalStructure":{"type":"string","enum":["PUBLIC_LISTED_COMPANY","PRIVATE_LIMITED","SOLE_TRADER","NON_PROFIT","GENERAL_PARTNERSHIP","LIMITED_PARTNERSHIP"],"examples":["PRIVATE_LIMITED"],"description":"The form an organization is constituted in."},"taxInformation":{"type":"array","items":{"type":"object","properties":{"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose authority issued the identifier."},"taxIdNumber":{"type":"string","examples":["ABCDE1234F"],"description":"The identifier itself, as the issuing authority writes it, punctuation included."}},"required":["issuingCountry","taxIdNumber"],"additionalProperties":false},"description":"The tax identifiers this organization holds, one entry per issuing country. A VAT number is one."},"registeredAddress":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"The registered office: the address on file in the register the organization is incorporated in."},"principalPlaceOfBusiness":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"Where the organization operates from, where that differs from the registered office."},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["REGISTRATION_DOCUMENT","CONSTITUTIONAL_DOCUMENT","PROOF_OF_OWNERSHIP","PROOF_OF_ADDRESS","PROOF_OF_TAX_INFORMATION"],"examples":["REGISTRATION_DOCUMENT"],"description":"The kind of document an organization holds."},"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country the document was issued in."}},"required":["type","issuingCountry"],"additionalProperties":false}},"associations":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"identityType":{"type":"string","const":"INDIVIDUAL"},"role":{"type":"string","enum":["UBO_THROUGH_OWNERSHIP","UBO_THROUGH_CONTROL","DIRECTOR","SIGNATORY","AUTHORIZED_REPRESENTATIVE"],"examples":["UBO_THROUGH_OWNERSHIP"],"description":"How a natural person is associated with an organization."},"individual":{"type":"object","properties":{"firstName":{"type":"string","examples":["Nadia"],"description":"Given names, in the order the person writes them."},"lastName":{"type":"string","examples":["Mehta"],"description":"Family name. A person who goes by a single name puts the whole of it here."},"dateOfBirth":{"type":"string","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","examples":["1990-03-14"],"description":"The person's date of birth."},"nationality":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose nationality the person holds. Single-valued."},"email":{"type":"string","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\\.)+[A-Za-z]{2,}$","maxLength":255,"examples":["nadia.mehta@novalia.example"],"description":"The person's own email address."},"phoneNumber":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$","examples":["+919876543210"],"description":"The person's own phone number."},"residentialAddress":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"Where the person lives."},"taxInformation":{"type":"array","items":{"type":"object","properties":{"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose authority issued the identifier."},"taxIdNumber":{"type":"string","examples":["ABCDE1234F"],"description":"The identifier itself, as the issuing authority writes it, punctuation included."}},"required":["issuingCountry","taxIdNumber"],"additionalProperties":false},"description":"The tax identifiers this person holds, one entry per issuing country. An Indian PAN belongs here."},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["PASSPORT","NATIONAL_ID","DRIVERS_LICENSE","SSN","RESIDENCE_PERMIT"],"examples":["PASSPORT"],"description":"The kind of document a person holds."},"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country the document was issued in."}},"required":["type","issuingCountry"],"additionalProperties":false}}},"required":["lastName"],"additionalProperties":false},"ownershipPercent":{"type":"number","minimum":0,"maximum":100,"examples":[40],"description":"The share of the organization this identity holds, as a percentage."}},"required":["identityType","role","individual"],"additionalProperties":false},{"type":"object","properties":{"identityType":{"type":"string","const":"ORGANIZATION"},"role":{"type":"string","enum":["ULTIMATE_PARENT_COMPANY"],"examples":["ULTIMATE_PARENT_COMPANY"],"description":"How an organization is associated with another organization."},"organization":{"type":"object","properties":{"legalName":{"type":"string","examples":["Novalia Handels GmbH"],"description":"The organization's name exactly as the register it is incorporated in records it, suffix included."},"doingBusinessAs":{"type":"string","examples":["Novalia"],"description":"The trading name the organization is known by, where that differs from the legal name."},"contactEmail":{"type":"string","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\\.)+[A-Za-z]{2,}$","maxLength":255,"examples":["treasury@novalia.example"],"description":"An address that reaches the organization; a channel into the company, not any one person's own."},"registrationNumber":{"type":"string","examples":["HRB 123456"],"description":"The organization's number in the public register it is incorporated in."},"dateOfIncorporation":{"type":"string","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","examples":["2014-09-01"],"description":"The date the organization was constituted."},"legalStructure":{"type":"string","enum":["PUBLIC_LISTED_COMPANY","PRIVATE_LIMITED","SOLE_TRADER","NON_PROFIT","GENERAL_PARTNERSHIP","LIMITED_PARTNERSHIP"],"examples":["PRIVATE_LIMITED"],"description":"The form an organization is constituted in."},"taxInformation":{"type":"array","items":{"type":"object","properties":{"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose authority issued the identifier."},"taxIdNumber":{"type":"string","examples":["ABCDE1234F"],"description":"The identifier itself, as the issuing authority writes it, punctuation included."}},"required":["issuingCountry","taxIdNumber"],"additionalProperties":false},"description":"The tax identifiers this organization holds, one entry per issuing country. A VAT number is one."},"registeredAddress":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"The registered office: the address on file in the register the organization is incorporated in."},"principalPlaceOfBusiness":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"Where the organization operates from, where that differs from the registered office."},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["REGISTRATION_DOCUMENT","CONSTITUTIONAL_DOCUMENT","PROOF_OF_OWNERSHIP","PROOF_OF_ADDRESS","PROOF_OF_TAX_INFORMATION"],"examples":["REGISTRATION_DOCUMENT"],"description":"The kind of document an organization holds."},"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country the document was issued in."}},"required":["type","issuingCountry"],"additionalProperties":false}}},"required":["legalName"],"additionalProperties":false},"ownershipPercent":{"type":"number","minimum":0,"maximum":100,"examples":[40],"description":"The share of the organization this identity holds, as a percentage."}},"required":["identityType","role","organization"],"additionalProperties":false}]}}},"required":["legalName"],"additionalProperties":false}},"required":["identityType","organization"],"additionalProperties":false}],"description":"Who the account is."},"label":{"type":"string","examples":["Novalia"],"description":"Freeform label to help you identify the account."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own key/value pairs, echoed back verbatim."}},"required":["object","id","status","archivedAt","createdAt","updatedAt","capabilities","identity"],"additionalProperties":false}},"required":["data"]},"examples":{"default_example":{"summary":"Archived account","value":{"data":{"object":"account","id":"acc_h82pJGF9p7kpzb6eU326EF","status":"ACTIVE","capabilities":[{"object":"accountCapability","id":"cap_Ce3AJmAmDGcJgTmTqgFVZ","status":"PENDING","hasActiveAddresses":false,"details":{"grants":["RECEIVE_PAYOUTS"],"currencies":["EUR"]}}],"identity":{"identityType":"ORGANIZATION","organization":{"legalName":"Novalia Handels GmbH","registeredAddress":{"country":"DE"}}},"archivedAt":"2026-07-01T09:00:00.000Z","createdAt":"2026-06-04T10:30:00.000Z","updatedAt":"2026-06-04T10:30:00.000Z"}}}}}}},"400":{"description":"The request failed validation, has an invalid Content-Type, the Idempotency-Key is malformed, or the gateway context was missing.","content":{"application/json":{"examples":{"validation_path_failed":{"summary":"URL path parameters failed validation.","value":{"error":{"code":"VALIDATION_PATH_FAILED","type":"VALIDATION_ERROR","message":"URL path parameters failed validation.","retryStrategy":"FIX_AND_RESUBMIT","details":{"issues":[{"path":"/payoutId","code":"invalid_string","message":"is not a well-formed payout id"}],"firstIssuePath":"/payoutId"}}}},"validation_content_type":{"summary":"Content-Type must be application/json.","value":{"error":{"code":"VALIDATION_CONTENT_TYPE","type":"VALIDATION_ERROR","message":"Content-Type must be application/json.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"idempotency_key_invalid":{"summary":"Idempotency-Key is malformed. Generate a new key matching the documented pattern and retry with that new key.","value":{"error":{"code":"IDEMPOTENCY_KEY_INVALID","type":"VALIDATION_ERROR","message":"Idempotency-Key is malformed. Generate a new key matching the documented pattern and retry with that new key.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"missing_request_context":{"summary":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","value":{"error":{"code":"MISSING_REQUEST_CONTEXT","type":"VALIDATION_ERROR","message":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"invalid_organization":{"summary":"The organization identifier on the request is malformed. Send the request through the documented gateway.","value":{"error":{"code":"INVALID_ORGANIZATION","type":"VALIDATION_ERROR","message":"The organization identifier on the request is malformed. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"The request is not authenticated.","content":{"application/json":{"examples":{"auth_token_missing":{"summary":"The Authorization header is missing. Provide a Bearer JWT.","value":{"error":{"code":"AUTH_TOKEN_MISSING","type":"AUTHENTICATION_ERROR","message":"The Authorization header is missing. Provide a Bearer JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid":{"summary":"Authorization token is invalid. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_expired":{"summary":"Authorization token has expired. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_EXPIRED","type":"AUTHENTICATION_ERROR","message":"Authorization token has expired. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid_config":{"summary":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","value":{"error":{"code":"AUTH_TOKEN_INVALID_CONFIG","type":"AUTHENTICATION_ERROR","message":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","retryStrategy":"TERMINAL","details":{}}}},"auth_api_key_invalid":{"summary":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","value":{"error":{"code":"AUTH_API_KEY_INVALID","type":"AUTHENTICATION_ERROR","message":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"The API key may not perform this operation.","content":{"application/json":{"examples":{"auth_insufficient_scope":{"summary":"The API key is missing the scope required for this operation.","value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"404":{"description":"A referenced resource does not exist in this org.","content":{"application/json":{"examples":{"account_not_found":{"summary":"No account with that id in this org.","value":{"error":{"code":"ACCOUNT_NOT_FOUND","type":"NOT_FOUND","message":"No account with that id in this org.","retryStrategy":"TERMINAL","details":{}}}}}}}},"409":{"description":"The request conflicts with current state, or with an in-flight request using the same key.","content":{"application/json":{"examples":{"idempotency_in_flight":{"summary":"Another request with this idempotency key is currently processing. Wait for some time and retry with the same key.","value":{"error":{"code":"IDEMPOTENCY_IN_FLIGHT","type":"CONFLICT","message":"Another request with this idempotency key is currently processing. Wait for some time and retry with the same key.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}},"422":{"description":"A business rule was tripped by the request's own values, or the key was replayed with a different body.","content":{"application/json":{"examples":{"idempotency_mismatch":{"summary":"This idempotency key was previously seen with a different request body. Use a new key for a new request, or resubmit the original body verbatim.","value":{"error":{"code":"IDEMPOTENCY_MISMATCH","type":"CONFLICT","message":"This idempotency key was previously seen with a different request body. Use a new key for a new request, or resubmit the original body verbatim.","retryStrategy":"FIX_AND_RESUBMIT","details":{"originalRequestHash":"sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"}}}}}}}},"428":{"description":"The Idempotency-Key header is required for this endpoint.","content":{"application/json":{"examples":{"idempotency_key_missing":{"summary":"The Idempotency-Key header is required for this endpoint.","value":{"error":{"code":"IDEMPOTENCY_KEY_MISSING","type":"VALIDATION_ERROR","message":"The Idempotency-Key header is required for this endpoint.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"429":{"description":"The API key has exceeded its request rate limit.","content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"This API key has exceeded its request rate limit for the current window.","value":{"error":{"code":"RATE_LIMIT_EXCEEDED","type":"RATE_LIMITED","message":"This API key has exceeded its request rate limit for the current window.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}},"500":{"description":"An unexpected internal error occurred.","content":{"application/json":{"examples":{"internal_error":{"summary":"An unexpected internal error occurred. Contact support with the trace ID.","value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"archiveAccount","summary":"Archive an account","tags":["Accounts"],"description":"Soft-archive an account. Idempotent, no body: sets `archivedAt` and returns the account; re-archiving an already-archived account returns 200 with the original `archivedAt` unchanged. An archived account is hidden from listAccounts by default, cannot be the target of new payouts, and cannot have new payout addresses created against it, but it is retained in full and stays retrievable by id. A payout already in flight against it keeps running to a terminal state.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255,"pattern":"^[a-zA-Z0-9_-]{1,255}$","example":"123e4567-e89b-12d3-a456-426614174000"},"description":"Unique key to ensure idempotent requests — 1-255 characters: alphanumerics, hyphens, underscores. UUID v4 recommended."},{"name":"accountId","in":"path","required":true,"schema":{"type":"string","examples":["acc_h82pJGF9p7kpzb6eU326EF"]},"description":"Account id."}]}},"/common/accounts/{accountId}/capabilities":{"post":{"responses":{"200":{"description":"The account, with the requested capabilities added.","headers":{"Idempotency-Replayed":{"description":"`true` when the response was served from the idempotency cache; `false` for a freshly executed request.","schema":{"type":"string","enum":["true","false"]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","const":"account","examples":["account"],"description":"The type of object represented, a fixed discriminator. Always `\"account\"` for this resource."},"id":{"type":"string","pattern":"^acc_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"acc_h82pJGF9p7kpzb6eU326EF","description":"Account identifier."},"status":{"type":"string","enum":["PENDING","ACTIVE","REJECTED","REQUIRES_INFORMATION"],"examples":["ACTIVE"],"description":"The account's standing with OpenFX as a whole. Not a rollup of `capabilities` — each capability carries its own status. `ACTIVE` is the only status in which a payout can name the account."},"archivedAt":{"type":["string","null"],"format":"date-time","examples":["2026-07-01T09:00:00.000Z"],"description":"When the client retired this account, or null while it is live. Terminal once set."},"createdAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"Creation timestamp."},"updatedAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"Update timestamp."},"capabilities":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"accountCapability","examples":["accountCapability"],"description":"The type of object represented, a fixed discriminator. Always `\"accountCapability\"` for this resource."},"id":{"type":"string","pattern":"^cap_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"cap_Ce3AJmAmDGcJgTmTqgFVZ","description":"The catalog capability this account holds."},"status":{"type":"string","enum":["PENDING","ACTIVE","REJECTED","REQUIRES_INFORMATION"],"examples":["ACTIVE"],"description":"Whether this capability can currently back its activity on a payout. Born `PENDING`; settles by webhook, usually within a minute."},"hasActiveAddresses":{"type":["boolean","null"],"description":"Indicates whether the capability serves any payout addresses"},"details":{"type":"object","properties":{"grants":{"type":"array","items":{"type":"string"},"minItems":1,"examples":[["RECEIVE_PAYOUTS"]],"description":"What this capability lets the holding account do, at least one grant (e.g. `RECEIVE_PAYOUTS`, `SEND_PAYOUTS_TO_THIRD_PARTIES`). Append-only: tolerate a member you do not recognize."},"currencies":{"type":"array","items":{"type":"string","pattern":"^[A-Z0-9]{2,15}$"},"minItems":1,"examples":[["EUR"]],"description":"The currencies this capability covers. Absent where the coverage is currency-independent."},"repatriability":{"type":"array","items":{"type":"string"},"minItems":1,"examples":[["REPATRIABLE"]],"description":"The repatriability categories this capability covers (`REPATRIABLE` / `NON_REPATRIABLE`). Absent where the axis does not apply."}},"required":["grants"],"additionalProperties":false}},"required":["object","id","status","hasActiveAddresses","details"],"additionalProperties":false},"description":"The capabilities this account holds, one entry per capability it has been set up for. Grows via POST /v3/common/accounts/{accountId}/capabilities."},"identity":{"oneOf":[{"type":"object","properties":{"identityType":{"type":"string","const":"INDIVIDUAL"},"individual":{"type":"object","properties":{"firstName":{"type":"string","examples":["Nadia"],"description":"Given names, in the order the person writes them."},"lastName":{"type":"string","examples":["Mehta"],"description":"Family name. A person who goes by a single name puts the whole of it here."},"dateOfBirth":{"type":"string","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","examples":["1990-03-14"],"description":"The person's date of birth."},"nationality":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose nationality the person holds. Single-valued."},"email":{"type":"string","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\\.)+[A-Za-z]{2,}$","maxLength":255,"examples":["nadia.mehta@novalia.example"],"description":"The person's own email address."},"phoneNumber":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$","examples":["+919876543210"],"description":"The person's own phone number."},"residentialAddress":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"Where the person lives."},"taxInformation":{"type":"array","items":{"type":"object","properties":{"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose authority issued the identifier."},"taxIdNumber":{"type":"string","examples":["ABCDE1234F"],"description":"The identifier itself, as the issuing authority writes it, punctuation included."}},"required":["issuingCountry","taxIdNumber"],"additionalProperties":false},"description":"The tax identifiers this person holds, one entry per issuing country. An Indian PAN belongs here."},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["PASSPORT","NATIONAL_ID","DRIVERS_LICENSE","SSN","RESIDENCE_PERMIT"],"examples":["PASSPORT"],"description":"The kind of document a person holds."},"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country the document was issued in."}},"required":["type","issuingCountry"],"additionalProperties":false}}},"required":["lastName"],"additionalProperties":false}},"required":["identityType","individual"],"additionalProperties":false},{"type":"object","properties":{"identityType":{"type":"string","const":"ORGANIZATION"},"organization":{"type":"object","properties":{"legalName":{"type":"string","examples":["Novalia Handels GmbH"],"description":"The organization's name exactly as the register it is incorporated in records it, suffix included."},"doingBusinessAs":{"type":"string","examples":["Novalia"],"description":"The trading name the organization is known by, where that differs from the legal name."},"contactEmail":{"type":"string","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\\.)+[A-Za-z]{2,}$","maxLength":255,"examples":["treasury@novalia.example"],"description":"An address that reaches the organization; a channel into the company, not any one person's own."},"registrationNumber":{"type":"string","examples":["HRB 123456"],"description":"The organization's number in the public register it is incorporated in."},"dateOfIncorporation":{"type":"string","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","examples":["2014-09-01"],"description":"The date the organization was constituted."},"legalStructure":{"type":"string","enum":["PUBLIC_LISTED_COMPANY","PRIVATE_LIMITED","SOLE_TRADER","NON_PROFIT","GENERAL_PARTNERSHIP","LIMITED_PARTNERSHIP"],"examples":["PRIVATE_LIMITED"],"description":"The form an organization is constituted in."},"taxInformation":{"type":"array","items":{"type":"object","properties":{"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose authority issued the identifier."},"taxIdNumber":{"type":"string","examples":["ABCDE1234F"],"description":"The identifier itself, as the issuing authority writes it, punctuation included."}},"required":["issuingCountry","taxIdNumber"],"additionalProperties":false},"description":"The tax identifiers this organization holds, one entry per issuing country. A VAT number is one."},"registeredAddress":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"The registered office: the address on file in the register the organization is incorporated in."},"principalPlaceOfBusiness":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"Where the organization operates from, where that differs from the registered office."},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["REGISTRATION_DOCUMENT","CONSTITUTIONAL_DOCUMENT","PROOF_OF_OWNERSHIP","PROOF_OF_ADDRESS","PROOF_OF_TAX_INFORMATION"],"examples":["REGISTRATION_DOCUMENT"],"description":"The kind of document an organization holds."},"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country the document was issued in."}},"required":["type","issuingCountry"],"additionalProperties":false}},"associations":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"identityType":{"type":"string","const":"INDIVIDUAL"},"role":{"type":"string","enum":["UBO_THROUGH_OWNERSHIP","UBO_THROUGH_CONTROL","DIRECTOR","SIGNATORY","AUTHORIZED_REPRESENTATIVE"],"examples":["UBO_THROUGH_OWNERSHIP"],"description":"How a natural person is associated with an organization."},"individual":{"type":"object","properties":{"firstName":{"type":"string","examples":["Nadia"],"description":"Given names, in the order the person writes them."},"lastName":{"type":"string","examples":["Mehta"],"description":"Family name. A person who goes by a single name puts the whole of it here."},"dateOfBirth":{"type":"string","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","examples":["1990-03-14"],"description":"The person's date of birth."},"nationality":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose nationality the person holds. Single-valued."},"email":{"type":"string","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\\.)+[A-Za-z]{2,}$","maxLength":255,"examples":["nadia.mehta@novalia.example"],"description":"The person's own email address."},"phoneNumber":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$","examples":["+919876543210"],"description":"The person's own phone number."},"residentialAddress":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"Where the person lives."},"taxInformation":{"type":"array","items":{"type":"object","properties":{"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose authority issued the identifier."},"taxIdNumber":{"type":"string","examples":["ABCDE1234F"],"description":"The identifier itself, as the issuing authority writes it, punctuation included."}},"required":["issuingCountry","taxIdNumber"],"additionalProperties":false},"description":"The tax identifiers this person holds, one entry per issuing country. An Indian PAN belongs here."},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["PASSPORT","NATIONAL_ID","DRIVERS_LICENSE","SSN","RESIDENCE_PERMIT"],"examples":["PASSPORT"],"description":"The kind of document a person holds."},"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country the document was issued in."}},"required":["type","issuingCountry"],"additionalProperties":false}}},"required":["lastName"],"additionalProperties":false},"ownershipPercent":{"type":"number","minimum":0,"maximum":100,"examples":[40],"description":"The share of the organization this identity holds, as a percentage."}},"required":["identityType","role","individual"],"additionalProperties":false},{"type":"object","properties":{"identityType":{"type":"string","const":"ORGANIZATION"},"role":{"type":"string","enum":["ULTIMATE_PARENT_COMPANY"],"examples":["ULTIMATE_PARENT_COMPANY"],"description":"How an organization is associated with another organization."},"organization":{"type":"object","properties":{"legalName":{"type":"string","examples":["Novalia Handels GmbH"],"description":"The organization's name exactly as the register it is incorporated in records it, suffix included."},"doingBusinessAs":{"type":"string","examples":["Novalia"],"description":"The trading name the organization is known by, where that differs from the legal name."},"contactEmail":{"type":"string","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\\.)+[A-Za-z]{2,}$","maxLength":255,"examples":["treasury@novalia.example"],"description":"An address that reaches the organization; a channel into the company, not any one person's own."},"registrationNumber":{"type":"string","examples":["HRB 123456"],"description":"The organization's number in the public register it is incorporated in."},"dateOfIncorporation":{"type":"string","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","examples":["2014-09-01"],"description":"The date the organization was constituted."},"legalStructure":{"type":"string","enum":["PUBLIC_LISTED_COMPANY","PRIVATE_LIMITED","SOLE_TRADER","NON_PROFIT","GENERAL_PARTNERSHIP","LIMITED_PARTNERSHIP"],"examples":["PRIVATE_LIMITED"],"description":"The form an organization is constituted in."},"taxInformation":{"type":"array","items":{"type":"object","properties":{"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose authority issued the identifier."},"taxIdNumber":{"type":"string","examples":["ABCDE1234F"],"description":"The identifier itself, as the issuing authority writes it, punctuation included."}},"required":["issuingCountry","taxIdNumber"],"additionalProperties":false},"description":"The tax identifiers this organization holds, one entry per issuing country. A VAT number is one."},"registeredAddress":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"The registered office: the address on file in the register the organization is incorporated in."},"principalPlaceOfBusiness":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."}},"required":["country"],"additionalProperties":false,"description":"Where the organization operates from, where that differs from the registered office."},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["REGISTRATION_DOCUMENT","CONSTITUTIONAL_DOCUMENT","PROOF_OF_OWNERSHIP","PROOF_OF_ADDRESS","PROOF_OF_TAX_INFORMATION"],"examples":["REGISTRATION_DOCUMENT"],"description":"The kind of document an organization holds."},"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country the document was issued in."}},"required":["type","issuingCountry"],"additionalProperties":false}}},"required":["legalName"],"additionalProperties":false},"ownershipPercent":{"type":"number","minimum":0,"maximum":100,"examples":[40],"description":"The share of the organization this identity holds, as a percentage."}},"required":["identityType","role","organization"],"additionalProperties":false}]}}},"required":["legalName"],"additionalProperties":false}},"required":["identityType","organization"],"additionalProperties":false}],"description":"Who the account is."},"label":{"type":"string","examples":["Novalia"],"description":"Freeform label to help you identify the account."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own key/value pairs, echoed back verbatim."}},"required":["object","id","status","archivedAt","createdAt","updatedAt","capabilities","identity"],"additionalProperties":false}},"required":["data"]},"examples":{"default_example":{"summary":"NRE receiving requested, new cell pending","value":{"data":{"object":"account","id":"acc_h82pJGF9p7kpzb6eU326EF","status":"ACTIVE","capabilities":[{"object":"accountCapability","id":"cap_Ce3AJmB1WMUZmkD9mMKVx","status":"ACTIVE","hasActiveAddresses":true,"details":{"grants":["RECEIVE_PAYOUTS"],"currencies":["INR"],"repatriability":["NON_REPATRIABLE"]}},{"object":"accountCapability","id":"cap_Ce3AJmB1WMUZmoAS6636h","status":"PENDING","hasActiveAddresses":false,"details":{"grants":["RECEIVE_PAYOUTS"],"currencies":["INR"],"repatriability":["REPATRIABLE"]}}],"identity":{"identityType":"INDIVIDUAL","individual":{"firstName":"Nadia","lastName":"Mehta","email":"nadia.mehta@example.in","nationality":"IN"}},"label":"Nadia Mehta","archivedAt":null,"createdAt":"2026-06-04T10:30:00.000Z","updatedAt":"2026-06-04T10:30:00.000Z"}}}}}}},"400":{"description":"The request failed validation, has an invalid Content-Type, the Idempotency-Key is malformed, or the gateway context was missing.","content":{"application/json":{"examples":{"validation_body_failed":{"summary":"Request body failed validation. See details.issues for field-level errors, or details.firstIssuePath for the most common single-field case.","value":{"error":{"code":"VALIDATION_BODY_FAILED","type":"VALIDATION_ERROR","message":"Request body failed validation. See details.issues for field-level errors, or details.firstIssuePath for the most common single-field case.","retryStrategy":"FIX_AND_RESUBMIT","details":{"issues":[{"path":"/identity/individual/lastName","code":"invalid_type","message":"Required","expected":"string","received":"undefined"},{"path":"/identity/individual/documents/0/type","code":"invalid_enum_value","message":"is not a supported document type","expected":"PASSPORT|NATIONAL_ID|DRIVERS_LICENSE|SSN|RESIDENCE_PERMIT","received":"LIBRARY_CARD"},{"path":"/identity/individual/residentialAddress/country","code":"custom","message":"is not an ISO 3166-1 alpha-2 country code (the United Kingdom is GB)","received":"UK"}],"firstIssuePath":"/identity/individual/lastName"}}}},"validation_path_failed":{"summary":"URL path parameters failed validation.","value":{"error":{"code":"VALIDATION_PATH_FAILED","type":"VALIDATION_ERROR","message":"URL path parameters failed validation.","retryStrategy":"FIX_AND_RESUBMIT","details":{"issues":[{"path":"/payoutId","code":"invalid_string","message":"is not a well-formed payout id"}],"firstIssuePath":"/payoutId"}}}},"validation_content_type":{"summary":"Content-Type must be application/json.","value":{"error":{"code":"VALIDATION_CONTENT_TYPE","type":"VALIDATION_ERROR","message":"Content-Type must be application/json.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"idempotency_key_invalid":{"summary":"Idempotency-Key is malformed. Generate a new key matching the documented pattern and retry with that new key.","value":{"error":{"code":"IDEMPOTENCY_KEY_INVALID","type":"VALIDATION_ERROR","message":"Idempotency-Key is malformed. Generate a new key matching the documented pattern and retry with that new key.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"missing_request_context":{"summary":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","value":{"error":{"code":"MISSING_REQUEST_CONTEXT","type":"VALIDATION_ERROR","message":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"invalid_organization":{"summary":"The organization identifier on the request is malformed. Send the request through the documented gateway.","value":{"error":{"code":"INVALID_ORGANIZATION","type":"VALIDATION_ERROR","message":"The organization identifier on the request is malformed. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"The request is not authenticated.","content":{"application/json":{"examples":{"auth_token_missing":{"summary":"The Authorization header is missing. Provide a Bearer JWT.","value":{"error":{"code":"AUTH_TOKEN_MISSING","type":"AUTHENTICATION_ERROR","message":"The Authorization header is missing. Provide a Bearer JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid":{"summary":"Authorization token is invalid. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_expired":{"summary":"Authorization token has expired. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_EXPIRED","type":"AUTHENTICATION_ERROR","message":"Authorization token has expired. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid_config":{"summary":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","value":{"error":{"code":"AUTH_TOKEN_INVALID_CONFIG","type":"AUTHENTICATION_ERROR","message":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","retryStrategy":"TERMINAL","details":{}}}},"auth_api_key_invalid":{"summary":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","value":{"error":{"code":"AUTH_API_KEY_INVALID","type":"AUTHENTICATION_ERROR","message":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"The API key may not perform this operation.","content":{"application/json":{"examples":{"auth_insufficient_scope":{"summary":"The API key is missing the scope required for this operation.","value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"404":{"description":"A referenced resource does not exist in this org.","content":{"application/json":{"examples":{"account_not_found":{"summary":"No account with that id in this org.","value":{"error":{"code":"ACCOUNT_NOT_FOUND","type":"NOT_FOUND","message":"No account with that id in this org.","retryStrategy":"TERMINAL","details":{}}}}}}}},"409":{"description":"The request conflicts with current state, or with an in-flight request using the same key.","content":{"application/json":{"examples":{"idempotency_in_flight":{"summary":"Another request with this idempotency key is currently processing. Wait for some time and retry with the same key.","value":{"error":{"code":"IDEMPOTENCY_IN_FLIGHT","type":"CONFLICT","message":"Another request with this idempotency key is currently processing. Wait for some time and retry with the same key.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}},"account_archived":{"summary":"The account is archived and cannot take new work.","value":{"error":{"code":"ACCOUNT_ARCHIVED","type":"CONFLICT","message":"The account is archived and cannot take new work.","retryStrategy":"TERMINAL","details":{"accountId":"acc_h82pJGF9p7kpzb6eU326EF"}}}},"identity_append_conflict":{"summary":"The identity delta would rewrite identity that is already set. Identity is append-only: an unset leaf can be filled, but a set value cannot change. details.conflicts names the offending paths.","value":{"error":{"code":"IDENTITY_APPEND_CONFLICT","type":"CONFLICT","message":"The identity delta would rewrite identity that is already set. Identity is append-only: an unset leaf can be filled, but a set value cannot change. details.conflicts names the offending paths.","retryStrategy":"FIX_AND_RESUBMIT","details":{"issues":[{"path":"/identity/individual/lastName","code":"append_conflict","message":"already set; identity is append-only"}],"firstIssuePath":"/identity/individual/lastName"}}}}}}}},"422":{"description":"A business rule was tripped by the request's own values, or the key was replayed with a different body.","content":{"application/json":{"examples":{"idempotency_mismatch":{"summary":"This idempotency key was previously seen with a different request body. Use a new key for a new request, or resubmit the original body verbatim.","value":{"error":{"code":"IDEMPOTENCY_MISMATCH","type":"CONFLICT","message":"This idempotency key was previously seen with a different request body. Use a new key for a new request, or resubmit the original body verbatim.","retryStrategy":"FIX_AND_RESUBMIT","details":{"originalRequestHash":"sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"}}}},"capability_duplicate":{"summary":"The account already holds a cell for a requested capability, or the request names the same capability twice. details.capabilities lists the duplicates.","value":{"error":{"code":"CAPABILITY_DUPLICATE","type":"VALIDATION_ERROR","message":"The account already holds a cell for a requested capability, or the request names the same capability twice. details.capabilities lists the duplicates.","retryStrategy":"FIX_AND_RESUBMIT","details":{"duplicates":["cap_Ce3AJmB1WMUZmkD9mMKVx"]}}}},"capability_not_requestable":{"summary":"A requested capability is not offered for enrollment (deprecated or otherwise closed). details.capabilities lists each offender with its reason.","value":{"error":{"code":"CAPABILITY_NOT_REQUESTABLE","type":"VALIDATION_ERROR","message":"A requested capability is not offered for enrollment (deprecated or otherwise closed). details.capabilities lists each offender with its reason.","retryStrategy":"FIX_AND_RESUBMIT","details":{"notRequestable":[{"capabilityId":"cap_2mR8kVxqPmYs2ZfMrkjcvB","reason":"DEPRECATED","supersededBy":"cap_Ce3AJmB1WMUZmkD9mMKVx"}]}}}},"identity_requirement_unmet":{"summary":"A requested capability needs more identity information than the account has supplied. details names each capability and its unmet requirements.","value":{"error":{"code":"IDENTITY_REQUIREMENT_UNMET","type":"VALIDATION_ERROR","message":"A requested capability needs more identity information than the account has supplied. details names each capability and its unmet requirements.","retryStrategy":"FIX_AND_RESUBMIT","details":{"issues":[{"path":"/identity/individual/nationality","code":"invalid_type","message":"Required","expected":"string","received":"undefined"},{"path":"/identity/individual/residentialAddress/country","code":"invalid_type","message":"Required","expected":"string","received":"undefined"}],"firstIssuePath":"/identity/individual/nationality"}}}}}}}},"428":{"description":"The Idempotency-Key header is required for this endpoint.","content":{"application/json":{"examples":{"idempotency_key_missing":{"summary":"The Idempotency-Key header is required for this endpoint.","value":{"error":{"code":"IDEMPOTENCY_KEY_MISSING","type":"VALIDATION_ERROR","message":"The Idempotency-Key header is required for this endpoint.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"429":{"description":"The API key has exceeded its request rate limit.","content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"This API key has exceeded its request rate limit for the current window.","value":{"error":{"code":"RATE_LIMIT_EXCEEDED","type":"RATE_LIMITED","message":"This API key has exceeded its request rate limit for the current window.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}},"500":{"description":"An unexpected internal error occurred.","content":{"application/json":{"examples":{"internal_error":{"summary":"An unexpected internal error occurred. Contact support with the trace ID.","value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"requestCapabilities","summary":"Request capabilities for an account","tags":["Capabilities"],"description":"Request one or more capabilities for an existing account, carrying any identity the new capabilities need in the same call. The gate is atomic and exhaustive: the whole batch and identity delta land, or nothing does, with identity checked after the delta is merged — every request-content problem reports together in a single 409 whose details.problems itemizes the batch. Identity is append-only: the delta fills unset leaves and appends to arrays; changing a value already set is rejected. On success the requested cells are added, each starting `PENDING`, and the response is the full account.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255,"pattern":"^[a-zA-Z0-9_-]{1,255}$","example":"123e4567-e89b-12d3-a456-426614174000"},"description":"Unique key to ensure idempotent requests — 1-255 characters: alphanumerics, hyphens, underscores. UUID v4 recommended."},{"name":"accountId","in":"path","required":true,"schema":{"type":"string","examples":["acc_h82pJGF9p7kpzb6eU326EF"]},"description":"Account id."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"capabilities":{"type":"array","items":{"type":"string","example":"cap_Ce3AJmAmDGcJgTmTqgFVZ","description":"A capability id from the capability catalog."},"minItems":1,"description":"Ids of the capabilities to request for this account. At least one. The whole batch lands or nothing does."},"identity":{"oneOf":[{"type":"object","properties":{"identityType":{"type":"string","const":"INDIVIDUAL"},"individual":{"type":"object","properties":{"firstName":{"type":"string","examples":["Nadia"],"description":"Given names, in the order the person writes them."},"lastName":{"type":"string","examples":["Mehta"],"description":"Family name. A person who goes by a single name puts the whole of it here."},"dateOfBirth":{"type":"string","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","examples":["1990-03-14"],"description":"The person's date of birth."},"nationality":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose nationality the person holds. Single-valued."},"email":{"type":"string","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\\.)+[A-Za-z]{2,}$","maxLength":255,"examples":["nadia.mehta@novalia.example"],"description":"The person's own email address."},"phoneNumber":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$","examples":["+919876543210"],"description":"The person's own phone number."},"residentialAddress":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$"}},"additionalProperties":false},"taxInformation":{"type":"array","items":{"type":"object","properties":{"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose authority issued the identifier."},"taxIdNumber":{"type":"string","examples":["ABCDE1234F"],"description":"The identifier itself, as the issuing authority writes it, punctuation included."}},"required":["issuingCountry","taxIdNumber"],"additionalProperties":false}},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["PASSPORT","NATIONAL_ID","DRIVERS_LICENSE","SSN","RESIDENCE_PERMIT"],"examples":["PASSPORT"],"description":"The kind of document a person holds."},"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country the document was issued in."},"number":{"type":"string","examples":["Z1234567"],"description":"The number printed on the document. Input-only: never returned on reads."}},"required":["type","issuingCountry","number"],"additionalProperties":false}}},"additionalProperties":false}},"required":["identityType","individual"],"additionalProperties":false},{"type":"object","properties":{"identityType":{"type":"string","const":"ORGANIZATION"},"organization":{"type":"object","properties":{"legalName":{"type":"string","examples":["Novalia Handels GmbH"],"description":"The organization's name exactly as the register it is incorporated in records it, suffix included."},"doingBusinessAs":{"type":"string","examples":["Novalia"],"description":"The trading name the organization is known by, where that differs from the legal name."},"contactEmail":{"type":"string","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\\.)+[A-Za-z]{2,}$","maxLength":255,"examples":["treasury@novalia.example"],"description":"An address that reaches the organization; a channel into the company, not any one person's own."},"registrationNumber":{"type":"string","examples":["HRB 123456"],"description":"The organization's number in the public register it is incorporated in."},"dateOfIncorporation":{"type":"string","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","examples":["2014-09-01"],"description":"The date the organization was constituted."},"legalStructure":{"type":"string","enum":["PUBLIC_LISTED_COMPANY","PRIVATE_LIMITED","SOLE_TRADER","NON_PROFIT","GENERAL_PARTNERSHIP","LIMITED_PARTNERSHIP"],"examples":["PRIVATE_LIMITED"],"description":"The form an organization is constituted in."},"taxInformation":{"type":"array","items":{"type":"object","properties":{"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose authority issued the identifier."},"taxIdNumber":{"type":"string","examples":["ABCDE1234F"],"description":"The identifier itself, as the issuing authority writes it, punctuation included."}},"required":["issuingCountry","taxIdNumber"],"additionalProperties":false}},"registeredAddress":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$"}},"additionalProperties":false},"principalPlaceOfBusiness":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$"}},"additionalProperties":false},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["REGISTRATION_DOCUMENT","CONSTITUTIONAL_DOCUMENT","PROOF_OF_OWNERSHIP","PROOF_OF_ADDRESS","PROOF_OF_TAX_INFORMATION"],"examples":["REGISTRATION_DOCUMENT"],"description":"The kind of document an organization holds."},"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country the document was issued in."},"number":{"type":"string","examples":["Z1234567"],"description":"The number printed on the document. Input-only: never returned on reads."}},"required":["type","issuingCountry","number"],"additionalProperties":false}},"associations":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"identityType":{"type":"string","const":"INDIVIDUAL"},"role":{"type":"string","enum":["UBO_THROUGH_OWNERSHIP","UBO_THROUGH_CONTROL","DIRECTOR","SIGNATORY","AUTHORIZED_REPRESENTATIVE"],"examples":["UBO_THROUGH_OWNERSHIP"],"description":"How a natural person is associated with an organization."},"individual":{"type":"object","properties":{"firstName":{"type":"string","examples":["Nadia"],"description":"Given names, in the order the person writes them."},"lastName":{"type":"string","examples":["Mehta"],"description":"Family name. A person who goes by a single name puts the whole of it here."},"dateOfBirth":{"type":"string","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","examples":["1990-03-14"],"description":"The person's date of birth."},"nationality":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose nationality the person holds. Single-valued."},"email":{"type":"string","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\\.)+[A-Za-z]{2,}$","maxLength":255,"examples":["nadia.mehta@novalia.example"],"description":"The person's own email address."},"phoneNumber":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$","examples":["+919876543210"],"description":"The person's own phone number."},"residentialAddress":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$"}},"additionalProperties":false},"taxInformation":{"type":"array","items":{"type":"object","properties":{"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose authority issued the identifier."},"taxIdNumber":{"type":"string","examples":["ABCDE1234F"],"description":"The identifier itself, as the issuing authority writes it, punctuation included."}},"required":["issuingCountry","taxIdNumber"],"additionalProperties":false}},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["PASSPORT","NATIONAL_ID","DRIVERS_LICENSE","SSN","RESIDENCE_PERMIT"],"examples":["PASSPORT"],"description":"The kind of document a person holds."},"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country the document was issued in."},"number":{"type":"string","examples":["Z1234567"],"description":"The number printed on the document. Input-only: never returned on reads."}},"required":["type","issuingCountry","number"],"additionalProperties":false}}},"additionalProperties":false},"ownershipPercent":{"type":"number","minimum":0,"maximum":100,"examples":[40],"description":"The share of the organization this identity holds, as a percentage."}},"required":["identityType","individual"],"additionalProperties":false},{"type":"object","properties":{"identityType":{"type":"string","const":"ORGANIZATION"},"role":{"type":"string","enum":["ULTIMATE_PARENT_COMPANY"],"examples":["ULTIMATE_PARENT_COMPANY"],"description":"How an organization is associated with another organization."},"organization":{"type":"object","properties":{"legalName":{"type":"string","examples":["Novalia Handels GmbH"],"description":"The organization's name exactly as the register it is incorporated in records it, suffix included."},"doingBusinessAs":{"type":"string","examples":["Novalia"],"description":"The trading name the organization is known by, where that differs from the legal name."},"contactEmail":{"type":"string","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\\.)+[A-Za-z]{2,}$","maxLength":255,"examples":["treasury@novalia.example"],"description":"An address that reaches the organization; a channel into the company, not any one person's own."},"registrationNumber":{"type":"string","examples":["HRB 123456"],"description":"The organization's number in the public register it is incorporated in."},"dateOfIncorporation":{"type":"string","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$","examples":["2014-09-01"],"description":"The date the organization was constituted."},"legalStructure":{"type":"string","enum":["PUBLIC_LISTED_COMPANY","PRIVATE_LIMITED","SOLE_TRADER","NON_PROFIT","GENERAL_PARTNERSHIP","LIMITED_PARTNERSHIP"],"examples":["PRIVATE_LIMITED"],"description":"The form an organization is constituted in."},"taxInformation":{"type":"array","items":{"type":"object","properties":{"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country whose authority issued the identifier."},"taxIdNumber":{"type":"string","examples":["ABCDE1234F"],"description":"The identifier itself, as the issuing authority writes it, punctuation included."}},"required":["issuingCountry","taxIdNumber"],"additionalProperties":false}},"registeredAddress":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$"}},"additionalProperties":false},"principalPlaceOfBusiness":{"type":"object","properties":{"line1":{"type":"string","examples":["Friedrichstraße 100"],"description":"Street name and number."},"line2":{"type":"string","examples":["Floor 3"],"description":"A second street line."},"city":{"type":"string","examples":["Berlin"],"description":"City or locality."},"state":{"type":"string","examples":["Berlin"],"description":"State, province or region."},"postalCode":{"type":"string","examples":["10117"],"description":"Postal or ZIP code."},"country":{"type":"string","pattern":"^[A-Z]{2}$"}},"additionalProperties":false},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["REGISTRATION_DOCUMENT","CONSTITUTIONAL_DOCUMENT","PROOF_OF_OWNERSHIP","PROOF_OF_ADDRESS","PROOF_OF_TAX_INFORMATION"],"examples":["REGISTRATION_DOCUMENT"],"description":"The kind of document an organization holds."},"issuingCountry":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"The country the document was issued in."},"number":{"type":"string","examples":["Z1234567"],"description":"The number printed on the document. Input-only: never returned on reads."}},"required":["type","issuingCountry","number"],"additionalProperties":false}}},"additionalProperties":false},"ownershipPercent":{"type":"number","minimum":0,"maximum":100,"examples":[40],"description":"The share of the organization this identity holds, as a percentage."}},"required":["identityType","organization"],"additionalProperties":false}]}}},"additionalProperties":false}},"required":["identityType","organization"],"additionalProperties":false}],"description":"Identity to add so the requested capabilities' requirements are met in this call. Omit when the account's supplied identity already satisfies every requested capability."}},"required":["capabilities"],"additionalProperties":false}}}}}},"/common/financial-accounts":{"get":{"responses":{"200":{"description":"The financial accounts available to fund a `receiveCurrency` payout (non-paginated). May be empty.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"financialAccount","examples":["financialAccount"],"description":"The type of object represented, a fixed discriminator. Always `\"financialAccount\"` for this resource."},"id":{"type":"string","pattern":"^finacc_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"finacc_eUzeSQF9ZY6q4x8AhBskUf","description":"Financial account identifier. Pass as `financialAccountId` on POST /v3/payments/payout-quotes to debit this financial account."},"currency":{"type":"string","pattern":"^[A-Z0-9]{2,15}$","examples":["USD"],"description":"Currency this financial account holds and is debited in — the `sendCurrency` of every quote and payout that names it."},"label":{"type":"string","examples":["USD - FX Balance"],"description":"Human-readable name. Use it to tell two financial accounts in the same currency apart."},"availableBalance":{"type":"string","pattern":"^-?[0-9]+\\.[0-9]{6}$","examples":["48250.000000","-3100.000000"],"description":"Funds currently available to source a payout, in this account's `currency`. Carries either sign: a negative value means held funds exceed `totalBalance`, so the account needs funding before it can source anything. A point-in-time snapshot: sufficiency is authoritative at quote and payout time, never inferred from this value."},"totalBalance":{"type":"string","pattern":"^-?[0-9]+\\.[0-9]{6}$","examples":["50000.000000","-2600.000000"],"description":"Total balance including held or earmarked funds. Carries either sign: a negative value is a debit balance. `availableBalance` never exceeds it; the difference is the held portion."}},"required":["object","id","currency","label","availableBalance","totalBalance"],"additionalProperties":false}}},"required":["data"]},"examples":{"default_example":{"summary":"Financial accounts that can fund a EUR payout","value":{"data":[{"object":"financialAccount","id":"finacc_eUzeSQF9ZY6q4x8AhBskUf","currency":"USD","label":"USD - FX Balance","availableBalance":"48250.000000","totalBalance":"50000.000000"},{"object":"financialAccount","id":"finacc_9KpR2mvnRWbZcTwY4N8sk1","currency":"USDC","label":"USDC - FX Balance","availableBalance":"-3100.000000","totalBalance":"-2600.000000"},{"object":"financialAccount","id":"finacc_2yDcmWvvyix2KwKBA2m9uh","currency":"EUR","label":"EUR - FX Balance","availableBalance":"60000.000000","totalBalance":"60000.000000"}]}}}}}},"400":{"description":"The request failed validation, or the gateway context was missing.","content":{"application/json":{"examples":{"validation_query_failed":{"summary":"Query parameters failed validation.","value":{"error":{"code":"VALIDATION_QUERY_FAILED","type":"VALIDATION_ERROR","message":"Query parameters failed validation.","retryStrategy":"FIX_AND_RESUBMIT","details":{"issues":[{"path":"/receiveCurrency","code":"invalid_type","message":"Required","expected":"string","received":"undefined"}],"firstIssuePath":"/receiveCurrency"}}}},"missing_request_context":{"summary":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","value":{"error":{"code":"MISSING_REQUEST_CONTEXT","type":"VALIDATION_ERROR","message":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"invalid_organization":{"summary":"The organization identifier on the request is malformed. Send the request through the documented gateway.","value":{"error":{"code":"INVALID_ORGANIZATION","type":"VALIDATION_ERROR","message":"The organization identifier on the request is malformed. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"The request is not authenticated.","content":{"application/json":{"examples":{"auth_token_missing":{"summary":"The Authorization header is missing. Provide a Bearer JWT.","value":{"error":{"code":"AUTH_TOKEN_MISSING","type":"AUTHENTICATION_ERROR","message":"The Authorization header is missing. Provide a Bearer JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid":{"summary":"Authorization token is invalid. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_expired":{"summary":"Authorization token has expired. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_EXPIRED","type":"AUTHENTICATION_ERROR","message":"Authorization token has expired. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid_config":{"summary":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","value":{"error":{"code":"AUTH_TOKEN_INVALID_CONFIG","type":"AUTHENTICATION_ERROR","message":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","retryStrategy":"TERMINAL","details":{}}}},"auth_api_key_invalid":{"summary":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","value":{"error":{"code":"AUTH_API_KEY_INVALID","type":"AUTHENTICATION_ERROR","message":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"The API key may not perform this operation.","content":{"application/json":{"examples":{"auth_insufficient_scope":{"summary":"The API key is missing the scope required for this operation.","value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}},"payout_currency_not_enabled":{"summary":"Your organization isn't enabled for payouts in the requested receiveCurrency.","value":{"error":{"code":"PAYOUT_CURRENCY_NOT_ENABLED","type":"AUTHORIZATION_ERROR","message":"Your organization isn't enabled for payouts in the requested receiveCurrency.","retryStrategy":"TERMINAL","details":{"receiveCurrency":"INR"}}}}}}}},"429":{"description":"The API key has exceeded its request rate limit.","content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"This API key has exceeded its request rate limit for the current window.","value":{"error":{"code":"RATE_LIMIT_EXCEEDED","type":"RATE_LIMITED","message":"This API key has exceeded its request rate limit for the current window.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}},"500":{"description":"An unexpected internal error occurred.","content":{"application/json":{"examples":{"internal_error":{"summary":"An unexpected internal error occurred. Contact support with the trace ID.","value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"listFinancialAccounts","summary":"List financial accounts available to fund a payout","tags":["Financial accounts"],"description":"List the financial accounts your organization can currently use to fund a payout settling in `receiveCurrency` — same-currency (no-FX) and cross-currency funders alike, subject to your organization's entitlements. Not paginated: the whole set comes back at once, in no guaranteed order. An empty list means your organization is enabled for `receiveCurrency` but holds no financial account that can currently source it; not being enabled for the currency at all returns 403 PAYOUT_CURRENCY_NOT_ENABLED instead.","parameters":[{"name":"receiveCurrency","in":"query","required":false,"schema":{"type":"string"},"description":"Currency which the receipient will receive"}]}},"/payments/payout-addresses":{"post":{"responses":{"200":{"description":"The created payout address.","headers":{"Idempotency-Replayed":{"description":"`true` when the response was served from the idempotency cache; `false` for a freshly executed request.","schema":{"type":"string","enum":["true","false"]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","const":"payoutAddress","examples":["payoutAddress"],"description":"The type of object represented, a fixed discriminator. Always `\"payoutAddress\"` for this resource."},"id":{"type":"string","pattern":"^pytadd_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"pytadd_NJAEqN76R7PwPfHt3oWb8R","description":"Payout address identifier."},"payoutAddressType":{"type":"string","const":"BANK_ACCOUNT"},"accountId":{"type":"string","pattern":"^acc_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"acc_h82pJGF9p7kpzb6eU326EF","description":"The account this payout address belongs to."},"bankAccount":{"anyOf":[{"type":"object","properties":{"routingFamily":{"type":"string","const":"SEPA"},"accountHolderName":{"type":"string","examples":["Nadia Holdings Pvt Ltd"],"description":"The name the receiving institution holds for this account. Not the identity's name and not compared against it."},"accountNumber":{"type":"string","pattern":"^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}$","examples":["DE89370400440532013000"],"description":"The IBAN in canonical contiguous form."},"bic":{"type":"string","pattern":"^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$","examples":["COBADEFFXXX"],"description":"The bank's BIC, ISO 9362, where the account has one. Present where the account is payable over SWIFT as well."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"Where the account is held, read from the IBAN prefix."}},"required":["routingFamily","accountHolderName","accountNumber","country"],"additionalProperties":false},{"type":"object","properties":{"routingFamily":{"type":"string","const":"SWIFT"},"accountHolderName":{"type":"string","pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","maxLength":140,"examples":["Novalia Handels GmbH"],"description":"The name the receiving institution holds for this account, up to 140 characters. Not the identity's name and not compared against it."},"accountNumber":{"type":"string","pattern":"^[A-Z0-9]{1,34}$","examples":["8801234567"],"description":"The account number at the bank, uppercase and contiguous whatever grouping it was supplied in."},"bic":{"type":"string","pattern":"^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$","examples":["PAVEGE22XXX"],"description":"The bank's BIC, ISO 9362."},"accountHolderAddress":{"type":"object","properties":{"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."},"city":{"type":"string","pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","maxLength":35,"examples":["Berlin"],"description":"Town or city."},"line1":{"type":"string","pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","maxLength":70,"examples":["Friedrichstrasse 100"],"description":"Street name and number."},"line2":{"type":"string","pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","maxLength":70,"examples":["Floor 3"],"description":"A second street line, for a floor, a unit or a care-of name."},"postalCode":{"type":"string","pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","maxLength":16,"examples":["10117"],"description":"Postal or ZIP code."},"state":{"type":"string","pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","maxLength":35,"examples":["Berlin"],"description":"State, province or region. No format is claimed, so write it as the country's own post would."}},"required":["country","city"],"additionalProperties":false,"description":"The postal address the account holder is at."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["GE"],"description":"Where the account is held, read from the BIC's country characters."}},"required":["routingFamily","accountHolderName","accountNumber","bic","accountHolderAddress","country"],"additionalProperties":false},{"type":"object","properties":{"routingFamily":{"type":"string","const":"IN_LOCAL"},"accountHolderName":{"type":"string","examples":["Nadia Holdings Pvt Ltd"],"description":"The name the receiving institution holds for this account. Not the identity's name and not compared against it."},"ifsc":{"type":"string","pattern":"^[A-Z]{4}0[A-Z0-9]{6}$","examples":["HDFC0001234"],"description":"The 11-character IFSC identifying the branch: four bank letters, a zero, then six branch characters."},"accountNumber":{"type":"string","pattern":"^[0-9]{9,18}$","examples":["50100234567890"],"description":"The account number at that branch, 9 to 18 digits."},"isNre":{"type":"boolean","examples":[false],"description":"Whether this is a repatriable NRE account. False is also what an omitted create resolves to."},"bankAccountType":{"type":"string","enum":["SAVINGS","CURRENT"],"examples":["SAVINGS"],"description":"Which kind of account this is at the institution. Defaults to `SAVINGS` when omitted."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"Where the account is held. Constant: this arm routes within India."}},"required":["routingFamily","accountHolderName","ifsc","accountNumber","isNre","country"],"additionalProperties":false},{"type":"object","properties":{"routingFamily":{"type":"string"}},"required":["routingFamily"]}],"description":"Where this bank account is, and how a payout is routed to it."},"supportedCurrencies":{"type":"array","items":{"type":"string","pattern":"^[A-Z0-9]{2,15}$"},"examples":[["EUR"]],"description":"The currencies and tokens this destination can receive. Tolerate an unrecognized value."},"supportedRails":{"type":"array","items":{"type":"string"},"examples":[["SEPA"]],"description":"The rails this destination can be paid over, following `routingFamily`. Tolerate an unrecognized value."},"status":{"type":"string","enum":["PENDING","ACTIVE","REJECTED","REQUIRES_INFORMATION"],"examples":["ACTIVE"],"description":"Whether the platform's setup of this payout address allows it to back a payout. `PENDING` while initial setup runs; `ACTIVE` is not terminal — a later blocking act moves it to `REJECTED`. Orthogonal to `archivedAt`."},"verifications":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"NAME_MATCH"},"mode":{"type":"string","examples":["SEPA_VOP"],"description":"How the account holder name was checked."},"result":{"type":"string","examples":["MATCH"],"description":"Outcome of the name check."},"providedName":{"type":"string","examples":["Novalia Handels GmbH"],"description":"The name submitted for comparison, frozen as it stood when the act ran."},"registeredName":{"type":["string","null"],"examples":["Novalia Handels GmbH"],"description":"The name the receiving institution holds. Null where the scheme returned none. Where present and different, it is the exact string to use on a replacement payout address."},"createdAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"When this act started."},"verifiedAt":{"type":["string","null"],"format":"date-time","examples":["2026-06-04T10:31:20.000Z"],"description":"When it resolved. Null while `PENDING`."},"expiresAt":{"type":["string","null"],"format":"date-time","description":"When this result goes stale, or null when it does not expire."}},"required":["kind","mode","result","providedName","registeredName","createdAt","verifiedAt","expiresAt"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string"}},"required":["kind"]}]},"description":"What the platform has established about this destination — the current act for each verification kind and mode, not a history."},"label":{"type":"string","examples":["Operating account"],"description":"Human-friendly label."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own key/value pairs, echoed back verbatim."},"archivedAt":{"type":["string","null"],"format":"date-time","examples":["2026-07-01T09:05:00.000Z"],"description":"When the client retired this payout address, or null while it is live. Terminal once set."},"createdAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"Creation timestamp."},"updatedAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:31:20.000Z"],"description":"Last-update timestamp."}},"required":["object","id","payoutAddressType","accountId","bankAccount","supportedCurrencies","supportedRails","status","verifications","archivedAt","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"]},"examples":{"sepa_example":{"summary":"SEPA bank account, name match pending","value":{"data":{"object":"payoutAddress","id":"pytadd_NJAEqN76R7PwPfHt3oWb8R","payoutAddressType":"BANK_ACCOUNT","accountId":"acc_h82pJGF9p7kpzb6eU326EF","bankAccount":{"routingFamily":"SEPA","accountHolderName":"Novalia Handels GmbH","accountNumber":"DE89370400440532013000","country":"DE"},"supportedCurrencies":["EUR"],"supportedRails":["SEPA"],"status":"PENDING","verifications":[{"kind":"NAME_MATCH","mode":"SEPA_VOP","result":"PENDING","providedName":"Novalia Handels GmbH","registeredName":null,"createdAt":"2026-06-04T10:30:00.000Z","verifiedAt":null,"expiresAt":null}],"archivedAt":null,"createdAt":"2026-06-04T10:30:00.000Z","updatedAt":"2026-06-04T10:30:00.000Z"}}},"swift_example":{"summary":"SWIFT bank account, no name check available","value":{"data":{"object":"payoutAddress","id":"pytadd_2Qk9vXbM4tRnzsLpYdHcW3","payoutAddressType":"BANK_ACCOUNT","accountId":"acc_h82pJGF9p7kpzb6eU326EF","bankAccount":{"routingFamily":"SWIFT","accountHolderName":"Novalia Handels GmbH","accountNumber":"8801234567","bic":"PAVEGE22XXX","accountHolderAddress":{"country":"DE","city":"Berlin","line1":"Friedrichstrasse 100","postalCode":"10117"},"country":"GE"},"supportedCurrencies":["EUR"],"supportedRails":["SWIFT"],"status":"PENDING","verifications":[],"archivedAt":null,"createdAt":"2026-06-04T10:30:00.000Z","updatedAt":"2026-06-04T10:30:00.000Z"}}}}}}},"400":{"description":"The request failed validation, has an invalid Content-Type, the Idempotency-Key is malformed, or the gateway context was missing.","content":{"application/json":{"examples":{"validation_body_failed":{"summary":"Request body failed validation. See details.issues for field-level errors, or details.firstIssuePath for the most common single-field case.","value":{"error":{"code":"VALIDATION_BODY_FAILED","type":"VALIDATION_ERROR","message":"Request body failed validation. See details.issues for field-level errors, or details.firstIssuePath for the most common single-field case.","retryStrategy":"FIX_AND_RESUBMIT","details":{"issues":[{"path":"/identity/individual/lastName","code":"invalid_type","message":"Required","expected":"string","received":"undefined"},{"path":"/identity/individual/documents/0/type","code":"invalid_enum_value","message":"is not a supported document type","expected":"PASSPORT|NATIONAL_ID|DRIVERS_LICENSE|SSN|RESIDENCE_PERMIT","received":"LIBRARY_CARD"},{"path":"/identity/individual/residentialAddress/country","code":"custom","message":"is not an ISO 3166-1 alpha-2 country code (the United Kingdom is GB)","received":"UK"}],"firstIssuePath":"/identity/individual/lastName"}}}},"validation_content_type":{"summary":"Content-Type must be application/json.","value":{"error":{"code":"VALIDATION_CONTENT_TYPE","type":"VALIDATION_ERROR","message":"Content-Type must be application/json.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"idempotency_key_invalid":{"summary":"Idempotency-Key is malformed. Generate a new key matching the documented pattern and retry with that new key.","value":{"error":{"code":"IDEMPOTENCY_KEY_INVALID","type":"VALIDATION_ERROR","message":"Idempotency-Key is malformed. Generate a new key matching the documented pattern and retry with that new key.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"missing_request_context":{"summary":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","value":{"error":{"code":"MISSING_REQUEST_CONTEXT","type":"VALIDATION_ERROR","message":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"invalid_organization":{"summary":"The organization identifier on the request is malformed. Send the request through the documented gateway.","value":{"error":{"code":"INVALID_ORGANIZATION","type":"VALIDATION_ERROR","message":"The organization identifier on the request is malformed. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"payout_address_field_missing":{"summary":"A field required by the selected routingFamily is missing or invalid.","value":{"error":{"code":"PAYOUT_ADDRESS_FIELD_MISSING","type":"VALIDATION_ERROR","message":"A field required by the selected routingFamily is missing or invalid.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"The request is not authenticated.","content":{"application/json":{"examples":{"auth_token_missing":{"summary":"The Authorization header is missing. Provide a Bearer JWT.","value":{"error":{"code":"AUTH_TOKEN_MISSING","type":"AUTHENTICATION_ERROR","message":"The Authorization header is missing. Provide a Bearer JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid":{"summary":"Authorization token is invalid. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_expired":{"summary":"Authorization token has expired. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_EXPIRED","type":"AUTHENTICATION_ERROR","message":"Authorization token has expired. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid_config":{"summary":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","value":{"error":{"code":"AUTH_TOKEN_INVALID_CONFIG","type":"AUTHENTICATION_ERROR","message":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","retryStrategy":"TERMINAL","details":{}}}},"auth_api_key_invalid":{"summary":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","value":{"error":{"code":"AUTH_API_KEY_INVALID","type":"AUTHENTICATION_ERROR","message":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"The API key may not perform this operation.","content":{"application/json":{"examples":{"auth_insufficient_scope":{"summary":"The API key is missing the scope required for this operation.","value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"404":{"description":"A referenced resource does not exist in this org.","content":{"application/json":{"examples":{"account_not_found":{"summary":"No account with that id in this org.","value":{"error":{"code":"ACCOUNT_NOT_FOUND","type":"NOT_FOUND","message":"No account with that id in this org.","retryStrategy":"TERMINAL","details":{}}}}}}}},"409":{"description":"The request conflicts with current state, or with an in-flight request using the same key.","content":{"application/json":{"examples":{"idempotency_in_flight":{"summary":"Another request with this idempotency key is currently processing. Wait for some time and retry with the same key.","value":{"error":{"code":"IDEMPOTENCY_IN_FLIGHT","type":"CONFLICT","message":"Another request with this idempotency key is currently processing. Wait for some time and retry with the same key.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}},"account_archived":{"summary":"The account is archived and cannot take new work.","value":{"error":{"code":"ACCOUNT_ARCHIVED","type":"CONFLICT","message":"The account is archived and cannot take new work.","retryStrategy":"TERMINAL","details":{"accountId":"acc_h82pJGF9p7kpzb6eU326EF"}}}},"account_not_active":{"summary":"The account's standing does not allow this operation.","value":{"error":{"code":"ACCOUNT_NOT_ACTIVE","type":"CONFLICT","message":"The account's standing does not allow this operation.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{"accountId":"acc_h82pJGF9p7kpzb6eU326EF","status":"REJECTED"}}}},"address_serves_no_capability":{"summary":"This address serves no capability the account holds.","value":{"error":{"code":"ADDRESS_SERVES_NO_CAPABILITY","type":"CONFLICT","message":"This address serves no capability the account holds.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{"accountId":"acc_h82pJGF9p7kpzb6eU326EF","required":{"grant":"RECEIVE_PAYOUTS","currency":"INR","repatriability":"NON_REPATRIABLE"}}}}},"payout_address_conflict":{"summary":"The bank details in this request already back a payout address on this account. details names the existing address.","value":{"error":{"code":"PAYOUT_ADDRESS_CONFLICT","type":"CONFLICT","message":"The bank details in this request already back a payout address on this account. details names the existing address.","retryStrategy":"TERMINAL","details":{"payoutAddressId":"pytadd_NJAEqN76R7PwPfHt3oWb8R","status":"ACTIVE"}}}}}}}},"422":{"description":"A business rule was tripped by the request's own values, or the key was replayed with a different body.","content":{"application/json":{"examples":{"idempotency_mismatch":{"summary":"This idempotency key was previously seen with a different request body. Use a new key for a new request, or resubmit the original body verbatim.","value":{"error":{"code":"IDEMPOTENCY_MISMATCH","type":"CONFLICT","message":"This idempotency key was previously seen with a different request body. Use a new key for a new request, or resubmit the original body verbatim.","retryStrategy":"FIX_AND_RESUBMIT","details":{"originalRequestHash":"sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"}}}}}}}},"428":{"description":"The Idempotency-Key header is required for this endpoint.","content":{"application/json":{"examples":{"idempotency_key_missing":{"summary":"The Idempotency-Key header is required for this endpoint.","value":{"error":{"code":"IDEMPOTENCY_KEY_MISSING","type":"VALIDATION_ERROR","message":"The Idempotency-Key header is required for this endpoint.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"429":{"description":"The API key has exceeded its request rate limit.","content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"This API key has exceeded its request rate limit for the current window.","value":{"error":{"code":"RATE_LIMIT_EXCEEDED","type":"RATE_LIMITED","message":"This API key has exceeded its request rate limit for the current window.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}},"500":{"description":"An unexpected internal error occurred.","content":{"application/json":{"examples":{"internal_error":{"summary":"An unexpected internal error occurred. Contact support with the trace ID.","value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"createPayoutAddress","summary":"Create a payout address","tags":["Addresses"],"description":"Register a destination `accountId` can be paid at. The body is discriminated on `payoutAddressType` and carries `bankAccount`, itself discriminated on `routingFamily`: `SEPA` takes an `accountNumber` alone, `SWIFT` adds a `bic` and the holder's address for a euro destination the SEPA scheme does not reach, and `IN_LOCAL` takes an `ifsc` and an `accountNumber`. An IBAN the SEPA roster covers is accepted on either EUR arm, and an address that has one is paid over SEPA. Creating the address does not wait on the covering capability's activation; address setup and capability setup run in parallel. The response reports `status` as it stands when written — `PENDING` while initial setup runs — and setup drives it to its settled value however fast it settles; subscribe to the payout_address webhooks rather than polling.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255,"pattern":"^[a-zA-Z0-9_-]{1,255}$","example":"123e4567-e89b-12d3-a456-426614174000"},"description":"Unique key to ensure idempotent requests — 1-255 characters: alphanumerics, hyphens, underscores. UUID v4 recommended."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"payoutAddressType":{"type":"string","const":"BANK_ACCOUNT"},"accountId":{"type":"string","example":"acc_h82pJGF9p7kpzb6eU326EF","description":"The account this payout address belongs to. Immutable once set."},"label":{"type":"string","examples":["Operating account"],"description":"Human-friendly label."},"metadata":{"type":"object","propertyNames":{"type":"string","minLength":1,"maxLength":40},"additionalProperties":{"type":"string","maxLength":500},"description":"Optional client-owned metadata bag (string keys → string values). Echoed back verbatim on a successful response. Limits: at most 50 keys, keys up to 40 characters, values up to 500 characters, and at most 8192 bytes when serialized.","examples":[{"requestId":"client-generated-correlation-id"}]},"bankAccount":{"oneOf":[{"type":"object","properties":{"routingFamily":{"type":"string","const":"SEPA"},"accountHolderName":{"type":"string","examples":["Nadia Holdings Pvt Ltd"],"description":"The name the receiving institution holds for this account. Optional: inherits the linked account's own name when omitted."},"accountNumber":{"type":"string","pattern":"^[\\sA-Za-z0-9]+$","examples":["DE89 3704 0044 0532 0130 00"],"description":"The IBAN, ISO 13616. Whitespace is stripped and the value uppercased before validation; the mod-97 checksum and per-country length are checked on the normalized value."},"bic":{"type":"string","pattern":"^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$","examples":["COBADEFFXXX"],"description":"The bank's BIC, ISO 9362, where the account has one. Supplying it also makes the account payable over SWIFT, which `supportedRails` reports."}},"required":["routingFamily","accountNumber"],"additionalProperties":false},{"type":"object","properties":{"routingFamily":{"type":"string","const":"SWIFT"},"accountHolderName":{"type":"string","pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","maxLength":140,"examples":["Novalia Handels GmbH"],"description":"The name the receiving institution holds for this account, up to 140 characters. Optional: inherits the linked account's own name when omitted."},"accountNumber":{"type":"string","pattern":"^[\\sA-Za-z0-9]+$","examples":["8801 234567"],"description":"The account number at the bank, an IBAN or the bank's own, up to 34 characters. Whitespace is stripped and the value uppercased before validation."},"bic":{"type":"string","pattern":"^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$","examples":["PAVEGE22XXX"],"description":"The bank's BIC, ISO 9362. Its fifth and sixth characters name the bank's country, which must be one the platform can pay SWIFT into."},"accountHolderAddress":{"type":"object","properties":{"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."},"city":{"type":"string","pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","maxLength":35,"examples":["Berlin"],"description":"Town or city."},"line1":{"type":"string","pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","maxLength":70,"examples":["Friedrichstrasse 100"],"description":"Street name and number."},"line2":{"type":"string","pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","maxLength":70,"examples":["Floor 3"],"description":"A second street line, for a floor, a unit or a care-of name."},"postalCode":{"type":"string","pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","maxLength":16,"examples":["10117"],"description":"Postal or ZIP code."},"state":{"type":"string","pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","maxLength":35,"examples":["Berlin"],"description":"State, province or region. No format is claimed, so write it as the country's own post would."}},"required":["country","city"],"additionalProperties":false,"description":"The postal address the account holder is at. Its town and country travel with the payment."}},"required":["routingFamily","accountNumber","bic","accountHolderAddress"],"additionalProperties":false},{"type":"object","properties":{"routingFamily":{"type":"string","const":"IN_LOCAL"},"accountHolderName":{"type":"string","examples":["Nadia Holdings Pvt Ltd"],"description":"The name the receiving institution holds for this account. Optional: inherits the linked account's own name when omitted."},"ifsc":{"type":"string","pattern":"^[A-Z]{4}0[A-Z0-9]{6}$","examples":["HDFC0001234"],"description":"The 11-character IFSC identifying the branch: four bank letters, a zero, then six branch characters."},"accountNumber":{"type":"string","pattern":"^[\\s0-9]+$","examples":["5010 0234 5678 90"],"description":"The account number at that branch, 9 to 18 digits. Whitespace is stripped before validation; any other separator fails the digits-only check."},"isNre":{"type":"boolean","examples":[false],"description":"Whether this is a repatriable NRE account, funded from abroad. Defaults to false, covering an NRO account and an ordinary resident-held account alike."},"bankAccountType":{"type":"string","enum":["SAVINGS","CURRENT"],"examples":["SAVINGS"],"description":"Which kind of account this is at the institution. Defaults to `SAVINGS` when omitted."}},"required":["routingFamily","ifsc","accountNumber"],"additionalProperties":false}],"description":"Where this bank account is, and how a payout is routed to it."}},"required":["payoutAddressType","accountId","bankAccount"],"additionalProperties":false}}}}},"get":{"responses":{"200":{"description":"A page of payout addresses.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"payoutAddress","examples":["payoutAddress"],"description":"The type of object represented, a fixed discriminator. Always `\"payoutAddress\"` for this resource."},"id":{"type":"string","pattern":"^pytadd_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"pytadd_NJAEqN76R7PwPfHt3oWb8R","description":"Payout address identifier."},"payoutAddressType":{"type":"string","const":"BANK_ACCOUNT"},"accountId":{"type":"string","pattern":"^acc_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"acc_h82pJGF9p7kpzb6eU326EF","description":"The account this payout address belongs to."},"bankAccount":{"anyOf":[{"type":"object","properties":{"routingFamily":{"type":"string","const":"SEPA"},"accountHolderName":{"type":"string","examples":["Nadia Holdings Pvt Ltd"],"description":"The name the receiving institution holds for this account. Not the identity's name and not compared against it."},"accountNumber":{"type":"string","pattern":"^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}$","examples":["DE89370400440532013000"],"description":"The IBAN in canonical contiguous form."},"bic":{"type":"string","pattern":"^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$","examples":["COBADEFFXXX"],"description":"The bank's BIC, ISO 9362, where the account has one. Present where the account is payable over SWIFT as well."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"Where the account is held, read from the IBAN prefix."}},"required":["routingFamily","accountHolderName","accountNumber","country"],"additionalProperties":false},{"type":"object","properties":{"routingFamily":{"type":"string","const":"SWIFT"},"accountHolderName":{"type":"string","pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","maxLength":140,"examples":["Novalia Handels GmbH"],"description":"The name the receiving institution holds for this account, up to 140 characters. Not the identity's name and not compared against it."},"accountNumber":{"type":"string","pattern":"^[A-Z0-9]{1,34}$","examples":["8801234567"],"description":"The account number at the bank, uppercase and contiguous whatever grouping it was supplied in."},"bic":{"type":"string","pattern":"^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$","examples":["PAVEGE22XXX"],"description":"The bank's BIC, ISO 9362."},"accountHolderAddress":{"type":"object","properties":{"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."},"city":{"type":"string","pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","maxLength":35,"examples":["Berlin"],"description":"Town or city."},"line1":{"type":"string","pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","maxLength":70,"examples":["Friedrichstrasse 100"],"description":"Street name and number."},"line2":{"type":"string","pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","maxLength":70,"examples":["Floor 3"],"description":"A second street line, for a floor, a unit or a care-of name."},"postalCode":{"type":"string","pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","maxLength":16,"examples":["10117"],"description":"Postal or ZIP code."},"state":{"type":"string","pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","maxLength":35,"examples":["Berlin"],"description":"State, province or region. No format is claimed, so write it as the country's own post would."}},"required":["country","city"],"additionalProperties":false,"description":"The postal address the account holder is at."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["GE"],"description":"Where the account is held, read from the BIC's country characters."}},"required":["routingFamily","accountHolderName","accountNumber","bic","accountHolderAddress","country"],"additionalProperties":false},{"type":"object","properties":{"routingFamily":{"type":"string","const":"IN_LOCAL"},"accountHolderName":{"type":"string","examples":["Nadia Holdings Pvt Ltd"],"description":"The name the receiving institution holds for this account. Not the identity's name and not compared against it."},"ifsc":{"type":"string","pattern":"^[A-Z]{4}0[A-Z0-9]{6}$","examples":["HDFC0001234"],"description":"The 11-character IFSC identifying the branch: four bank letters, a zero, then six branch characters."},"accountNumber":{"type":"string","pattern":"^[0-9]{9,18}$","examples":["50100234567890"],"description":"The account number at that branch, 9 to 18 digits."},"isNre":{"type":"boolean","examples":[false],"description":"Whether this is a repatriable NRE account. False is also what an omitted create resolves to."},"bankAccountType":{"type":"string","enum":["SAVINGS","CURRENT"],"examples":["SAVINGS"],"description":"Which kind of account this is at the institution. Defaults to `SAVINGS` when omitted."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"Where the account is held. Constant: this arm routes within India."}},"required":["routingFamily","accountHolderName","ifsc","accountNumber","isNre","country"],"additionalProperties":false},{"type":"object","properties":{"routingFamily":{"type":"string"}},"required":["routingFamily"]}],"description":"Where this bank account is, and how a payout is routed to it."},"supportedCurrencies":{"type":"array","items":{"type":"string","pattern":"^[A-Z0-9]{2,15}$"},"examples":[["EUR"]],"description":"The currencies and tokens this destination can receive. Tolerate an unrecognized value."},"supportedRails":{"type":"array","items":{"type":"string"},"examples":[["SEPA"]],"description":"The rails this destination can be paid over, following `routingFamily`. Tolerate an unrecognized value."},"status":{"type":"string","enum":["PENDING","ACTIVE","REJECTED","REQUIRES_INFORMATION"],"examples":["ACTIVE"],"description":"Whether the platform's setup of this payout address allows it to back a payout. `PENDING` while initial setup runs; `ACTIVE` is not terminal — a later blocking act moves it to `REJECTED`. Orthogonal to `archivedAt`."},"verifications":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"NAME_MATCH"},"mode":{"type":"string","examples":["SEPA_VOP"],"description":"How the account holder name was checked."},"result":{"type":"string","examples":["MATCH"],"description":"Outcome of the name check."},"providedName":{"type":"string","examples":["Novalia Handels GmbH"],"description":"The name submitted for comparison, frozen as it stood when the act ran."},"registeredName":{"type":["string","null"],"examples":["Novalia Handels GmbH"],"description":"The name the receiving institution holds. Null where the scheme returned none. Where present and different, it is the exact string to use on a replacement payout address."},"createdAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"When this act started."},"verifiedAt":{"type":["string","null"],"format":"date-time","examples":["2026-06-04T10:31:20.000Z"],"description":"When it resolved. Null while `PENDING`."},"expiresAt":{"type":["string","null"],"format":"date-time","description":"When this result goes stale, or null when it does not expire."}},"required":["kind","mode","result","providedName","registeredName","createdAt","verifiedAt","expiresAt"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string"}},"required":["kind"]}]},"description":"What the platform has established about this destination — the current act for each verification kind and mode, not a history."},"label":{"type":"string","examples":["Operating account"],"description":"Human-friendly label."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own key/value pairs, echoed back verbatim."},"archivedAt":{"type":["string","null"],"format":"date-time","examples":["2026-07-01T09:05:00.000Z"],"description":"When the client retired this payout address, or null while it is live. Terminal once set."},"createdAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"Creation timestamp."},"updatedAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:31:20.000Z"],"description":"Last-update timestamp."}},"required":["object","id","payoutAddressType","accountId","bankAccount","supportedCurrencies","supportedRails","status","verifications","archivedAt","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"limit":{"type":"number","examples":[25],"description":"Page size used for this request."},"hasNext":{"type":"boolean","examples":[true],"description":"Whether more results exist after this page."},"nextCursor":{"type":["string","null"],"description":"Cursor pointing to the last item on this page. Pass as `startingAfter` to fetch the next page."},"hasPrev":{"type":"boolean","examples":[false],"description":"Whether results exist before this page."},"prevCursor":{"type":["string","null"],"description":"Cursor pointing to the first item on this page. Pass as `endingBefore` to fetch the previous page."}},"required":["limit","hasNext","nextCursor","hasPrev","prevCursor"]}},"required":["data","pagination"]},"examples":{"default_example":{"summary":"Single-row page","value":{"data":[{"object":"payoutAddress","id":"pytadd_NJAEqN76R7PwPfHt3oWb8R","payoutAddressType":"BANK_ACCOUNT","accountId":"acc_h82pJGF9p7kpzb6eU326EF","bankAccount":{"routingFamily":"SEPA","accountHolderName":"Novalia Handels GmbH","accountNumber":"DE89370400440532013000","country":"DE"},"supportedCurrencies":["EUR"],"supportedRails":["SEPA"],"status":"ACTIVE","verifications":[{"kind":"NAME_MATCH","mode":"SEPA_VOP","result":"MATCH","providedName":"Novalia Handels GmbH","registeredName":"Novalia Handels GmbH","createdAt":"2026-06-04T10:30:00.000Z","verifiedAt":"2026-06-04T10:31:20.000Z","expiresAt":null}],"archivedAt":null,"createdAt":"2026-06-04T10:30:00.000Z","updatedAt":"2026-06-04T10:31:20.000Z"}],"pagination":{"limit":25,"hasNext":false,"nextCursor":null,"hasPrev":false,"prevCursor":null}}}}}}},"400":{"description":"The request failed validation, or the gateway context was missing.","content":{"application/json":{"examples":{"validation_query_failed":{"summary":"Query parameters failed validation.","value":{"error":{"code":"VALIDATION_QUERY_FAILED","type":"VALIDATION_ERROR","message":"Query parameters failed validation.","retryStrategy":"FIX_AND_RESUBMIT","details":{"issues":[{"path":"/receiveCurrency","code":"invalid_type","message":"Required","expected":"string","received":"undefined"}],"firstIssuePath":"/receiveCurrency"}}}},"missing_request_context":{"summary":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","value":{"error":{"code":"MISSING_REQUEST_CONTEXT","type":"VALIDATION_ERROR","message":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"invalid_organization":{"summary":"The organization identifier on the request is malformed. Send the request through the documented gateway.","value":{"error":{"code":"INVALID_ORGANIZATION","type":"VALIDATION_ERROR","message":"The organization identifier on the request is malformed. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"The request is not authenticated.","content":{"application/json":{"examples":{"auth_token_missing":{"summary":"The Authorization header is missing. Provide a Bearer JWT.","value":{"error":{"code":"AUTH_TOKEN_MISSING","type":"AUTHENTICATION_ERROR","message":"The Authorization header is missing. Provide a Bearer JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid":{"summary":"Authorization token is invalid. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_expired":{"summary":"Authorization token has expired. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_EXPIRED","type":"AUTHENTICATION_ERROR","message":"Authorization token has expired. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid_config":{"summary":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","value":{"error":{"code":"AUTH_TOKEN_INVALID_CONFIG","type":"AUTHENTICATION_ERROR","message":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","retryStrategy":"TERMINAL","details":{}}}},"auth_api_key_invalid":{"summary":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","value":{"error":{"code":"AUTH_API_KEY_INVALID","type":"AUTHENTICATION_ERROR","message":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"The API key may not perform this operation.","content":{"application/json":{"examples":{"auth_insufficient_scope":{"summary":"The API key is missing the scope required for this operation.","value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"429":{"description":"The API key has exceeded its request rate limit.","content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"This API key has exceeded its request rate limit for the current window.","value":{"error":{"code":"RATE_LIMIT_EXCEEDED","type":"RATE_LIMITED","message":"This API key has exceeded its request rate limit for the current window.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}},"500":{"description":"An unexpected internal error occurred.","content":{"application/json":{"examples":{"internal_error":{"summary":"An unexpected internal error occurred. Contact support with the trace ID.","value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"listPayoutAddresses","summary":"List payout addresses","tags":["Addresses"],"description":"Cursor list of payout addresses across the organization, newest-first by `createdAt`, optionally narrowed to one account via `?accountId=`. Archived addresses are hidden by default; pass `archived=true` to include them.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size. Default 25, max 100."},{"name":"startingAfter","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor for the next (older) page. Mutually exclusive with `endingBefore`."},{"name":"endingBefore","in":"query","required":false,"schema":{"type":"string"},"description":"Cursor for the previous (newer) page. Mutually exclusive with `startingAfter`."},{"name":"accountId","in":"query","required":false,"schema":{"type":"string"},"description":"Account ID owning the payout addresses"},{"name":"archived","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]},"description":"Whether to include archived payout addresses. Defaults to false."}]}},"/payments/payout-addresses/verify":{"post":{"responses":{"200":{"description":"The account was found. `bankAccount` carries everything the check discovered, the registered account holder name included; an account the check could not use is a 404, never an unfavorable 200.","headers":{"Idempotency-Replayed":{"description":"`true` when the response was served from the idempotency cache; `false` for a freshly executed request.","schema":{"type":"string","enum":["true","false"]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","const":"payoutAddressVerification","examples":["payoutAddressVerification"],"description":"The type of object represented, a fixed discriminator. Always `\"payoutAddressVerification\"` for this resource."},"checkType":{"type":"string","examples":["IMPS_PENNY_DROP"],"description":"Which check ran, following the submitted `routingFamily`."},"verifiedAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:02.000Z"],"description":"When the check resolved."},"bankAccount":{"type":"object","properties":{"routingFamily":{"type":"string","const":"IN_LOCAL"},"accountHolderName":{"type":"string","examples":["NADIA MEHTA"],"description":"The account holder name as the receiving institution registers it. Replaces the submitted spelling where the two differ; the exact string to carry onto the create."},"ifsc":{"type":"string","pattern":"^[A-Z]{4}0[A-Z0-9]{6}$","examples":["HDFC0001234"],"description":"The 11-character IFSC identifying the branch: four bank letters, a zero, then six branch characters."},"accountNumber":{"type":"string","pattern":"^[0-9]{9,18}$","examples":["50100234567890"],"description":"The account number at that branch, 9 to 18 digits."},"isNre":{"type":"boolean","examples":[false],"description":"Whether this is a repatriable NRE account, as the receiving bank disclosed it during the penny drop. Absent where the bank disclosed nothing."}},"required":["routingFamily","accountHolderName","ifsc","accountNumber"],"additionalProperties":false,"description":"The most the check could discover about the account, in create-ready form."}},"required":["object","checkType","verifiedAt","bankAccount"],"additionalProperties":false}},"required":["data"]},"examples":{"default_example":{"summary":"Penny drop, account found","value":{"data":{"object":"payoutAddressVerification","checkType":"IMPS_PENNY_DROP","verifiedAt":"2026-06-04T10:30:02.000Z","bankAccount":{"routingFamily":"IN_LOCAL","accountHolderName":"NADIA MEHTA","ifsc":"HDFC0001234","accountNumber":"50100234567890","isNre":false}}}}}}}},"400":{"description":"The request failed validation, has an invalid Content-Type, the Idempotency-Key is malformed, or the gateway context was missing.","content":{"application/json":{"examples":{"validation_body_failed":{"summary":"Request body failed validation. See details.issues for field-level errors, or details.firstIssuePath for the most common single-field case.","value":{"error":{"code":"VALIDATION_BODY_FAILED","type":"VALIDATION_ERROR","message":"Request body failed validation. See details.issues for field-level errors, or details.firstIssuePath for the most common single-field case.","retryStrategy":"FIX_AND_RESUBMIT","details":{"issues":[{"path":"/identity/individual/lastName","code":"invalid_type","message":"Required","expected":"string","received":"undefined"},{"path":"/identity/individual/documents/0/type","code":"invalid_enum_value","message":"is not a supported document type","expected":"PASSPORT|NATIONAL_ID|DRIVERS_LICENSE|SSN|RESIDENCE_PERMIT","received":"LIBRARY_CARD"},{"path":"/identity/individual/residentialAddress/country","code":"custom","message":"is not an ISO 3166-1 alpha-2 country code (the United Kingdom is GB)","received":"UK"}],"firstIssuePath":"/identity/individual/lastName"}}}},"validation_content_type":{"summary":"Content-Type must be application/json.","value":{"error":{"code":"VALIDATION_CONTENT_TYPE","type":"VALIDATION_ERROR","message":"Content-Type must be application/json.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"idempotency_key_invalid":{"summary":"Idempotency-Key is malformed. Generate a new key matching the documented pattern and retry with that new key.","value":{"error":{"code":"IDEMPOTENCY_KEY_INVALID","type":"VALIDATION_ERROR","message":"Idempotency-Key is malformed. Generate a new key matching the documented pattern and retry with that new key.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"missing_request_context":{"summary":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","value":{"error":{"code":"MISSING_REQUEST_CONTEXT","type":"VALIDATION_ERROR","message":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"invalid_organization":{"summary":"The organization identifier on the request is malformed. Send the request through the documented gateway.","value":{"error":{"code":"INVALID_ORGANIZATION","type":"VALIDATION_ERROR","message":"The organization identifier on the request is malformed. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"The request is not authenticated.","content":{"application/json":{"examples":{"auth_token_missing":{"summary":"The Authorization header is missing. Provide a Bearer JWT.","value":{"error":{"code":"AUTH_TOKEN_MISSING","type":"AUTHENTICATION_ERROR","message":"The Authorization header is missing. Provide a Bearer JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid":{"summary":"Authorization token is invalid. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_expired":{"summary":"Authorization token has expired. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_EXPIRED","type":"AUTHENTICATION_ERROR","message":"Authorization token has expired. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid_config":{"summary":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","value":{"error":{"code":"AUTH_TOKEN_INVALID_CONFIG","type":"AUTHENTICATION_ERROR","message":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","retryStrategy":"TERMINAL","details":{}}}},"auth_api_key_invalid":{"summary":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","value":{"error":{"code":"AUTH_API_KEY_INVALID","type":"AUTHENTICATION_ERROR","message":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"The API key may not perform this operation.","content":{"application/json":{"examples":{"auth_insufficient_scope":{"summary":"The API key is missing the scope required for this operation.","value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"404":{"description":"A referenced resource does not exist in this org.","content":{"application/json":{"examples":{"bank_account_not_found":{"summary":"The account could not be verified: the identifiers are invalid, name no account, or name an account verification does not support. details.reason says which.","value":{"error":{"code":"BANK_ACCOUNT_NOT_FOUND","type":"NOT_FOUND","message":"The account could not be verified: the identifiers are invalid, name no account, or name an account verification does not support. details.reason says which.","retryStrategy":"FIX_AND_RESUBMIT","details":{"reason":"NOT_FOUND"}}}}}}}},"409":{"description":"The request conflicts with current state, or with an in-flight request using the same key.","content":{"application/json":{"examples":{"idempotency_in_flight":{"summary":"Another request with this idempotency key is currently processing. Wait for some time and retry with the same key.","value":{"error":{"code":"IDEMPOTENCY_IN_FLIGHT","type":"CONFLICT","message":"Another request with this idempotency key is currently processing. Wait for some time and retry with the same key.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}},"422":{"description":"A business rule was tripped by the request's own values, or the key was replayed with a different body.","content":{"application/json":{"examples":{"idempotency_mismatch":{"summary":"This idempotency key was previously seen with a different request body. Use a new key for a new request, or resubmit the original body verbatim.","value":{"error":{"code":"IDEMPOTENCY_MISMATCH","type":"CONFLICT","message":"This idempotency key was previously seen with a different request body. Use a new key for a new request, or resubmit the original body verbatim.","retryStrategy":"FIX_AND_RESUBMIT","details":{"originalRequestHash":"sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"}}}}}}}},"428":{"description":"The Idempotency-Key header is required for this endpoint.","content":{"application/json":{"examples":{"idempotency_key_missing":{"summary":"The Idempotency-Key header is required for this endpoint.","value":{"error":{"code":"IDEMPOTENCY_KEY_MISSING","type":"VALIDATION_ERROR","message":"The Idempotency-Key header is required for this endpoint.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"429":{"description":"The API key has exceeded its request rate limit.","content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"This API key has exceeded its request rate limit for the current window.","value":{"error":{"code":"RATE_LIMIT_EXCEEDED","type":"RATE_LIMITED","message":"This API key has exceeded its request rate limit for the current window.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}},"500":{"description":"An unexpected internal error occurred.","content":{"application/json":{"examples":{"internal_error":{"summary":"An unexpected internal error occurred. Contact support with the trace ID.","value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}},"verification_execution_failed":{"summary":"The verification could not be performed: a technical failure on the platform's or the scheme's side. The account was not judged; retry after a short backoff.","value":{"error":{"code":"VERIFICATION_EXECUTION_FAILED","type":"INTERNAL_ERROR","message":"The verification could not be performed: a technical failure on the platform's or the scheme's side. The account was not judged; retry after a short backoff.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}}},"operationId":"verifyPayoutAddress","summary":"Verify a payout address","tags":["Addresses"],"description":"Advisory: run a live penny drop against the bank account a prospective payout address would carry, without creating anything. The outcome is the HTTP status — a 200 means the account was found, and `bankAccount` comes back carrying the most the check could discover (the canonical identifiers, the account holder name corrected to the institution's registered spelling, and `isNre` where the bank disclosed it), a block that drops into `createPayoutAddress` unchanged. Only `IN_LOCAL` accounts can be verified standalone today, by `IMPS_PENNY_DROP`, which lands a one-rupee credit in the account being verified. `createPayoutAddress` still runs its own create-time verification.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255,"pattern":"^[a-zA-Z0-9_-]{1,255}$","example":"123e4567-e89b-12d3-a456-426614174000"},"description":"Unique key to ensure idempotent requests — 1-255 characters: alphanumerics, hyphens, underscores. UUID v4 recommended."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"payoutAddressType":{"type":"string","const":"BANK_ACCOUNT"},"bankAccount":{"type":"object","properties":{"routingFamily":{"type":"string","const":"IN_LOCAL"},"accountHolderName":{"type":"string","minLength":1,"maxLength":255,"examples":["Nadia Mehta"],"description":"The name you hold for this account's holder, 1 to 255 characters. Always supplied: there is no linked account to inherit a name from. The response corrects it to the institution's registered spelling."},"ifsc":{"type":"string","pattern":"^[\\sA-Z0-9]+$","examples":["HDFC 0001 234"],"description":"The 11-character IFSC. Whitespace is stripped before validation and echoed back contiguous; lowercase is rejected."},"accountNumber":{"type":"string","pattern":"^[\\s0-9]+$","examples":["5010 0234 5678 90"],"description":"The account number at that branch, 9 to 18 digits. Whitespace is stripped before validation; any other separator fails the digits-only check."}},"required":["routingFamily","accountHolderName","ifsc","accountNumber"],"additionalProperties":false,"description":"The bank account to verify, and how a payout would be routed to it."}},"required":["payoutAddressType","bankAccount"],"additionalProperties":false}}}}}},"/payments/payout-addresses/{payoutAddressId}":{"get":{"responses":{"200":{"description":"The requested payout address.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","const":"payoutAddress","examples":["payoutAddress"],"description":"The type of object represented, a fixed discriminator. Always `\"payoutAddress\"` for this resource."},"id":{"type":"string","pattern":"^pytadd_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"pytadd_NJAEqN76R7PwPfHt3oWb8R","description":"Payout address identifier."},"payoutAddressType":{"type":"string","const":"BANK_ACCOUNT"},"accountId":{"type":"string","pattern":"^acc_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"acc_h82pJGF9p7kpzb6eU326EF","description":"The account this payout address belongs to."},"bankAccount":{"anyOf":[{"type":"object","properties":{"routingFamily":{"type":"string","const":"SEPA"},"accountHolderName":{"type":"string","examples":["Nadia Holdings Pvt Ltd"],"description":"The name the receiving institution holds for this account. Not the identity's name and not compared against it."},"accountNumber":{"type":"string","pattern":"^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}$","examples":["DE89370400440532013000"],"description":"The IBAN in canonical contiguous form."},"bic":{"type":"string","pattern":"^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$","examples":["COBADEFFXXX"],"description":"The bank's BIC, ISO 9362, where the account has one. Present where the account is payable over SWIFT as well."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"Where the account is held, read from the IBAN prefix."}},"required":["routingFamily","accountHolderName","accountNumber","country"],"additionalProperties":false},{"type":"object","properties":{"routingFamily":{"type":"string","const":"SWIFT"},"accountHolderName":{"type":"string","pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","maxLength":140,"examples":["Novalia Handels GmbH"],"description":"The name the receiving institution holds for this account, up to 140 characters. Not the identity's name and not compared against it."},"accountNumber":{"type":"string","pattern":"^[A-Z0-9]{1,34}$","examples":["8801234567"],"description":"The account number at the bank, uppercase and contiguous whatever grouping it was supplied in."},"bic":{"type":"string","pattern":"^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$","examples":["PAVEGE22XXX"],"description":"The bank's BIC, ISO 9362."},"accountHolderAddress":{"type":"object","properties":{"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."},"city":{"type":"string","pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","maxLength":35,"examples":["Berlin"],"description":"Town or city."},"line1":{"type":"string","pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","maxLength":70,"examples":["Friedrichstrasse 100"],"description":"Street name and number."},"line2":{"type":"string","pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","maxLength":70,"examples":["Floor 3"],"description":"A second street line, for a floor, a unit or a care-of name."},"postalCode":{"type":"string","pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","maxLength":16,"examples":["10117"],"description":"Postal or ZIP code."},"state":{"type":"string","pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","maxLength":35,"examples":["Berlin"],"description":"State, province or region. No format is claimed, so write it as the country's own post would."}},"required":["country","city"],"additionalProperties":false,"description":"The postal address the account holder is at."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["GE"],"description":"Where the account is held, read from the BIC's country characters."}},"required":["routingFamily","accountHolderName","accountNumber","bic","accountHolderAddress","country"],"additionalProperties":false},{"type":"object","properties":{"routingFamily":{"type":"string","const":"IN_LOCAL"},"accountHolderName":{"type":"string","examples":["Nadia Holdings Pvt Ltd"],"description":"The name the receiving institution holds for this account. Not the identity's name and not compared against it."},"ifsc":{"type":"string","pattern":"^[A-Z]{4}0[A-Z0-9]{6}$","examples":["HDFC0001234"],"description":"The 11-character IFSC identifying the branch: four bank letters, a zero, then six branch characters."},"accountNumber":{"type":"string","pattern":"^[0-9]{9,18}$","examples":["50100234567890"],"description":"The account number at that branch, 9 to 18 digits."},"isNre":{"type":"boolean","examples":[false],"description":"Whether this is a repatriable NRE account. False is also what an omitted create resolves to."},"bankAccountType":{"type":"string","enum":["SAVINGS","CURRENT"],"examples":["SAVINGS"],"description":"Which kind of account this is at the institution. Defaults to `SAVINGS` when omitted."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"Where the account is held. Constant: this arm routes within India."}},"required":["routingFamily","accountHolderName","ifsc","accountNumber","isNre","country"],"additionalProperties":false},{"type":"object","properties":{"routingFamily":{"type":"string"}},"required":["routingFamily"]}],"description":"Where this bank account is, and how a payout is routed to it."},"supportedCurrencies":{"type":"array","items":{"type":"string","pattern":"^[A-Z0-9]{2,15}$"},"examples":[["EUR"]],"description":"The currencies and tokens this destination can receive. Tolerate an unrecognized value."},"supportedRails":{"type":"array","items":{"type":"string"},"examples":[["SEPA"]],"description":"The rails this destination can be paid over, following `routingFamily`. Tolerate an unrecognized value."},"status":{"type":"string","enum":["PENDING","ACTIVE","REJECTED","REQUIRES_INFORMATION"],"examples":["ACTIVE"],"description":"Whether the platform's setup of this payout address allows it to back a payout. `PENDING` while initial setup runs; `ACTIVE` is not terminal — a later blocking act moves it to `REJECTED`. Orthogonal to `archivedAt`."},"verifications":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"NAME_MATCH"},"mode":{"type":"string","examples":["SEPA_VOP"],"description":"How the account holder name was checked."},"result":{"type":"string","examples":["MATCH"],"description":"Outcome of the name check."},"providedName":{"type":"string","examples":["Novalia Handels GmbH"],"description":"The name submitted for comparison, frozen as it stood when the act ran."},"registeredName":{"type":["string","null"],"examples":["Novalia Handels GmbH"],"description":"The name the receiving institution holds. Null where the scheme returned none. Where present and different, it is the exact string to use on a replacement payout address."},"createdAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"When this act started."},"verifiedAt":{"type":["string","null"],"format":"date-time","examples":["2026-06-04T10:31:20.000Z"],"description":"When it resolved. Null while `PENDING`."},"expiresAt":{"type":["string","null"],"format":"date-time","description":"When this result goes stale, or null when it does not expire."}},"required":["kind","mode","result","providedName","registeredName","createdAt","verifiedAt","expiresAt"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string"}},"required":["kind"]}]},"description":"What the platform has established about this destination — the current act for each verification kind and mode, not a history."},"label":{"type":"string","examples":["Operating account"],"description":"Human-friendly label."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own key/value pairs, echoed back verbatim."},"archivedAt":{"type":["string","null"],"format":"date-time","examples":["2026-07-01T09:05:00.000Z"],"description":"When the client retired this payout address, or null while it is live. Terminal once set."},"createdAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"Creation timestamp."},"updatedAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:31:20.000Z"],"description":"Last-update timestamp."}},"required":["object","id","payoutAddressType","accountId","bankAccount","supportedCurrencies","supportedRails","status","verifications","archivedAt","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"]},"examples":{"default_example":{"summary":"IBAN bank account","value":{"data":{"object":"payoutAddress","id":"pytadd_NJAEqN76R7PwPfHt3oWb8R","payoutAddressType":"BANK_ACCOUNT","accountId":"acc_h82pJGF9p7kpzb6eU326EF","bankAccount":{"routingFamily":"SEPA","accountHolderName":"Novalia Handels GmbH","accountNumber":"DE89370400440532013000","country":"DE"},"supportedCurrencies":["EUR"],"supportedRails":["SEPA"],"status":"ACTIVE","verifications":[{"kind":"NAME_MATCH","mode":"SEPA_VOP","result":"MATCH","providedName":"Novalia Handels GmbH","registeredName":"Novalia Handels GmbH","createdAt":"2026-06-04T10:30:00.000Z","verifiedAt":"2026-06-04T10:31:20.000Z","expiresAt":null}],"archivedAt":null,"createdAt":"2026-06-04T10:30:00.000Z","updatedAt":"2026-06-04T10:31:20.000Z"}}}}}}},"400":{"description":"The request failed validation, or the gateway context was missing.","content":{"application/json":{"examples":{"validation_path_failed":{"summary":"URL path parameters failed validation.","value":{"error":{"code":"VALIDATION_PATH_FAILED","type":"VALIDATION_ERROR","message":"URL path parameters failed validation.","retryStrategy":"FIX_AND_RESUBMIT","details":{"issues":[{"path":"/payoutId","code":"invalid_string","message":"is not a well-formed payout id"}],"firstIssuePath":"/payoutId"}}}},"missing_request_context":{"summary":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","value":{"error":{"code":"MISSING_REQUEST_CONTEXT","type":"VALIDATION_ERROR","message":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"invalid_organization":{"summary":"The organization identifier on the request is malformed. Send the request through the documented gateway.","value":{"error":{"code":"INVALID_ORGANIZATION","type":"VALIDATION_ERROR","message":"The organization identifier on the request is malformed. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"The request is not authenticated.","content":{"application/json":{"examples":{"auth_token_missing":{"summary":"The Authorization header is missing. Provide a Bearer JWT.","value":{"error":{"code":"AUTH_TOKEN_MISSING","type":"AUTHENTICATION_ERROR","message":"The Authorization header is missing. Provide a Bearer JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid":{"summary":"Authorization token is invalid. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_expired":{"summary":"Authorization token has expired. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_EXPIRED","type":"AUTHENTICATION_ERROR","message":"Authorization token has expired. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid_config":{"summary":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","value":{"error":{"code":"AUTH_TOKEN_INVALID_CONFIG","type":"AUTHENTICATION_ERROR","message":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","retryStrategy":"TERMINAL","details":{}}}},"auth_api_key_invalid":{"summary":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","value":{"error":{"code":"AUTH_API_KEY_INVALID","type":"AUTHENTICATION_ERROR","message":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"The API key may not perform this operation.","content":{"application/json":{"examples":{"auth_insufficient_scope":{"summary":"The API key is missing the scope required for this operation.","value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"404":{"description":"The requested resource does not exist in this org.","content":{"application/json":{"examples":{"payout_address_not_found":{"summary":"No payout address with that id in this org.","value":{"error":{"code":"PAYOUT_ADDRESS_NOT_FOUND","type":"NOT_FOUND","message":"No payout address with that id in this org.","retryStrategy":"TERMINAL","details":{}}}}}}}},"429":{"description":"The API key has exceeded its request rate limit.","content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"This API key has exceeded its request rate limit for the current window.","value":{"error":{"code":"RATE_LIMIT_EXCEEDED","type":"RATE_LIMITED","message":"This API key has exceeded its request rate limit for the current window.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}},"500":{"description":"An unexpected internal error occurred.","content":{"application/json":{"examples":{"internal_error":{"summary":"An unexpected internal error occurred. Contact support with the trace ID.","value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"getPayoutAddress","summary":"Get a payout address by id","tags":["Addresses"],"description":"Retrieve a full payout address, including its `verifications[]` and the `status` derived from them.","parameters":[{"name":"payoutAddressId","in":"path","required":true,"schema":{"type":"string","examples":["pytadd_NJAEqN76R7PwPfHt3oWb8R"]},"description":"Payout address id (`pytadd_`)."}]}},"/payments/payout-addresses/{payoutAddressId}/archive":{"post":{"responses":{"200":{"description":"The archived payout address (`archivedAt` set).","headers":{"Idempotency-Replayed":{"description":"`true` when the response was served from the idempotency cache; `false` for a freshly executed request.","schema":{"type":"string","enum":["true","false"]}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","const":"payoutAddress","examples":["payoutAddress"],"description":"The type of object represented, a fixed discriminator. Always `\"payoutAddress\"` for this resource."},"id":{"type":"string","pattern":"^pytadd_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"pytadd_NJAEqN76R7PwPfHt3oWb8R","description":"Payout address identifier."},"payoutAddressType":{"type":"string","const":"BANK_ACCOUNT"},"accountId":{"type":"string","pattern":"^acc_[1-9A-HJ-NP-Za-km-z]{21,22}$","example":"acc_h82pJGF9p7kpzb6eU326EF","description":"The account this payout address belongs to."},"bankAccount":{"anyOf":[{"type":"object","properties":{"routingFamily":{"type":"string","const":"SEPA"},"accountHolderName":{"type":"string","examples":["Nadia Holdings Pvt Ltd"],"description":"The name the receiving institution holds for this account. Not the identity's name and not compared against it."},"accountNumber":{"type":"string","pattern":"^[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}$","examples":["DE89370400440532013000"],"description":"The IBAN in canonical contiguous form."},"bic":{"type":"string","pattern":"^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$","examples":["COBADEFFXXX"],"description":"The bank's BIC, ISO 9362, where the account has one. Present where the account is payable over SWIFT as well."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"Where the account is held, read from the IBAN prefix."}},"required":["routingFamily","accountHolderName","accountNumber","country"],"additionalProperties":false},{"type":"object","properties":{"routingFamily":{"type":"string","const":"SWIFT"},"accountHolderName":{"type":"string","pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","maxLength":140,"examples":["Novalia Handels GmbH"],"description":"The name the receiving institution holds for this account, up to 140 characters. Not the identity's name and not compared against it."},"accountNumber":{"type":"string","pattern":"^[A-Z0-9]{1,34}$","examples":["8801234567"],"description":"The account number at the bank, uppercase and contiguous whatever grouping it was supplied in."},"bic":{"type":"string","pattern":"^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$","examples":["PAVEGE22XXX"],"description":"The bank's BIC, ISO 9362."},"accountHolderAddress":{"type":"object","properties":{"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["DE"],"description":"The country the address is in."},"city":{"type":"string","pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","maxLength":35,"examples":["Berlin"],"description":"Town or city."},"line1":{"type":"string","pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","maxLength":70,"examples":["Friedrichstrasse 100"],"description":"Street name and number."},"line2":{"type":"string","pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","maxLength":70,"examples":["Floor 3"],"description":"A second street line, for a floor, a unit or a care-of name."},"postalCode":{"type":"string","pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","maxLength":16,"examples":["10117"],"description":"Postal or ZIP code."},"state":{"type":"string","pattern":"^[A-Za-z0-9/\\-?:().,'+ ]+$","maxLength":35,"examples":["Berlin"],"description":"State, province or region. No format is claimed, so write it as the country's own post would."}},"required":["country","city"],"additionalProperties":false,"description":"The postal address the account holder is at."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["GE"],"description":"Where the account is held, read from the BIC's country characters."}},"required":["routingFamily","accountHolderName","accountNumber","bic","accountHolderAddress","country"],"additionalProperties":false},{"type":"object","properties":{"routingFamily":{"type":"string","const":"IN_LOCAL"},"accountHolderName":{"type":"string","examples":["Nadia Holdings Pvt Ltd"],"description":"The name the receiving institution holds for this account. Not the identity's name and not compared against it."},"ifsc":{"type":"string","pattern":"^[A-Z]{4}0[A-Z0-9]{6}$","examples":["HDFC0001234"],"description":"The 11-character IFSC identifying the branch: four bank letters, a zero, then six branch characters."},"accountNumber":{"type":"string","pattern":"^[0-9]{9,18}$","examples":["50100234567890"],"description":"The account number at that branch, 9 to 18 digits."},"isNre":{"type":"boolean","examples":[false],"description":"Whether this is a repatriable NRE account. False is also what an omitted create resolves to."},"bankAccountType":{"type":"string","enum":["SAVINGS","CURRENT"],"examples":["SAVINGS"],"description":"Which kind of account this is at the institution. Defaults to `SAVINGS` when omitted."},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["IN"],"description":"Where the account is held. Constant: this arm routes within India."}},"required":["routingFamily","accountHolderName","ifsc","accountNumber","isNre","country"],"additionalProperties":false},{"type":"object","properties":{"routingFamily":{"type":"string"}},"required":["routingFamily"]}],"description":"Where this bank account is, and how a payout is routed to it."},"supportedCurrencies":{"type":"array","items":{"type":"string","pattern":"^[A-Z0-9]{2,15}$"},"examples":[["EUR"]],"description":"The currencies and tokens this destination can receive. Tolerate an unrecognized value."},"supportedRails":{"type":"array","items":{"type":"string"},"examples":[["SEPA"]],"description":"The rails this destination can be paid over, following `routingFamily`. Tolerate an unrecognized value."},"status":{"type":"string","enum":["PENDING","ACTIVE","REJECTED","REQUIRES_INFORMATION"],"examples":["ACTIVE"],"description":"Whether the platform's setup of this payout address allows it to back a payout. `PENDING` while initial setup runs; `ACTIVE` is not terminal — a later blocking act moves it to `REJECTED`. Orthogonal to `archivedAt`."},"verifications":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"NAME_MATCH"},"mode":{"type":"string","examples":["SEPA_VOP"],"description":"How the account holder name was checked."},"result":{"type":"string","examples":["MATCH"],"description":"Outcome of the name check."},"providedName":{"type":"string","examples":["Novalia Handels GmbH"],"description":"The name submitted for comparison, frozen as it stood when the act ran."},"registeredName":{"type":["string","null"],"examples":["Novalia Handels GmbH"],"description":"The name the receiving institution holds. Null where the scheme returned none. Where present and different, it is the exact string to use on a replacement payout address."},"createdAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"When this act started."},"verifiedAt":{"type":["string","null"],"format":"date-time","examples":["2026-06-04T10:31:20.000Z"],"description":"When it resolved. Null while `PENDING`."},"expiresAt":{"type":["string","null"],"format":"date-time","description":"When this result goes stale, or null when it does not expire."}},"required":["kind","mode","result","providedName","registeredName","createdAt","verifiedAt","expiresAt"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string"}},"required":["kind"]}]},"description":"What the platform has established about this destination — the current act for each verification kind and mode, not a history."},"label":{"type":"string","examples":["Operating account"],"description":"Human-friendly label."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Your own key/value pairs, echoed back verbatim."},"archivedAt":{"type":["string","null"],"format":"date-time","examples":["2026-07-01T09:05:00.000Z"],"description":"When the client retired this payout address, or null while it is live. Terminal once set."},"createdAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:30:00.000Z"],"description":"Creation timestamp."},"updatedAt":{"type":"string","format":"date-time","examples":["2026-06-04T10:31:20.000Z"],"description":"Last-update timestamp."}},"required":["object","id","payoutAddressType","accountId","bankAccount","supportedCurrencies","supportedRails","status","verifications","archivedAt","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"]},"examples":{"default_example":{"summary":"Archived payout address","value":{"data":{"object":"payoutAddress","id":"pytadd_NJAEqN76R7PwPfHt3oWb8R","payoutAddressType":"BANK_ACCOUNT","accountId":"acc_h82pJGF9p7kpzb6eU326EF","bankAccount":{"routingFamily":"SEPA","accountHolderName":"Novalia Handels GmbH","accountNumber":"DE89370400440532013000","country":"DE"},"supportedCurrencies":["EUR"],"supportedRails":["SEPA"],"status":"ACTIVE","verifications":[{"kind":"NAME_MATCH","mode":"SEPA_VOP","result":"MATCH","providedName":"Novalia Handels GmbH","registeredName":"Novalia Handels GmbH","createdAt":"2026-06-04T10:30:00.000Z","verifiedAt":"2026-06-04T10:31:20.000Z","expiresAt":null}],"archivedAt":"2026-07-01T09:05:00.000Z","createdAt":"2026-06-04T10:30:00.000Z","updatedAt":"2026-06-04T10:31:20.000Z"}}}}}}},"400":{"description":"The request failed validation, has an invalid Content-Type, the Idempotency-Key is malformed, or the gateway context was missing.","content":{"application/json":{"examples":{"validation_path_failed":{"summary":"URL path parameters failed validation.","value":{"error":{"code":"VALIDATION_PATH_FAILED","type":"VALIDATION_ERROR","message":"URL path parameters failed validation.","retryStrategy":"FIX_AND_RESUBMIT","details":{"issues":[{"path":"/payoutId","code":"invalid_string","message":"is not a well-formed payout id"}],"firstIssuePath":"/payoutId"}}}},"validation_content_type":{"summary":"Content-Type must be application/json.","value":{"error":{"code":"VALIDATION_CONTENT_TYPE","type":"VALIDATION_ERROR","message":"Content-Type must be application/json.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"idempotency_key_invalid":{"summary":"Idempotency-Key is malformed. Generate a new key matching the documented pattern and retry with that new key.","value":{"error":{"code":"IDEMPOTENCY_KEY_INVALID","type":"VALIDATION_ERROR","message":"Idempotency-Key is malformed. Generate a new key matching the documented pattern and retry with that new key.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"missing_request_context":{"summary":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","value":{"error":{"code":"MISSING_REQUEST_CONTEXT","type":"VALIDATION_ERROR","message":"The organization, user, or idempotency context every request carries was absent or unreadable. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}},"invalid_organization":{"summary":"The organization identifier on the request is malformed. Send the request through the documented gateway.","value":{"error":{"code":"INVALID_ORGANIZATION","type":"VALIDATION_ERROR","message":"The organization identifier on the request is malformed. Send the request through the documented gateway.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"401":{"description":"The request is not authenticated.","content":{"application/json":{"examples":{"auth_token_missing":{"summary":"The Authorization header is missing. Provide a Bearer JWT.","value":{"error":{"code":"AUTH_TOKEN_MISSING","type":"AUTHENTICATION_ERROR","message":"The Authorization header is missing. Provide a Bearer JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid":{"summary":"Authorization token is invalid. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_INVALID","type":"AUTHENTICATION_ERROR","message":"Authorization token is invalid. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_expired":{"summary":"Authorization token has expired. Issue a fresh JWT.","value":{"error":{"code":"AUTH_TOKEN_EXPIRED","type":"AUTHENTICATION_ERROR","message":"Authorization token has expired. Issue a fresh JWT.","retryStrategy":"TERMINAL","details":{}}}},"auth_token_invalid_config":{"summary":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","value":{"error":{"code":"AUTH_TOKEN_INVALID_CONFIG","type":"AUTHENTICATION_ERROR","message":"Authorization token configuration is invalid. Check the token's validity window and clock skew.","retryStrategy":"TERMINAL","details":{}}}},"auth_api_key_invalid":{"summary":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","value":{"error":{"code":"AUTH_API_KEY_INVALID","type":"AUTHENTICATION_ERROR","message":"The API key referenced by the token is inactive or revoked. Issue a new key in the dashboard.","retryStrategy":"TERMINAL","details":{}}}}}}}},"403":{"description":"The API key may not perform this operation.","content":{"application/json":{"examples":{"auth_insufficient_scope":{"summary":"The API key is missing the scope required for this operation.","value":{"error":{"code":"AUTH_INSUFFICIENT_SCOPE","type":"AUTHORIZATION_ERROR","message":"The API key is missing the scope required for this operation.","retryStrategy":"TERMINAL","details":{}}}}}}}},"404":{"description":"A referenced resource does not exist in this org.","content":{"application/json":{"examples":{"payout_address_not_found":{"summary":"No payout address with that id in this org.","value":{"error":{"code":"PAYOUT_ADDRESS_NOT_FOUND","type":"NOT_FOUND","message":"No payout address with that id in this org.","retryStrategy":"TERMINAL","details":{}}}}}}}},"409":{"description":"The request conflicts with current state, or with an in-flight request using the same key.","content":{"application/json":{"examples":{"idempotency_in_flight":{"summary":"Another request with this idempotency key is currently processing. Wait for some time and retry with the same key.","value":{"error":{"code":"IDEMPOTENCY_IN_FLIGHT","type":"CONFLICT","message":"Another request with this idempotency key is currently processing. Wait for some time and retry with the same key.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}},"422":{"description":"A business rule was tripped by the request's own values, or the key was replayed with a different body.","content":{"application/json":{"examples":{"idempotency_mismatch":{"summary":"This idempotency key was previously seen with a different request body. Use a new key for a new request, or resubmit the original body verbatim.","value":{"error":{"code":"IDEMPOTENCY_MISMATCH","type":"CONFLICT","message":"This idempotency key was previously seen with a different request body. Use a new key for a new request, or resubmit the original body verbatim.","retryStrategy":"FIX_AND_RESUBMIT","details":{"originalRequestHash":"sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"}}}}}}}},"428":{"description":"The Idempotency-Key header is required for this endpoint.","content":{"application/json":{"examples":{"idempotency_key_missing":{"summary":"The Idempotency-Key header is required for this endpoint.","value":{"error":{"code":"IDEMPOTENCY_KEY_MISSING","type":"VALIDATION_ERROR","message":"The Idempotency-Key header is required for this endpoint.","retryStrategy":"FIX_AND_RESUBMIT","details":{}}}}}}}},"429":{"description":"The API key has exceeded its request rate limit.","content":{"application/json":{"examples":{"rate_limit_exceeded":{"summary":"This API key has exceeded its request rate limit for the current window.","value":{"error":{"code":"RATE_LIMIT_EXCEEDED","type":"RATE_LIMITED","message":"This API key has exceeded its request rate limit for the current window.","retryStrategy":"WAIT_THEN_RETRY_SAME_KEY","details":{}}}}}}}},"500":{"description":"An unexpected internal error occurred.","content":{"application/json":{"examples":{"internal_error":{"summary":"An unexpected internal error occurred. Contact support with the trace ID.","value":{"error":{"code":"INTERNAL_ERROR","type":"INTERNAL_ERROR","message":"An unexpected internal error occurred. Contact support with the trace ID.","retryStrategy":"CHECK_STATE_THEN_RETRY","details":{}}}}}}}}},"operationId":"archivePayoutAddress","summary":"Archive a payout address","tags":["Addresses"],"description":"Soft-archive a payout address. Idempotent, no body: sets `archivedAt` and returns the address; re-archiving an already-archived address returns 200 with the original `archivedAt` unchanged. An archived address is hidden from listPayoutAddresses by default and cannot back new payouts, but stays retrievable by id; a payout already in flight against it keeps running to a terminal state. The record is otherwise immutable, so this and create are the only writes — correcting anything means creating a replacement and archiving this one.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255,"pattern":"^[a-zA-Z0-9_-]{1,255}$","example":"123e4567-e89b-12d3-a456-426614174000"},"description":"Unique key to ensure idempotent requests — 1-255 characters: alphanumerics, hyphens, underscores. UUID v4 recommended."},{"name":"payoutAddressId","in":"path","required":true,"schema":{"type":"string","examples":["pytadd_NJAEqN76R7PwPfHt3oWb8R"]},"description":"Payout address id."}]}}}}