Introduction

This documentation has been written for merchant that has already an account validated by Awdpay.

You can access and check your Awdpay account here

You need to use an API Key (Token) and API Secret from your account under the "Merchants > API Payment" menu. to generate those informations just click the "generate" button.

Swagger UI Link: Swagger API V3

Generate Token

This operation is used to create an access token which can then be used to authorize and authenticate towards the other end-points of the API.

Request

Request URL: https://gateway.awdpay.com/v3/token
Method: POST

Body Parameters

NAME	TYPE	MANDATORY	DESCRIPTION
apiKey	string	Yes	API Key (Token) from your "Merchant > API Payment" menu

Example (curl)

curl --request POST \
  --url https://gateway.awdpay.com/v3/token \
  --data apiKey=YOUR_API_KEY

YOUR_API_KEY generate from your Merchant area on awdpay.com

Responses

200 OK

{
  "success": "boolean",
  "token": "string",
  "expires_in": 0
}

400 Unauthorized

{
  "success": "boolean",
  "message": "string"
}

500 Internal Server Error

Gateway List

This operation is used to get the list of gateways for payment.

Request

Request URL: https://gateway.awdpay.com/v3/gateways
Method: GET

Headers

NAME	DESCRIPTION
Authorization	Authorization header used for oauth. Format of the header parameter follows the standard for Bearer. Oauth uses Bearer authentication type where the credential is the received access token.

Responses

200 OK

[
  {
    "value": string,
    "name": string,
    "supportedCurrencies": string[]
    "supportedCountries": string[]
  }
]

401 Unauthorized

{
  "message": "string"
}

500 Internal Server Error

Create Payment

This operation is used to take payments directly from your customers in your awdpay account.

Request

Request URL: https://gateway.awdpay.com/v3/payment
Method: POST

Headers

NAME	DESCRIPTION
Authorization	Authorization header used for oauth. Format of the header parameter follows the standard for Bearer. Oauth uses Bearer authentication type where the credential is the received access token.

Body Parameters

NAME	TYPE	MANDATORY	DESCRIPTION
currency	string	Yes	a value compatible with AWDPay supported currencies
country	string	Yes	ISO3166-1-Alpha-2, a value compatible with the payment method choosen. This parameter is mandatory. Ref: https://github.com/datasets/country-codes/blob/master/data/country-codes.csv ("ISO3166-1-Alpha-2" column)
amount	number	Yes	amount to be received
logo	string (URL)	Yes	An URL to your logo. It'll be shown on the payment page.
callbackUrl	string (URL)	Yes	An URL to receive webhook callback about payment status.
successUrl	string (URL)	Yes	An URL to redirect the customer after payment is completed.
cancelUrl	string (URL)	Yes	An URL to redirect the customer after payment is cancelled/failed.
sandbox	boolean	Yes	Set it to "true" to test payment integration during development phase. Otherwise keep it "false" to take real payments.
custom	object	No	A custom object where you can add your custom data like customer email or transaction ID to verify the payment from your side. This field will be sent during webhook callbacks.
customerName	string	Yes	Customer name for identification purpose.
customerEmail	string	Yes	Customer email for identification purpose.
customerAddress	string	Yes	Customer address for identification purpose.
feeByCustomer	boolean	Yes	If set to "true" the payment will take the fee from the customer directly.

Example (curl)

curl -XPOST -H 'Authorization: Bearer [token_access]' -H "Content-type: application/json" -d '{
  "amount": 200,
  "currency": "XOF",
  "country": "CI",
  "logo": "https://test.com/logo.png",
  "callbackUrl": "https://webhook.site/d83fd3c6-6b36-4a70-8de8-37b9c3c2b27e",
  "successUrl": "https://test.com/success",
  "cancelUrl": "https://test.com/failed",
  "sandbox": false,
  "custom": {
      "email": "test@test.com"
  },
  "customerName": "John Doe",
  "customerEmail": "john.doe@gmail.com",
  "customerAddress": "House #34, Long Drive Rd, US",
  "feeByCustomer": false
}' 'https://gateway.awdpay.com/v3/payment'

[token_access] from generate token api

Responses

200 OK

{
  "success": boolean,
  "message": string,
  "trxId": string,
  "redirectUrl": string,
}

Redirect your customer to [redirectUrl]

400 Bad Request

{
  "success": boolean,
  "error": object/string
}

401 Unauthorized

{
  "message": "string"
}

500 Internal Server Error

Webhook (POST)

{
  "trxId": string,
  "type": "payment",
  "status": "success" | "pending" | "failed",
  "sandbox": boolean,
  "amount": number,
  "fee": number,
  "currency": string,
  "country": string,
  "custom": object,
  "transactedAt": DateTime,
  "paidWith": string | null,
  "customer": {
    "name": string,
    "email": string,
    "address": string,
    "phone": string
  }
}

Check Payment Status

This operation is used to get the status of a payment request. TrxId is the id received after request to payment has been successful.

Request

Request URL: https://gateway.awdpay.com/v3/payment/check/{TrxId}
Method: GET

Headers

NAME	DESCRIPTION
Authorization	Authorization header used for oauth. Format of the header parameter follows the standard for Bearer. Oauth uses Bearer authentication type where the credential is the received access token.

Responses

200 OK

{
  "success": boolean,
  "data": {
    "trxId": string,
    "status": "success" | "pending" | "failed",
    "sandbox": boolean,
    "amount": number,
    "fee": number,
    "currency": string,
    "country": string,
    "custom": object,
    "transactedAt": string,
    "paidWith": string | null,
    "customer": {
      "name": string,
      "email": string,
      "address": string,
      "phone": string
    }
  }
}

401 Unauthorized

{
  "success": boolean,
  "message": string
}

500 Internal Server Error

Method List

This operation is used to get the list of method with their corresponding value. Value to be used for request a withdraw.

Request

Request URL: https://gateway.awdpay.com/v3/methods
Method: GET

Headers

NAME	DESCRIPTION
Authorization	Authorization header used for oauth. Format of the header parameter follows the standard for Bearer. Oauth uses Bearer authentication type where the credential is the received access token.

Responses

200 OK

{
  "data": [
    {
      "id": integer,
      "name": string,
      "minAmount": number,
      "maxAmount": number,
      "currency": string,
      "fixedCharge": number,
      "percentageCharge": number,
      "active": bool,
      "country": string
    }
  ],
  "count": integer
}

401 Unauthorized

{
  "message": "string"
}

500 Internal Server Error

Withdraw

This operation is used to Withdraw money to your customer from your awdpay account.

Request

Request URL: https://gateway.awdpay.com/v3/withdraw
Method: POST

Headers

NAME	DESCRIPTION
Authorization	Authorization header used for oauth. Format of the header parameter follows the standard for Bearer. Oauth uses Bearer authentication type where the credential is the received access token.

Body Parameters

NAME	TYPE	MANDATORY	DESCRIPTION
paymentMethod	number	Yes	a value from method api
amount	number	Yes	amount to be send
currency	string	Yes	a value compatible with AWDPay supported currencies
country	string	Yes	ISO3166-1-Alpha-2, a value compatible with the payment method choosen. This parameter is mandatory. Ref: https://github.com/datasets/country-codes/blob/master/data/country-codes.csv ("ISO3166-1-Alpha-2" column)
callbackUrl	string (URL)	Yes	An URL to receive webhook callback about payment status.
customerName	string	Yes	Customer name for identification purpose.
customerEmail	string	Yes	Customer email for identification purpose.
customerAddress	string	Yes	Customer address for identification purpose.
number	string	No, under condition	phone number without country code and +. For ref: https://github.com/datasets/country-codes/blob/master/data/country-codes.csv (get country code on "Dial" column)
extWallet	string	No, under condition	Wallet number from selected method. This parameter is mandatory for perfectmoney method.

Responses

200 OK

{
  "success": boolean,
  "message": string,
  "data": {
    "trxId": string,
    "status": "success" | "pending" | "failed",
    "amount": number,
    "fee": number,
    "total": number,
    "withdrawId": number
  },
}

400 Bad Request

{
  "success": boolean,
  "message": string,
  "data": {
    "trxId": string,
    "status": "success" | "pending" | "failed",
    "amount": number,
    "fee": number,
    "total": number,
    "withdrawId": number
  },
}

401 Unauthorized

{
  "message": "string"
}

500 Internal Server Error

Webhook (POST)

{
  "trxId": string,
  "type": "withdraw",
  "status": "success" | "pending" | "failed",
  "sandbox": boolean,
  "amount": number,
  "fee": number,
  "total": number,
  "currency": string,
  "country": string,
  "custom": object,
  "transactedAt": DateTime,
  "customer": {
    "name": string,
    "email": string,
    "address": string,
    "phone": string
  }
}

Withdraw Status

This operation is used to get the status of a request to withdraw. TrxId is the id received after request to withdraw has been sucessfull.

Request

Request URL: https://gateway.awdpay.com/v3/withdraw/{TrxId}
Method: GET

Headers

NAME	DESCRIPTION
Authorization	Authorization header used for oauth. Format of the header parameter follows the standard for Bearer. Oauth uses Bearer authentication type where the credential is the received access token.

Responses

200 OK

{
  "success": boolean,
  "data": {
    "trxId": string,
    "status": "success" | "pending" | "failed",
    "sandbox": boolean,
    "amount": number,
    "fee": number,
    "total": number,
    "withdrawId": number
  }
}

401 Unauthorized

{
  "message": "string"
}

500 Internal Server Error

Withdraw List

This operation is used to get the list of requests to withdraw.

Request

Request URL: https://www.awdpay.com/api/v1/withdraws
Method: GET

Headers

NAME	DESCRIPTION
Authorization	Authorization header used for oauth. Format of the header parameter follows the standard for Bearer. Oauth uses Bearer authentication type where the credential is the received access token.

Responses

200 OK

{
  "count": integer,
  "data": [
    {
      "id": integer,
      "status": string,
      "method": string,
      "amount": number,
      "fee": number,
      "currency": string,
      "createdAt": date
    }
  ]
}

401 Unauthorized

{
  "message": "string"
}

500 Internal Server Error

Transfer Money

This operation is used to send money to an awdpay wallet.

Request

Request URL: https://gateway.awdpay.com/v3/transfer
Method: POST

Headers

NAME	DESCRIPTION
Authorization	Authorization header used for oauth. Format of the header parameter follows the standard for Bearer. Oauth uses Bearer authentication type where the credential is the received access token.

Body Parameters

NAME	TYPE	MANDATORY	DESCRIPTION
customerEmail	string	Yes	a know email from awdpay
amount	number	yes	amount of the transaction
currency	string	yes	a value available from currency api

Responses

200 OK

{
  "success": boolean,
  "status": "success" | "pending" | "failed",
  "message": string,
  "currency": string,
  "trxId": string,
}

401 Unauthorized

{
  "success": boolean,
  "error": "string"
}

500 Internal Server Error