AirTM Provider Guide

AirTM is a global payment network that lets your users add fiat balance (top-ups) and withdraw to their own bank accounts, mobile money, or crypto wallets. With AirTM credentials configured, the Orchestrator exposes these fiat endpoints alongside the Stellar/crypto paths — both are mounted at the same time, and escrow mechanics are identical either way.

Enabling AirTM

AirtmModule is registered unconditionally in apps/api/src/app.module.ts and imported by UsersModule, TopUpsModule, WithdrawalsModule and WebhooksModule. Nothing switches it on or off — the endpoints POST /users/:id/airtm/link, POST /topups, POST /withdrawals and POST /webhooks/airtm are always mounted, and they start returning real data once AIRTM_API_KEY and AIRTM_API_SECRET are set.

Two consequences worth knowing before you configure anything:

• AirtmConfig (apps/api/src/providers/airtm/airtm.config.ts) validates on instantiation and throws Missing required Airtm environment variables: AIRTM_API_KEY, AIRTM_API_SECRET when the credentials are absent. Because the module is always imported, the API will not boot in crypto mode either without those two values.
• GET /api/v1/config reports features.airtm as true only when AIRTM_API_KEY is set (apps/api/src/modules/config/config.controller.ts), and GET /api/v1/health reports the AirTM dependency as degraded with Not configured when it is not (apps/api/src/modules/health/health.service.ts). Use both to verify a deployment.

Prerequisites

1. Orchestrator at a version that ships the AirTM modules — no provider flag to set, but PAYMENT_PROVIDER must stay crypto.
2. Enterprise AirTM account — the AirTM Enterprise environment (API base enterprise.airtm.io), with API access granted.
3. API credentials — AIRTM_API_KEY and AIRTM_API_SECRET from the AirTM dashboard. Both are required for the API to start.
4. Webhook signing secret — a Svix secret (whsec_...) used to verify inbound webhooks. Generate one with openssl rand -base64 24.
5. Public base URL — the TOPUP_CALLBACK_BASE_URL, plus your app's TOPUP_SUCCESS_REDIRECT_URL and TOPUP_CANCEL_REDIRECT_URL (configured in your .env).

Configuration

Set the AirTM variables in your Orchestrator environment. Leave PAYMENT_PROVIDER on crypto — it is unrelated to the endpoints below:

# Payment Provider — must stay crypto; `airtm` throws at startup
PAYMENT_PROVIDER=crypto

# AirTM
AIRTM_ENV=sandbox                 # sandbox | production
AIRTM_API_KEY=your-airtm-api-key
AIRTM_API_SECRET=your-airtm-api-secret
AIRTM_WEBHOOK_SECRET=whsec_...     # recommended; disables signature verification if unset

# Top-up callback + redirect URLs
TOPUP_CALLBACK_BASE_URL=http://localhost:3000/topups
TOPUP_SUCCESS_REDIRECT_URL=http://localhost:3001/topups/success
TOPUP_CANCEL_REDIRECT_URL=http://localhost:3001/topups/canceled

Environments and Base URLs

The Orchestrator authenticates with AirTM using HTTP Basic Auth: Authorization: Basic base64(AIRTM_API_KEY:AIRTM_API_SECRET).

Linking a User's AirTM Account

Before a user can top up or withdraw, their internal OFFER-HUB user must be linked to an AirTM account. The Orchestrator verifies the user's email against AirTM (and checks that the account is active and KYC-verified), then stores the airtmUserId on the user record.

POST /api/v1/users/:id/airtm/link — requires write scope

curl -X POST http://localhost:4000/api/v1/users/usr_abc123/airtm/link \
  -H "Authorization: Bearer ohk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'

Response — 200 OK, the email must match the account registered in AirTM:

{
  "data": {
    "userId": "usr_abc123",
    "airtmUserId": "usr_airtm_123",
    "airtmLinkedAt": "2026-02-25T12:00:00.000Z",
    "eligible": true,
    "email": "user@example.com"
  }
}

If the user is already linked, the same payload is returned with the existing linkage. Linking failures are surfaced as 400 or 422 with a failure reason:

Top-Ups (Pay-ins)

Top-ups add fiat balance to a user's OFFER-HUB balance. The flow is asynchronous: you create a top-up, send the user to AirTM's hosted confirmation page, and the Orchestrator credits the balance when AirTM reports the payment as succeeded.

Create a Top-Up

POST /api/v1/topups — requires write scope, 201 Created

The acting user is taken from the authenticated API key — it is not passed in the body.

curl -X POST http://localhost:4000/api/v1/topups \
  -H "Authorization: Bearer ohk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100.00",
    "currency": "USD",
    "description": "Wallet funding"
  }'

Response:

{
  "data": {
    "id": "top_xyz789",
    "amount": "100.00",
    "currency": "USD",
    "status": "TOPUP_AWAITING_USER_CONFIRMATION",
    "confirmationUri": "http://localhost:3000/topups/top_xyz789/callback?code=topup_abc123&status=confirmed",
    "expiresAt": "2026-02-25T13:00:00.000Z",
    "createdAt": "2026-02-25T12:00:00.000Z"
  }
}

Pre-flight checks fail with 422 Unprocessable Entity when the user has no linked AirTM account (AIRTM_USER_NOT_LINKED) or is not eligible (AIRTM_USER_INVALID), and with 404 when the user does not exist.

Complete the Payment

Redirect the user to confirmationUri (returned in the create response). On that page the user:

1. Logs into AirTM (or creates an account with the linked email)
2. Chooses a payment method (bank, mobile money, card, local method)
3. Completes the payment

The callback URI points at GET /api/v1/topups/:id/callback — a public endpoint (no auth) that refreshes the top-up status from AirTM and then redirects the browser:

• Status TOPUP_SUCCEEDED or TOPUP_PROCESSING → redirect to TOPUP_SUCCESS_REDIRECT_URL
• Anything else (including missing top-up) → redirect to TOPUP_CANCEL_REDIRECT_URL

Top-Up Status Lifecycle

Top-Up Endpoints

The balance is credited either from the payin.succeeded webhook or from a refresh/callback that observes the transition to TOPUP_SUCCEEDED. The balance is never incremented by the create call.

Withdrawals (Payouts)

Withdrawals move funds out of a user's OFFER-HUB balance to a destination AirTM supports. Withdrawals are created in two steps by default (create, then commit) — use commit: true for a trusted one-step flow.

Create a Withdrawal

POST /api/v1/withdrawals — requires write scope, 201 Created

Unlike top-ups, userId is passed in the body — this is a server-to-server API, and the acting user is explicit.

curl -X POST http://localhost:4000/api/v1/withdrawals \
  -H "Authorization: Bearer ohk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "usr_abc123",
    "amount": "50.00",
    "currency": "USD",
    "destinationType": "bank",
    "destinationRef": "bank-acct-12345",
    "commit": false
  }'

For a non-crypto destination the Orchestrator reserves the funds immediately (available balance decreases, reserved increases), creates the AirTM payout, and stores airtmPayoutId. On confirmation the reserved amount is either sent out (WITHDRAWAL_COMPLETED) or refunded back to available (WITHDRAWAL_FAILED / WITHDRAWAL_CANCELED).

Response:

{
  "data": {
    "id": "wth_abc456",
    "amount": "50.00",
    "currency": "USD",
    "status": "WITHDRAWAL_CREATED",
    "destinationType": "bank",
    "committed": false,
    "createdAt": "2026-02-25T12:00:00.000Z"
  }
}

With destinationType: "crypto" the withdrawal is executed synchronously over Stellar and completes immediately (WITHDRAWAL_COMPLETED), with no AirTM dependency. Creation fails with 422 INSUFFICIENT_FUNDS when the available balance is too low, and with 422 AIRTM_USER_NOT_LINKED / AIRTM_USER_INVALID when the user isn't set up on AirTM.

Commit a Withdrawal (Two-Step Flow)

With commit: false (the default), the payout stays in WITHDRAWAL_CREATED until you commit it. Only a withdrawal in WITHDRAWAL_CREATED can be committed.

POST /api/v1/withdrawals/:id/commit?userId=usr_abc123 — requires write scope

curl -X POST "http://localhost:4000/api/v1/withdrawals/wth_abc456/commit?userId=usr_abc123" \
  -H "Authorization: Bearer ohk_live_your_api_key"

Committing from any other status returns 409 WITHDRAWAL_NOT_COMMITTABLE.

Withdrawal Status Lifecycle

Withdrawal Endpoints

Webhook Verification

AirTM notifies the Orchestrator of payment and payout lifecycle events by calling its inbound webhook receiver. You never call this endpoint — AirTM does. The Orchestrator verifies the signature, returns 200 OK immediately, then processes the event asynchronously.

POST /api/v1/webhooks/airtm — 200 OK always (even if processing fails, to prevent retries)

The request must include the standard Svix headers and the raw body used to build the signature:

Verification Flow

1. The Orchestrator verifies the signature with the Svix Webhook class using AIRTM_WEBHOOK_SECRET. A mismatch throws a 401 WEBHOOK_SIGNATURE_INVALID.
2. It de-duplicates events via a unique (provider, providerEventId) constraint — repeats return { "status": "ok", "duplicate": true } and are ignored.
3. The event is recorded and processed:
   • payin.* events update the matching top-up (by airtmPayinId) and credit the balance on payin.succeeded.
   • payout.* events update the matching withdrawal (by airtmPayoutId) and refund the reserved balance on payout.failed / payout.canceled.
4. The receiver responds { "status": "ok", "processed": true }.

Supported event types:

Sample payload (illustrative):

{
  "eventId": "evt_01J2Y...",
  "eventType": "payin.succeeded",
  "occurredAt": "2026-02-25T14:32:10.000Z",
  "data": {
    "id": "payin_abc123",
    "code": "topup_xyz789",
    "amount": "100.00",
    "currency": "USD",
    "status": "SUCCEEDED",
    "reasonCode": null,
    "reasonDescription": null
  }
}

Troubleshooting

Startup Failures

Webhook Failures

AirTM Provider Error Mapping

The Orchestrator maps AirTM HTTP failures to stable error codes and masks opaque IDs in paths:

These surface under details.provider = "AIRTM" with the original method, masked path, and originalStatus.

Common API Errors

Next Steps

• Deposits Guide — Crypto vs AirTM top-ups at a glance
• Withdrawals Guide — Crypto vs AirTM payout flows
• Inbound Webhooks — AirTM and Trustless Work receivers, signature verification
• Events — SSE stream and the full domain event catalog
• Configuration — All Orchestrator environment variables
• Data Model — TopUp, Withdrawal, and WebhookEvent schemas