Unified Providers Paylinks APICopy Anchor Link

A single, provider-agnostic API for BNPL payment links (Tabby, Tamara, MisPay). GET /api/v1/providers also lists gateway sync processors (stripe, moyasar, tap, dinero, paypal, hyperpay); those IDs are not valid for paylink create — use Payments Orders instead.

Supported ProvidersCopy Anchor Link

List ProvidersCopy Anchor Link

Returns all registered payment providers and their metadata.

GET /api/v1/providers
Authorization: Bearer <token>

ResponseCopy Anchor Link

Each entry includes id, name, description, type, regions, and when applicable app_slug (integration app used by Payments Orders).

{
  "providers": [
    {
      "id": "dinero",
      "name": "Dinero Pay",
      "description": "Dinero Pay: refresh configured payment_ids…",
      "type": "gateway_sync",
      "regions": "KSA and supported Dinero markets",
      "app_slug": "dinero-payments"
    },
    {
      "id": "mispay",
      "name": "MisPay",
      "description": "Split-in-4 BNPL with QR code checkout for POS",
      "type": "bnpl",
      "regions": "KSA",
      "app_slug": "mispay-pos-paylinks"
    }
  ],
  "total": 9
}

Provider ConfigurationCopy Anchor Link

Returns provider-specific configuration, required fields, and endpoint documentation.

GET /api/v1/providers/config/{provider}
Authorization: Bearer <token>

Create Payment LinkCopy Anchor Link

POST /api/v1/providers/paylinks
Authorization: Bearer <token>
Content-Type: application/json

The field table below is the Go contract (GET /providers/config/{provider} still lists these required_fields).

Common FieldsCopy Anchor Link

Provider-Specific FieldsCopy Anchor Link

TamaraCopy Anchor Link

The React App Store Tabby step lists and cancels existing rows. It does not offer create.

Get Payment Link StatusCopy Anchor Link

GET /api/v1/providers/paylinks/{id}
Authorization: Bearer <token>

Retrieves the stored row after Go's refreshProviderPaylinkStatus poll (Tabby RetrievePayment, Tamara GetOrderDetails, MisPay TrackCheckout). A vendor error is swallowed and the stored row is still 200. A missing or cross-tenant id is 404 Payment link not found. (not an existence oracle). Amount and the other scalar fields are strings. List and get share this shape. List does not refresh.

ResponseCopy Anchor Link

{
  "id": "abc123",
  "provider": "tabby",
  "org_app_id": "...",
  "order_id": "POS-1234",
  "status": "authorized",
  "amount": "150.00",
  "currency": "SAR",
  "checkout_url": "https://checkout.tabby.sa/...",
  "qr_code_url": "https://checkout.tabby.sa/qr/..."
}

List Payment LinksCopy Anchor Link

GET /api/v1/providers/paylinks?provider=tabby&org_app_id=YOUR_ORG_APP_ID
Authorization: Bearer <token>

{"items":[…],"total":n}. Optional query parameters:

• provider — Filter by provider (e.g. tabby, tamara, mispay)
• org_app_id — Filter by organization app

An empty list is also the answer when the org has no installs, the requested org_app_id is not one of them, or the query failed. A client cannot tell those apart.

Capture/Finalize PaymentCopy Anchor Link

POST /api/v1/providers/paylinks/{id}/capture
Authorization: Bearer <token>
Content-Type: application/json

Cancel Payment LinkCopy Anchor Link

Cancels a pending payment link. Served. The local row is set to cancelled whether or not the vendor cancel succeeds (Tabby close / Tamara void+cancel errors are discarded; MisPay has no remote cancel). A missing id is 404 Payment link not found.

POST /api/v1/providers/paylinks/{id}/cancel
Authorization: Bearer <token>

ResponseCopy Anchor Link

{
  "success": true,
  "paylink_id": "abc123",
  "provider": "tabby",
  "status": "cancelled"
}

Provider-specific endpointsCopy Anchor Link

There are none. Every payment link operation goes through the unified /api/v1/providers/paylinks endpoints with "provider" in the body or query, and provider configuration is GET /api/v1/providers/config/{provider}.

POS Integration FlowCopy Anchor Link

POS flow is create → display QR/SMS → wait → webhook → capture, same as Go:

1. Create — POST /api/v1/providers/paylinks (BNPL ids only)
2. List / get — cashier tracks rows; GET {id} may refresh vendor status
3. Cancel — POST …/{id}/cancel marks the local row cancelled
4. Capture — POST …/{id}/capture after the vendor session is payable

RelatedCopy Anchor Link