Skip to main content

AWDPay Transfers API

The AWDPay Transfers API allows you to transfer funds between AWDPay accounts without going through external operators (Mobile Money). It's an instant internal transfer on the AWDPay ledger.

Special configuration

For AWDPay transfers, always use:

  • gatewayName: "awdpay"
  • country: "AF" (Africa - AWDPay internal code)

Use cases​

  • 🛒 Marketplaces — Credit sellers instantly after a sale
  • 💰 Wallet apps — Fund user sub-accounts
  • 🎁 Loyalty programs — Transfer rewards between members
  • 🔄 P2P transfers — Enable transfers between AWDPay users
  • 🏢 Inter-subsidiary — Fund movements between entities of the same group

Transfer directions​

DirectionAPIDescription
User → MerchantCollections (Deposit)AWDPay user pays the merchant
Merchant → UserDisbursements (Withdrawal)Merchant sends funds to an AWDPay user

AWDPay Collection (User → Merchant)​

Receive payments from an AWDPay account to your merchant balance.

Endpoint​

POST /api/deposits/initiate

Request example​

curl -X POST "https://app.awdpay.com/api/deposits/initiate" \
  -H "Authorization: Bearer $AWDPAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "XOF",
    "customerName": "Jean Dupont",
    "customerPhone": "+221770123456",
    "customerEmail": "jean@example.com",
    "country": "AF",
    "gatewayName": "awdpay",
    "callbackUrl": "https://merchant.example/webhooks/collections",
    "metadata": {
      "orderReference": "ORDER-1192",
      "userId": "usr_12345"
    }
  }'

Specific parameters​

ParameterValueDescription
country"AF"Special country code for internal AWDPay
gatewayName"awdpay"Internal AWDPay gateway
customerPhoneStringNumber associated with payer's AWDPay account

Response​

{
  "reference": "DEP1704067200000ABC123",
  "status": "pending",
  "fees": 0,
  "paymentType": "otp",
  "createdAt": "2025-01-15T10:30:00Z",
  "expiresAt": "2025-01-15T11:30:00Z",
  "message": "Waiting for OTP confirmation"
}

AWDPay Disbursement (Merchant → User)​

Send funds from your merchant balance to an AWDPay account.

Endpoint​

POST /api/withdraws/initiate

Request example​

curl -X POST "https://app.awdpay.com/api/withdraws/initiate" \
  -H "Authorization: Bearer $AWDPAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "XOF",
    "beneficiaryName": "Marie Ndiaye",
    "beneficiaryPhone": "+221771234567",
    "beneficiaryEmail": "marie@example.com",
    "country": "AF",
    "gatewayName": "awdpay",
    "callbackUrl": "https://merchant.example/webhooks/disbursements",
    "metadata": {
      "orderReference": "PAYOUT-8831",
      "reason": "Order refund"
    }
  }'

Specific parameters​

ParameterValueDescription
country"AF"Special country code for internal AWDPay
gatewayName"awdpay"Internal AWDPay gateway
beneficiaryPhoneStringNumber associated with beneficiary's AWDPay account

Response​

{
  "reference": "WTD1704067200000DEF456",
  "status": "pending",
  "fees": 0,
  "paymentType": "direct",
  "createdAt": "2025-01-15T10:30:00Z",
  "expiresAt": "2025-01-15T11:30:00Z",
  "message": "Withdrawal initiated successfully"
}

Check status​

Collection​

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

Disbursement​

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

AWDPay transfer advantages​

FeatureAWDPay TransferMobile Money
Fees0% or reducedVariable by operator
Speed⚡ Instant5 sec - 2 min
Availability24/7Depends on operator
ConfirmationOTP (Collection) / Direct (Disbursement)Variable
LimitAccording to your planOperator limits

Specific rules​

Balance verification​

AWDPay checks the balance of both parties:

  • Collection: Payer's AWDPay account must have sufficient funds
  • Disbursement: Your merchant balance must be sufficient
{
  "error": "insufficient_balance",
  "message": "Payer's account does not have sufficient funds"
}

OTP confirmation (Collections)​

For collections, the payer receives an OTP to confirm:

  1. You initiate the collection
  2. Payer receives an SMS with OTP code
  3. Payer confirms payment in AWDPay app
  4. Status changes from pending → success

Direct transfers (Disbursements)​

Disbursements to an AWDPay account are instant and don't require beneficiary confirmation.

Webhooks​

Events use the same topics as other methods:

Successful collection​

{
  "event": "deposit.success",
  "timestamp": "2025-01-15T10:30:45Z",
  "data": {
    "reference": "DEP1704067200000ABC123",
    "status": "success",
    "amount": 5000.00,
    "currency": "XOF",
    "gatewayName": "awdpay",
    "country": "AF",
    "customerPhone": "+221770123456",
    "metadata": {
      "orderReference": "ORDER-1192"
    }
  }
}

Successful disbursement​

{
  "event": "withdrawal.success",
  "timestamp": "2025-01-15T10:31:00Z",
  "data": {
    "reference": "WTD1704067200000DEF456",
    "status": "success",
    "amount": 5000.00,
    "currency": "XOF",
    "gatewayName": "awdpay",
    "country": "AF",
    "beneficiaryPhone": "+221771234567",
    "metadata": {
      "orderReference": "PAYOUT-8831"
    }
  }
}

Reconciliation​

In the AWDPay dashboard and exports:

  • AWDPay transfers are identified by gatewayName: "awdpay"
  • The country: "AF" field allows easy filtering
  • Distinguish them from Mobile Money movements for your reports

Next steps​

  1. Collections API → Complete deposits documentation
  2. Disbursements API → Complete withdrawals documentation
  3. Authentication → Get your API token
  4. Error handling → Handle failure cases