Quickstart: Make your first withdrawal

Use provisioned sandbox resources to authenticate, create and review a withdrawal, confirm it, and reconcile the outcome.

Integration tools

• Postman collection — Try requests in Sandbox. Set clientId and clientSecret, then send the Auth token request; the collection saves the token for subsequent requests.
• Integrate using AI — Documentation formats and an optional integration prompt for your coding agent.

Before you start

You need sandbox OAuth credentials with the ACCOUNT scope, an ACTIVE Axiym account with test balance, and an ACTIVE address book entry owned by your organization in the same currency.

Complete Access setup and read Sandbox testing. Bank withdrawal progression requires Axiym's help; wallet withdrawals use the configured testnet.

Set AXIYM_CLIENT_ID and AXIYM_CLIENT_SECRET in your shell to your sandbox OAuth credentials. All requests below use the sandbox base URL.

1. Authenticate

curl --request POST "https://partner-api.sandbox.axiym.io/api/v1/oauth/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "client_id=$AXIYM_CLIENT_ID" \
  --data-urlencode "client_secret=$AXIYM_CLIENT_SECRET" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "scope=ACCOUNT"

Set AXIYM_ACCESS_TOKEN to the returned access_token. Keep it secure; the remaining requests send it as a bearer token.

2. Configure webhooks

Register and test your HTTPS receiver using Webhook Registration and Management. Verify signatures, persist or queue deliveries, and deduplicate by event id. Subscriptions receive account, address book, and test events as well as withdrawals.

3. Select the source account

curl "https://partner-api.sandbox.axiym.io/api/v1/accounts" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN"

Choose an ACTIVE account with sufficient test balance. Set ACCOUNT_ID to its returned accountId and WITHDRAWAL_CURRENCY to its currency. Set WITHDRAWAL_AMOUNT to the decimal string you intend to debit, within the account balance.

4. Select the destination

curl "https://partner-api.sandbox.axiym.io/api/v1/address-book" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN"

Choose an ACTIVE entry owned by your organization with the same currency. For a wallet, confirm the intended network. Set DESTINATION_ID to the returned destinationId. Follow pagination if the entry is not on the first page.

Register missing entries through the Axiym Dashboard and wait for activation. See Select an address book entry.

5. Create and review the withdrawal

Generate separate keys once for this new withdrawal:

CREATE_IDEMPOTENCY_KEY=$(uuidgen)
CONFIRM_IDEMPOTENCY_KEY=$(uuidgen)

Keep both keys for this attempt. After a timeout or lost response, retry only the relevant request with its original key, path, and body. Generate fresh keys when starting another withdrawal.

The example below omits documents. If the destination corridor requires evidence, include supportingDocuments in the body. Each document contains documentType, name, and raw file bytes encoded as base64 in data, without a data-URL prefix. Use synthetic documents agreed for sandbox testing.

curl --request POST "https://partner-api.sandbox.axiym.io/api/v1/withdrawals" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN" \
  --header "Idempotency-Key: $CREATE_IDEMPOTENCY_KEY" \
  --header "Content-Type: application/json" \
  --data @- <<EOF_BODY
{
  "sourceAccountId": "$ACCOUNT_ID",
  "sourceAmount": { "amount": "$WITHDRAWAL_AMOUNT", "currency": "$WITHDRAWAL_CURRENCY" },
  "destinationId": "$DESTINATION_ID",
  "reference": "Sandbox withdrawal",
  "externalReference": "sandbox-$CREATE_IDEMPOTENCY_KEY"
}
EOF_BODY

Creation returns PENDING_CONFIRMATION; execution has not started. Set WITHDRAWAL_ID to the returned withdrawalId and retain the response for review.

Before confirming, check:

6. Confirm the reviewed instruction

After accepting those details, confirm using the separate key generated above. The request has no body.

curl --request POST \
  "https://partner-api.sandbox.axiym.io/api/v1/withdrawals/$WITHDRAWAL_ID/confirm" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN" \
  --header "Idempotency-Key: $CONFIRM_IDEMPOTENCY_KEY"

The response has status PENDING: execution is queued, not completed. For a bank scenario, share WITHDRAWAL_ID with Axiym to coordinate subsequent progression and events.

7. Track the outcome

curl \
  "https://partner-api.sandbox.axiym.io/api/v1/withdrawals/$WITHDRAWAL_ID" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN"

Use signed events for notification and this read for current state.

If still pending or held, retrieve it again later. For an unsuccessful outcome, resolve the cause before starting a new withdrawal.

For a completed wallet withdrawal, use the returned transactionHash to verify receipt on testnet. For a bank scenario, validate the simulated external outcome with Axiym.

8. Verify the account movement

Once the withdrawal is COMPLETED, retrieve the source account statement:

curl \
  "https://partner-api.sandbox.axiym.io/api/v1/accounts/$ACCOUNT_ID/statement" \
  --header "Authorization: Bearer $AXIYM_ACCESS_TOKEN"

Find the entry with relatedResourceType: WITHDRAWAL and relatedResourceId equal to WITHDRAWAL_ID. Verify type: DEBIT and an amount and currency matching the withdrawal's sourceAmount. The fee is already included in that debit. A current account balance alone does not identify this withdrawal.

If the entry is not on the first page, use pageInfo.endCursor as after while pageInfo.hasNextPage is true. Keep the account and filters unchanged.

The quickstart is complete when the withdrawal reaches COMPLETED, its debit matches the statement, and the external test outcome is verified. Continue with Reconcile activity for period totals and handling other account movements.