Withdrawals SDK Reference

sdk.withdrawals moves funds off the platform: to external Stellar wallets (crypto mode) or through AirTM payouts (bank accounts, mobile money). All methods are backed by the withdrawals module on the Orchestrator.

Request fields

The API creates withdrawals through POST /withdrawals with this body (see CreateWithdrawalDto in the orchestrator repo):

Withdrawal lifecycle

Source: packages/shared/src/enums/withdrawal-status.enum.ts in the orchestrator repo.

Create a withdrawal

sdk.withdrawals.create(data) → POST /withdrawals

Two-step mode (default): creates the withdrawal, reserves the amount from the user's available balance, and creates the payout in AirTM. Commit later with sdk.withdrawals.commit().

One-step mode (commit: true): creates and commits in a single call.

// Two-step (default)
const withdrawal = await sdk.withdrawals.create({
  userId: 'usr_abc123',
  amount: '50.00',
  destinationType: 'airtm_balance',
  destinationRef: 'bank_account_42',
  description: 'Cash out earnings'
});
// withdrawal.status === 'WITHDRAWAL_CREATED'
await sdk.withdrawals.commit(withdrawal.id);

// One-step
const instant = await sdk.withdrawals.create({
  userId: 'usr_abc123',
  amount: '50.00',
  destinationType: 'crypto',
  destinationRef: 'GDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOUJ3EQRQGPGAVRQ',
  commit: true
});

Server-side flow for AirTM destinations:

1. Verify the user exists and has a linked, eligible AirTM account
2. Verify sufficient available balance and reserve the amount
3. Create the withdrawal record in WITHDRAWAL_CREATED
4. Create the payout in AirTM and map its status onto the withdrawal
5. If the AirTM payout fails, the reservation is rolled back and the withdrawal is marked WITHDRAWAL_FAILED

Possible errors:

• 404 — user not found (USER_NOT_FOUND)
• 422 — insufficient available balance (INSUFFICIENT_FUNDS), AirTM account not linked (AIRTM_USER_NOT_LINKED), or AirTM user not eligible (AIRTM_USER_INVALID)
• 502 — payout provider failure (PROVIDER_ERROR)

List withdrawals

sdk.withdrawals.list(params?) → GET /withdrawals

Returns a cursor-paginated list of withdrawals for a user.

curl -X GET "http://localhost:4000/api/v1/withdrawals?userId=usr_abc123&limit=20" \
  -H "Authorization: Bearer ohk_live_your_api_key"

Possible errors:

• 401 / 403 — missing or insufficient API key scopes (read scope required)

Get a withdrawal

sdk.withdrawals.get(withdrawalId) → GET /withdrawals/{withdrawalId}

Returns a single withdrawal. The REST endpoint also takes the acting user as ?userId= for authorization.

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

Possible errors:

• 404 — withdrawal not found for this user (WITHDRAWAL_NOT_FOUND)

Commit a withdrawal

sdk.withdrawals.commit(withdrawalId) → POST /withdrawals/{withdrawalId}/commit

Commits a withdrawal created in two-step mode, sending it to AirTM for processing.

Preconditions:

• Withdrawal must be in WITHDRAWAL_CREATED status — this is the only committable state
• The withdrawal must have an associated AirTM payout

Possible errors:

• 404 — withdrawal not found (WITHDRAWAL_NOT_FOUND)
• 409 — withdrawal cannot be committed in its current status (WITHDRAWAL_NOT_COMMITTABLE)
• 422 — withdrawal has no associated AirTM payout (PROVIDER_ERROR)

Refresh withdrawal status

sdk.withdrawals.refresh(withdrawalId) → POST /withdrawals/{withdrawalId}/refresh?userId=

Pulls the latest payout status from AirTM and updates the local record when the transition is valid. Use this when a webhook may have been missed.

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

The refresh is a no-op when the mapped AirTM status does not represent a valid transition from the current status (per the withdrawal state machine above). Withdrawals without an AirTM payout are returned unchanged.

Possible errors:

• 404 — withdrawal not found for this user (WITHDRAWAL_NOT_FOUND)

Error handling

All methods throw typed SDK errors. The most relevant for withdrawals:

import { InsufficientFundsError, NotFoundError } from '@offerhub/sdk';

try {
  await sdk.withdrawals.commit('wd_abc123');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.error('Withdrawal not found for this user');
  } else if (error instanceof OfferHubError && error.code === 'WITHDRAWAL_NOT_COMMITTABLE') {
    console.error('Withdrawal already committed or canceled');
  }
}

Sources

All behavior on this page was verified against the orchestrator repository (OFFER-HUB/OFFER-HUB), not inferred:

• SDK client: packages/sdk/src/resources/withdrawals.ts
• Controller: apps/api/src/modules/withdrawals/withdrawals.controller.ts
• Service: apps/api/src/modules/withdrawals/withdrawals.service.ts
• DTO: apps/api/src/modules/withdrawals/dto/create-withdrawal.dto.ts
• Status mapper: apps/api/src/providers/airtm/mappers/payout-status.mapper.ts
• State machine: packages/shared/src/enums/withdrawal-status.enum.ts
• Error codes: packages/shared/src/constants/error-codes.ts

Related pages

• Withdrawals Guide — withdrawal flows and provider modes
• Deposits Guide — the inbound side of fund movement
• Orders SDK Reference — sdk.orders method reference
• Real-Time Events & Webhooks — WITHDRAWAL_* event delivery