Skip to content

Create Payment

POST /api/payments/create

Create a balance-recharge payment for your account. You receive a hosted payment URL — send your payer there, and after payment the payer is redirected to your custom success page.

Requirements:

  • The hostname of your success_url (and cancel_url, if used) must be registered on our side before use (contact support to allowlist your domain, e.g. shop.example.com). Requests with unregistered hosts are rejected with 422.
  • Your account needs a valid Bangladeshi mobile number (01XXXXXXXXX) in its profile; the payment gateway requires one for every payment. Without it the request is rejected with 422.

Payers can pay with bKash, Nagad, Rocket, Upay and other mobile wallets, cards (Visa, Mastercard, American Express) and internet banking.

Parameter Type Required Description
amount number Yes Amount in BDT. Minimum 20.
success_url string Yes HTTPS URL on an allowlisted host. Payer is sent here after payment.
cancel_url string No HTTPS URL on an allowlisted host. Payer is sent here if they cancel or the payment fails.
Terminal window
curl -X POST https://api.awajdigital.com/api/payments/create \
-H "Authorization: Bearer your_api_token_here" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"amount": 500,
"success_url": "https://shop.example.com/payment/success",
"cancel_url": "https://shop.example.com/payment/cancel"
}'
{
"success": true,
"payment_url": "https://pay.example.com/checkout/23e02880-...",
"invoice_id": "17941438309537516"
}

Redirect your payer to payment_url. After payment, the flow is:

  1. The payment gateway returns the payer to our server first. The payer sees a short “confirming your payment” page while we confirm the payment with the gateway server-to-server and credit your balance — usually a few seconds, at most about 2 minutes.

  2. We then redirect the payer to your success_url with two query parameters appended:

    • invoice_id — the payment reference
    • status — completed (paid and credited) or pending (not confirmed yet)

    A cancelled or failed payment goes to your cancel_url instead (or to success_url if you sent no cancel_url), with status set to cancelled or failed.

A payment that is still pending is credited by itself as soon as the gateway confirms it: the gateway notifies us directly, and we keep re-checking pending payments for 24 hours. A payment is never credited twice, however many of these confirm it.

Status Description
401 Missing or invalid access token
422 Validation failed (amount < 20, non-https URL, non-allowlisted host, no valid mobile number on your account)
502 Gateway error — payment could not be created (safe to try again)