# Getting started

Follow the recommended path from sandbox access to a production-ready payout integration.

Product: Payment API
Guides follow API reference 0.1.0 and event reference 0.1.0.
Canonical page: https://docs.axiym.io/payment-api/integration-guide

This guide takes you from initial access through your first payout and the
operational handling required for production.

## The integration path

### 1. Set up

* [Configure access and environments](/payment-api/integration-guide/access-and-environments).
* Understand the [sandbox testing](/payment-api/integration-guide/sandbox-testing)
  model and fixtures available to your partnership.

### 2. Prepare your data

* Discover the corridors available to the partnership.
* Use Axiym's fields and exact codes directly, or prepare a
  [Payment Data Map](/payment-api/integration-guide/prepare-payout-data/payment-data-maps)
  for custom sender fields, recipient fields, value labels, or any combination.
* Collect the required recipient and destination details. When paying for
  yourself, omit `sender`; Axiym uses the account holder's onboarded profile.
* Supply purpose and supporting evidence where required. A reference is optional.

### 3. Execute a payout

* Create the payout for the selected Axiym account, amount, and corridor. It
  returns `PENDING_CONFIRMATION` without reserving funds.
* Review the financial terms and final prepared instruction.
* Confirm the payout to reserve `sourceAmount` and start asynchronous processing.

### 4. Operate reliably

* Verify signed webhook events and de-duplicate deliveries.
* Poll the payout when authoritative current state matters.
* Retry ambiguous state-changing requests with the same idempotency key.
* Reconcile settled movements against the funding account statement.

Complete [Make your first payout](/payment-api/integration-guide/quickstart) to
see the full payment sequence.

## Implementation guides

| Guide                                                                         | Outcome                                                                                                    |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| [Discover corridors](/payment-api/integration-guide/discover-corridors)       | Select an available route and retrieve its amount limits and requirements.                                 |
| [Prepare payment data](/payment-api/integration-guide/prepare-payout-data)    | Choose direct Axiym input or prepare reusable field mappings and value translations.                       |
| [Create and confirm a payout](/payment-api/integration-guide/create-a-payout) | Create and price the payment instruction, review it, and confirm it to reserve funds and start processing. |
| [Track a payout](/payment-api/integration-guide/track-a-payout)               | Process asynchronous status updates using webhooks and polling.                                            |
| [Reconcile payouts](/payment-api/integration-guide/reconcile-payouts)         | Join payouts, events, references, and account statement entries.                                           |

## Shared fundamentals

Use these rules across every endpoint:

* [Authentication](/payment-api/integration-guide/fundamentals/authentication)
* [Common headers](/payment-api/integration-guide/fundamentals/common-headers)
* [Idempotency](/payment-api/integration-guide/fundamentals/idempotency)
* [Pagination and query parameters](/payment-api/integration-guide/fundamentals/pagination-and-query-parameters)
* [Error handling and retries](/payment-api/integration-guide/fundamentals/error-handling-and-retries)
* [Rate limits](/payment-api/integration-guide/fundamentals/rate-limits)
* [Data formats and constants](/payment-api/integration-guide/fundamentals/data-formats-and-constants)

## Production-ready checklist

* Credentials and base URLs are isolated by environment.
* Every runtime calls from an allowlisted public egress address.
* Every account, payout, Payment Data Map, and webhook subscription is
  accessible through the integration's credentials in the correct environment.
* The selected funding account is active, payout-enabled, and sufficiently
  funded when the payment is confirmed.
* Creation and confirmation use separate idempotency keys, each stable across
  retries of that operation.
* Commercial-term expiry is handled before confirmation.
* Representative payout data has been tested for each supported destination
  context and input structure.
* When using maps, the correct active `paymentDataMapId` is configured for the
  deployment and retained with each payout created using it.
* The payout's financial terms and final translated values are reviewed before
  confirmation.
* Insufficient funds and invalid payout status at confirmation are handled.
* Funding reservations and settlement debits are represented separately.
* Webhook signatures are verified against the raw request body.
* Event deliveries are de-duplicated and can arrive out of order.
* Payouts are polled when current state matters.
* Account statement reconciliation can recover from missed notifications.
* Secrets, access tokens, base64 document content, and sensitive party data are
  excluded from application logs.