AWDPay Gateway API V3

1. Overview

AWDPay Gateway API V3 allows merchants to create payment requests directly from their own backend, redirect customers to the AWDPay payment page, and receive payment status updates through secure server-to-server callbacks.

2. Base URL

https://gateway.awdpay.com

3. Authentication

Generate an access token using your merchant API key.

Request body

{
  "apiKey": "YOUR_MERCHANT_API_KEY"
}

Selected payment method example

curl -X POST https://gateway.awdpay.com/v3/payment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -d '{
    "amount": 300,
    "currency": "XOF",
    "country": "CI",
    "paymentMethod": "wave",
    "customerName": "First Last",
    "customerEmail": "test@example.com",
    "customerAddress": "Abidjan",
    "successUrl": "https://merchant.com/payment/success",
    "cancelUrl": "https://merchant.com/payment/cancel",
    "callbackUrl": "https://merchant.com/api/awdpay/callback"
  }'

cURL example

curl -X POST https://gateway.awdpay.com/v3/token \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "YOUR_MERCHANT_API_KEY"
  }'

Success response

{
  "success": true,
  "token": "ACCESS_TOKEN",
  "expiredIn": 3600
}

Use the token on protected routes:

Authorization: Bearer ACCESS_TOKEN

4. Get Available Payment Methods

cURL example

curl -X GET https://gateway.awdpay.com/v3/gateways

Response example

[
  {
    "value": "mtn",
    "name": "MTN Money",
    "supportedCurrencies": ["XOF", "XAF", "GNF"],
    "supportedCountries": ["BJ", "CI", "GN", "CM"]
  },
  {
    "value": "wave",
    "name": "Wave",
    "supportedCurrencies": ["XOF", "XAF"],
    "supportedCountries": ["SN", "CI"]
  }
]

5. Create a Payment

Headers

Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN

Request fields

cURL example

curl -X POST https://gateway.awdpay.com/v3/payment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -d '{
    "amount": 1000,
    "currency": "XOF",
    "country": "CI",
    "allowedMethods": ["wave", "mtn", "orange", "moov"],
    "successUrl": "https://merchant.com/payment/success",
    "cancelUrl": "https://merchant.com/payment/cancel",
    "callbackUrl": "https://merchant.com/api/awdpay/callback",
    "sandbox": false,
    "custom": {
      "orderId": "CMD-2026-0001",
      "customerId": "CLIENT-1001"
    },
    "feeByCustomer": false,
    "customerName": "John Doe",
    "customerEmail": "john@example.com",
    "customerAddress": "Abidjan"
  }'

Success response

{
  "success": true,
  "message": "Payment created successfully",
  "trxId": "M8VQA190J71Y",
  "redirectUrl": "https://gateway.awdpay.com/payment/M8VQA190J71Y"
}

6. Check Payment Status

Protected status check

curl -X GET https://gateway.awdpay.com/v3/payment/check/M8VQA190J71Y \
  -H "Authorization: Bearer ACCESS_TOKEN"

Response example

{
  "success": true,
  "data": {
    "trxId": "M8VQA190J71Y",
    "status": "success",
    "sandbox": false,
    "amount": 1000,
    "fee": 0,
    "currency": "XOF",
    "country": "CI",
    "custom": {
      "orderId": "CMD-2026-0001"
    },
    "paidWith": "mtn",
    "customer": {
      "name": "John Doe",
      "email": "john@example.com",
      "address": "Abidjan"
    }
  }
}

Public status check

curl -X GET https://gateway.awdpay.com/status-check/M8VQA190J71Y

{
  "success": true,
  "status": "success"
}

7. Payment Statuses

8. Merchant Callback

AWDPay sends an HTTP POST request to the merchant’s callbackUrl when the payment status changes.

Callback payload example

{
  "type": "payment",
  "event": "payment.success",
  "trxId": "M8VQA190J71Y",
  "status": "success",
  "amount": 1000,
  "fee": 0,
  "currency": "XOF",
  "country": "CI",
  "sandbox": false,
  "paidWith": "mtn",
  "custom": {
    "orderId": "CMD-2026-0001",
    "customerId": "CLIENT-1001"
  },
  "customer": {
    "name": "John Doe",
    "email": "john@example.com",
    "address": "Abidjan"
  },
  "transactedAt": "2026-05-09T07:39:33.000+00:00"
}

Callback headers

Content-Type: application/json
X-AWDPAY-Event: payment.success
X-AWDPAY-Signature: sha256=SIGNATURE
X-AWDPAY-Timestamp: TIMESTAMP

9. Verify Callback Signature

Use the raw request body and your webhook secret to verify X-AWDPAY-Signature.

Node.js example

import crypto from "crypto";

function verifyAwdpaySignature(rawBody, signatureHeader, webhookSecret) {
  const expectedSignature =
    "sha256=" +
    crypto
      .createHmac("sha256", webhookSecret)
      .update(rawBody)
      .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature),
    Buffer.from(signatureHeader)
  );
}

Express callback example

import express from "express";
import crypto from "crypto";

const app = express();

app.post(
  "/api/awdpay/callback",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const signature = req.headers["x-awdpay-signature"];
    const rawBody = req.body;
    const webhookSecret = process.env.AWDPAY_WEBHOOK_SECRET;

    const expectedSignature =
      "sha256=" +
      crypto
        .createHmac("sha256", webhookSecret)
        .update(rawBody)
        .digest("hex");

    if (signature !== expectedSignature) {
      return res.status(401).json({
        success: false,
        message: "Invalid signature"
      });
    }

    const payload = JSON.parse(rawBody.toString("utf8"));

    if (payload.status === "success") {
      // Mark your order as paid using payload.custom.orderId
    }

    return res.status(200).json({
      success: true,
      message: "Callback received"
    });
  }
);

app.listen(3000);

10. Sandbox Mode

Use "sandbox": true in the payment creation request to create a test transaction.

{
  "amount": 100,
  "currency": "XOF",
  "country": "CI",
  "sandbox": true,
  "callbackUrl": "https://merchant.com/api/awdpay/callback"
}

11. Observed Payment Method IDs

12. Withdraw / Payout Methods

Use this endpoint to retrieve the list of available withdraw/payout methods. The response includes method ID, country, currency, minimum amount, maximum amount, API availability, and fees.

Headers

Authorization: Bearer ACCESS_TOKEN

cURL example

curl -X GET https://gateway.awdpay.com/v3/methods \
  -H "Authorization: Bearer ACCESS_TOKEN"

Response example

{
  "data": [
    {
      "id": 8,
      "name": "MTN Money CIV",
      "minAmount": 300,
      "maxAmount": 100000,
      "currency": "XOF",
      "percentageCharge": 2.5,
      "country": "CI",
      "active_api": true,
      "recommanded": true
    },
    {
      "id": 39,
      "name": "WAVE Côte d'ivoire",
      "minAmount": 300,
      "maxAmount": 100000,
      "currency": "XOF",
      "percentageCharge": 3,
      "country": "CI",
      "active_api": true,
      "recommanded": false
    }
  ],
  "count": 21
}

13. Create Withdraw / Payout

This endpoint creates a withdraw request from the merchant account to a customer wallet. The amount field is always the amount the customer should receive. Gateway V3 calculates the withdraw fee and the merchant debit total automatically. For testing, use "sandbox": true. In sandbox mode, AWDPay creates a local pending withdraw record without triggering a real payout.

Headers

Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN

Request fields

Sandbox cURL example

curl -X POST https://gateway.awdpay.com/v3/withdraw \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -d '{
    "amount": 300,
    "currency": "XOF",
    "country": "CI",
    "paymentMethod": 8,
    "callbackUrl": "https://merchant.com/api/awdpay/withdraw-callback",
    "sandbox": true,
    "custom": {
      "withdrawRef": "WD-SANDBOX-001",
      "source": "manual_test"
    },
    "customerName": "Client Retrait Test",
    "customerEmail": "withdraw.test@example.com",
    "customerAddress": "Abidjan",
    "number": "0101010101"
  }'

Sandbox success response

{
  "success": true,
  "message": "Withdraw sandbox created successfully",
  "data": {
    "trxId": "CPJ8P3GQA4OE",
    "status": "pending",
    "amount": 300,
    "fee": 0,
    "total": 300,
    "withdrawId": null,
    "sandbox": true
  }
}

14. Withdraw Fees & Merchant Debit

For API V3 withdrawals, the customer receives the requested amount. The merchant is debited the requested amount plus the Gateway V3 withdraw fee.

Calculation rule

fee = amount × percentageCharge / 100
total = amount + fee

Example

Response example

{
  "success": true,
  "message": "Withdraw is pending",
  "data": {
    "trxId": "SG8MN2U9YJHP",
    "status": "pending",
    "amount": 500,
    "fee": 12.5,
    "total": 512.5,
    "currency": "XOF",
    "country": "CI",
    "paymentMethod": 8,
    "withdrawId": 51056,
    "sandbox": false
  }
}

15. Check Withdraw Status

Use this endpoint to verify the status of a withdraw request using its trxId.

Headers

Authorization: Bearer ACCESS_TOKEN

cURL example

curl -X GET https://gateway.awdpay.com/v3/withdraw/CPJ8P3GQA4OE \
  -H "Authorization: Bearer ACCESS_TOKEN"

Response example

{
  "success": true,
  "data": {
    "trxId": "CPJ8P3GQA4OE",
    "status": "pending",
    "amount": 300,
    "fee": 0,
    "total": 300,
    "withdrawId": null,
    "sandbox": true
  }
}

16. Integration Best Practices

1. Never expose your merchant API key in frontend code.
2. Generate the AWDPay token from your backend only.
3. Create payments from your backend only.
4. Redirect the customer to redirectUrl.
5. Store trxId with your internal order.
6. Do not mark an order as paid only because the customer returns to successUrl.
7. Always verify payment status using callback or /v3/payment/check/{trxId}.
8. Always verify X-AWDPAY-Signature before confirming an order.
9. For withdrawals, the customer receives amount; the merchant is debited amount + fee.
10. Always use GET /v3/methods before creating a withdrawal to get current Gateway V3 limits and fees.
11. Use "sandbox": true for withdrawal testing to avoid triggering a real payout.
12. Respond with HTTP 200 OK after receiving a valid callback.
13. Only success should be treated as final payment confirmation.

17. Support Information

When contacting AWDPay support, please provide:

• trxId
• Transaction date
• Amount and currency
• Country
• Payment method used
• API response received
• Callback URL concerned