# Payment API

> Discover corridors, request quotes, submit payouts, track outcomes, and reconcile settlement.

Product: Payment API

Guides follow the current API reference (0.1.0) and event reference (0.1.0). Older reference versions are listed separately; the guides are not historical snapshots.

Operation references are compact. Follow the linked schemas for field details, or the complete-reference link to retrieve all related definitions in one document.

## Guides and concepts

- [Build with the Payment API](https://docs.axiym.io/payment-api.md): Make cross-border payments to beneficiaries in the specified destination currency.
- [Overview](https://docs.axiym.io/payment-api/concepts/overview.md): Make cross-border payments to beneficiaries in the specified destination currency.
- [Axiym accounts and funding](https://docs.axiym.io/payment-api/concepts/accounts-and-funding.md): Understand how an Axiym account is funded and how its balance funds a payment.
- [Corridors and destinations](https://docs.axiym.io/payment-api/concepts/corridors.md): Understand how destination, currency, access, and local requirements define a cross-border payment route.
- [Payment details](https://docs.axiym.io/payment-api/concepts/payment-details.md): Use your existing payment data, describe supported values in familiar terms, and understand destination requirements.
- [Commercial terms](https://docs.axiym.io/payment-api/concepts/commercial-terms.md): Understand the amounts, exchange rate, fees, and expiry returned when a payout is created.
- [Payout lifecycle](https://docs.axiym.io/payment-api/concepts/payout-lifecycle.md): Follow a payment from preparation and pricing through confirmation, approval, settlement, delivery, and reconciliation.
- [Notifications and tracking](https://docs.axiym.io/payment-api/concepts/notifications-and-tracking.md): Combine webhook notifications, payout reads, and reconciliation for reliable status handling.
- [Terminology](https://docs.axiym.io/payment-api/concepts/terminology.md): Definitions for payment concepts, commercial terms, and the API names used in this documentation.
- [Getting started](https://docs.axiym.io/payment-api/integration-guide.md): Follow the recommended path from sandbox access to a production-ready payout integration.
- [Access and environments](https://docs.axiym.io/payment-api/integration-guide/access-and-environments.md): Configure credentials, base URLs, and network access for sandbox and production.
- [Sandbox testing](https://docs.axiym.io/payment-api/integration-guide/sandbox-testing.md): Test the complete payment flow with a funded test account and coordinated payout scenarios.
- [Make your first payout](https://docs.axiym.io/payment-api/integration-guide/quickstart.md): Discover a corridor, create and review a sandbox payout, then confirm and track it.
- [Integrate using AI](https://docs.axiym.io/payment-api/integration-guide/integrate-with-ai.md): Use Axiym documentation and an optional integration prompt with your coding agent.
- [Discover corridors](https://docs.axiym.io/payment-api/integration-guide/discover-corridors.md): Find an available payout route and retrieve its amount limits and corridor requirements.
- [Prepare payment data](https://docs.axiym.io/payment-api/integration-guide/prepare-payout-data.md): Assemble payment details and choose direct input or a reusable field and value map.
- [Build the payout payload](https://docs.axiym.io/payment-api/integration-guide/prepare-payout-data/payout-payload.md): Understand how the funding account, amount, parties, and payment fields form one complete payout instruction.
- [Sender and related individuals](https://docs.axiym.io/payment-api/integration-guide/prepare-payout-data/sender.md): Supply identity, address, contact, registration, and ownership information for the sending business.
- [Recipient](https://docs.axiym.io/payment-api/integration-guide/prepare-payout-data/recipient.md): Identify the business being paid and the destination that receives the payout.
- [Source of funds, purpose, and documents](https://docs.axiym.io/payment-api/integration-guide/prepare-payout-data/payment-fields.md): Supply source of funds, payment purpose, recipient reference, and payment evidence.
- [Supporting documents](https://docs.axiym.io/payment-api/integration-guide/prepare-payout-data/supporting-documents.md): Attach the evidence required to review and process each payout, on the party or payment it relates to.
- [Payment Data Maps](https://docs.axiym.io/payment-api/integration-guide/prepare-payout-data/payment-data-maps.md): Reuse your field names and labels, identify missing data, and prepare a reusable payment map.
- [Controlled values](https://docs.axiym.io/payment-api/integration-guide/prepare-payout-data/controlled-values.md): Allowed Axiym payment codes and fields supported by saved value mappings.
- [Create and confirm a payout](https://docs.axiym.io/payment-api/integration-guide/create-a-payout.md): Create a payout with complete payment details, review the prepared instruction, and confirm it to start processing.
- [Track a payout](https://docs.axiym.io/payment-api/integration-guide/track-a-payout.md): Use webhooks and polling to follow a payout through processing and its final outcome.
- [Reconcile payouts](https://docs.axiym.io/payment-api/integration-guide/reconcile-payouts.md): Join payout resources, webhook events, partner references, and funding account statement entries.
- [Authentication](https://docs.axiym.io/payment-api/integration-guide/fundamentals/authentication.md): Obtain an OAuth 2.0 access token and authenticate Axiym API requests.
- [Common headers](https://docs.axiym.io/payment-api/integration-guide/fundamentals/common-headers.md): Use authentication, tracing, idempotency, and content-type headers consistently.
- [Idempotency](https://docs.axiym.io/payment-api/integration-guide/fundamentals/idempotency.md): Retry state-changing requests without creating duplicate operations.
- [Pagination and query parameters](https://docs.axiym.io/payment-api/integration-guide/fundamentals/pagination-and-query-parameters.md): Follow cursor-based pages and use list filters without changing resource scope.
- [Error handling and retries](https://docs.axiym.io/payment-api/integration-guide/fundamentals/error-handling-and-retries.md): Interpret structured API errors and retry only temporary or ambiguous failures.
- [Rate limits](https://docs.axiym.io/payment-api/integration-guide/fundamentals/rate-limits.md): Pace requests and handle throttling using the response headers.
- [Data formats and constants](https://docs.axiym.io/payment-api/integration-guide/fundamentals/data-formats-and-constants.md): Store and send identifiers, decimals, currencies, countries, dates, and timestamps correctly.
- [Webhooks overview](https://docs.axiym.io/payment-api/webhooks/overview.md): Receive signed notifications when payout resources change.
- [Events](https://docs.axiym.io/payment-api/webhooks/events.md): Understand Payment API event types, payloads, and processing rules.
- [Registration and management](https://docs.axiym.io/payment-api/webhooks/registration-and-management.md): Create, list, test, and disable webhook subscriptions.
- [Verifying signatures](https://docs.axiym.io/payment-api/webhooks/verifying-signatures.md): Verify each Ed25519 webhook signature before trusting the event payload.
- [Webhook reconciliation](https://docs.axiym.io/payment-api/webhooks/reconciliation.md): Recover from missed, delayed, duplicate, or unprocessed payout notifications.

## API reference 0.1.0 (current)

[OpenAPI contract](https://docs.axiym.io/openapi/payment-api/0.1.0.yaml)

- [Axiym Payment API](https://docs.axiym.io/payment-api/api-reference/0.1.0.md)
- [Get access token](https://docs.axiym.io/payment-api/api-reference/0.1.0/auth/oauth/token/post.md): 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.
- [List payment data maps](https://docs.axiym.io/payment-api/api-reference/0.1.0/payment-data-maps/listPaymentDataMaps.md): Returns Payment Data Maps stored for your integration. Omit status to include both active and archived maps, or filter by ACTIVE or ARCHIVED.
- [Store a payment data map](https://docs.axiym.io/payment-api/api-reference/0.1.0/payment-data-maps/createPaymentDataMap.md): 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.
- [Get a payment data map](https://docs.axiym.io/payment-api/api-reference/0.1.0/payment-data-maps/getPaymentDataMap.md): Returns an active or archived Payment Data Map accessible to your integration, including its status, immutable definition, and content hash.
- [Archive a payment data map](https://docs.axiym.io/payment-api/api-reference/0.1.0/payment-data-maps/archivePaymentDataMap.md): 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.
- [List webhook subscriptions](https://docs.axiym.io/payment-api/api-reference/0.1.0/webhook-subscriptions/webhooks/subscriptions/get.md): Returns the active webhook endpoints registered for your partnership. Use pagination to retrieve additional subscriptions.
- [Create webhook subscription](https://docs.axiym.io/payment-api/api-reference/0.1.0/webhook-subscriptions/webhooks/subscriptions/post.md): 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.
- [Test webhook subscription](https://docs.axiym.io/payment-api/api-reference/0.1.0/webhook-subscriptions/webhooks/subscriptions/subscriptionid/tests/post.md): 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.
- [Disable webhook subscription](https://docs.axiym.io/payment-api/api-reference/0.1.0/webhook-subscriptions/webhooks/subscriptions/subscriptionid/delete.md): Disables the selected webhook subscription. The endpoint stops receiving new deliveries, and the subscription no longer appears when listing active subscriptions.
- [Get webhook public key](https://docs.axiym.io/payment-api/api-reference/0.1.0/webhook-subscriptions/webhooks/public-keys/publickeyid/get.md): 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.
- [List accounts](https://docs.axiym.io/payment-api/api-reference/0.1.0/accounts/listAccounts.md): 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.
- [Get account](https://docs.axiym.io/payment-api/api-reference/0.1.0/accounts/getAccount.md): Returns the balance, currency, payment rail, and status of an Axiym account accessible to your integration.
- [Get account statement](https://docs.axiym.io/payment-api/api-reference/0.1.0/accounts/getAccountStatement.md): 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.
- [List payment corridors](https://docs.axiym.io/payment-api/api-reference/0.1.0/corridors/listCorridors.md): 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.
- [Get payment corridor details](https://docs.axiym.io/payment-api/api-reference/0.1.0/corridors/getCorridorDetails.md): 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`.
- [List payouts](https://docs.axiym.io/payment-api/api-reference/0.1.0/payouts/listPayouts.md): Returns payouts using the common payment response document, including payouts awaiting confirmation. Filter by funding account, `externalReference`, or status.
- [Create a payout](https://docs.axiym.io/payment-api/api-reference/0.1.0/payouts/createPayout.md): 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.
- [Create a payout with mapped data](https://docs.axiym.io/payment-api/api-reference/0.1.0/payouts/createMappedPayout.md): 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.
- [Confirm a payout](https://docs.axiym.io/payment-api/api-reference/0.1.0/payouts/confirmPayout.md): 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`.
- [Get a payout](https://docs.axiym.io/payment-api/api-reference/0.1.0/payouts/getPayout.md): Returns the payout as a flat payment document containing its current status, commercial terms, prepared payment instruction, and any outcome reason.
- [Schemas](https://docs.axiym.io/payment-api/api-reference/0.1.0/schemas.md): Data models used by the Payment API.

## Event reference 0.1.0 (current)

[OpenAPI contract](https://docs.axiym.io/openapi/payment-api/events/0.1.0.yaml)

- [Axiym Payment API Events](https://docs.axiym.io/payment-api/events/0.1.0.md)
- [Payout created](https://docs.axiym.io/payment-api/events/0.1.0/payout/onPayoutCreated.md): Sent once a payout has been confirmed and accepted for processing.
- [Payout rejected](https://docs.axiym.io/payment-api/events/0.1.0/payout/onPayoutRejected.md): Sent when the payout is rejected and will not complete, by compliance or transaction controls before settlement or by the bank or network during delivery. Reserved funds are released. See `reasonCode` for the reason.
- [Payout held](https://docs.axiym.io/payment-api/events/0.1.0/payout/onPayoutHeld.md): Sent when a confirmed payout is temporarily placed on hold.
- [Payout completed](https://docs.axiym.io/payment-api/events/0.1.0/payout/onPayoutCompleted.md): Sent when the payout has been delivered successfully to the beneficiary.
- [Payout canceled](https://docs.axiym.io/payment-api/events/0.1.0/payout/onPayoutCanceled.md): Sent when a payout moves to `CANCELED` because unconfirmed terms expired (`reasonCode: TERMS_EXPIRED`), it was canceled before execution, or funds were returned after delivery. See `reasonCode` for the reason.
- [Account credited](https://docs.axiym.io/payment-api/events/0.1.0/account/onAccountCredited.md): Sent when a credit has been posted to an account.
- [Account debited](https://docs.axiym.io/payment-api/events/0.1.0/account/onAccountDebited.md): Sent when a debit has been posted to an account.
- [Account activated](https://docs.axiym.io/payment-api/events/0.1.0/account/onAccountActivated.md): Sent when an account becomes active and available for supported operations.
- [Account suspended](https://docs.axiym.io/payment-api/events/0.1.0/account/onAccountSuspended.md): Sent when an account is suspended and temporarily unavailable for supported operations.
- [Account closed](https://docs.axiym.io/payment-api/events/0.1.0/account/onAccountClosed.md): Sent when an account is permanently closed.
- [Webhook subscription test](https://docs.axiym.io/payment-api/events/0.1.0/webhook-subscription/onSubscriptionTest.md): Sent only when you request a test delivery for a webhook subscription.

- [Schemas](https://docs.axiym.io/payment-api/events/0.1.0/schemas.md): Individual event schema definitions.