openapi: 3.1.0 info: title: Axiym Payment API version: 0.1.0 description: |- Use the Payment API to make cross-border business payments on behalf of your clients. The partner access token identifies the partnership that owns each account, quote, payment, Party Data Map, and webhook subscription. The sender and receiver are supplied in full with each payment and do not need to be onboarded as Axiym clients. Party Data Maps and webhook subscriptions are partnership-owned resources. A Party Data Map can therefore be reused across the clients represented by the same partnership. The public Payload Mapping Tool produces portable sender-and-receiver mapping JSON. Submit the reviewed definition through the authenticated Party Data Maps endpoints, then test it with representative payment data before creating a payment. Values that use an Axiym-controlled vocabulary are normalized for each payment before the prepared instruction is returned for confirmation. servers: - url: https://partner-api.sandbox.axiym.io/api/v1 description: Sandbox - url: https://partner-api.axiym.io/api/v1 description: Production security: - Default: [] tags: - name: Auth description: OAuth 2.0 client credentials authentication for the partnership. - name: Accounts description: Partner-owned Axiym accounts whose existing balances can fund payments. - name: Corridors description: Payment routes available to the partnership. - name: Quotes description: Time-limited payment quotes funded by partner-owned accounts. - name: Payouts description: Cross-border payments made by the partner on behalf of its clients. - name: Party Data Maps description: Partnership-owned reusable mappings for sender and receiver field paths. - name: Webhook Subscriptions description: Partnership-owned webhook subscriptions and signing keys. x-tagGroups: - name: Foundation tags: - Auth - Accounts - Webhook Subscriptions - name: Payment API tags: - Corridors - Quotes - Payouts paths: /oauth/token: post: tags: - Auth summary: Get access token description: Creates an OAuth 2.0 access token using your client credentials. Request the `PAYMENT` scope and send the returned token as a bearer token on subsequent Payment API requests. deprecated: false security: [] parameters: - $ref: "#/components/parameters/RequestId" requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: client_id: type: string examples: - eb81336d-378a-4ab8-8c0e-a2f39ac0e87a example: eb81336d-378a-4ab8-8c0e-a2f39ac0e87a client_secret: type: string examples: - d5a9df2f93dba5f3def1e1d7585f476f054fe955a02e6b152f3145adce49c6ffc94be6ea7a2d7385f111f17541c1fe0239e8902b33e41fed7610098995081d3e59b2fe7ae2877dcbcdcd04c14cdfa298e85a079066d0b1e0eaaa978110ba300c7e8341b68c0d9a8deb03122f4504e6317b53b473c5917e4ae073422241f59120 example: d5a9df2f93dba5f3def1e1d7585f476f054fe955a02e6b152f3145adce49c6ffc94be6ea7a2d7385f111f17541c1fe0239e8902b33e41fed7610098995081d3e59b2fe7ae2877dcbcdcd04c14cdfa298e85a079066d0b1e0eaaa978110ba300c7e8341b68c0d9a8deb03122f4504e6317b53b473c5917e4ae073422241f59120 grant_type: type: string examples: - client_credentials example: client_credentials scope: type: string enum: - PAYMENT examples: - PAYMENT example: PAYMENT example: client_id: eb81336d-378a-4ab8-8c0e-a2f39ac0e87a client_secret: d5a9df2f93dba5f3def1e1d7585f476f054fe955a02e6b152f3145adce49c6ffc94be6ea7a2d7385f111f17541c1fe0239e8902b33e41fed7610098995081d3e59b2fe7ae2877dcbcdcd04c14cdfa298e85a079066d0b1e0eaaa978110ba300c7e8341b68c0d9a8deb03122f4504e6317b53b473c5917e4ae073422241f59120 grant_type: client_credentials scope: PAYMENT responses: "201": description: "" content: application/json: schema: type: object properties: token_type: type: string expires_in: type: integer access_token: type: string scope: type: string required: - token_type - expires_in - access_token - scope headers: {} "400": $ref: "#/components/responses/BadRequest" description: "" "401": $ref: "#/components/responses/Unauthorized" description: "" "500": $ref: "#/components/responses/InternalError" description: "" /party-data-maps: get: tags: - Party Data Maps operationId: listPartyDataMaps summary: List party data maps description: Returns the immutable party data maps stored for your partnership. A map may be reused across payments created by the same partnership. parameters: - $ref: "#/components/parameters/RequestId" - $ref: "#/components/parameters/First" - $ref: "#/components/parameters/After" responses: "200": description: Party data map page content: application/json: schema: $ref: "#/components/schemas/PartyDataMapPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "422": $ref: "#/components/responses/InvalidParams" "500": $ref: "#/components/responses/InternalError" post: tags: - Party Data Maps operationId: createPartyDataMap summary: Store a party data map description: |- Validates and stores a portable party-data-map definition for the authenticated partnership. The definition is normally exported by the [Payload Mapping Tool](/payment-api/tools/payload-mapper), but any compatible JSON document may be submitted. The authenticated access token determines ownership; do not include a partner identifier in the map. Axiym canonicalizes the accepted definition, calculates `contentHash`, and returns an immutable `partyDataMapId`. Changes must be stored as a new party data map. parameters: - $ref: "#/components/parameters/RequestId" - $ref: "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreatePartyDataMapRequest" responses: "201": description: Party data map stored content: application/json: schema: $ref: "#/components/schemas/PartyDataMap" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "422": $ref: "#/components/responses/InvalidParams" "500": $ref: "#/components/responses/InternalError" /party-data-maps/{partyDataMapId}: get: tags: - Party Data Maps operationId: getPartyDataMap summary: Get a party data map description: Returns one immutable party data map owned by your partnership, including the exact stored definition and its content hash. parameters: - $ref: "#/components/parameters/PartyDataMapId" - $ref: "#/components/parameters/RequestId" responses: "200": description: Party data map found content: application/json: schema: $ref: "#/components/schemas/PartyDataMap" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/InvalidParams" "500": $ref: "#/components/responses/InternalError" /webhooks/subscriptions: get: summary: List webhook subscriptions description: Returns the active webhook endpoints registered for your partnership. Use pagination to retrieve additional subscriptions. deprecated: false tags: - Webhook Subscriptions parameters: - $ref: "#/components/parameters/RequestId" - name: first in: query description: Maximum number of items to return (page size). required: false schema: type: integer default: 10 maximum: 100 examples: - 20 - name: after in: query description: Cursor for the next page, from the previous response's pageInfo.endCursor. required: false schema: type: string examples: - eyJvZmZzZXQiOjI1fQ== responses: "200": description: "" content: application/json: schema: type: object properties: nodes: type: array items: $ref: "#/components/schemas/Subscription" pageInfo: $ref: "#/components/schemas/PageInfo" required: - nodes - pageInfo headers: {} "400": $ref: "#/components/responses/BadRequest" description: "" "401": $ref: "#/components/responses/Unauthorized" description: "" "403": $ref: "#/components/responses/Forbidden" description: Forbidden "422": $ref: "#/components/responses/InvalidParams" description: "" "500": $ref: "#/components/responses/InternalError" description: "" security: - Default: [] post: summary: Create webhook subscription description: |- Registers a publicly reachable HTTPS endpoint for webhook deliveries. A subscription receives every event available to your partnership; per-event filters are not supported. Store the returned `subscriptionId` so you can test or disable the subscription later. deprecated: false tags: - Webhook Subscriptions parameters: - $ref: "#/components/parameters/RequestId" - $ref: "#/components/parameters/IdempotencyKey" requestBody: content: application/json: schema: type: object properties: endpoint: type: string title: "" description: URL of the endpoint to subscribe to notifications. Must be publicly accessible, use HTTPS, and respond with a 2XX status to a POST request. required: - endpoint responses: "201": description: "" content: application/json: schema: $ref: "#/components/schemas/Subscription" headers: {} "400": $ref: "#/components/responses/BadRequest" description: "" "401": $ref: "#/components/responses/Unauthorized" description: "" "403": $ref: "#/components/responses/Forbidden" description: Forbidden "422": $ref: "#/components/responses/InvalidParams" description: "" "500": $ref: "#/components/responses/InternalError" description: "" security: - Default: [] /webhooks/subscriptions/{subscriptionId}/tests: post: tags: - Webhook Subscriptions summary: Test webhook subscription description: |- Requests a signed test delivery for the selected subscription. Use it to verify endpoint reachability, signature validation, event persistence, and a successful `2xx` acknowledgement. A successful API response means Axiym accepted the test request. It does not prove that your endpoint processed the delivery successfully. deprecated: false parameters: - name: subscriptionId in: path description: Subscription identifier (UUID). required: true schema: type: string examples: - "" - $ref: "#/components/parameters/RequestId" - $ref: "#/components/parameters/IdempotencyKey" responses: "201": description: "" content: application/json: schema: $ref: "#/components/schemas/RequestStatus" headers: {} "400": $ref: "#/components/responses/BadRequest" description: "" "401": $ref: "#/components/responses/Unauthorized" description: "" "403": $ref: "#/components/responses/Forbidden" description: Forbidden "404": $ref: "#/components/responses/NotFound" description: "" "422": $ref: "#/components/responses/InvalidParams" description: "" "500": $ref: "#/components/responses/InternalError" description: "" security: - Default: [] /webhooks/subscriptions/{subscriptionId}: delete: tags: - Webhook Subscriptions summary: Disable webhook subscription description: Disables the selected webhook subscription. The endpoint stops receiving new deliveries, and the subscription no longer appears when listing active subscriptions. deprecated: false parameters: - name: subscriptionId in: path description: Subscription identifier (UUID). required: true schema: type: string format: uuid examples: - "" - $ref: "#/components/parameters/RequestId" responses: "200": description: "" content: application/json: schema: $ref: "#/components/schemas/Subscription" headers: {} "400": $ref: "#/components/responses/BadRequest" description: "" "401": $ref: "#/components/responses/Unauthorized" description: "" "403": $ref: "#/components/responses/Forbidden" description: Forbidden "404": $ref: "#/components/responses/NotFound" description: "" "422": $ref: "#/components/responses/InvalidParams" description: "" "500": $ref: "#/components/responses/InternalError" description: "" security: - Default: [] /webhooks/public-keys/{publicKeyId}: get: tags: - Webhook Subscriptions summary: Get webhook public key description: |- Returns the Ed25519 public key identified by the webhook's `X-Key-Id` header. Use the key to verify `X-Signature` against the raw request body. Cache keys by `publicKeyId`. Retrieve the key again when a delivery contains an identifier you do not recognize. deprecated: false parameters: - name: publicKeyId in: path description: Public key identifier (UUID). required: true schema: type: string examples: - "" - $ref: "#/components/parameters/RequestId" responses: "200": description: "" content: application/json: schema: $ref: "#/components/schemas/PublicKey" headers: {} "400": $ref: "#/components/responses/BadRequest" description: "" "401": $ref: "#/components/responses/Unauthorized" description: "" "403": $ref: "#/components/responses/Forbidden" description: Forbidden "404": $ref: "#/components/responses/NotFound" description: "" "422": $ref: "#/components/responses/InvalidParams" description: "" "500": $ref: "#/components/responses/InternalError" description: "" security: - Default: [] /accounts: get: tags: - Accounts summary: List accounts operationId: listAccounts description: |- Returns the Axiym accounts belonging to the authenticated partnership. Each account holds a balance in one currency on one payment rail. Use the optional filters to narrow the results by currency or account status. parameters: - $ref: "#/components/parameters/RequestId" - name: first in: query description: Maximum number of items to return (page size). required: false schema: type: integer default: 10 maximum: 100 examples: - 10 - name: after in: query description: Cursor for the next page, from the previous response's pageInfo.endCursor. required: false schema: type: string examples: - eyJvZmZzZXQiOjI1fQ== - name: currency in: query description: Filter by currency. schema: $ref: "#/components/schemas/Currency" examples: - USD - name: status in: query description: Filter by status. schema: $ref: "#/components/schemas/AccountStatus" examples: - ACTIVE responses: "200": description: Accounts. content: application/json: schema: type: object required: - nodes properties: nodes: type: array items: $ref: "#/components/schemas/Account" examples: Accounts: summary: Bank and wallet accounts value: nodes: - accountId: 5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e currency: USD paymentRails: ZENUS_BANK balance: "48250.00" status: ACTIVE - accountId: 8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a currency: USDT paymentRails: TRON balance: "12500.00" status: ACTIVE "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/InvalidParams" "500": $ref: "#/components/responses/InternalError" /accounts/{accountId}: get: tags: - Accounts summary: Get account operationId: getAccount description: Returns the current balance, currency, payment rail, and status of one partner-owned Axiym account. parameters: - $ref: "#/components/parameters/AccountId" - $ref: "#/components/parameters/RequestId" responses: "200": description: Account. content: application/json: schema: $ref: "#/components/schemas/Account" examples: Bank account: summary: Bank account value: accountId: 5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e currency: USD paymentRails: ZENUS_BANK balance: "48250.00" status: ACTIVE Wallet account: summary: Wallet account value: accountId: 8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a currency: USDT paymentRails: TRON balance: "12500.00" status: ACTIVE "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/InvalidParams" "500": $ref: "#/components/responses/InternalError" /accounts/{accountId}/statement: get: tags: - Accounts summary: Get account statement operationId: getAccountStatement description: |- Returns the posted credits and debits for one partner-owned account, including its opening balance, closing balance, and movement totals. Use the statement to reconcile the partnership's payments and other ledger movements. The balances follow this equation: `openingBalance + totalCredited - totalDebited = closingBalance` If `from` and `to` are omitted, the statement covers the account's full history. parameters: - $ref: "#/components/parameters/AccountId" - $ref: "#/components/parameters/RequestId" - $ref: "#/components/parameters/First" - $ref: "#/components/parameters/After" - name: from in: query required: false description: First calendar day of the period (UTC), inclusive. The period bounds apply to the posting time of the movement. schema: type: string format: date examples: - 2026-06-01 - name: to in: query required: false description: "Last calendar day of the period (UTC), inclusive. Adjacent statements chain without gaps: June `to=2026-06-30` is followed by July `from=2026-07-01`." schema: type: string format: date examples: - 2026-06-30 - name: type in: query required: false description: Filter by credit or debit direction. schema: $ref: "#/components/schemas/StatementEntryType" examples: - DEBIT responses: "200": description: Account statement for the period. content: application/json: schema: type: object required: - openingBalance - closingBalance - totalCredited - totalDebited - nodes - pageInfo properties: openingBalance: allOf: - $ref: "#/components/schemas/Decimal" description: Balance as of the start of the period (`from`). examples: - "47750.00" closingBalance: allOf: - $ref: "#/components/schemas/Decimal" description: Balance as of the end of the period (`to`). examples: - "48250.00" totalCredited: allOf: - $ref: "#/components/schemas/Decimal" description: Sum of credits within the period. examples: - "1005.00" totalDebited: allOf: - $ref: "#/components/schemas/Decimal" description: Sum of debits within the period. examples: - "505.00" nodes: type: array items: $ref: "#/components/schemas/StatementEntry" pageInfo: $ref: "#/components/schemas/PageInfo" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/InvalidParams" "500": $ref: "#/components/responses/InternalError" /corridors: get: tags: - Corridors operationId: listCorridors summary: List payout corridors description: |- Lists the payment corridors configured for the partnership and reports whether each corridor is currently available. Axiym derives the origin country from the partner's onboarded location. Use the optional filters to narrow the results by sell currency, destination country, buy currency, or payout method. Without filters, the endpoint returns every configured corridor. parameters: - $ref: "#/components/parameters/RequestId" - $ref: "#/components/parameters/SellCurrency" - $ref: "#/components/parameters/DestinationCountry" - $ref: "#/components/parameters/BuyCurrency" - $ref: "#/components/parameters/PayoutMethodQuery" responses: "200": description: Payout corridors content: application/json: schema: type: object required: - nodes properties: nodes: type: array items: $ref: "#/components/schemas/Corridor" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/InvalidParams" "500": $ref: "#/components/responses/InternalError" /corridors/details: get: tags: - Corridors operationId: getCorridorDetails summary: Get payout corridor details description: |- Returns one corridor configured for the partnership together with its destination-specific requirements and compliance information. Requirements that apply to every payment are not repeated. Axiym derives the origin country from the partner's onboarded location. parameters: - $ref: "#/components/parameters/RequestId" - $ref: "#/components/parameters/SellCurrencyRequired" - $ref: "#/components/parameters/DestinationCountryRequired" - $ref: "#/components/parameters/BuyCurrencyRequired" - $ref: "#/components/parameters/PayoutMethodRequired" responses: "200": description: Payout corridor details content: application/json: schema: $ref: "#/components/schemas/CorridorDetails" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/InvalidParams" "500": $ref: "#/components/responses/InternalError" /quotes: get: tags: - Quotes operationId: listQuotes summary: List quotes description: |- Returns the payment quotes created by the partnership, ordered from newest to oldest. Use pagination to retrieve additional results. parameters: - $ref: "#/components/parameters/AccountIdQuery" - $ref: "#/components/parameters/RequestId" - $ref: "#/components/parameters/First" - $ref: "#/components/parameters/After" responses: "200": description: Quote page content: application/json: schema: type: object required: - nodes - pageInfo properties: nodes: type: array items: $ref: "#/components/schemas/Quote" pageInfo: $ref: "#/components/schemas/PageInfo" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "422": $ref: "#/components/responses/InvalidParams" "500": $ref: "#/components/responses/InternalError" post: tags: - Quotes operationId: createQuote summary: Create a quote description: |- Creates a time-limited payment quote using a partner-owned account and the partnership's corridor access. The quote fixes the financial terms used by the later payment. Create and confirm the payment before the quote expires. parameters: - $ref: "#/components/parameters/RequestId" - $ref: "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/QuoteRequest" responses: "201": description: Resource created content: application/json: schema: $ref: "#/components/schemas/Quote" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/InvalidParams" "500": $ref: "#/components/responses/InternalError" /quotes/{quoteId}: get: tags: - Quotes operationId: getQuote summary: Get a quote description: |- Returns one payment quote belonging to the partnership, including its financial terms, status, and expiry time. parameters: - $ref: "#/components/parameters/QuoteId" - $ref: "#/components/parameters/RequestId" responses: "200": description: Quote found content: application/json: schema: $ref: "#/components/schemas/Quote" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/InvalidParams" "500": $ref: "#/components/responses/InternalError" /payouts: get: tags: - Payouts operationId: listPayouts summary: List payouts description: |- Returns the payments created by the partnership. Use the optional filters to narrow the results by funding account, client reference, or payment status. parameters: - $ref: "#/components/parameters/AccountIdQuery" - $ref: "#/components/parameters/ClientReferenceQuery" - $ref: "#/components/parameters/PayoutStatusQuery" - $ref: "#/components/parameters/RequestId" - $ref: "#/components/parameters/First" - $ref: "#/components/parameters/After" responses: "200": description: Payout page content: application/json: schema: type: object required: - nodes - pageInfo properties: nodes: type: array items: $ref: "#/components/schemas/Payout" pageInfo: $ref: "#/components/schemas/PageInfo" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "422": $ref: "#/components/responses/InvalidParams" "500": $ref: "#/components/responses/InternalError" post: tags: - Payouts operationId: createPayout summary: Create a payout description: |- Prepares a payment using a partner-owned account and active quote. **Choose the party-data structure** - Without `partyDataMapId`, `sender` and `receiver` use Axiym's documented field structure. - With `partyDataMapId`, `sender` and `receiver` may use the partner-defined structure associated with that map. Axiym maps their field paths before validation. **Normalization and validation** Values that use an Axiym-controlled vocabulary are normalized for this payment. Exact Axiym values pass through unchanged. Axiym then validates the complete instruction against the baseline and corridor requirements. **Review before committing** The response contains the prepared instruction and its final normalized values. Its status is `PENDING_CONFIRMATION`, and no funds move until the payment is confirmed. parameters: - $ref: "#/components/parameters/RequestId" - $ref: "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PayoutRequest" responses: "201": description: Payout prepared and awaiting confirmation content: application/json: schema: $ref: "#/components/schemas/PayoutDetails" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/InvalidParams" "500": $ref: "#/components/responses/InternalError" /payouts/tests: post: tags: - Payouts operationId: testPayout summary: Test a payout description: |- Validates representative payout data without first creating a quote. Use it with or without a Party Data Map to check party data, controlled-value normalization, and country- or corridor-specific requirements. Without `partyDataMapId`, the party objects use Axiym's documented structure. With `partyDataMapId`, Axiym first applies the stored Party Data Map. In both modes, controlled values across sender, receiver, and transaction data are normalized and the result is validated against baseline and destination requirements selected by `context`. This test does not create a quote or payout, check a rate or amount limit, reserve funds, or persist the submitted data. A structurally valid request returns `200` even when `valid` is `false`. parameters: - $ref: "#/components/parameters/RequestId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PayoutTestRequest" responses: "200": description: Payout-payload normalization and validation completed content: application/json: schema: $ref: "#/components/schemas/PayoutTestResult" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/InvalidParams" "500": $ref: "#/components/responses/InternalError" /payouts/{payoutId}: get: tags: - Payouts operationId: getPayout summary: Get a payout description: |- Returns one payment belonging to the partnership, including its prepared payment data and current normalized status. Use this endpoint to review the payment before confirmation or retrieve its latest state afterward. parameters: - $ref: "#/components/parameters/PayoutId" - $ref: "#/components/parameters/RequestId" responses: "200": description: Payout found content: application/json: schema: $ref: "#/components/schemas/PayoutDetails" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/InvalidParams" "500": $ref: "#/components/responses/InternalError" /payouts/{payoutId}/confirm: post: tags: - Payouts operationId: confirmPayout summary: Confirm a payout description: |- Confirms the exact prepared payment and starts compliance review, approval, settlement, and execution. **Funding effect** Axiym reserves `totalPayable` in the partner's funding account. The reserved amount cannot fund another payment. It becomes an account debit at settlement, or is released if the payment ends before settlement. **Confirmation requirements** - The payment must have status `PENDING_CONFIRMATION`. - Confirmation must occur before `confirmationExpiresAt`. - The available balance must cover `totalPayable`. Confirmation consumes the referenced quote. If the prepared payment or quote has expired, create a new payment. parameters: - $ref: "#/components/parameters/PayoutId" - $ref: "#/components/parameters/RequestId" - $ref: "#/components/parameters/IdempotencyKey" responses: "202": description: Payout confirmed and accepted for processing content: application/json: schema: $ref: "#/components/schemas/PayoutDetails" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "422": $ref: "#/components/responses/InvalidParams" "500": $ref: "#/components/responses/InternalError" components: securitySchemes: Default: type: http scheme: bearer bearerFormat: JWT headers: RequestId: description: Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request. schema: type: string format: uuid examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 parameters: RequestId: name: X-Request-Id in: header required: false description: Optional identifier for tracing a request end to end. A UUID is recommended. Axiym returns it in the `X-Request-Id` response header and records it in logs. If omitted, Axiym generates one. Include it when contacting support. schema: type: string format: uuid examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 IdempotencyKey: name: Idempotency-Key in: header required: true description: A unique key that makes a resource-creating or funds-moving request safe to retry. Reusing the key returns the original result instead of creating a duplicate. A UUID is recommended. schema: type: string maxLength: 255 examples: - a1b2c3d4-e5f6-7890-abcd-ef1234567890 First: name: first in: query description: Maximum number of items to return (page size). schema: type: integer minimum: 1 maximum: 100 default: 20 examples: - 20 After: name: after in: query description: Cursor for the next page, from the previous response's pageInfo.endCursor. schema: type: string examples: - eyJvZmZzZXQiOjI1fQ== AccountId: name: accountId in: path required: true schema: type: string format: uuid examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 description: Account identifier (UUID). AccountIdQuery: name: accountId in: query schema: type: string format: uuid QuoteId: name: quoteId in: path required: true schema: type: string format: uuid PayoutId: name: payoutId in: path required: true schema: type: string format: uuid PartyDataMapId: name: partyDataMapId in: path required: true description: Immutable party-data-map identifier (UUID). schema: type: string format: uuid DestinationCountry: name: destinationCountry in: query required: false description: Filter by ISO 3166-1 alpha-2 destination country. schema: $ref: "#/components/schemas/CountryCode" SellCurrency: name: sellCurrency in: query required: false description: Filter by the currency sold from the funding account. Fiat and supported digital currencies are accepted. schema: $ref: "#/components/schemas/Currency" BuyCurrency: name: buyCurrency in: query required: false description: Filter by the ISO 4217 fiat currency bought and delivered to the beneficiary. Digital currencies are not valid payout currencies. schema: $ref: "#/components/schemas/FiatCurrency" PayoutMethodQuery: name: payoutMethod in: query required: false description: Filter by payout method. Currently, the only supported value is BANK. schema: $ref: "#/components/schemas/PayoutMethod" SellCurrencyRequired: name: sellCurrency in: query required: true description: Currency sold from the funding account. Fiat and supported digital currencies are accepted. schema: $ref: "#/components/schemas/Currency" DestinationCountryRequired: name: destinationCountry in: query required: true description: ISO 3166-1 alpha-2 destination country. schema: $ref: "#/components/schemas/CountryCode" BuyCurrencyRequired: name: buyCurrency in: query required: true description: ISO 4217 fiat currency bought and delivered to the beneficiary. Digital currencies are not valid payout currencies. schema: $ref: "#/components/schemas/FiatCurrency" PayoutMethodRequired: name: payoutMethod in: query required: true description: Payout method. Currently, the only supported value is BANK. schema: $ref: "#/components/schemas/PayoutMethod" ClientReferenceQuery: name: clientReference in: query schema: type: string PayoutStatusQuery: name: status in: query schema: $ref: "#/components/schemas/PayoutStatus" responses: BadRequest: description: "" content: application/json: schema: type: object properties: code: type: integer description: HTTP status code, duplicated in the body. message: type: string description: Human-readable message describing the error. errors: type: - object - "null" properties: message: type: string description: Additional error details; null when there are none. required: - code - message - errors examples: Malformed JSON body: summary: Malformed JSON body value: code: 400 message: Bad Request errors: message: "Failed to parse the request body as JSON: expected value at line 1 column 5" Generic: summary: Generic value: code: 400 message: Invalid cursor errors: null headers: X-Request-Id: description: Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request. schema: type: string format: uuid examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unauthorized: description: "" content: application/json: schema: type: object properties: code: type: integer description: HTTP status code, duplicated in the body. message: type: string description: Human-readable message describing the error. errors: type: - object - "null" description: Additional error details; null when there are none. required: - code - message - errors examples: Example 1: summary: Example 1 value: code: 401 message: Unauthorized errors: null headers: X-Request-Id: description: Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request. schema: type: string format: uuid examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 Forbidden: description: Forbidden content: application/json: schema: type: object properties: code: type: integer description: HTTP status code, duplicated in the body. message: type: string description: Human-readable message describing the error. errors: type: - object - "null" description: Additional error details; null when there are none. required: - code - message - errors examples: Example 1: summary: Example 1 value: code: 403 message: Forbidden errors: null headers: X-Request-Id: description: Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request. schema: type: string format: uuid examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 NotFound: description: "" content: application/json: schema: type: object properties: code: type: integer description: HTTP status code, duplicated in the body. message: type: string description: "Human-readable message: either the generic 'Not Found' or a domain-specific one such as 'Client Not Found'." errors: type: - object - "null" description: Additional error details; null when there are none. required: - code - message - errors examples: Generic: summary: Generic value: code: 404 message: Not Found errors: null Client not found: summary: Client not found value: code: 404 message: Client Not Found errors: null headers: X-Request-Id: description: Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request. schema: type: string format: uuid examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 InvalidParams: description: "The request failed validation or a business rule. Validation failures return `errors` keyed by request field. Business rejections return `errors: null` and explain the reason in `message`." content: application/json: schema: type: object properties: code: type: integer description: HTTP status code, duplicated in the body. message: type: string description: "`Invalid Parameters` for validation failures; the rejection reason otherwise." errors: type: - object - "null" description: For validation failures, keys follow the request fields and values contain field errors or nested errors. Business rejections return `null`. additionalProperties: $ref: "#/components/schemas/ValidationFieldErrors" required: - code - message - errors examples: Flat field errors: summary: Flat field errors value: code: 422 message: Invalid Parameters errors: legalEntityName: - code: length message: null params: value: "" min: 1 currency: - code: invalid_currency message: null params: value: ZZZ Nested struct errors: summary: Nested struct errors value: code: 422 message: Invalid Parameters errors: legalAddress: country: - code: invalid_country message: null params: value: INVALID postalCode: - code: length message: null params: value: "" min: 1 List item errors: summary: List item errors value: code: 422 message: Invalid Parameters errors: authorizedDirectors: "0": firstName: - code: length message: null params: value: "" min: 1 email: - code: email message: null params: value: not-an-email Custom validator: summary: Custom validator value: code: 422 message: Invalid Parameters errors: disbursementAccount: - code: disbursement_account_required message: null params: value: null Business rejection: summary: Business rejection value: code: 422 message: Documents Not Accepted errors: null headers: X-Request-Id: description: Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request. schema: type: string format: uuid examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 InternalError: description: "" content: application/json: schema: type: object properties: code: type: integer description: HTTP status code, duplicated in the body. message: type: string description: Human-readable message describing the error. errors: type: - object - "null" description: Additional error details; null when there are none. required: - code - message - errors examples: Example 1: summary: Example 1 value: code: 500 message: Internal Error errors: null headers: X-Request-Id: description: Unique id of this request (echoed from the request, or generated when omitted). Recorded in Axiym logs — quote it when contacting support about a failed request. schema: type: string format: uuid examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 schemas: AccessToken: type: object required: - token_type - expires_in - access_token - scope properties: token_type: type: string examples: - Bearer expires_in: type: integer examples: - 3600 access_token: type: string scope: type: string examples: - PAYMENT Currency: type: string description: Currency code — ISO 4217 (e.g. USD, EUR) or a supported digital currency (USDT, USDC). examples: - USD FiatCurrency: type: string pattern: ^[A-Z]{3}$ description: ISO 4217 fiat currency used for local payout. Digital currencies are not valid buy currencies. examples: - PHP CountryCode: type: string pattern: ^[A-Z]{2}$ description: ISO 3166-1 alpha-2 country code. examples: - US Decimal: type: string description: Decimal number serialized as a string to preserve precision. examples: - "1000.00" Money: type: object additionalProperties: false required: - amount - currency properties: amount: $ref: "#/components/schemas/Decimal" currency: $ref: "#/components/schemas/Currency" FiatMoney: type: object additionalProperties: false required: - amount - currency properties: amount: $ref: "#/components/schemas/Decimal" currency: $ref: "#/components/schemas/FiatCurrency" PageInfo: type: object properties: hasNextPage: type: boolean description: When paginating forwards, are there more items? examples: - true endCursor: type: string description: When paginating forwards, the cursor to continue. examples: - eyJvZmZzZXQiOjI1fQ== required: - hasNextPage PaymentRailsCode: type: string description: Payment rail code the account settles on (e.g. `ZENUS_BANK`, `TRON`). examples: - ZENUS_BANK AccountStatus: type: string enum: - ACTIVE - SUSPENDED - CLOSED examples: - ACTIVE Account: type: object description: An Axiym account that holds one currency on one payment rail. Its available balance funds payments. Account funding is arranged outside the Payment API. required: - accountId - currency - paymentRails - balance - status properties: accountId: type: string format: uuid description: Account identifier (UUID). examples: - 5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e currency: $ref: "#/components/schemas/Currency" description: Account currency. examples: - USD paymentRails: $ref: "#/components/schemas/PaymentRailsCode" description: Rail the account settles on. examples: - ZENUS_BANK balance: allOf: - $ref: "#/components/schemas/Decimal" description: Current balance. examples: - "48250.00" status: $ref: "#/components/schemas/AccountStatus" description: Account status. examples: - ACTIVE StatementEntryType: type: string description: Direction of movement on the account. enum: - CREDIT - DEBIT examples: - DEBIT StatementEntry: type: object description: A posted ledger movement on an account. Entries are returned in posting order and carry the running balance, so consecutive entries reconcile against each other. required: - entryId - accountId - type - amount - currency - balanceAfter - occurredAt properties: entryId: type: string format: uuid description: Ledger entry identifier (UUID). examples: - 7f9a2d1c-8b31-4f59-9e2f-1d63c4a27b12 accountId: type: string format: uuid description: Account identifier (UUID). examples: - 8f1d4a2c-3b5e-4c7a-9d1f-2a6b8c0e4d3a type: $ref: "#/components/schemas/StatementEntryType" description: Credit or debit direction. examples: - DEBIT amount: allOf: - $ref: "#/components/schemas/Decimal" description: Positive movement amount in the account currency; direction is in `type`. examples: - "505.00" currency: $ref: "#/components/schemas/Currency" description: Account currency. examples: - USD balanceBefore: allOf: - $ref: "#/components/schemas/Decimal" description: Running balance before this movement. examples: - "48250.00" balanceAfter: allOf: - $ref: "#/components/schemas/Decimal" description: Running balance after this movement. examples: - "47745.00" relatedResourceType: type: string description: Type of the linked money movement; absent for ledger adjustments with no linked resource. enum: - DEPOSIT - WITHDRAWAL - CONVERSION - PAYOUT examples: - PAYOUT relatedResourceId: type: string format: uuid description: Identifier of the linked resource, where present. examples: - 9b4e2a1c-6d3f-4a8e-bc7d-1f2a3b4c5d6e occurredAt: type: string format: date-time description: When the movement occurred. Formatted in ISO 8601. examples: - 2026-06-14T20:07:31Z Corridor: type: object description: A configured payout route from the partner's onboarded origin country and sell currency to a destination country, buy currency, and payout method. required: - originCountry - sellCurrency - destinationCountry - buyCurrency - payoutMethod - availability properties: originCountry: $ref: "#/components/schemas/CountryCode" description: Derived from the partner's onboarded location. examples: - SG sellCurrency: $ref: "#/components/schemas/Currency" description: Currency sold from the funding account. examples: - USD destinationCountry: $ref: "#/components/schemas/CountryCode" description: Destination country for the payout. examples: - PH buyCurrency: $ref: "#/components/schemas/FiatCurrency" description: Fiat currency bought and delivered to the receiver. examples: - PHP payoutMethod: $ref: "#/components/schemas/PayoutMethod" description: Method used to deliver the payout. examples: - BANK availability: $ref: "#/components/schemas/CorridorAvailability" description: Current availability of the payout route. examples: - AVAILABLE CorridorAvailability: type: string enum: - AVAILABLE - UNAVAILABLE description: Current availability of the corridor. A payout quote can only be created when the corridor is AVAILABLE. examples: - AVAILABLE CorridorDetails: allOf: - $ref: "#/components/schemas/Corridor" - type: object required: - amountLimits - requirements properties: amountLimits: $ref: "#/components/schemas/CorridorAmountLimits" description: Minimum and maximum payout amounts expressed in the corridor's buy currency. requirements: $ref: "#/components/schemas/CorridorRequirements" description: Country-playbook requirements and constraints for this corridor. Baseline payout fields are not repeated. CorridorAmountLimits: type: object description: Permitted payout range expressed in the corridor's buy currency. A quote outside this range is rejected. required: - minimum - maximum properties: minimum: $ref: "#/components/schemas/FiatMoney" description: Smallest buy amount that can be paid through the corridor. maximum: $ref: "#/components/schemas/FiatMoney" description: Largest buy amount that can be paid through the corridor. examples: - minimum: amount: "100.00" currency: PHP maximum: amount: "500000.00" currency: PHP PayoutMethod: type: string enum: - BANK description: Method used to deliver the payout. Currently only bank payouts are supported. examples: - BANK QuoteRequest: type: object additionalProperties: false required: - accountId - buyCurrency - destinationCountry - payoutMethod - amount - amountBasis properties: accountId: type: string format: uuid description: A funded Axiym account enabled for payouts. The sell currency is derived from this account. buyCurrency: $ref: "#/components/schemas/FiatCurrency" description: Fiat currency to deliver to the receiver. destinationCountry: $ref: "#/components/schemas/CountryCode" description: Destination country for the payout. payoutMethod: $ref: "#/components/schemas/PayoutMethod" amount: $ref: "#/components/schemas/Decimal" description: Amount expressed in the currency selected by amountBasis. amountBasis: type: string enum: - sell - buy description: Indicates whether amount is expressed in the sell or buy currency. QuoteStatus: type: string enum: - ACTIVE - EXPIRED - USED - CANCELED ExchangeRate: type: object additionalProperties: false required: - base - quote - rate properties: base: $ref: "#/components/schemas/Currency" quote: $ref: "#/components/schemas/Currency" rate: $ref: "#/components/schemas/Decimal" Quote: type: object required: - quoteId - accountId - status - originCountry - destinationCountry - payoutMethod - sell - buy - fee - totalPayable - rate - requestedAt - expiresAt properties: quoteId: type: string format: uuid accountId: type: string format: uuid status: $ref: "#/components/schemas/QuoteStatus" originCountry: $ref: "#/components/schemas/CountryCode" description: Derived from the partner's onboarded location. examples: - SG destinationCountry: $ref: "#/components/schemas/CountryCode" examples: - PH payoutMethod: $ref: "#/components/schemas/PayoutMethod" sell: $ref: "#/components/schemas/Money" description: Amount sold from the funding account currency, excluding the fee. buy: $ref: "#/components/schemas/FiatMoney" description: Amount bought and delivered to the beneficiary. fee: $ref: "#/components/schemas/Money" totalPayable: $ref: "#/components/schemas/Money" description: Total amount payable from the funding account, including the fee. rate: $ref: "#/components/schemas/ExchangeRate" requestedAt: type: string format: date-time expiresAt: type: string format: date-time examples: - quoteId: 978490c4-4227-4a75-9820-5f90482bb78b accountId: d96b90c1-b69e-4f5d-8154-46ecfcad8d0a status: ACTIVE originCountry: SG destinationCountry: PH payoutMethod: BANK sell: amount: "1000.00" currency: USD buy: amount: "56500.00" currency: PHP fee: amount: "10.00" currency: USD totalPayable: amount: "1010.00" currency: USD rate: base: USD quote: PHP rate: "56.5000" requestedAt: 2026-08-04T05:07:00Z expiresAt: 2026-08-04T05:08:00Z CorridorRequirements: type: object description: Country-playbook additions and overrides for the corridor. This does not repeat fields that are required for every payout. required: - fields - complianceInformation properties: fields: type: array description: Fields whose requiredness, format, validation or normalization is specific to this corridor. items: $ref: "#/components/schemas/CorridorFieldRequirement" complianceInformation: type: array description: Destination-specific compliance information that may affect the payout data Axiym validates. items: type: string CorridorFieldRequirement: type: object required: - field - label - requiredness - format - description properties: field: type: string description: Partner-facing payment-data field path. examples: - receiver.bank.clearingCode label: type: string description: Human-readable field name. examples: - Bank routing number requiredness: type: string enum: - REQUIRED - OPTIONAL description: Requiredness for this corridor. format: type: string description: Human-readable value format. examples: - 9 digits pattern: type: string description: Regular expression used to validate the value when one applies. examples: - ^[0-9]{9}$ normalization: type: string description: Normalization applied before validation when one applies. examples: - Remove whitespace description: type: string description: Additional guidance for supplying the field. PartyAddress: type: object additionalProperties: false required: - addressLine - city - country properties: addressLine: type: string minLength: 1 city: type: string minLength: 1 postalCode: type: string region: type: string country: $ref: "#/components/schemas/CountryCode" PartyContact: type: object additionalProperties: false required: - email - phoneNumber properties: email: type: string format: email phoneNumber: type: string pattern: ^\+[1-9][0-9]{7,14}$ description: International phone number in E.164 format. PartyIdentificationType: type: string description: Partner-facing classification of a party identification document or identifier. Corridor requirements determine which types are accepted for a specific payout. enum: - REGISTRATION_NUMBER - TAX_ID - VAT_NUMBER - NATIONAL_ID - PASSPORT - DRIVER_LICENSE - RESIDENCE_PERMIT - LEI - OTHER examples: - REGISTRATION_NUMBER PartyIdentification: type: object additionalProperties: false required: - type - number properties: type: $ref: "#/components/schemas/PartyIdentificationType" number: type: string minLength: 1 country: $ref: "#/components/schemas/CountryCode" issueDate: type: string format: date expiryDate: type: string format: date PartyIdentificationInput: type: object description: Identification data supplied while preparing a payout. The type value is normalized to Axiym's closed PartyIdentificationType vocabulary for the prepared instruction. additionalProperties: false required: - type - number properties: type: type: string minLength: 1 description: How you describe the identification type. Provide an accepted Axiym value or descriptive text; Axiym normalizes it before validation. examples: - company registration number number: type: string minLength: 1 country: $ref: "#/components/schemas/CountryCode" issueDate: type: string format: date expiryDate: type: string format: date UboDesignation: type: string description: Relationship of the individual to the sender. Every entry in the sender.ubos array represents an ultimate beneficial owner. enum: - ubo examples: - ubo UltimateBeneficialOwner: type: object additionalProperties: false required: - firstName - lastName - designation - nationalities - address - id properties: firstName: type: string minLength: 1 lastName: type: string minLength: 1 designation: $ref: "#/components/schemas/UboDesignation" nationalities: type: array minItems: 1 uniqueItems: true items: $ref: "#/components/schemas/CountryCode" address: $ref: "#/components/schemas/PartyAddress" id: $ref: "#/components/schemas/PartyIdentification" UltimateBeneficialOwnerInput: type: object additionalProperties: false required: - firstName - lastName - designation - nationalities - address - id properties: firstName: type: string minLength: 1 lastName: type: string minLength: 1 designation: type: string minLength: 1 description: How you describe the individual's ownership or control relationship. Axiym normalizes it to the final UBO designation before validation. examples: - ultimate beneficial owner nationalities: type: array minItems: 1 uniqueItems: true items: $ref: "#/components/schemas/CountryCode" address: $ref: "#/components/schemas/PartyAddress" id: $ref: "#/components/schemas/PartyIdentificationInput" AxiymSender: type: object description: The normalized sender returned with a prepared payout. Fields with an allowed-value list contain their final Axiym values. additionalProperties: false required: - name - countryOfIncorporation - address - contact - id - ubos properties: name: type: string minLength: 1 countryOfIncorporation: $ref: "#/components/schemas/CountryCode" address: $ref: "#/components/schemas/PartyAddress" contact: $ref: "#/components/schemas/PartyContact" id: $ref: "#/components/schemas/PartyIdentification" ubos: type: array minItems: 1 items: $ref: "#/components/schemas/UltimateBeneficialOwner" AxiymSenderInput: type: object description: Sender data using Axiym's field structure. Fields with an allowed-value list may use descriptive partner terms; Axiym normalizes them before validation. additionalProperties: false required: - name - countryOfIncorporation - address - contact - id - ubos properties: name: type: string minLength: 1 countryOfIncorporation: $ref: "#/components/schemas/CountryCode" address: $ref: "#/components/schemas/PartyAddress" contact: $ref: "#/components/schemas/PartyContact" id: $ref: "#/components/schemas/PartyIdentificationInput" ubos: type: array minItems: 1 items: $ref: "#/components/schemas/UltimateBeneficialOwnerInput" BankAccountType: type: string description: Functional type of the receiver's destination bank account. enum: - CURRENT - SAVINGS - CHECKING - CORPORATE - OTHER examples: - CURRENT ReceiverBankAccount: type: object description: The normalized destination bank account returned with a prepared payout. Axiym derives the clearing system and account currency. additionalProperties: false required: - accountHolderName - accountType - accountNumber - name - country properties: accountHolderName: type: string minLength: 1 accountType: $ref: "#/components/schemas/BankAccountType" accountNumber: type: string minLength: 1 name: type: string minLength: 1 country: $ref: "#/components/schemas/CountryCode" bic: type: string pattern: ^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$ description: ISO 9362 BIC, when required for the corridor. clearingCode: type: string description: Local clearing or routing code, when required for the corridor. ReceiverBankAccountInput: type: object description: Destination bank-account details. `accountType` may use descriptive partner terms and is normalized before validation. Axiym derives the clearing system and account currency. additionalProperties: false required: - accountHolderName - accountType - accountNumber - name - country properties: accountHolderName: type: string minLength: 1 accountType: type: string minLength: 1 description: How you describe the bank-account type. Provide an accepted Axiym value or descriptive text; Axiym normalizes it before validation. examples: - business checking account accountNumber: type: string minLength: 1 name: type: string minLength: 1 country: $ref: "#/components/schemas/CountryCode" bic: type: string pattern: ^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$ description: ISO 9362 BIC, when required for the corridor. clearingCode: type: string description: Local clearing or routing code, when required for the corridor. ReceiverRelationship: type: string description: Provider-neutral business relationship between the receiver and sender. enum: - SUPPLIER - CUSTOMER - CONTRACTOR - SERVICE_PROVIDER - GROUP_COMPANY - SUBSIDIARY - PARENT - INVESTMENT_TARGET - DEBTOR - CREDITOR - OTHER examples: - SUPPLIER AxiymReceiver: type: object description: The normalized receiver returned with a prepared payout. Fields with an allowed-value list contain their final Axiym values. The corridor determines any extra identification and routing requirements. additionalProperties: false required: - name - countryOfIncorporation - relationship - address - contact - bank properties: name: type: string minLength: 1 countryOfIncorporation: $ref: "#/components/schemas/CountryCode" relationship: $ref: "#/components/schemas/ReceiverRelationship" address: $ref: "#/components/schemas/PartyAddress" contact: $ref: "#/components/schemas/PartyContact" id: $ref: "#/components/schemas/PartyIdentification" bank: $ref: "#/components/schemas/ReceiverBankAccount" AxiymReceiverInput: type: object description: Receiver data using Axiym's field structure. Fields with an allowed-value list may use descriptive partner terms; Axiym normalizes them before validation. The corridor determines any extra identification and routing requirements. additionalProperties: false required: - name - countryOfIncorporation - relationship - address - contact - bank properties: name: type: string minLength: 1 countryOfIncorporation: $ref: "#/components/schemas/CountryCode" relationship: type: string minLength: 1 description: How you describe the receiver's relationship to the sender. Provide an accepted Axiym value or descriptive text; Axiym normalizes it before validation. examples: - vendor providing IT services address: $ref: "#/components/schemas/PartyAddress" contact: $ref: "#/components/schemas/PartyContact" id: $ref: "#/components/schemas/PartyIdentificationInput" bank: $ref: "#/components/schemas/ReceiverBankAccountInput" PartyDataMapDefinition: type: object description: Portable, partner-independent mapping definition exported by the Payload Mapping Tool. It contains field paths, but no partner identifier, sample party values, or enum translations. additionalProperties: false required: - schemaVersion - targetModelVersion - sender - receiver properties: schemaVersion: type: string description: Version of the portable party-data-map document format. examples: - "1" targetModelVersion: type: string description: Version of Axiym's partner-facing party fields used when the map was authored. examples: - 2026-08 sender: $ref: "#/components/schemas/PartyDataMapSection" receiver: $ref: "#/components/schemas/PartyDataMapSection" PartyDataMapSection: type: object description: Declarative field mappings for one party object. Source paths use the partner's JSON structure; target paths use Axiym's documented sender or receiver structure. additionalProperties: false required: - mappings properties: mappings: type: object minProperties: 1 description: Source paths keyed to their Axiym target paths. Array paths use `[]`, for example `owners[].fullName`. additionalProperties: type: string minLength: 1 examples: - company.legalName: sender.name company.registrationCountry: sender.countryOfIncorporation CreatePartyDataMapRequest: type: object additionalProperties: false required: - name - definition properties: name: type: string minLength: 1 maxLength: 120 description: Partner-facing name for the stored map. examples: - Acme ERP v2 description: type: string maxLength: 500 description: Optional note describing the source structures or integration that uses this map. definition: $ref: "#/components/schemas/PartyDataMapDefinition" PartyDataMapStatus: type: string description: Lifecycle state of a stored party data map. enum: - ACTIVE - ARCHIVED PartyDataMap: type: object description: Immutable party data map stored for the authenticated partnership. additionalProperties: false required: - partyDataMapId - name - definition - version - status - contentHash - createdAt properties: partyDataMapId: type: string format: uuid name: type: string description: type: string definition: $ref: "#/components/schemas/PartyDataMapDefinition" version: type: integer minimum: 1 description: Stored resource version. A changed definition is stored as a new immutable party data map. examples: - 1 status: $ref: "#/components/schemas/PartyDataMapStatus" contentHash: type: string pattern: ^sha256:[a-f0-9]{64}$ description: SHA-256 digest of Axiym's canonical serialization of the map definition. examples: - sha256:8a4b22d6421e6349c74b6814880d19c9c96a73427bb42d088d057f15c17b37e7 createdAt: type: string format: date-time PartyDataMapPage: type: object additionalProperties: false required: - nodes - pageInfo properties: nodes: type: array items: $ref: "#/components/schemas/PartyDataMap" pageInfo: $ref: "#/components/schemas/PageInfo" MappedPartyData: type: object description: Sender or receiver data using the partner-defined structure linked to `partyDataMapId`. The saved map translates field paths. Axiym then normalizes allowed-value fields and validates the result using the same party-data requirements. minProperties: 1 additionalProperties: true SupportingDocumentType: type: string description: Axiym classification of evidence supplied with a payout. enum: - PASSPORT - NATIONAL_ID - DRIVER_LICENSE - RESIDENCE_PERMIT - PROOF_OF_ADDRESS - UTILITY_BILL - BANK_STATEMENT - TAX_CERTIFICATE - CERTIFICATE_OF_INCORPORATION - REGISTRY_EXTRACT - ARTICLES_OF_ASSOCIATION - SHAREHOLDER_REGISTER - DIRECTOR_REGISTER - UBO_DECLARATION - POWER_OF_ATTORNEY - BOARD_RESOLUTION - REGULATORY_LICENSE - BUSINESS_LICENSE - FINANCIAL_STATEMENT - AUDIT_REPORT - SOURCE_OF_FUNDS - INVOICE - CONTRACT - PURCHASE_ORDER - PAYROLL_FILE - LOAN_AGREEMENT - SHIPPING_DOCUMENT - CUSTOMS_DECLARATION - OTHER examples: - INVOICE TransactionPurpose: type: string description: Axiym's classification of the business reason for the payment. enum: - GOODS_PURCHASE - SERVICES_PAYMENT - SALARY_PAYROLL - CONTRACTOR_PAYMENT - RENT_LEASE - LOAN_DISBURSEMENT - LOAN_REPAYMENT - INTERCOMPANY_TRANSFER - TREASURY_MANAGEMENT - TAX_PAYMENT - INVESTMENT - REFUND - OTHER examples: - GOODS_PURCHASE SourceOfFunds: type: string description: Axiym's classification of where the payment funds originated. enum: - BUSINESS_REVENUE - BANK_ACCOUNT_BALANCE - SAVINGS - SALARY_INCOME - INVESTMENT_PROCEEDS - SALE_OF_ASSET - LOAN_PROCEEDS - CAPITAL_CONTRIBUTION - SHAREHOLDER_FUNDS - GRANT_OR_DONATION - INHERITANCE - OTHER examples: - BUSINESS_REVENUE SupportingDocumentInput: type: object description: Supporting evidence supplied while preparing a payout. The document type is normalized to Axiym's closed SupportingDocumentType vocabulary for the prepared instruction. additionalProperties: false required: - documentType - documentContentType - documentData properties: documentType: type: string minLength: 1 description: How you describe the supporting document. Provide an accepted Axiym value or descriptive text; Axiym normalizes it before validation. examples: - supplier bill documentDescription: type: string documentContentType: type: string examples: - application/pdf documentData: type: string contentEncoding: base64 documentDataBackside: type: string contentEncoding: base64 TransactionInput: type: object description: Transaction details and supporting evidence for the payment. Purpose, source of funds, and document types may use descriptive partner terms; Axiym normalizes them before validation. additionalProperties: false required: - purpose - sourceOfFunds - supportingDocuments properties: purpose: type: string minLength: 1 description: The business reason for the payment. Provide an accepted Axiym value or descriptive text; Axiym normalizes it before validation. examples: - monthly payment for software development sourceOfFunds: type: string minLength: 1 description: Where the payment funds originated. Provide an accepted Axiym value or descriptive text; Axiym normalizes it before validation. examples: - income from normal business operations reference: type: string supportingDocuments: type: array minItems: 1 items: $ref: "#/components/schemas/SupportingDocumentInput" AxiymPartyPayoutRequest: type: object title: Axiym party structure description: Use this variant when `sender` and `receiver` follow Axiym's documented field structure. Do not provide `partyDataMapId`. Axiym normalizes allowed-value fields before validation. additionalProperties: false required: - quoteId - clientReference - transaction - sender - receiver properties: quoteId: type: string format: uuid clientReference: type: string description: Partner's unique, idempotent reference to the payout. transaction: $ref: "#/components/schemas/TransactionInput" sender: $ref: "#/components/schemas/AxiymSenderInput" receiver: $ref: "#/components/schemas/AxiymReceiverInput" MappedPartyPayoutRequest: type: object title: Mapped partner party structure description: Use this variant when `sender` and `receiver` follow the partner-defined structures linked to `partyDataMapId`. The saved map translates party-field paths. `transaction` still uses Axiym's structure, and Axiym normalizes allowed-value fields before validation. additionalProperties: false required: - quoteId - clientReference - partyDataMapId - transaction - sender - receiver properties: quoteId: type: string format: uuid clientReference: type: string description: Partner's unique, idempotent reference to the payout. partyDataMapId: type: string format: uuid description: Immutable saved mapping applied to sender and receiver only. transaction: $ref: "#/components/schemas/TransactionInput" sender: $ref: "#/components/schemas/MappedPartyData" receiver: $ref: "#/components/schemas/MappedPartyData" PayoutRequest: description: Choose one party-data mode. Without `partyDataMapId`, use Axiym's documented `sender` and `receiver` structure. With `partyDataMapId`, use the partner structures linked to that map. Both modes normalize allowed-value fields and apply the same payment and corridor validation. oneOf: - $ref: "#/components/schemas/AxiymPartyPayoutRequest" - $ref: "#/components/schemas/MappedPartyPayoutRequest" PayoutTestContext: type: object description: Non-financial context used to select the applicable destination requirements. Axiym derives the origin country from the partner's onboarded location. additionalProperties: false required: - sellCurrency - destinationCountry - buyCurrency - payoutMethod properties: sellCurrency: $ref: "#/components/schemas/Currency" description: Currency that would fund the payment. destinationCountry: $ref: "#/components/schemas/CountryCode" description: Country where the beneficiary would be paid. buyCurrency: $ref: "#/components/schemas/FiatCurrency" description: Local fiat currency that would be delivered to the beneficiary. payoutMethod: $ref: "#/components/schemas/PayoutMethod" examples: - sellCurrency: USD destinationCountry: PH buyCurrency: PHP payoutMethod: BANK AxiymPayoutTestRequest: type: object title: Axiym party structure description: Tests a complete representative payload whose sender and receiver already use Axiym's documented field structure. additionalProperties: false required: - context - transaction - sender - receiver properties: context: $ref: "#/components/schemas/PayoutTestContext" transaction: $ref: "#/components/schemas/TransactionInput" sender: $ref: "#/components/schemas/AxiymSenderInput" receiver: $ref: "#/components/schemas/AxiymReceiverInput" MappedPayoutTestRequest: type: object title: Mapped partner party structure description: Tests a complete representative payload after applying the stored Party Data Map to sender and receiver. Transaction data continues to use Axiym's documented structure. additionalProperties: false required: - context - partyDataMapId - transaction - sender - receiver properties: context: $ref: "#/components/schemas/PayoutTestContext" partyDataMapId: type: string format: uuid description: Stored Party Data Map applied to the representative sender and receiver objects. transaction: $ref: "#/components/schemas/TransactionInput" sender: $ref: "#/components/schemas/MappedPartyData" receiver: $ref: "#/components/schemas/MappedPartyData" PayoutTestRequest: description: Representative payout data used to test party structure, optional Party Data Map application, controlled-value normalization, and destination-specific validation without creating a quote or payout. `clientReference` is omitted because no resource is created. oneOf: - $ref: "#/components/schemas/AxiymPayoutTestRequest" - $ref: "#/components/schemas/MappedPayoutTestRequest" PayoutTestResult: type: object description: Normalized representative payout data and its validation result. Nothing in this response is a quote or payout instruction, and no submitted payload data is persisted. additionalProperties: false required: - valid - context - normalizedData - normalizations - warnings - errors properties: valid: type: boolean description: True when the mapped and normalized payload satisfies the baseline and destination requirements selected by context. context: $ref: "#/components/schemas/PayoutTestContext" partyDataMapId: type: string format: uuid description: Party Data Map used by the test. Omitted when the submitted parties used Axiym's structure. normalizedData: $ref: "#/components/schemas/PayoutTestNormalizedData" normalizations: type: array description: Controlled values changed during normalization. Exact Axiym values that passed through unchanged are not included. items: $ref: "#/components/schemas/PayoutTestNormalization" warnings: type: array description: Non-blocking mapping or validation observations, such as unused source fields. items: $ref: "#/components/schemas/PayoutTestWarning" errors: description: Mapping or validation failures keyed by the mapped payout-data path; null when `valid` is true. oneOf: - type: object additionalProperties: $ref: "#/components/schemas/ValidationFieldErrors" - type: "null" PayoutTestNormalizedData: type: object description: Mapped and normalized sender, receiver, and transaction data produced during a test. It can be incomplete when validation fails, so it is less restrictive than `PreparedPaymentData`. additionalProperties: false required: - sender - receiver - transaction properties: sender: type: object additionalProperties: true receiver: type: object additionalProperties: true transaction: type: object additionalProperties: true PayoutTestNormalization: type: object description: One supplied value that was normalized to a controlled Axiym value during the test. additionalProperties: false required: - path - inputValue - normalizedValue - vocabulary properties: path: type: string description: Axiym payout-data path containing the normalized value. examples: - transaction.purpose inputValue: type: string examples: - monthly software development normalizedValue: type: string description: Final allowed Axiym value. examples: - SERVICES_PAYMENT vocabulary: type: string description: Controlled vocabulary used for normalization. examples: - TransactionPurpose PayoutTestWarning: type: object additionalProperties: false required: - code - message properties: code: type: string examples: - UNUSED_SOURCE_FIELD path: type: string description: Partner source path or mapped Axiym path associated with the warning. message: type: string PayoutStatus: type: string description: Normalized payout lifecycle status. PENDING_CONFIRMATION means the prepared payout has not yet been committed and cannot move funds or be submitted for execution. enum: - PENDING_CONFIRMATION - PROCESSING - APPROVED - SETTLED - SUBMITTED - COMPLETED - REJECTED - FAILED - RETURNED - CANCELED - EXPIRED Payout: type: object required: - payoutId - quoteId - accountId - clientReference - status - payoutMethod - sell - buy - fee - totalPayable - confirmationExpiresAt - createdAt - updatedAt properties: payoutId: type: string format: uuid quoteId: type: string format: uuid accountId: type: string format: uuid clientReference: type: string status: $ref: "#/components/schemas/PayoutStatus" payoutMethod: $ref: "#/components/schemas/PayoutMethod" sell: $ref: "#/components/schemas/Money" description: Amount sold from the funding account currency, excluding the fee. buy: $ref: "#/components/schemas/FiatMoney" description: Amount bought and delivered to the beneficiary. fee: $ref: "#/components/schemas/Money" totalPayable: $ref: "#/components/schemas/Money" description: Total amount payable from the funding account, including the fee. confirmationExpiresAt: type: string format: date-time description: Deadline for confirming a payout with status PENDING_CONFIRMATION. Derived from the referenced quote's expiry. confirmedAt: type: string format: date-time description: Present after the partner has confirmed the prepared payout. failure: $ref: "#/components/schemas/PayoutFailure" createdAt: type: string format: date-time updatedAt: type: string format: date-time PayoutDetails: allOf: - $ref: "#/components/schemas/Payout" - type: object required: - paymentData properties: paymentData: $ref: "#/components/schemas/PreparedPaymentData" description: A payment with its prepared party and transaction data. `paymentData` contains the normalized instruction that confirmation commits. PreparedPaymentData: type: object additionalProperties: false required: - sender - receiver - transaction properties: sender: $ref: "#/components/schemas/AxiymSender" receiver: $ref: "#/components/schemas/AxiymReceiver" transaction: $ref: "#/components/schemas/PreparedTransactionData" PreparedTransactionData: type: object additionalProperties: false required: - purpose - sourceOfFunds - supportingDocuments properties: purpose: $ref: "#/components/schemas/TransactionPurpose" sourceOfFunds: $ref: "#/components/schemas/SourceOfFunds" reference: type: string supportingDocuments: type: array minItems: 1 items: $ref: "#/components/schemas/PreparedSupportingDocument" PreparedSupportingDocument: type: object additionalProperties: false required: - documentType - documentContentType - sha256 - hasBackside properties: documentType: $ref: "#/components/schemas/SupportingDocumentType" documentDescription: type: string documentContentType: type: string examples: - application/pdf sha256: type: string pattern: ^[a-f0-9]{64}$ description: SHA-256 digest of the decoded document content. The API does not echo base64 document data in payout responses. hasBackside: type: boolean description: Indicates whether backside document content was supplied. PayoutFailure: type: object required: - code - message properties: code: type: string message: type: string CreateSubscriptionRequest: type: object required: - endpoint properties: endpoint: type: string title: "" description: URL of the endpoint to subscribe to notifications. Must be publicly accessible, use HTTPS, and respond with a 2XX status to a POST request. Subscription: type: object properties: subscriptionId: type: string description: Subscription identifier (UUID). format: uuid examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 endpoint: type: string description: URL of the endpoint to subscribe to notifications. Must be publicly accessible, use HTTPS, and respond with a 2XX status to a POST request. title: "" format: uri examples: - https://api.acme.example/webhooks required: - subscriptionId - endpoint RequestStatus: type: object properties: status: type: string description: Request status. examples: - OK default: OK enum: - OK required: - status PublicKey: type: object properties: publicKeyId: type: string description: Public key identifier (UUID). format: uuid examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 active: type: boolean description: Indicates whether the key is active examples: - true algorithm: type: string description: Encryption algorithm examples: - ED25519 publicKey: type: string description: Public Key examples: - string createdAt: type: string format: date-time description: Creation timestamp. Formatted in ISO 8601. examples: - 2026-06-23T14:05:09Z required: - publicKeyId - algorithm - publicKey - createdAt - active Error: type: object required: - code - message - errors properties: code: type: integer description: HTTP status code, duplicated in the body. message: type: string description: Human-readable message describing the error. errors: type: - object - "null" description: Additional error details; null when there are none. ValidationErrorResponse: type: object required: - code - message - errors properties: code: type: integer description: HTTP status code, duplicated in the body. message: type: string description: Invalid Parameters for validation failures; the rejection reason otherwise. errors: type: - object - "null" description: Validation failures are keyed by field name. Business rejections return null. additionalProperties: $ref: "#/components/schemas/ValidationFieldErrors" ValidationFieldErrors: description: Nested validation errors keyed by field name or array index. Leaf values are arrays of `ValidationError` objects. oneOf: - type: array items: $ref: "#/components/schemas/ValidationError" - type: object additionalProperties: $ref: "#/components/schemas/ValidationFieldErrors" properties: {} ValidationError: type: object description: One field-level validation error. required: - code - params properties: code: type: string description: Validation rule code (e.g. 'length', 'email', 'invalid_currency', 'disbursement_account_required'). examples: - AXI000221 message: type: - string - "null" description: Human-readable message. examples: - string params: type: object description: Rule-specific parameters. Always includes `value` (the offending input). Additional keys depend on the rule (e.g. `min`, `max` for length). properties: value: description: The submitted value that failed validation. examples: - string