Skip to main content

Initiate Deposit

Classic Deposit (DIRECT & REDIRECT)​

For gateways with type: DIRECT or REDIRECT, use this single-step endpoint.

Endpoint​

POST /api/v2/classic/deposit/initiate

Request Body​

{
  "amount": 10000.0,
  "currency": "XOF",
  "customerEmail": "customer@example.com",
  "customerPhone": "+221701234567",
  "country": "SN",
  "gatewayName": "wave-senegal",
  "callbackUrl": "https://merchant.example/webhooks/deposit",
  "customerName": "Awa Diop",
  "returnUrl": "https://merchant.example/thank-you",
  "metadata": {
    "order_id": "ORDER_123",
    "description": "Premium subscription"
  }
}

Sandbox Example​

curl -X POST "https://sandbox.awdpay.com/test/api/v2/classic/deposit/initiate" \
  -H "Authorization: Bearer $AWDPAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000.0,
    "currency": "XOF",
    "customerEmail": "test@example.com",
    "customerPhone": "+221701234567",
    "country": "SN",
    "gatewayName": "wave-senegal",
    "callbackUrl": "https://merchant.example/webhooks/deposit",
    "customerName": "Test User",
    "returnUrl": "https://merchant.example/thank-you",
    "metadata": {
      "order_id": "ORDER_123"
    }
  }'

Response​

{
  "reference": "DEP_TEST_1763646304918_1D05265E",
  "status": "pending",
  "fees": 104.0,
  "paymentType": "REDIRECT",
  "createdAt": "2025-11-20T14:45:04.921662462",
  "expiresAt": "2025-11-21T14:45:04.921748366",
  "message": "Dépôt de test créé avec succès. Ceci est un environnement sandbox.",
  "url": "https://sandbox.awdpay.com/payment/DEP_TEST_1763646304918_1D05265E"
}

Integration Notes​

  • REDIRECT gateways: redirect customer to the url field
  • DIRECT gateways: customer receives STK push notification on their phone

Two-Flow Deposit (OTP gateways)​

For gateways with type: OTP (e.g., orange-money-ci, awdpay), use this two-step process.

Step 1: Generate Invoice​

Endpoint​

POST /api/v2/validation/deposit/generate-invoice

Request​

{
  "amount": 50000.0,
  "currency": "XOF",
  "customerEmail": "client@example.com",
  "customerPhone": "+221701234567",
  "country": "CI",
  "gatewayName": "orange-money-ci",
  "callbackUrl": "https://merchant.example/webhooks/deposit",
  "customerName": "Koffi Mensah",
  "metadata": {
    "order_id": "ORDER_67890"
  }
}

Sandbox Example​

curl -X POST "https://sandbox.awdpay.com/test/api/v2/validation/deposit/generate-invoice" \
  -H "Authorization: Bearer $AWDPAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000.0,
    "currency": "XOF",
    "customerEmail": "test@example.com",
    "customerPhone": "+225070000000",
    "country": "CI",
    "gatewayName": "orange-money-ci",
    "callbackUrl": "https://merchant.example/webhooks/deposit",
    "customerName": "Test User"
  }'

Response​

{
  "reference": "DEP_INV_TEST_1732108900000_E5F6G7H8",
  "status": "pending",
  "fees": 1050.0,
  "createdAt": "2025-11-20T15:01:40",
  "expiresAt": "2025-11-20T21:01:40",
  "message": "Invoice généré en sandbox"
}

Step 2: Confirm with OTP​

Customer receives OTP on their phone; submit it to finalize payment.

Endpoint​

POST /api/v2/validation/deposit/confirm

Request​

{
  "trxReference": "DEP_INV_TEST_1732108900000_E5F6G7H8",
  "otp": "123456"
}

Sandbox Example​

curl -X POST "https://sandbox.awdpay.com/test/api/v2/validation/deposit/confirm" \
  -H "Authorization: Bearer $AWDPAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "trxReference": "DEP_INV_TEST_1732108900000_E5F6G7H8",
    "otp": "123456"
  }'

Response​

{
  "reference": "DEP_VALID_TEST_1732109000000_I9J0K1L2",
  "status": "completed",
  "fees": 120.0,
  "createdAt": "2025-11-20T15:03:20",
  "message": "Dépôt validé en sandbox"
}

Fees Structure​

  • Fees are automatically calculated and included in the response
  • Final amount debited from customer = amount + fees

Next Steps​