Create and confirm a payout

Creating a payout prepares the complete instruction but does not commit funds or start execution. Review the prepared response, then confirm that exact instruction before the confirmation deadline.

Validate payout data first

Follow Prepare and test payout data before requesting a quote. Payout Test can:

validate party data that already uses Axiym's structure;
apply a stored Party Data Map before validation;
show how controlled values are normalized; and
check country and corridor-specific data requirements.

The test uses destination context instead of a quote and does not check rates, amount limits, funding, or account balances. It creates no payment and reserves no funds.

Read The payout payload first for the role of the quote, sender, receiver, transaction, supporting evidence, and optional party data mapping in this request.

Request shape

{
  "quoteId": "978490c4-4227-4a75-9820-5f90482bb78b",
  "clientReference": "PAYOUT-2026-001",
  "transaction": {},
  "sender": {},
  "receiver": {}
}

Add partyDataMapId only when the sender and receiver objects use a structure that your partnership has stored through the Party Data Maps API. If it is absent, the API validates the objects directly against the documented Axiym sender and receiver schemas.

These are separate request variants in the OpenAPI document:

AxiymPartyPayoutRequest rejects partyDataMapId, unknown party fields, and missing baseline Axiym fields.
MappedPartyPayoutRequest requires partyDataMapId, accepts the associated partner party structures, and validates their normalized result.

Both variants always require Axiym-shaped transaction data and are checked against the corridor requirements derived from the quote. “Axiym-shaped” describes field names and nesting. Controlled-value fields may contain an exact Axiym value or descriptive text; Axiym normalizes them in both request modes.

Use Custom party data maps to decide which input mode fits your integration, or inspect a sample structure in the Payload Mapping Tool.

Complete example

{
  "quoteId": "978490c4-4227-4a75-9820-5f90482bb78b",
  "clientReference": "PAYOUT-2026-001",
  "transaction": {
    "purpose": "payment for imported inventory",
    "sourceOfFunds": "revenue from normal business operations",
    "reference": "INV-2026-001",
    "supportingDocuments": [
      {
        "documentType": "supplier invoice",
        "documentDescription": "Invoice INV-2026-001",
        "documentContentType": "application/pdf",
        "documentData": "JVBERi0xLjQKJcTl8uXrCg=="
      }
    ]
  },
  "sender": {
    "name": "Acme Trading Pte Ltd",
    "countryOfIncorporation": "SG",
    "address": {
      "addressLine": "18 Robinson Road",
      "city": "Singapore",
      "postalCode": "048547",
      "country": "SG"
    },
    "contact": {
      "email": "payments@acme.example",
      "phoneNumber": "+6561234567"
    },
    "id": {
      "type": "company registration number",
      "number": "202412345A",
      "country": "SG"
    },
    "ubos": [
      {
        "firstName": "Maya",
        "lastName": "Tan",
        "designation": "ultimate beneficial owner",
        "nationalities": ["SG"],
        "address": {
          "addressLine": "10 Anson Road",
          "city": "Singapore",
          "postalCode": "079903",
          "country": "SG"
        },
        "id": {
          "type": "passport",
          "number": "E1234567A",
          "country": "SG",
          "expiryDate": "2033-01-09"
        }
      }
    ]
  },
  "receiver": {
    "name": "Example Supplier Corporation",
    "countryOfIncorporation": "PH",
    "relationship": "supplier of imported goods",
    "address": {
      "addressLine": "6789 Ayala Avenue",
      "city": "Makati",
      "postalCode": "1226",
      "country": "PH"
    },
    "contact": {
      "email": "accounts@example-supplier.test",
      "phoneNumber": "+63281234567"
    },
    "bank": {
      "accountHolderName": "Example Supplier Corporation",
      "accountType": "business current account",
      "accountNumber": "1234567890",
      "name": "Example Bank",
      "country": "PH",
      "clearingCode": "010000018"
    }
  }
}

Create the payout

curl --request POST \
  "https://partner-api.sandbox.axiym.io/api/v1/payouts" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "X-Request-Id: 4df45565-62bd-4ceb-9f5e-788a8b501093" \
  --header "Idempotency-Key: payout-2026-001" \
  --data @payout.json

The API returns 201 Created with status PENDING_CONFIRMATION. Store payoutId, quoteId, clientReference, and confirmationExpiresAt together.

Review the prepared payout

Before confirming, verify:

sell, buy, fee, and totalPayable match the quote;
accountId, payoutMethod, and clientReference are correct;
paymentData.sender and paymentData.receiver contain the expected mapped values;
each descriptive controlled value has been normalized to an acceptable final Axiym value;
the destination bank and account details are correct;
the transaction purpose, source of funds, and reference are correct; and
each supporting-document digest matches the submitted document.

The API does not echo base64 document content. It returns document metadata, sha256, and hasBackside so the submitted evidence can be verified without returning the encoded file.

No funds are reserved or moved, and no instruction is sent for compliance review or execution while the payout has status PENDING_CONFIRMATION.

Confirm the payout

curl --request POST \
  "https://partner-api.sandbox.axiym.io/api/v1/payouts/$PAYOUT_ID/confirm" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN" \
  --header "X-Request-Id: 261a4f35-c0c0-4c39-ad2f-9c740410508e" \
  --header "Idempotency-Key: confirm-payout-2026-001"

Confirmation returns 202 Accepted and changes the payout to PROCESSING. It consumes the quote, reserves totalPayable, and starts compliance review, approval, settlement, and execution. The reservation prevents the same balance from funding another payout. It becomes a debit at settlement or is released if the payout ends before settlement.

Retry an ambiguous confirmation response with the same Idempotency-Key. Never create another payout merely because the confirmation response was lost.

Common validation failures

quote is expired, used, or belongs to another scope;
partyDataMapId is omitted and sender or receiver does not match the Axiym schema;
required baseline party data is missing;
a corridor-specific bank or identification field is missing or invalid;
no supporting document is included;
embedded content is not valid base64; or
partyDataMapId does not match the submitted party structures;
a mapped sender or receiver is incomplete after normalization.

Fix validation errors and create a new payout request as appropriate. If the HTTP outcome is ambiguous, retry the identical request with the same Idempotency-Key.

Common confirmation failures

the payout is not in PENDING_CONFIRMATION;
confirmationExpiresAt has passed;
the referenced quote expired, was canceled, or became otherwise invalid;
the funding account cannot cover totalPayable; or
the payout or quote belongs to another client.

An expired prepared payout cannot be changed or revived. Request a new quote and create a new payout.

On this page