Implement redirect checkout

Create a redirect deposit, send the payer to hosted checkout, and read its status.

Before you start

You need:

an OmniPay organization with deposits enabled;
an API key stored in a server-side secret manager;
an HTTPS return page for the payer;
a unique business identifier for each order.

All examples use https://omnipay.page/api/v1.

1. Create an API key

Open Dashboard → Developers, create an API key, and expose it only to your backend:

export OMNIPAY_API_KEY="your-api-key"

Never place the key in browser JavaScript, mobile application code, URLs, or analytics events.

2. Create a deposit

curl --fail-with-body --request POST \
  --url https://omnipay.page/api/v1/deposits \
  --header "Authorization: Bearer $OMNIPAY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": "1000",
    "payment_method": "bkash",
    "merchant_id": "order-1001",
    "redirect_url": "https://merchant.example/payments/return",
    "metadata": {
      "invoice_id": "INV-1001"
    }
  }'

checkout_mode is optional and defaults to redirect. A successful create returns HTTP 200:

{
  "id": "cm7deposit01",
  "amount": "1000",
  "payment_method": "bkash",
  "status": "pending",
  "metadata": {
    "invoice_id": "INV-1001"
  },
  "merchant_id": "order-1001",
  "redirect_url": "https://omnipay.page/api/v1/payments/cm7deposit01"
}

Persist both identifiers before redirecting the payer:

merchant_id is your order identifier and protects against accidental duplicate creation;
id is the OmniPay deposit identifier used for status requests and support.

3. Redirect the payer

The request and response both contain a field named redirect_url, but they serve different purposes:

Location	Meaning
Request `redirect_url`	Your page that receives the payer after checkout
Response `redirect_url`	Hosted checkout URL that the payer should open now

Send the payer only to the URL returned in the response:

window.location.assign(deposit.redirect_url);

Do not interpret the payer arriving at your return page as payment proof.

4. Read the deposit

curl --fail-with-body \
  --url https://omnipay.page/api/v1/deposits/cm7deposit01 \
  --header "Authorization: Bearer $OMNIPAY_API_KEY"

Example successful result:

{
  "id": "cm7deposit01",
  "amount": "1000",
  "payment_method": "bkash",
  "status": "succeeded",
  "metadata": {
    "invoice_id": "INV-1001"
  },
  "merchant_id": "order-1001",
  "bank_transaction_id": "B8F2L9X3"
}

Treat pending and processing as nonterminal. Stop polling on succeeded, failed, expired, cancelled, rejected, or refunded.

Handle redirect completion safely →