Withdrawals Guide

This page documents the withdrawal controller and DTOs in the OFFER-HUB Orchestrator: apps/api/src/modules/withdrawals/withdrawals.controller.ts, apps/api/src/modules/withdrawals/dto/create-withdrawal.dto.ts, and apps/api/src/modules/withdrawals/withdrawals.service.ts.

Every request uses Authorization: Bearer <api-key>. Write endpoints require the write scope; read endpoints require read.

Destination types and lifecycle

The statuses used by the service are WITHDRAWAL_CREATED, WITHDRAWAL_COMMITTED, WITHDRAWAL_PENDING, WITHDRAWAL_PENDING_USER_ACTION, WITHDRAWAL_COMPLETED, WITHDRAWAL_FAILED, and WITHDRAWAL_CANCELED.

POST /withdrawals

Creates a withdrawal. The request body is CreateWithdrawalDto:

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": "crypto",
    "destinationRef": "GDQP2KPQGKIHYJGXNUIYOMHARUARCA7DJT5FO2FFOOUJ3EQRQGPGAVRQ"
  }'

const withdrawal = await sdk.withdrawals.create({
  userId: "usr_abc123",
  amount: "50.00",
  currency: "USD",
  destinationType: "crypto",
  destinationRef: stellarAddress,
});

The response contains id, amount, currency, status, destinationType, committed, and createdAt. Crypto withdrawals complete synchronously. AirTM withdrawals reserve funds and normally return WITHDRAWAL_CREATED; call commit next.

Errors include USER_NOT_FOUND (404), INSUFFICIENT_FUNDS (422), AIRTM_USER_NOT_LINKED (422), AIRTM_USER_INVALID (422), and validation errors (400).

GET /withdrawals

Lists a user's withdrawals. The controller accepts only these query parameters:

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

The response is { "data": WithdrawalResponse[], "hasMore": boolean, "nextCursor"?: string }.

GET /withdrawals/:id

Fetches one withdrawal. userId is required as a query parameter because the controller passes it to the service for ownership scoping.

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

An individual WithdrawalResponse includes id, userId, amount, fee?, currency, status, destinationType, destinationRef, airtmPayoutId?, failureReason?, createdAt, and updatedAt.

POST /withdrawals/:id/commit

Commits an AirTM withdrawal created with commit: false. It accepts no body and requires userId in the query string.

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

This endpoint returns the updated WithdrawalResponse. It is not applicable to crypto withdrawals, which complete during creation. A non-committable state returns WITHDRAWAL_NOT_COMMITTABLE (409); a missing provider payout returns PROVIDER_ERROR (422).

POST /withdrawals/:id/refresh

Refreshes an AirTM payout when a webhook may have been missed. It accepts no body and requires userId in the query string.

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

The response is the current WithdrawalResponse. Crypto withdrawals do not need provider refreshes.

Idempotency and integration notes

The withdrawal controller does not declare an idempotency header or an idempotency DTO field. Do not describe Idempotency-Key as a withdrawal-specific guarantee until the controller and guard expose one. Clients should use their own request deduplication and treat the returned withdrawal ID as the operation identifier.

For provider-specific status and webhook events, see Webhooks, Balance Reference, and the upstream withdrawal endpoint source.