Check Status

Retrieve detailed information and current status of a withdrawal.

Endpoint

GET /api/withdraws/withdraws/{reference}

Parameters

Parameter	Type	Required	Description
reference	String	✅	Unique withdrawal reference (e.g. WTD1704067200000ABC123)

Request example

curl -X GET "https://app.awdpay.com/api/withdraws/withdraws/WTD1704067200000ABC123" \
  -H "Authorization: Bearer $AWDPAY_TOKEN"

Response

{
  "reference": "WTD1704067200000ABC123",
  "status": "success",
  "amount": 5000.00,
  "currency": "XOF",
  "beneficiaryName": "Amadou Diallo",
  "beneficiaryPhone": "+221770123456",
  "beneficiaryEmail": "amadou@example.com",
  "country": "SN",
  "gatewayName": "wave-senegal",
  "createdAt": "2025-01-15T10:30:00Z",
  "processedAt": "2025-01-15T10:30:45Z",
  "expiresAt": "2025-01-15T11:30:00Z",
  "failureReason": null,
  "externalReference": "WAVE_TXN_987654",
  "description": "Payment completed successfully"
}

Response fields

Field	Type	Description
reference	String	Unique withdrawal reference
status	String	Current status (see table below)
amount	Double	Withdrawal amount
currency	String	Currency code
beneficiaryName	String	Beneficiary name
beneficiaryPhone	String	Phone number
beneficiaryEmail	String	Beneficiary email
country	String	Country code
gatewayName	String	Gateway used
createdAt	DateTime	Creation date
processedAt	DateTime	Processing date (if completed)
expiresAt	DateTime	Expiration date
failureReason	String	Failure reason (if failed)
externalReference	String	External gateway reference
description	String	Status description

Possible statuses

Status	Description	Recommended action
pending	Withdrawal created, awaiting processing	Wait or cancel
processing	Being processed by gateway	Wait
success	✅ Funds successfully transferred to beneficiary	Completed
failed	❌ Transfer failed	Check failureReason, retry
expired	⏰ Withdrawal expired before processing	Create a new withdrawal
cancelled	🚫 Withdrawal cancelled	Create a new withdrawal

Status flow diagram

┌─────────┐
│ pending │
└────┬────┘
     │
     ▼
┌────────────┐
│ processing │
└─────┬──────┘
      │
      ├──────────────┬──────────────┐
      ▼              ▼              ▼
┌─────────┐    ┌─────────┐    ┌─────────┐
│ success │    │ failed  │    │ expired │
└─────────┘    └─────────┘    └─────────┘

Recommended polling

Polling strategy

For gateways without webhooks, query status with exponential backoff:

• 1st attempt: after 5 seconds
• 2nd attempt: after 15 seconds
• 3rd attempt: after 30 seconds
• Then every minute for max 10 minutes

async function pollWithdrawStatus(reference, maxAttempts = 10) {
  const delays = [5000, 15000, 30000, 60000, 60000, 60000, 60000, 60000, 60000, 60000];
  
  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://app.awdpay.com/api/withdraws/withdraws/${reference}`,
      { headers: { 'Authorization': `Bearer ${token}` } }
    );
    
    const data = await response.json();
    
    if (['success', 'failed', 'expired', 'cancelled'].includes(data.status)) {
      return data; // Final state reached
    }
    
    await new Promise(resolve => setTimeout(resolve, delays[i]));
  }
  
  throw new Error('Timeout: status not resolved');
}

---

Next step

➡️ List withdrawals — View your disbursement history