Payments API

Base URL: https://fastaar.com/api/v1. Authenticate every request with your API key as a bearer token: Authorization: Bearer fk_live_.... All amounts are in BDT. An active subscription is required.

Create a payment

POST /api/v1/payments

{
  "amount": 500,
  "invoice_id": "ORDER-42",                          // optional — your order reference (also an idempotency key)
  "success_url": "https://shop.example.com/thanks",  // optional — customer returns here after paying
  "cancel_url": "https://shop.example.com/cart",     // optional — customer returns here if they cancel
  "metadata": {"channel": "web"}                     // optional, up to 20 string values
}

Response 201:

{
  "data": {
    "id": "01jxyz...",                    // payment reference
    "object": "payment",
    "amount": "500.00",
    "currency": "BDT",
    "livemode": true,
    "status": "pending",
    "invoice_id": "ORDER-42",
    "metadata": {"channel": "web"},
    "success_url": "https://shop.example.com/thanks",
    "cancel_url": "https://shop.example.com/cart",
    "checkout_url": "https://fastaar.com/pay/01jxyz...",
    "expires_at": "2026-06-12T15:00:00+06:00",
    "created_at": "2026-06-12T14:30:00+06:00"
  }
}

Redirect your customer to checkout_url. Payments expire after 30 minutes if the customer does not submit a transaction ID. When success_url/cancel_url are set, the customer is returned there once checkout resolves, with payment_id (and invoice_id, if set) appended to the URL.

Idempotency

Send an invoice_id to make creates idempotent: retrying with the same invoice_id returns the existing payment with HTTP 200 instead of creating a duplicate, so a dropped connection never double-charges. A new payment is only created if the previous one for that invoice failed or expired.

Payment lifecycle

pending → customer submits TrxID → awaiting_verification → SMS matched → completed. Terminal failure states are failed (e.g. duplicate_trx_id, rejected_by_admin) and expired.

Retrieve a payment

GET /api/v1/payments/{id}

List payments

GET /api/v1/payments?status=completed&per_page=25
GET /api/v1/payments?invoice_id=ORDER-42      // look up by your own reference

Returns a paginated list, newest first. status, invoice_id, and per_page (max 100) are optional.

Polling vs webhooks

You can poll GET /api/v1/payments/{id} until the status is terminal, but we recommend webhooks for instant notification.