Statuses and Errors

Overview

Statuses tell you where a payment, SMS event, or webhook delivery is in the lifecycle. Your integration should use these values exactly and treat unknown future values conservatively.

Step-by-step guide

1. Store the payment intent ID with your order.
2. Wait for payment.paid webhook or retrieve the intent from your backend.
3. Fulfill only when payment intent status is PAID.
4. Investigate REVIEW_REQUIRED, FAILED, and EXPIRED.
5. Build idempotent handlers for repeated webhook deliveries.

Payment Intent statuses

SMS Event statuses

SMS Match statuses

Webhook Delivery statuses

Code example

function canFulfill(status: string) {
  return status === "PAID";
}

function needsOperator(status: string) {
  return (
    status === "REVIEW_REQUIRED" || status === "FAILED" || status === "EXPIRED"
  );
}

Request and response samples

Expired payment response:

{
  "id": "b5012f33-207e-4999-bf8d-5a1ebb10988e",
  "status": "EXPIRED",
  "amount": "500",
  "currency": "BDT",
  "customerReference": "ORDER-10045",
  "receiverMsisdn": "01700000001"
}

Validation error example:

{
  "statusCode": 400,
  "message": ["receiverMsisdn must be a valid Bangladeshi mobile number"],
  "error": "Bad Request"
}

Business error example:

{
  "code": "INTENT_EXPIRED",
  "message": "Payment intent has expired"
}

Common error cases

Hosted checkout redirect lifecycle

When redirect URLs are provided on a payment intent, the hosted checkout page automatically redirects the customer after resolution:

The redirect includes a 3-second delay with a visible countdown message. These query parameters are appended:

Warning: Do not fulfill orders solely based on browser redirects. Always verify status server-side using webhooks or GET /v1/payments/intents/:id.

Edge cases and constraints

• Unknown statuses should not trigger fulfillment.
• REVIEW_REQUIRED is not paid.
• EXPIRED can happen when checkout is loaded after expiry or by expiry worker.
• Webhooks may arrive more than once.
• Environment mismatches can look like missing records.