Payments Orders API

This API creates payment-intent orders in Linkit, routes execution to the provider integration app, and tracks lifecycle transitions.

The request payload now uses providers (formerly requested_platforms) to specify which payment providers to use.

Supported providers are the same IDs returned by GET /api/v1/providers (see also Payment gateway providers).

BNPL (type: bnpl)

• tabby — Buy Now, Pay Later with QR code checkout (tabby-pos-paylinks)
• tamara — Buy Now, Pay Later with SMS-based checkout (tamara-pos-paylinks)
• mispay — Split in 4 BNPL with QR code checkout (mispay-pos-paylinks)

Gateway sync (type: gateway_sync) — reconciliation apps; not paylink providers

• stripe → stripe-payments
• moyasar → moyasar-payments
• tap → tap-payments
• dinero → dinero-payments
• paypal → paypal-commerce
• hyperpay → hyperpay-checkout

Unsupported provider strings in providers are silently ignored (the first supported entry wins as active_gateway).

Migration Note: The requested_platforms field has been renamed to providers. Update your API consumers accordingly.

Create Payment Order

POST /api/v1/payments/orders

Creates a pending payment order for the organization, resolves provider routing from the integration catalog, then runs the mapped provider integration for that order.

Request

{
  "providers": ["tabby", "tamara", "mispay"],
  "order": {
    "total_amount": 149.5,
    "currency": "SAR",
    "line_items": [
      { "sku": "SKU-001", "name": "Item A", "qty": 1, "price": 99.5 },
      { "sku": "SKU-002", "name": "Item B", "qty": 1, "price": 50.0 }
    ]
  }
}

Response (201)

{
  "success": true,
  "message": "payment order created and pending gateway execution",
  "data": {
    "order_id": "r1234567890abcdef",
    "accepted_gateways": ["tabby", "tamara"],
    "active_gateway": "tabby",
    "app_slug": "tabby-pos-paylinks",
    "execute_endpoint": "/api/v2/checkout",
    "execute_method": "POST",
    "next_action": "execute_or_send_payment_link"
  }
}

Get Payment Order

GET /api/v1/payments/orders/{id}

Returns the linked order as the same order.snapshot envelope used elsewhere: spec_version, event metadata, and a normalized order object (UnifiedOrderPayload — line items, totals, status, optional dispatch/shipping shapes). Vendor-native payloads are not included in the JSON.

Confirm Payment Order

POST /api/v1/payments/orders/{id}/confirm

Marks the order as confirmed/completed, resolves the provider route from the integration catalog, and runs the provider integration.

Request

{
  "provider": "tabby"
}

Response (200)

{
  "success": true,
  "message": "payment confirmed and captured",
  "data": {
    "order_id": "r1234567890abcdef",
    "provider": "tabby",
    "status": "completed",
    "confirmed_app": "tabby-pos-paylinks",
    "confirm_endpoint": "/api/v1/payments/{payment_id}/captures",
    "confirm_method": "POST",
    "requires_qr_sms": true
  }
}

Related

• Unified Providers Paylinks API — BNPL paylink create, capture, cancel, list.
• Payment gateway providers — Stripe, Moyasar, Tap, Dinero credentials and synced provider data.