openapi: 3.1.0 info: title: Axiym Payment API version: 0.1.0 description: |- Use the Payment API to make cross-border payments to beneficiaries, whether paying for your organization or on behalf of a client. Each outgoing payment is represented by a payout resource. Create a payout with the funding account, amount, and complete payment instruction. Axiym returns the prepared instruction and time-limited commercial terms. Review and confirm the payout before the terms expire to reserve funds and start processing. Your credentials determine which accounts, payouts, Payment Data Maps, and webhook subscriptions your integration can access. 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 authentication for your integration." - name: Accounts description: "Axiym accounts and balances available to fund payments." - name: Corridors description: "Payment corridors available to your integration." - name: Payouts description: "Create, review, confirm, and track outgoing payments." - name: Payment Data Maps description: "Reusable party field mappings and reviewed value translations, stored as immutable definitions for mapped payout requests." - name: Webhook Subscriptions description: "Webhook endpoint registration, test deliveries, and signing keys." x-tagGroups: - name: Foundation tags: - Auth - Accounts - Webhook Subscriptions - name: Payment API tags: - Corridors - Payment Data Maps - 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: "Access token issued." 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: "Malformed or invalid request." "401": $ref: "#/components/responses/Unauthorized" description: "Missing, expired, or invalid credentials." "500": $ref: "#/components/responses/InternalError" description: "Unexpected server error." /payment-data-maps: get: tags: - Payment Data Maps operationId: listPaymentDataMaps summary: List payment data maps description: "Returns Payment Data Maps stored for your integration. Omit status to include both active and archived maps, or filter by ACTIVE or ARCHIVED." parameters: - $ref: "#/components/parameters/RequestId" - $ref: "#/components/parameters/First" - $ref: "#/components/parameters/After" - name: status in: query required: false description: Filter maps by status. Omit to include both active and archived maps. schema: $ref: "#/components/schemas/PaymentDataMapStatus" responses: "200": description: Payment data map page content: application/json: schema: $ref: "#/components/schemas/PaymentDataMapPage" "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: - Payment Data Maps operationId: createPaymentDataMap summary: Store a payment data map description: |- Validates and stores rules for mapping a complete payment object: payment and party fields, document connections, reviewed value translations, sender handling, and amount resolution. Download or copy the definition from [Smart Payload Mapping](/payment-api/tools/payload-mapper-v2), then submit it as definition alongside a name. Access is determined by your credentials. Storage validates the schema version, safe paths, known targets, unique field sources and targets, compatible array associations, document connection rules, and allowed translation outputs. Value rules must match a configured field or document-type connection and must not redefine an existing Axiym code. Invalid or conflicting rules are rejected with HTTP 422. Actual source data, document matches, and corridor requirements are validated when the map is used. New maps have status ACTIVE. The response includes paymentDataMapId and contentHash. Definitions are immutable: store changed rules as a new map and use its new identifier. parameters: - $ref: "#/components/parameters/RequestId" - $ref: "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreatePaymentDataMapRequest" responses: "201": description: Payment data map stored content: application/json: schema: $ref: "#/components/schemas/PaymentDataMap" "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" /payment-data-maps/{paymentDataMapId}: get: tags: - Payment Data Maps operationId: getPaymentDataMap summary: Get a payment data map description: "Returns an active or archived Payment Data Map accessible to your integration, including its status, immutable definition, and content hash." parameters: - $ref: "#/components/parameters/PaymentDataMapId" - $ref: "#/components/parameters/RequestId" responses: "200": description: Payment data map found content: application/json: schema: $ref: "#/components/schemas/PaymentDataMap" "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" /payment-data-maps/{paymentDataMapId}/archive: post: tags: - Payment Data Maps operationId: archivePaymentDataMap summary: Archive a payment data map description: |- Archives a Payment Data Map accessible to your integration, preventing its use in new mapped payouts. Returns the map with status ARCHIVED. Repeating the request for an archived map returns the same archived map successfully. The map identifier, definition, and content hash are retained for audit and troubleshooting. Archived maps remain retrievable by identifier and appear in unfiltered or ARCHIVED-filtered listings. Payouts already created with the map retain their prepared instruction and can still be confirmed and processed. Archiving does not cancel or change those payouts. parameters: - $ref: "#/components/parameters/PaymentDataMapId" - $ref: "#/components/parameters/RequestId" responses: "200": description: Payment data map archived, or already archived. content: application/json: schema: allOf: - $ref: "#/components/schemas/PaymentDataMap" - type: object properties: status: type: string enum: - ARCHIVED "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "500": $ref: "#/components/responses/InternalError" /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: "Active webhook subscriptions." 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: "Malformed or invalid request." "401": $ref: "#/components/responses/Unauthorized" description: "Missing, expired, or invalid credentials." "403": $ref: "#/components/responses/Forbidden" description: Forbidden "422": $ref: "#/components/responses/InvalidParams" description: "Request validation or a business precondition failed." "500": $ref: "#/components/responses/InternalError" description: "Unexpected server error." 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: "Public HTTPS endpoint for webhook deliveries. Return `2xx` after durably accepting each event." required: - endpoint responses: "201": description: "Webhook subscription created." content: application/json: schema: $ref: "#/components/schemas/Subscription" headers: {} "400": $ref: "#/components/responses/BadRequest" description: "Malformed or invalid request." "401": $ref: "#/components/responses/Unauthorized" description: "Missing, expired, or invalid credentials." "403": $ref: "#/components/responses/Forbidden" description: Forbidden "422": $ref: "#/components/responses/InvalidParams" description: "Request validation or a business precondition failed." "500": $ref: "#/components/responses/InternalError" description: "Unexpected server error." 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: "Test delivery request accepted." content: application/json: schema: $ref: "#/components/schemas/RequestStatus" headers: {} "400": $ref: "#/components/responses/BadRequest" description: "Malformed or invalid request." "401": $ref: "#/components/responses/Unauthorized" description: "Missing, expired, or invalid credentials." "403": $ref: "#/components/responses/Forbidden" description: Forbidden "404": $ref: "#/components/responses/NotFound" description: "Resource not found or not accessible to this integration." "422": $ref: "#/components/responses/InvalidParams" description: "Request validation or a business precondition failed." "500": $ref: "#/components/responses/InternalError" description: "Unexpected server error." 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: "Webhook subscription disabled." content: application/json: schema: $ref: "#/components/schemas/Subscription" headers: {} "400": $ref: "#/components/responses/BadRequest" description: "Malformed or invalid request." "401": $ref: "#/components/responses/Unauthorized" description: "Missing, expired, or invalid credentials." "403": $ref: "#/components/responses/Forbidden" description: Forbidden "404": $ref: "#/components/responses/NotFound" description: "Resource not found or not accessible to this integration." "422": $ref: "#/components/responses/InvalidParams" description: "Request validation or a business precondition failed." "500": $ref: "#/components/responses/InternalError" description: "Unexpected server error." 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: "Webhook signing public key." content: application/json: schema: $ref: "#/components/schemas/PublicKey" headers: {} "400": $ref: "#/components/responses/BadRequest" description: "Malformed or invalid request." "401": $ref: "#/components/responses/Unauthorized" description: "Missing, expired, or invalid credentials." "403": $ref: "#/components/responses/Forbidden" description: Forbidden "404": $ref: "#/components/responses/NotFound" description: "Resource not found or not accessible to this integration." "422": $ref: "#/components/responses/InvalidParams" description: "Request validation or a business precondition failed." "500": $ref: "#/components/responses/InternalError" description: "Unexpected server error." security: - Default: [] /accounts: get: tags: - Accounts summary: List accounts operationId: listAccounts description: |- Returns the Axiym accounts accessible to your integration. Each holds a balance in one currency and is connected to a payment rail. Filter by currency or account status. Account funding is arranged outside the Payment API. parameters: - $ref: "#/components/parameters/RequestId" - $ref: "#/components/parameters/First" - $ref: "#/components/parameters/After" - 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 - pageInfo properties: nodes: type: array items: $ref: "#/components/schemas/Account" pageInfo: $ref: "#/components/schemas/PageInfo" 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 pageInfo: hasNextPage: false "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 balance, currency, payment rail, and status of an Axiym account accessible to your integration." 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 posted credits and debits for an Axiym account, with opening and closing balances and movement totals. Funding reservations are not posted debits; the payment debit appears at settlement. `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 payment corridors" description: |- Lists the payment corridors configured for your integration and their current availability. A corridor combines the funding currency, destination country, and destination currency. Use the optional filters to narrow the results. Without filters, the endpoint returns every configured corridor. parameters: - $ref: "#/components/parameters/RequestId" - $ref: "#/components/parameters/SourceCurrency" - $ref: "#/components/parameters/DestinationCountry" - $ref: "#/components/parameters/DestinationCurrency" 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 payment corridor details" description: |- Returns availability, amount limits, and destination-specific data and compliance requirements for the selected corridor. Apply these alongside the baseline requirements in the payout schemas. Identify the corridor using `sourceCurrency`, `destinationCountry`, and `destinationCurrency`. parameters: - $ref: "#/components/parameters/RequestId" - $ref: "#/components/parameters/SourceCurrencyRequired" - $ref: "#/components/parameters/DestinationCountryRequired" - $ref: "#/components/parameters/DestinationCurrencyRequired" 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" /payouts: get: tags: - Payouts operationId: listPayouts x-axiym-navigation-order: 10 summary: List payouts description: "Returns payouts using the common payment response document, including payouts awaiting confirmation. Filter by funding account, `externalReference`, or status." parameters: - $ref: "#/components/parameters/AccountIdQuery" - $ref: "#/components/parameters/ExternalReferenceQuery" - $ref: "#/components/parameters/PaymentStatusQuery" - $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/Payment" 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 x-axiym-navigation-order: 20 summary: Create a payout description: |- Creates a payout using Axiym field names and exact controlled-value codes. Non-canonical labels are rejected. To use your own field structure or value labels, store a Payment Data Map and use POST /payouts/mapped. Axiym validates corridor availability, amount limits, and payment requirements, applies any documented deterministic formatting rules, and calculates commercial terms. Creation returns the prepared instruction and commercial terms in PENDING_CONFIRMATION. It does not reserve funds or start processing. Review the returned document, then confirm it before termsExpireAt. parameters: - $ref: "#/components/parameters/RequestId" - $ref: "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PayoutRequest" responses: "201": description: Payout created with status PENDING_CONFIRMATION and commercial terms valid until termsExpireAt. content: application/json: schema: $ref: "#/components/schemas/Payment" "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/mapped: post: tags: - Payouts operationId: createMappedPayout x-axiym-navigation-order: 30 summary: Create a payout with mapped data description: |- Creates a payout from one payment object using the immutable definition identified by paymentDataMapId. All source paths are relative to payment. The map must be ACTIVE; an archived map is rejected with HTTP 422. Axiym applies the saved field mappings, connects documents through nesting or exact ID matches and filters, and translates controlled labels. Exact Axiym codes pass unchanged. Other values must match a saved label exactly, including case and whitespace. Each array entry is processed independently. Missing optional paths are omitted; unmapped source fields are ignored. Ambiguous or unmatched files in a configured document collection are rejected. The map also determines sender handling and the fixed amount side. A map using onboarded-profile uses the account holder profile and skips sender rules. A map using supplied requires the mapped sender data. Amount resolution uses the mapped amount currency, the Axiym funding account currency, and the recipient destination currency, or the saved fixed-side rule. The resulting data must satisfy the strict PayoutRequest schema and current corridor requirements. Unknown labels, missing required data, incompatible source types, and invalid document or currency associations are rejected with HTTP 422. Axiym then calculates commercial terms. Creation returns the prepared instruction and commercial terms in PENDING_CONFIRMATION. It does not reserve funds or start processing. Review the returned instruction, then confirm it before termsExpireAt. Confirmation uses the stored instruction without rerunning the map. parameters: - $ref: "#/components/parameters/RequestId" - $ref: "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/MappedPayoutRequest" responses: "201": description: Payout created with status PENDING_CONFIRMATION and commercial terms valid until termsExpireAt. content: application/json: schema: $ref: "#/components/schemas/Payment" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "422": description: The map or resulting payout data failed validation. Archived maps return payment_data_map_archived at paymentDataMapId. Unrecognized controlled values return unmapped_value at the original request field. Parameters identify the canonical target path and map. Other validation errors use the standard field-error shape. 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: Archived map: value: code: 422 message: Invalid Parameters errors: paymentDataMapId: - code: payment_data_map_archived message: This map is archived and cannot be used for new payouts. params: paymentDataMapId: d2a1c7e4-9b3f-4e6a-8c5d-1f0b2a3c4d5e Unmapped purpose: value: code: 422 message: Invalid Parameters errors: payment.instruction.reason: - code: unmapped_value message: No saved translation matches this value. params: value: new purpose label targetPath: purpose paymentDataMapId: d2a1c7e4-9b3f-4e6a-8c5d-1f0b2a3c4d5e "500": $ref: "#/components/responses/InternalError" /payouts/{paymentId}: get: tags: - Payouts operationId: getPayout x-axiym-navigation-order: 50 summary: Get a payout description: "Returns the payout as a flat payment document containing its current status, commercial terms, prepared payment instruction, and any outcome reason." parameters: - $ref: "#/components/parameters/PaymentId" - $ref: "#/components/parameters/RequestId" responses: "200": description: Payout found content: application/json: schema: $ref: "#/components/schemas/Payment" "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/{paymentId}/confirm: post: tags: - Payouts operationId: confirmPayout x-axiym-navigation-order: 40 summary: Confirm a payout description: |- Confirms a payout in `PENDING_CONFIRMATION`, reserves `sourceAmount` from the funding account, and starts processing the stored payment instruction. The request has no body and confirms the stored instruction and commercial terms. Use a new `Idempotency-Key` for confirmation; reuse that key when retrying the same request. The terms must not have expired, and the funding account must be active, enabled for payouts, and sufficiently funded. Insufficient funds return `422` and leave the payout in `PENDING_CONFIRMATION` with no reservation. At `termsExpireAt`, an unconfirmed payout automatically moves to `CANCELED` with `reasonCode: TERMS_EXPIRED`; confirmation after that returns `422`. parameters: - $ref: "#/components/parameters/PaymentId" - $ref: "#/components/parameters/RequestId" - $ref: "#/components/parameters/IdempotencyKey" responses: "200": description: Payout confirmed with status PENDING and sourceAmount reserved in the funding account. content: application/json: schema: $ref: "#/components/schemas/Payment" "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" description: Confirmation precondition failed. The payout must be PENDING_CONFIRMATION with unexpired terms, and the funding account must be active, payout-enabled, and sufficiently funded. Insufficient funds leave the payout awaiting confirmation with no reservation; an unconfirmed payout automatically moves to CANCELED with reasonCode TERMS_EXPIRED at termsExpireAt. An idempotent replay of a successful confirmation returns its original result. "500": $ref: "#/components/responses/InternalError" components: securitySchemes: Default: type: http scheme: bearer bearerFormat: JWT headers: RequestId: description: "Request identifier for tracing and support, echoed from the request or generated by Axiym." schema: type: string format: uuid examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 parameters: RequestId: name: X-Request-Id in: header required: false description: "Optional request identifier for tracing and support. A UUID is recommended. Axiym echoes it in `X-Request-Id`, or generates one when omitted." schema: type: string format: uuid examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 IdempotencyKey: name: Idempotency-Key in: header required: true description: "Identifies one state-changing operation. Retry with the same endpoint, request body, and key to receive the original result without repeating the operation. Use a new key for a new operation, including confirmation after creation." 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 description: Filter by funding account identifier. schema: type: string format: uuid PaymentId: name: paymentId in: path required: true description: Payment identifier (UUID). schema: type: string format: uuid PaymentDataMapId: name: paymentDataMapId in: path required: true description: Immutable payment-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" SourceCurrency: name: sourceCurrency in: query required: false description: Filter by funding currency. schema: $ref: "#/components/schemas/Currency" DestinationCurrency: name: destinationCurrency in: query required: false description: Filter by destination currency. schema: $ref: "#/components/schemas/Currency" SourceCurrencyRequired: name: sourceCurrency in: query required: true description: Funding currency. 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" DestinationCurrencyRequired: name: destinationCurrency in: query required: true description: Destination currency to be delivered to the beneficiary. schema: $ref: "#/components/schemas/Currency" ExternalReferenceQuery: name: externalReference in: query description: Filter by the reference supplied when the payout was created. schema: type: string PaymentStatusQuery: name: status in: query description: Filter by payout status. schema: $ref: "#/components/schemas/PaymentStatus" responses: BadRequest: description: "Malformed or invalid request." 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: "Request identifier for tracing and support, echoed from the request or generated by Axiym." schema: type: string format: uuid examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unauthorized: description: "Missing, expired, or invalid credentials." 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: "Request identifier for tracing and support, echoed from the request or generated by Axiym." 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: "Request identifier for tracing and support, echoed from the request or generated by Axiym." schema: type: string format: uuid examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 NotFound: description: "Resource not found or not accessible to this integration." content: application/json: schema: type: object properties: code: type: integer description: HTTP status code, duplicated in the body. message: type: string description: "Human-readable explanation of the missing or inaccessible resource." 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 headers: X-Request-Id: description: "Request identifier for tracing and support, echoed from the request or generated by Axiym." 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: amount: - code: length message: null params: value: "" min: 1 recipient: destination: currency: - code: invalid_currency message: null params: value: ZZZ Nested struct errors: summary: Nested struct errors value: code: 422 message: Invalid Parameters errors: sender: address: country: - code: invalid_country message: null params: value: INVALID List item errors: summary: List item errors value: code: 422 message: Invalid Parameters errors: sender: relationships: "0": firstName: - code: length message: null params: value: "" min: 1 Business rejection: summary: Business rejection value: code: 422 message: Documents Not Accepted errors: null headers: X-Request-Id: description: "Request identifier for tracing and support, echoed from the request or generated by Axiym." schema: type: string format: uuid examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 InternalError: description: "Unexpected server error." 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: "Request identifier for tracing and support, echoed from the request or generated by Axiym." 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 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 description: Monetary amount and its currency. additionalProperties: false required: - amount - currency properties: amount: $ref: "#/components/schemas/Decimal" currency: $ref: "#/components/schemas/Currency" PageInfo: type: object description: Cursor information for a paginated response. 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: "Code identifying the payment rail connected to the Axiym account, such as `ZENUS_BANK` or `TRON`. This is separate from the method used to deliver a payout." examples: - ZENUS_BANK AccountStatus: type: string description: Current availability of an Axiym account. enum: - ACTIVE - SUSPENDED - CLOSED examples: - ACTIVE Account: type: object description: An account holding a currency balance. Receiving details for funding it are served by the deposit instructions. 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: - 5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e 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: - "1010.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: - "47240.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: - c3d65312-6575-43de-b8ae-728d8d0a9371 occurredAt: type: string format: date-time description: When the movement occurred. Formatted in ISO 8601. examples: - 2026-09-07T10:12:00Z Corridor: type: object description: "A payment route defined by the funding currency, destination country, and destination currency." required: - sourceCurrency - destinationCountry - destinationCurrency - availability properties: sourceCurrency: $ref: "#/components/schemas/Currency" description: Funding currency. examples: - USD destinationCountry: allOf: - $ref: "#/components/schemas/CountryCode" description: Destination country for the payout. examples: - PH destinationCurrency: $ref: "#/components/schemas/Currency" description: Destination currency to be delivered to the beneficiary. examples: - PHP availability: $ref: "#/components/schemas/CorridorAvailability" description: Current availability of the payout route. examples: - AVAILABLE CorridorAvailability: type: string enum: - AVAILABLE - UNAVAILABLE description: "Current corridor availability. A payout can be created only 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 amounts the beneficiary can receive, expressed in `destinationCurrency`." requirements: $ref: "#/components/schemas/CorridorRequirements" description: "Additional data requirements and constraints for this corridor. Apply alongside the baseline payout schemas." CorridorAmountLimits: type: object description: "Permitted amount-to-receive range in the destination currency (`destinationCurrency`). Payout creation is rejected when the target amount is outside this range." required: - minimum - maximum properties: minimum: $ref: "#/components/schemas/Money" description: "Minimum amount the beneficiary can receive through the corridor." maximum: $ref: "#/components/schemas/Money" description: "Maximum amount the beneficiary can receive through the corridor." examples: - minimum: amount: "100.00" currency: PHP maximum: amount: "500000.00" currency: PHP CorridorRequirements: type: object description: "Additional field requirements and constraints for the selected corridor. Apply these alongside the baseline payout schemas." required: - fields - complianceInformation properties: fields: type: array description: Fields whose requiredness, format, validation, or formatting rules are 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 description: Corridor-specific requirement for one payment-instruction field. required: - field - label - requiredness - format - description properties: field: type: string description: Partner-facing payment-data field path. examples: - recipient.destination.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: Deterministic formatting rule applied to this field before validation, such as removing whitespace. examples: - Remove whitespace description: type: string description: Additional guidance for supplying the field. PartyAddress: type: object description: "Structured postal address. `streetName` accepts the full primary address line; a separate `buildingNumber` is optional. See the field descriptions for supported address forms." additionalProperties: false required: - streetName - city - country properties: streetName: type: string minLength: 1 description: Primary address line. It may contain a street and number, a PO box, or a building or lot description when no street address applies. examples: - MG Road buildingNumber: type: string examples: - "14" city: type: string minLength: 1 region: type: string postalCode: type: string country: $ref: "#/components/schemas/CountryCode" PartyContact: type: object description: Contact details for a sender, recipient, or related individual. 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: "Identification document or identifier type. The corridor determines which types are accepted." enum: - REGISTRATION_NUMBER - TAX_ID - VAT_NUMBER - NATIONAL_ID - PASSPORT - DRIVER_LICENSE - RESIDENCE_PERMIT - LEI - OTHER examples: - REGISTRATION_NUMBER PartyIdentification: type: object description: Identification details returned in the prepared payment instruction. 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 documents: type: array items: $ref: "#/components/schemas/SupportingDocument" description: Documents evidencing this identification. File content is not returned. PartyIdentificationInput: type: object description: "Identification details supplied for a payment, using an exact Axiym identification type code." additionalProperties: false required: - type - number properties: type: allOf: - $ref: "#/components/schemas/PartyIdentificationType" x-axiym-controlled-value: vocabulary: PartyIdentificationType inputPaths: - sender.identification.type - sender.relationships[].identification.type - recipient.identification.type - recipient.relationships[].identification.type description: Use an exact Axiym PartyIdentificationType code. To send your own labels, store reviewed value translations in a Payment Data Map and use POST /payouts/mapped. examples: - REGISTRATION_NUMBER number: type: string minLength: 1 country: $ref: "#/components/schemas/CountryCode" issueDate: type: string format: date expiryDate: type: string format: date documents: type: array items: $ref: "#/components/schemas/SupportingDocumentInput" description: Documents evidencing this identification, such as a passport scan or a registry extract. Required where the corridor requires identity evidence. BusinessRelationship: type: string description: Relationship of the recipient to the sender. enum: - SUPPLIER - CUSTOMER - CONTRACTOR - SERVICE_PROVIDER - GROUP_COMPANY - SUBSIDIARY - PARENT - INVESTMENT_TARGET - DEBTOR - CREDITOR - OTHER examples: - SUPPLIER PartyInput: type: object description: "Sender or recipient details in Axiym's field structure, using exact controlled-value codes. Other labels require saved translations on the mapped endpoint." additionalProperties: false required: - name - address properties: name: type: string minLength: 1 countryOfIncorporation: $ref: "#/components/schemas/CountryCode" address: $ref: "#/components/schemas/PartyAddress" contact: $ref: "#/components/schemas/PartyContact" identification: $ref: "#/components/schemas/PartyIdentificationInput" relationships: type: array minItems: 1 items: $ref: "#/components/schemas/PartyRelationshipInput" description: Individuals related to the party and the role in which they are related. Required for the sender; supply it for a recipient where the corridor asks for it. documents: type: array items: $ref: "#/components/schemas/SupportingDocumentInput" description: Documents about the party that do not evidence a specific identification, such as a proof of address. Party: type: object description: "Sender or recipient details returned with the payout, using Axiym field names and codes." additionalProperties: false required: - name - countryOfIncorporation - address properties: name: type: string countryOfIncorporation: $ref: "#/components/schemas/CountryCode" address: $ref: "#/components/schemas/PartyAddress" contact: $ref: "#/components/schemas/PartyContact" identification: $ref: "#/components/schemas/PartyIdentification" relationships: type: array items: $ref: "#/components/schemas/PartyRelationship" documents: type: array items: $ref: "#/components/schemas/SupportingDocument" description: Documents about the party. File content is not returned. SourceOfFunds: type: string description: >- Origin of the sender's funds used for this payment. Use BUSINESS_INCOME for general business income not covered by a more specific category. INVESTMENT_INCOME covers investment returns such as interest and dividends; proceeds from selling investments use SALE_OF_OTHER_ASSETS. CAPITAL_CONTRIBUTION covers equity funding; shareholder and intercompany loans use LOAN_PROCEEDS. enum: - BUSINESS_INCOME - SALE_OF_GOODS - SALE_OF_SERVICES - COMMISSION - RENTAL_INCOME - INVESTMENT_INCOME - LOAN_PROCEEDS - CAPITAL_CONTRIBUTION - SALE_OF_REAL_ESTATE - SALE_OF_OTHER_ASSETS - GRANT - DONATION - INSURANCE_PAYOUT examples: - BUSINESS_INCOME RelationshipRole: type: string description: Canonical role of an individual in relation to the party. enum: - UBO - DIRECTOR - OFFICER - SHAREHOLDER - AUTHORIZED_SIGNATORY - EMPLOYEE_OF - OTHER_RELATIONSHIP examples: - UBO PartyRelationshipInput: type: object description: An individual related to the sender or recipient, and the role in which they are related. additionalProperties: false required: - role - firstName - lastName - nationalities - address - identification properties: role: allOf: - $ref: "#/components/schemas/RelationshipRole" x-axiym-controlled-value: vocabulary: RelationshipRole inputPaths: - sender.relationships[].role - recipient.relationships[].role description: Use an exact Axiym RelationshipRole code. To send your own labels, store reviewed value translations in a Payment Data Map and use POST /payouts/mapped. examples: - UBO firstName: type: string minLength: 1 lastName: type: string minLength: 1 nationalities: type: array minItems: 1 uniqueItems: true items: $ref: "#/components/schemas/CountryCode" address: $ref: "#/components/schemas/PartyAddress" identification: $ref: "#/components/schemas/PartyIdentificationInput" PartyRelationship: type: object description: Related individual details stored in the prepared payment instruction. additionalProperties: false required: - role - firstName - lastName - nationalities - address - identification properties: role: $ref: "#/components/schemas/RelationshipRole" firstName: type: string lastName: type: string nationalities: type: array items: $ref: "#/components/schemas/CountryCode" address: $ref: "#/components/schemas/PartyAddress" identification: $ref: "#/components/schemas/PartyIdentification" SenderInput: type: object description: "Sender details using Axiym field names and exact controlled-value codes. Corridor requirements may add evidence or other constraints." additionalProperties: false required: - name - address - countryOfIncorporation - contact - identification - relationships properties: name: type: string minLength: 1 countryOfIncorporation: $ref: "#/components/schemas/CountryCode" address: $ref: "#/components/schemas/PartyAddress" contact: $ref: "#/components/schemas/PartyContact" identification: $ref: "#/components/schemas/PartyIdentificationInput" relationships: type: array minItems: 1 items: $ref: "#/components/schemas/PartyRelationshipInput" description: Individuals related to the party and the role in which they are related. Required for the sender; supply it for a recipient where the corridor asks for it. documents: type: array items: $ref: "#/components/schemas/SupportingDocumentInput" description: Documents about the party that do not evidence a specific identification, such as a proof of address. Sender: type: object description: "Sender details stored in the prepared payment instruction, using Axiym field names and codes." additionalProperties: false required: - name - countryOfIncorporation - address - contact - identification - relationships properties: name: type: string countryOfIncorporation: $ref: "#/components/schemas/CountryCode" address: $ref: "#/components/schemas/PartyAddress" contact: $ref: "#/components/schemas/PartyContact" identification: $ref: "#/components/schemas/PartyIdentification" relationships: type: array items: $ref: "#/components/schemas/PartyRelationship" documents: type: array items: $ref: "#/components/schemas/SupportingDocument" description: Documents about the party. File content is not returned. Recipient: type: object description: "The party receiving the payment and its destination account, with canonical controlled values. `recipientId` is present when the recipient comes from the address book." additionalProperties: false required: - businessRelationship - name - address - destination properties: recipientId: type: string format: uuid description: Address book recipient identifier, when the payment uses a stored recipient. businessRelationship: $ref: "#/components/schemas/BusinessRelationship" name: type: string countryOfIncorporation: $ref: "#/components/schemas/CountryCode" address: $ref: "#/components/schemas/PartyAddress" contact: $ref: "#/components/schemas/PartyContact" identification: $ref: "#/components/schemas/PartyIdentification" relationships: type: array items: $ref: "#/components/schemas/PartyRelationship" destination: $ref: "#/components/schemas/Destination" documents: type: array items: $ref: "#/components/schemas/SupportingDocument" description: Documents about the recipient. File content is not returned. PaymentDataMapDefinition: type: object description: Reusable rules that transform your complete payment JSON into the Axiym payout input. Field paths are relative to the payment object sent to POST /payouts/mapped. The definition stores rules and reviewed labels, not payment records or file content. Definitions are immutable; store changed rules as a new map. Unsupported schema versions are rejected. additionalProperties: false required: - schemaVersion - fields - documents - values - sender - amountResolution properties: schemaVersion: type: string enum: - "3" examples: - "3" description: Map document format version. Version 3 describes full-payment field mappings, document connections, value translations, sender handling, and amount resolution. fields: type: array minItems: 1 items: $ref: "#/components/schemas/PaymentMapField" description: Mappings for all payment and party fields you supply. Include sourceAccountId, amount.amount, amount.currency, and the recipient fields required by the payout input. Configure document content separately in documents. Missing optional source paths are omitted; missing required output data rejects the payout. documents: type: array items: $ref: "#/components/schemas/PaymentMapDocument" description: Connections for the documents your integration supplies. Use [] if no documents are supplied; corridor requirements still apply. A source collection may serve different destinations through distinct ownership rules. values: type: array items: $ref: "#/components/schemas/PaymentMapValue" description: Reviewed dictionaries for controlled fields that use your labels. Use [] if all controlled fields already use exact Axiym codes. Fields without a value rule must use Axiym codes. Names, references, amounts, and other free-text fields do not need dictionaries. sender: type: string enum: - supplied - onboarded-profile description: supplied requires sender data through the saved field mappings on every payout. onboarded-profile uses the account holder profile and omits sender from the mapped input; sender field, document, and value rules are skipped. Use separate maps when your integration needs both behaviours. amountResolution: $ref: "#/components/schemas/PaymentMapAmountResolution" examples: - schemaVersion: "3" fields: - source: instruction.account target: sourceAccountId - source: instruction.total target: amount.amount - source: instruction.currency target: amount.currency - source: instruction.reason target: purpose - source: instruction.funding target: sourceOfFunds - source: instruction.reference target: reference - source: beneficiary.name target: recipient.name - source: beneficiary.relationship target: recipient.businessRelationship - source: beneficiary.address.line target: recipient.address.streetName - source: beneficiary.address.city target: recipient.address.city - source: beneficiary.address.country target: recipient.address.country - source: beneficiary.account.number target: recipient.destination.accountNumber - source: beneficiary.account.currency target: recipient.destination.currency - source: beneficiary.account.bank.name target: recipient.destination.bank.bankName - source: beneficiary.account.bank.swift target: recipient.destination.bank.swiftBic - source: beneficiary.account.bank.country target: recipient.destination.bank.address.country documents: - target: supportingDocuments[] source: files[] association: linked fields: documentType: kind name: fileName data: content matches: - fileField: ownerId recordPath: instruction.reference filters: - field: usage value: payment values: - source: instruction.reason targets: - purpose translations: supplier invoice: GOODS_PURCHASE - source: instruction.funding targets: - sourceOfFunds translations: business income: BUSINESS_INCOME - source: beneficiary.relationship targets: - recipient.businessRelationship translations: supplier: SUPPLIER - source: files[].kind targets: - supportingDocuments[].documentType translations: invoice: INVOICE sender: onboarded-profile amountResolution: method: currency fundingAccount: sourceAccountId recipientCurrency: recipient.destination.currency whenBothMatch: sourceAmount whenNeitherMatches: reject CreatePaymentDataMapRequest: type: object description: Name, optional description, and mapping definition to store. additionalProperties: false required: - name - definition properties: name: type: string minLength: 1 maxLength: 120 description: Name used to identify the stored map in your integration. examples: - Supplier payments description: type: string maxLength: 500 description: Optional note describing the source structures or integration that uses this map. definition: $ref: "#/components/schemas/PaymentDataMapDefinition" examples: - name: Supplier payments definition: schemaVersion: "3" fields: - source: instruction.account target: sourceAccountId - source: instruction.total target: amount.amount - source: instruction.currency target: amount.currency - source: instruction.reason target: purpose - source: instruction.funding target: sourceOfFunds - source: instruction.reference target: reference - source: beneficiary.name target: recipient.name - source: beneficiary.relationship target: recipient.businessRelationship - source: beneficiary.address.line target: recipient.address.streetName - source: beneficiary.address.city target: recipient.address.city - source: beneficiary.address.country target: recipient.address.country - source: beneficiary.account.number target: recipient.destination.accountNumber - source: beneficiary.account.currency target: recipient.destination.currency - source: beneficiary.account.bank.name target: recipient.destination.bank.bankName - source: beneficiary.account.bank.swift target: recipient.destination.bank.swiftBic - source: beneficiary.account.bank.country target: recipient.destination.bank.address.country documents: - target: supportingDocuments[] source: files[] association: linked fields: documentType: kind name: fileName data: content matches: - fileField: ownerId recordPath: instruction.reference filters: - field: usage value: payment values: - source: instruction.reason targets: - purpose translations: supplier invoice: GOODS_PURCHASE - source: instruction.funding targets: - sourceOfFunds translations: business income: BUSINESS_INCOME - source: beneficiary.relationship targets: - recipient.businessRelationship translations: supplier: SUPPLIER - source: files[].kind targets: - supportingDocuments[].documentType translations: invoice: INVOICE sender: onboarded-profile amountResolution: method: currency fundingAccount: sourceAccountId recipientCurrency: recipient.destination.currency whenBothMatch: sourceAmount whenNeitherMatches: reject PaymentDataMapStatus: type: string description: ACTIVE maps can be used to create payouts. ARCHIVED maps are retained for audit and cannot be used for new payouts. enum: - ACTIVE - ARCHIVED PaymentDataMap: type: object description: "Payment Data Map stored for your integration. Its definition and content hash remain unchanged when it is archived." additionalProperties: false required: - paymentDataMapId - name - definition - status - contentHash - createdAt properties: paymentDataMapId: type: string format: uuid name: type: string description: type: string definition: $ref: "#/components/schemas/PaymentDataMapDefinition" status: $ref: "#/components/schemas/PaymentDataMapStatus" 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 PaymentDataMapPage: type: object description: Paginated list of stored Payment Data Maps. additionalProperties: false required: - nodes - pageInfo properties: nodes: type: array description: Payment Data Maps in this page. items: $ref: "#/components/schemas/PaymentDataMap" pageInfo: $ref: "#/components/schemas/PageInfo" 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: >- Reason for the payment. Each code corresponds to one ISO 20022 purpose code (ExternalPurpose1Code). SERVICES_PAYMENT covers every kind of service, including contractor, IT, legal and financial services. OWN_ACCOUNT_TRANSFER is between accounts of the same legal entity; INTERCOMPANY_TRANSFER is between separate companies in a group; TREASURY_MANAGEMENT is a group treasury operation. LOAN_REPAYMENT covers principal; INTEREST_PAYMENT covers interest. INVESTMENT is a financial investment; a property purchase uses REAL_ESTATE_PURCHASE. OTHER covers purposes outside the listed codes. Accepted purposes depend on the selected corridor. enum: - GOODS_PURCHASE - SERVICES_PAYMENT - SUPPLIER_PAYMENT - SALARY_PAYROLL - RENT_LEASE - LOAN_DISBURSEMENT - LOAN_REPAYMENT - INTEREST_PAYMENT - INTERCOMPANY_TRANSFER - OWN_ACCOUNT_TRANSFER - TREASURY_MANAGEMENT - TAX_PAYMENT - INVESTMENT - REAL_ESTATE_PURCHASE - INSURANCE_PAYMENT - BUSINESS_EXPENSES - EDUCATION_TRAINING_FEES - SUBSCRIPTION_MEMBERSHIP_FEES - ROYALTY_LICENSE_FEES - CHARITABLE_DONATION - REFUND - OTHER examples: - GOODS_PURCHASE SupportingDocumentInput: type: object description: "A document supporting the payment, such as an invoice or contract. One item is one file; supply the file content as base64." additionalProperties: false required: - documentType - data - name properties: documentType: allOf: - $ref: "#/components/schemas/SupportingDocumentType" x-axiym-controlled-value: vocabulary: SupportingDocumentType inputPaths: - supportingDocuments[].documentType - sender.documents[].documentType - recipient.documents[].documentType - sender.identification.documents[].documentType - recipient.identification.documents[].documentType - sender.relationships[].identification.documents[].documentType - recipient.relationships[].identification.documents[].documentType description: Use an exact Axiym SupportingDocumentType code. To send your own labels, store reviewed value translations in a Payment Data Map and use POST /payouts/mapped. examples: - INVOICE data: type: string contentEncoding: base64 description: Complete file encoded as base64 from its raw bytes. Do not include a data-URL prefix. name: type: string description: File name, including the extension. examples: - INV-2026-0917.pdf PayoutRequest: type: object description: "Creates a payout from a funding account, a fixed amount on one side, and complete payment instruction. Exactly one of `sourceAmount` or `destinationAmount` must be supplied. Sender and recipient data use Axiym's field structure." additionalProperties: false required: - sourceAccountId - recipient properties: sourceAccountId: type: string format: uuid description: "Axiym account debited for the payout. Available funds are checked when the payout is confirmed." sourceAmount: allOf: - $ref: "#/components/schemas/Money" description: Amount to debit from the source account, in the source account currency. Supply exactly one of `sourceAmount` or `destinationAmount`. destinationAmount: allOf: - $ref: "#/components/schemas/Money" description: Amount the recipient must receive, in the destination currency. Supply exactly one of `sourceAmount` or `destinationAmount`. sender: allOf: - $ref: "#/components/schemas/SenderInput" description: The party on whose behalf the payment is made. Omit when you pay for yourself — the account holder is then the sender and its onboarded profile is used. recipient: $ref: "#/components/schemas/RecipientInput" externalReference: type: string description: "Your reference for the payout. It is returned on the payout and related webhook events, and must be unique when supplied." sourceOfFunds: allOf: - $ref: "#/components/schemas/SourceOfFunds" x-axiym-controlled-value: vocabulary: SourceOfFunds inputPaths: - sourceOfFunds description: Origin of the funds used for this payment. Required where the corridor requires a source-of-funds code, including when sender is omitted. Use an exact Axiym code; other labels require a saved value translation on POST /payouts/mapped. examples: - BUSINESS_INCOME purpose: allOf: - $ref: "#/components/schemas/TransactionPurpose" x-axiym-controlled-value: vocabulary: TransactionPurpose inputPaths: - purpose description: Use an exact Axiym TransactionPurpose code. To send your own labels, store reviewed value translations in a Payment Data Map and use POST /payouts/mapped. Required where the corridor requires a purpose code. examples: - SERVICES_PAYMENT reference: type: string description: Text shown to the recipient, typically the invoice number. supportingDocuments: type: array items: $ref: "#/components/schemas/SupportingDocumentInput" description: Documents supporting the payment, such as an invoice. Required where the corridor requires evidence. examples: - sourceAccountId: 5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e destinationAmount: amount: "56500.00" currency: PHP sender: name: Acme Pte. Ltd. countryOfIncorporation: SG address: streetName: 1 Raffles Place city: Singapore postalCode: "048616" country: SG contact: email: payments@acme.example phoneNumber: "+6591234567" identification: type: REGISTRATION_NUMBER number: 202612345N country: SG documents: - documentType: REGISTRY_EXTRACT name: acme-registry-extract.pdf data: JVBERi0xLjQKJSBBeGl5bSBleGFtcGxlCg== relationships: - role: UBO firstName: Alex lastName: Tan nationalities: - SG address: streetName: 10 Anson Road city: Singapore postalCode: "079903" country: SG identification: type: PASSPORT number: E1234567A country: SG recipient: businessRelationship: SUPPLIER name: Manila Software Services Inc. countryOfIncorporation: PH address: streetName: 6789 Ayala Avenue city: Makati postalCode: "1226" country: PH destination: accountNumber: "123456789012" currency: PHP bank: bankName: Example Bank Philippines address: country: PH swiftBic: BNORPHMMXXX externalReference: PAYOUT-2026-001 sourceOfFunds: BUSINESS_INCOME purpose: SERVICES_PAYMENT reference: INV-2026-0917 supportingDocuments: - documentType: INVOICE name: INV-2026-0917.pdf data: JVBERi0xLjQKJSBBeGl5bSBleGFtcGxlCg== MappedPayoutRequest: type: object description: A saved map identifier and one complete payment object in your agreed source structure. The map prepares the strict Axiym payout input, including payment details, parties, documents, and exactly one fixed amount. The prepared result must meet current corridor requirements. additionalProperties: false required: - paymentDataMapId - payment properties: paymentDataMapId: type: string format: uuid description: Identifier of the ACTIVE, immutable Payment Data Map defining how payment is transformed. payment: type: object minProperties: 1 additionalProperties: true description: Your complete payment JSON. Field names and nesting follow the saved map; values and array lengths may vary between payouts. Include all data required to produce the Axiym payout input and satisfy the corridor. Input types must match mapped destination types. Unmapped source fields are ignored. JSON property order does not matter. The names in the example are illustrative, not required fields. examples: - paymentDataMapId: d2a1c7e4-9b3f-4e6a-8c5d-1f0b2a3c4d5e payment: instruction: account: 5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e total: "1000.00" currency: USD reason: supplier invoice funding: business income reference: INV-1042 beneficiary: name: Example Supplier Corporation relationship: supplier address: line: Ayala Avenue city: Makati country: PH account: number: "1234567890" currency: PHP bank: name: Example Bank swift: BNORPHMM country: PH files: - ownerId: INV-1042 usage: payment kind: invoice fileName: INV-1042.pdf content: JVBERi0xLjQKJSBBeGl5bSBleGFtcGxlCg== PaymentStatus: type: string description: |- - `PENDING_CONFIRMATION` — created with time-limited terms and awaiting confirmation. No funds are reserved. - `PENDING` — confirmed and awaiting or undergoing execution. - `HELD` — temporarily on hold; no action is required unless Axiym requests information. - `COMPLETED` — delivered successfully. - `CANCELED` or `REJECTED` — not completed; see `reasonCode` when present. enum: - PENDING_CONFIRMATION - PENDING - HELD - COMPLETED - CANCELED - REJECTED examples: - PENDING_CONFIRMATION AccountRef: type: object description: Compact account reference. Fetch the account via `GET /accounts/{accountId}` for the current balance and status; deposit instructions serve its payment details. required: - accountId - currency - paymentRails 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 Payment: type: object description: "Common response document for an outgoing payment. Confirmation authorizes this exact document and reserves `sourceAmount`." additionalProperties: false required: - paymentId - code - status - sourceAccount - sourceAmount - destinationAmount - fee - sender - recipient - createdAt - updatedAt properties: paymentId: type: string format: uuid description: Payment identifier (UUID). sourceAccount: allOf: - $ref: "#/components/schemas/AccountRef" description: Axiym account funding the payment. externalReference: type: string description: Your reference supplied when the payment was created. status: $ref: "#/components/schemas/PaymentStatus" sourceAmount: allOf: - $ref: "#/components/schemas/Money" description: Amount debited from the source account, in the source account currency. destinationAmount: allOf: - $ref: "#/components/schemas/Money" description: Amount delivered to the recipient, in the destination currency. rate: allOf: - $ref: "#/components/schemas/Decimal" description: "Exchange rate applied to `sourceAmount` less `fee` to obtain `destinationAmount`: units of the destination currency for one unit of the source currency. Omitted when no conversion applies." fee: allOf: - $ref: "#/components/schemas/Money" description: Total deducted from `sourceAmount` before delivery, in the source account currency. termsExpireAt: type: string format: date-time description: "When the unconfirmed commercial terms expire. A payment still in `PENDING_CONFIRMATION` at this time moves to `CANCELED` with `reasonCode: TERMS_EXPIRED`." code: type: string description: System payment code, assigned at creation and shown in the account statement. examples: - AXI00000420 reasonCode: type: string description: "Reason the payment was canceled or rejected, when present. `TERMS_EXPIRED` means it was not confirmed before `termsExpireAt`." examples: - TERMS_EXPIRED sender: allOf: - $ref: "#/components/schemas/Sender" description: The paying party — the account holder, or the third party the payment is made on behalf of. recipient: $ref: "#/components/schemas/Recipient" sourceOfFunds: $ref: "#/components/schemas/SourceOfFunds" description: Origin of the funds used for this payment, using the canonical Axiym code. Present when supplied during payout creation. purpose: $ref: "#/components/schemas/TransactionPurpose" reference: type: string description: Text shown to the recipient, as submitted. supportingDocuments: type: array items: $ref: "#/components/schemas/SupportingDocument" description: Documents accepted with the payment. File content is not returned. transactionHash: type: string description: Transaction hash for an on-chain payment, once available. createdAt: type: string format: date-time description: Time the payment was created, in ISO 8601 format. updatedAt: type: string format: date-time description: Time the payment was last updated, in ISO 8601 format. examples: - paymentId: c3d65312-6575-43de-b8ae-728d8d0a9371 code: AXI00000420 sourceAccount: accountId: 5c0a9d3e-1f2b-4a6c-8e7d-9b3f5a1c2d4e currency: USD paymentRails: ZENUS_BANK externalReference: PAYOUT-2026-001 status: PENDING_CONFIRMATION sourceAmount: amount: "1010.00" currency: USD fee: amount: "10.00" currency: USD destinationAmount: amount: "56500.00" currency: PHP rate: "56.5000" termsExpireAt: 2026-09-07T10:05:00Z sender: name: Acme Pte. Ltd. countryOfIncorporation: SG address: streetName: 1 Raffles Place city: Singapore postalCode: "048616" country: SG contact: email: payments@acme.example phoneNumber: "+6591234567" identification: type: REGISTRATION_NUMBER number: 202612345N country: SG documents: - documentType: REGISTRY_EXTRACT fileId: 6c1d0e42-8b7a-4f39-9d21-3a5e7c9b1f08 name: acme-registry-extract.pdf contentType: application/pdf size: 96311 relationships: - role: UBO firstName: Alex lastName: Tan nationalities: - SG address: streetName: 10 Anson Road city: Singapore postalCode: "079903" country: SG identification: type: PASSPORT number: E1234567A country: SG recipient: businessRelationship: SUPPLIER name: Manila Software Services Inc. countryOfIncorporation: PH address: streetName: 6789 Ayala Avenue city: Makati postalCode: "1226" country: PH contact: email: accounts@manilasoftware.example phoneNumber: "+639171234567" destination: accountNumber: "123456789012" currency: PHP bank: bankName: Example Bank Philippines address: country: PH swiftBic: BNORPHMMXXX sourceOfFunds: BUSINESS_INCOME purpose: SERVICES_PAYMENT reference: INV-2026-0917 supportingDocuments: - documentType: INVOICE fileId: 0f6a2c91-4b7e-4d31-9c58-2e8a1f6b3d40 name: INV-2026-0917.pdf contentType: application/pdf size: 184233 createdAt: 2026-09-07T10:00:00Z updatedAt: 2026-09-07T10:00:00Z SupportingDocument: type: object description: Metadata of a document accepted with the payment. File content is not returned. additionalProperties: false required: - documentType - fileId - name - contentType - size properties: documentType: $ref: "#/components/schemas/SupportingDocumentType" fileId: type: string format: uuid description: Identifier of the stored file. name: type: string description: File name supplied with the document. contentType: type: string description: MIME type detected from the file content. examples: - application/pdf size: type: integer description: File size in bytes. CreateSubscriptionRequest: type: object required: - endpoint properties: endpoint: type: string title: "" description: "Public HTTPS endpoint for webhook deliveries. Return `2xx` after durably accepting each event." Subscription: type: object properties: subscriptionId: type: string description: Subscription identifier (UUID). format: uuid examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 endpoint: type: string description: "Public HTTPS endpoint for webhook deliveries. Return `2xx` after durably accepting each event." 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: "Whether the signing key is active." examples: - true algorithm: type: string description: "Signature algorithm." examples: - ED25519 publicKey: type: string description: "Public key used to verify webhook signatures." 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 description: Error response for requests that do not contain field-level validation failures. 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 description: Error response for field validation failures and business-rule rejections. 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: "Machine-readable validation rule code, such as `length`, `email`, or `invalid_currency`." examples: - length message: type: - string - "null" description: Human-readable message. examples: - string params: type: object description: "Rule-specific parameters, including `value`, the submitted input. Values may contain sensitive data; do not log them without redaction." properties: value: description: The submitted value that failed validation. examples: - string BankAddress: type: object description: "Receiving bank address. Its country identifies the payout's destination country and determines the applicable bank-routing requirements. Supply additional address fields when required by the corridor." additionalProperties: false properties: streetName: type: string description: Primary address line. It may contain a street and number, a PO box, or a building or lot description when no street address applies. buildingNumber: type: string city: type: string region: type: string postalCode: type: string country: $ref: "#/components/schemas/CountryCode" required: - country DestinationInput: type: object description: "Bank account to which the payout is delivered. Corridor requirements determine any additional routing fields." additionalProperties: false required: - accountNumber - currency - bank properties: accountNumber: type: string minLength: 1 description: Recipient's account number or IBAN, as required by the corridor. currency: $ref: "#/components/schemas/Currency" description: Currency delivered to the recipient. bank: $ref: "#/components/schemas/BankInput" Destination: description: |- Where the funds are delivered, as recorded on the operation at creation time. This is a snapshot: it carries the account or wallet details and, when the destination was taken from the address book, its `destinationId`. It does not carry the address book entry's status or creation date; read the address book entry for its current state. - A bank destination contains `accountNumber` and `bank`. - A wallet destination contains `walletAddress` and `network`. The two field sets never appear together. oneOf: - $ref: "#/components/schemas/BankDestination" - $ref: "#/components/schemas/WalletDestination" BankDestination: type: object title: Bank account required: - currency - accountNumber - bank properties: destinationId: type: string format: uuid description: Address book entry the destination was taken from, when applicable. examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 currency: $ref: "#/components/schemas/Currency" description: Currency delivered to the destination. examples: - USD accountNumber: type: string description: Bank account number or IBAN. examples: - "0123456789" bank: $ref: "#/components/schemas/Bank" description: Destination bank details. WalletDestination: type: object title: Wallet address required: - currency - walletAddress - network properties: destinationId: type: string format: uuid description: Address book entry the destination was taken from, when applicable. examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 currency: $ref: "#/components/schemas/Currency" description: Currency delivered to the destination. examples: - USDT walletAddress: type: string description: Wallet address on the given network. examples: - TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL network: $ref: "#/components/schemas/Network" description: Network of the wallet address. examples: - TRON BankInput: type: object description: "Receiving bank details. The bank address country determines the destination corridor; additional routing fields depend on that corridor's requirements." additionalProperties: false required: - bankName - address properties: bankName: type: string minLength: 1 address: $ref: "#/components/schemas/BankAddress" swiftBic: 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. clearingSystemCode: type: string description: "Clearing system associated with `clearingCode`. Axiym derives it when only one system applies; supply it when the corridor supports more than one." examples: - JPZGN Bank: type: object description: "Receiving bank details returned with the payout, including the applicable clearing system." additionalProperties: false required: - bankName - address properties: bankName: type: string address: $ref: "#/components/schemas/BankAddress" swiftBic: type: string clearingCode: type: string clearingSystemCode: type: string description: "Clearing system used for bank routing, resolved from the bank country and supplied routing details." examples: - INFSC Network: type: string description: Blockchain network of a wallet address. enum: - TRON - AVALANCHE RecipientInput: type: object description: "Recipient details using Axiym field names and exact controlled-value codes. Corridor requirements may add identification, evidence, or routing requirements." additionalProperties: false required: - businessRelationship - name - address - destination properties: businessRelationship: allOf: - $ref: "#/components/schemas/BusinessRelationship" x-axiym-controlled-value: vocabulary: BusinessRelationship inputPaths: - recipient.businessRelationship description: Use an exact Axiym BusinessRelationship code. To send your own labels, store reviewed value translations in a Payment Data Map and use POST /payouts/mapped. examples: - SUPPLIER name: type: string minLength: 1 countryOfIncorporation: $ref: "#/components/schemas/CountryCode" address: $ref: "#/components/schemas/PartyAddress" contact: $ref: "#/components/schemas/PartyContact" identification: $ref: "#/components/schemas/PartyIdentificationInput" relationships: type: array minItems: 1 items: $ref: "#/components/schemas/PartyRelationshipInput" description: Individuals related to the recipient and the role in which they are related. Supply them where the corridor asks for them. destination: $ref: "#/components/schemas/DestinationInput" documents: type: array items: $ref: "#/components/schemas/SupportingDocumentInput" description: Documents about the recipient that do not evidence a specific identification. PartyIdentificationTypeValueMap: type: object minProperties: 1 propertyNames: type: string minLength: 1 pattern: \S description: Exact partner labels mapped to PartyIdentificationType codes. Case and whitespace are significant. Many labels may map to the same code; only values used by your integration need entries. Existing Axiym codes pass unchanged and cannot be mapped to a different code. additionalProperties: $ref: "#/components/schemas/PartyIdentificationType" RelationshipRoleValueMap: type: object minProperties: 1 propertyNames: type: string minLength: 1 pattern: \S description: Exact partner labels mapped to RelationshipRole codes. Case and whitespace are significant. Many labels may map to the same code; only values used by your integration need entries. Existing Axiym codes pass unchanged and cannot be mapped to a different code. additionalProperties: $ref: "#/components/schemas/RelationshipRole" SupportingDocumentTypeValueMap: type: object minProperties: 1 propertyNames: type: string minLength: 1 pattern: \S description: Exact partner labels mapped to SupportingDocumentType codes. Case and whitespace are significant. Many labels may map to the same code; only values used by your integration need entries. Existing Axiym codes pass unchanged and cannot be mapped to a different code. additionalProperties: $ref: "#/components/schemas/SupportingDocumentType" SourceOfFundsValueMap: type: object minProperties: 1 propertyNames: type: string minLength: 1 pattern: \S description: Exact partner labels mapped to SourceOfFunds codes. Case and whitespace are significant. Many labels may map to the same code; only values used by your integration need entries. Existing Axiym codes pass unchanged and cannot be mapped to a different code. additionalProperties: $ref: "#/components/schemas/SourceOfFunds" TransactionPurposeValueMap: type: object minProperties: 1 propertyNames: type: string minLength: 1 pattern: \S description: Exact partner labels mapped to TransactionPurpose codes. Case and whitespace are significant. Many labels may map to the same code; only values used by your integration need entries. Existing Axiym codes pass unchanged and cannot be mapped to a different code. additionalProperties: $ref: "#/components/schemas/TransactionPurpose" BusinessRelationshipValueMap: type: object minProperties: 1 propertyNames: type: string minLength: 1 pattern: \S description: Exact partner labels mapped to BusinessRelationship codes. Case and whitespace are significant. Many labels may map to the same code; only values used by your integration need entries. Existing Axiym codes pass unchanged and cannot be mapped to a different code. additionalProperties: $ref: "#/components/schemas/BusinessRelationship" PaymentMapSourcePath: type: string pattern: ^(?!(?:__proto__|prototype|constructor)(?:\[\])?(?:\.|$))[A-Za-z0-9_]+(?:\[\])?(?:\.(?!(?:__proto__|prototype|constructor)(?:\[\])?(?:\.|$))[A-Za-z0-9_]+(?:\[\])?)*$ description: Field path relative to the payment object in a mapped payout request. Use dots for nesting and [] for each array level, for example client.people[].fullName. The payment request wrapper is not part of the path. Keys contain letters, digits, or underscores; prototype-related keys are not allowed. PaymentMapRelativeField: type: string pattern: ^(?!(?:__proto__|prototype|constructor)(?:\.|$))[A-Za-z0-9_]+(?:\.(?!(?:__proto__|prototype|constructor)(?:\.|$))[A-Za-z0-9_]+)*$ description: Field path within one file record. Dots represent nested objects. Array traversal is not supported within a file field. PaymentMapFieldTarget: type: string enum: - sourceAccountId - sender.name - sender.countryOfIncorporation - sender.address.streetName - sender.address.buildingNumber - sender.address.city - sender.address.region - sender.address.postalCode - sender.address.country - sender.contact.email - sender.contact.phoneNumber - sender.identification.type - sender.identification.number - sender.identification.country - sender.identification.issueDate - sender.identification.expiryDate - sender.relationships[].role - sender.relationships[].firstName - sender.relationships[].lastName - sender.relationships[].nationalities[] - sender.relationships[].address.streetName - sender.relationships[].address.buildingNumber - sender.relationships[].address.city - sender.relationships[].address.region - sender.relationships[].address.postalCode - sender.relationships[].address.country - sender.relationships[].identification.type - sender.relationships[].identification.number - sender.relationships[].identification.country - sender.relationships[].identification.issueDate - sender.relationships[].identification.expiryDate - recipient.businessRelationship - recipient.name - recipient.countryOfIncorporation - recipient.address.streetName - recipient.address.buildingNumber - recipient.address.city - recipient.address.region - recipient.address.postalCode - recipient.address.country - recipient.contact.email - recipient.contact.phoneNumber - recipient.identification.type - recipient.identification.number - recipient.identification.country - recipient.identification.issueDate - recipient.identification.expiryDate - recipient.relationships[].role - recipient.relationships[].firstName - recipient.relationships[].lastName - recipient.relationships[].nationalities[] - recipient.relationships[].address.streetName - recipient.relationships[].address.buildingNumber - recipient.relationships[].address.city - recipient.relationships[].address.region - recipient.relationships[].address.postalCode - recipient.relationships[].address.country - recipient.relationships[].identification.type - recipient.relationships[].identification.number - recipient.relationships[].identification.country - recipient.relationships[].identification.issueDate - recipient.relationships[].identification.expiryDate - recipient.destination.accountNumber - recipient.destination.currency - recipient.destination.bank.bankName - recipient.destination.bank.address.streetName - recipient.destination.bank.address.buildingNumber - recipient.destination.bank.address.city - recipient.destination.bank.address.region - recipient.destination.bank.address.postalCode - recipient.destination.bank.address.country - recipient.destination.bank.swiftBic - recipient.destination.bank.clearingCode - recipient.destination.bank.clearingSystemCode - externalReference - sourceOfFunds - purpose - reference - amount.amount - amount.currency description: Leaf in the Axiym payout input. amount.amount and amount.currency are intermediate fields resolved to sourceAmount or destinationAmount by amountResolution. Document fields are configured through documents. PaymentMapField: type: object description: Copies one source field to an Axiym field without type coercion. Include every field you intend to send, even if its name already matches Axiym. Unmapped input fields are ignored. Source and target paths must be unique across field rules. Array depth and order must match; fields belonging to the same target array must use the same source array. additionalProperties: false required: - source - target properties: source: $ref: "#/components/schemas/PaymentMapSourcePath" target: $ref: "#/components/schemas/PaymentMapFieldTarget" PaymentMapDocumentTarget: type: string enum: - sender.identification.documents[] - sender.relationships[].identification.documents[] - sender.documents[] - recipient.identification.documents[] - recipient.relationships[].identification.documents[] - recipient.documents[] - supportingDocuments[] description: Axiym document collection that receives the files. Requirements for that collection and its owner follow the payout input schema and selected corridor. PaymentMapDocumentFields: type: object description: Fields within each source file containing its classification, filename, and complete base64 content. URLs and file identifiers do not replace content. A non-canonical document classification requires a value rule for this destination. additionalProperties: false required: - documentType - name - data properties: documentType: $ref: "#/components/schemas/PaymentMapRelativeField" name: $ref: "#/components/schemas/PaymentMapRelativeField" data: $ref: "#/components/schemas/PaymentMapRelativeField" PaymentMapDocumentMatch: type: object description: An exact ID equality linking a file to its destination record. All matches must hold. IDs must be non-empty strings or finite numbers; strings and numbers are not coerced. For identification evidence, include a match to the identification as well as the owner. Record paths within an array must follow the owner array established by the field rules. additionalProperties: false required: - fileField - recordPath properties: fileField: $ref: "#/components/schemas/PaymentMapRelativeField" recordPath: $ref: "#/components/schemas/PaymentMapSourcePath" PaymentMapDocumentFilter: type: object description: Includes a file only when this field equals the saved string, including case and whitespace. All filters must match. Use stable tags to distinguish uses, such as party evidence and payment evidence. additionalProperties: false required: - field - value properties: field: $ref: "#/components/schemas/PaymentMapRelativeField" value: type: string NestedPaymentMapDocument: title: Nested document connection type: object description: Files are already nested with the payment, party, person, or identification they support. Ownership follows the source structure and established field mappings. No ID matches are needed. Separate owners or identifications cannot be inferred from file names or types. additionalProperties: false required: - target - source - fields - filters - association - matches properties: target: $ref: "#/components/schemas/PaymentMapDocumentTarget" source: type: string allOf: - $ref: "#/components/schemas/PaymentMapSourcePath" pattern: \[\]$ description: Source file collection, relative to payment. The path ends in []. For nested connections, the source follows the same owner arrays as the field mappings. Linked connections use one source array at a fixed path, such as files[] or records.files[]. fields: $ref: "#/components/schemas/PaymentMapDocumentFields" filters: type: array items: $ref: "#/components/schemas/PaymentMapDocumentFilter" description: Exact conditions selecting files for this connection. Use [] when no filtering is needed. association: type: string enum: - nested matches: type: array maxItems: 0 items: $ref: "#/components/schemas/PaymentMapDocumentMatch" description: Empty for nested files. LinkedPaymentMapDocument: title: Linked document connection type: object description: Files are supplied in a separate collection. Match their IDs to the relevant records and optionally filter by usage tags. Each file in a configured source collection must resolve to exactly one destination across all connections; unmatched or ambiguous files cause payout creation to fail. Files retain source order within their destination collection. additionalProperties: false required: - target - source - fields - filters - association - matches properties: target: $ref: "#/components/schemas/PaymentMapDocumentTarget" source: type: string allOf: - $ref: "#/components/schemas/PaymentMapSourcePath" pattern: ^(?:[A-Za-z0-9_]+\.)*[A-Za-z0-9_]+\[\]$ description: Source file collection, relative to payment. The path ends in []. For nested connections, the source follows the same owner arrays as the field mappings. Linked connections use one source array at a fixed path, such as files[] or records.files[]. fields: $ref: "#/components/schemas/PaymentMapDocumentFields" filters: type: array items: $ref: "#/components/schemas/PaymentMapDocumentFilter" description: Exact conditions selecting files for this connection. Use [] when no filtering is needed. association: type: string enum: - linked matches: type: array minItems: 1 items: $ref: "#/components/schemas/PaymentMapDocumentMatch" PaymentMapDocument: description: Saved connection from one file collection to its Axiym destination. Ownership is determined by nesting or explicit ID matches. The same rules apply to every file on each payout. oneOf: - $ref: "#/components/schemas/NestedPaymentMapDocument" - $ref: "#/components/schemas/LinkedPaymentMapDocument" discriminator: propertyName: association mapping: nested: "#/components/schemas/NestedPaymentMapDocument" linked: "#/components/schemas/LinkedPaymentMapDocument" SourceOfFundsPaymentMapValue: title: SourceOfFunds translations type: object description: Reviewed exact translations for a SourceOfFunds field. The source and target must correspond to an existing field rule or document-type connection. A shared source, such as files[].kind, can have different translations for different document destinations. additionalProperties: false required: - source - targets - translations properties: source: $ref: "#/components/schemas/PaymentMapSourcePath" targets: type: array minItems: 1 maxItems: 1 items: type: string enum: - sourceOfFunds description: The Axiym controlled field for these translations. Each rule contains one target; use separate rules for other destinations. translations: $ref: "#/components/schemas/SourceOfFundsValueMap" PartyIdentificationTypePaymentMapValue: title: PartyIdentificationType translations type: object description: Reviewed exact translations for a PartyIdentificationType field. The source and target must correspond to an existing field rule or document-type connection. A shared source, such as files[].kind, can have different translations for different document destinations. additionalProperties: false required: - source - targets - translations properties: source: $ref: "#/components/schemas/PaymentMapSourcePath" targets: type: array minItems: 1 maxItems: 1 items: type: string enum: - sender.identification.type - sender.relationships[].identification.type - recipient.identification.type - recipient.relationships[].identification.type description: The Axiym controlled field for these translations. Each rule contains one target; use separate rules for other destinations. translations: $ref: "#/components/schemas/PartyIdentificationTypeValueMap" RelationshipRolePaymentMapValue: title: RelationshipRole translations type: object description: Reviewed exact translations for a RelationshipRole field. The source and target must correspond to an existing field rule or document-type connection. A shared source, such as files[].kind, can have different translations for different document destinations. additionalProperties: false required: - source - targets - translations properties: source: $ref: "#/components/schemas/PaymentMapSourcePath" targets: type: array minItems: 1 maxItems: 1 items: type: string enum: - sender.relationships[].role - recipient.relationships[].role description: The Axiym controlled field for these translations. Each rule contains one target; use separate rules for other destinations. translations: $ref: "#/components/schemas/RelationshipRoleValueMap" SupportingDocumentTypePaymentMapValue: title: SupportingDocumentType translations type: object description: Reviewed exact translations for a SupportingDocumentType field. The source and target must correspond to an existing field rule or document-type connection. A shared source, such as files[].kind, can have different translations for different document destinations. additionalProperties: false required: - source - targets - translations properties: source: $ref: "#/components/schemas/PaymentMapSourcePath" targets: type: array minItems: 1 maxItems: 1 items: type: string enum: - supportingDocuments[].documentType - sender.documents[].documentType - recipient.documents[].documentType - sender.identification.documents[].documentType - recipient.identification.documents[].documentType - sender.relationships[].identification.documents[].documentType - recipient.relationships[].identification.documents[].documentType description: The Axiym controlled field for these translations. Each rule contains one target; use separate rules for other destinations. translations: $ref: "#/components/schemas/SupportingDocumentTypeValueMap" TransactionPurposePaymentMapValue: title: TransactionPurpose translations type: object description: Reviewed exact translations for a TransactionPurpose field. The source and target must correspond to an existing field rule or document-type connection. A shared source, such as files[].kind, can have different translations for different document destinations. additionalProperties: false required: - source - targets - translations properties: source: $ref: "#/components/schemas/PaymentMapSourcePath" targets: type: array minItems: 1 maxItems: 1 items: type: string enum: - purpose description: The Axiym controlled field for these translations. Each rule contains one target; use separate rules for other destinations. translations: $ref: "#/components/schemas/TransactionPurposeValueMap" BusinessRelationshipPaymentMapValue: title: BusinessRelationship translations type: object description: Reviewed exact translations for a BusinessRelationship field. The source and target must correspond to an existing field rule or document-type connection. A shared source, such as files[].kind, can have different translations for different document destinations. additionalProperties: false required: - source - targets - translations properties: source: $ref: "#/components/schemas/PaymentMapSourcePath" targets: type: array minItems: 1 maxItems: 1 items: type: string enum: - recipient.businessRelationship description: The Axiym controlled field for these translations. Each rule contains one target; use separate rules for other destinations. translations: $ref: "#/components/schemas/BusinessRelationshipValueMap" PaymentMapValue: description: A dictionary of exact labels for one controlled destination. Rules are unique by source and target. Translations apply after field and document mapping, independently to each array entry. Exact Axiym codes pass unchanged and cannot be redefined. Unknown labels, including differences in case or whitespace, are rejected. Missing optional data is omitted; there are no default values. oneOf: - $ref: "#/components/schemas/SourceOfFundsPaymentMapValue" - $ref: "#/components/schemas/PartyIdentificationTypePaymentMapValue" - $ref: "#/components/schemas/RelationshipRolePaymentMapValue" - $ref: "#/components/schemas/SupportingDocumentTypePaymentMapValue" - $ref: "#/components/schemas/TransactionPurposePaymentMapValue" - $ref: "#/components/schemas/BusinessRelationshipPaymentMapValue" CurrencyPaymentMapAmount: title: Resolve from currency type: object description: Compares the mapped amount currency with the funding account currency and recipient destination currency on each payout. A funding-currency match fixes sourceAmount; a recipient-only match fixes destinationAmount. If both match, sourceAmount is fixed. Invalid or unavailable required currency information, or a match to neither side, rejects the payout. The funding currency comes from Axiym account data, not the submitted payment. additionalProperties: false required: - method - fundingAccount - recipientCurrency - whenBothMatch - whenNeitherMatches properties: method: type: string enum: - currency fundingAccount: type: string enum: - sourceAccountId recipientCurrency: type: string enum: - recipient.destination.currency whenBothMatch: type: string enum: - sourceAmount whenNeitherMatches: type: string enum: - reject FixedPaymentMapAmount: title: Fix one amount side type: object description: "Always treats the mapped amount as the selected side. Its currency must match that side: the Axiym funding account for sourceAmount, or the mapped recipient destination for destinationAmount. A mismatch rejects the payout." additionalProperties: false required: - method - side - requireMatchingCurrency properties: method: type: string enum: - fixed side: type: string enum: - sourceAmount - destinationAmount requireMatchingCurrency: type: boolean enum: - true PaymentMapAmountResolution: description: How the intermediate amount.amount and amount.currency fields become exactly one of sourceAmount or destinationAmount in the prepared payout. oneOf: - $ref: "#/components/schemas/CurrencyPaymentMapAmount" - $ref: "#/components/schemas/FixedPaymentMapAmount" discriminator: propertyName: method mapping: currency: "#/components/schemas/CurrencyPaymentMapAmount" fixed: "#/components/schemas/FixedPaymentMapAmount"