API reference

Payments

Create, read and re-check a payment directly.

Create a payment

POST /v1/payments

curl https://api.brightsecuretech.com/v1/payments \
  -H "Authorization: Bearer $BST_SECRET_KEY" \
  -H "Idempotency-Key: order-10482-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_minor": 12000,
    "currency": "GHS",
    "method": "mtn_momo",
    "customer_phone": "0244123456",
    "customer_email": "ama@example.com",
    "description": "Jollof and chicken x2",
    "merchant_reference": "ORDER-10482"
  }'

Response · 201

{
  "reference": "BST-4F9A21C0D7E3",
  "status": "processing",
  "amount_minor": 12000,
  "currency": "GHS",
  "method": "mtn_momo",
  "description": "Jollof and chicken x2",
  "merchant_reference": "ORDER-10482",
  "customer_phone": "024•••4567",
  "redirect_url": null,
  "failure_reason": null,
  "needs_review": false,
  "created_at": "2026-11-12T14:30:02.511Z",
  "updated_at": "2026-11-12T14:30:03.004Z"
}

Mobile money (mtn_momo, telecel_cash, at_money): customer_phone is required. The customer gets a prompt on their phone to approve.
Cards (visa, mastercard): the response has a redirect_url. Send the customer there to enter their card on the bank’s secure 3-D Secure page.

Who pays the fee

By default the business pays the fee: it is taken from the payout. A business can pass the fee to its customers in Settings → Payouts → Transaction fees. Then the fee is added on top of amount_minor at checkout, and the business receives its full price.

Field	Meaning
fee_bearer	Optional on POST /v1/payments: merchant or customer. Overrides the business setting for this one payment.
amount_minor	In responses and webhooks: what the customer was charged (price + fee when the customer pays it).
requested_amount_minor	Your price, exactly as you sent it. Match this against your order.
fee_minor	Our fee on this payment, fixed when the payment was created.

Checking the amount

When you confirm a payment, compare requested_amount_minor with your order total. amount_minor is higher when the customer pays the fee.

Get a payment

GET /v1/payments/{reference}

curl https://api.brightsecuretech.com/v1/payments/BST-4F9A21C0D7E3 \
  -H "Authorization: Bearer $BST_SECRET_KEY"

Re-check with the bank

Asks the bank for the latest status and returns the updated payment. Safe to call as often as you like; a payment is only ever recorded once.

POST /v1/payments/{reference}/verify

curl -X POST https://api.brightsecuretech.com/v1/payments/BST-4F9A21C0D7E3/verify \
  -H "Authorization: Bearer $BST_SECRET_KEY"

Never trust the browser

A customer landing on your success page proves nothing. Deliver only after a signed payment.success webhook or a server-side GET/verify that returns status successful with the amount and merchant_reference you expect.