Integration API base URL

Payment host

Prerequisites (from RsomPay)

End-to-end flow

flowchart TB
  subgraph partner [Partner system]
    ERP[ERP backend]
    WH[Webhook endpoint]
    RET[return_url handler]
  end
  subgraph rsom [RsomPay]
    INT[integration.rsompay.com]
    PAY[payment.rsompay.com]
  end
  ERP -->|POST /invoices| INT
  INT -->|payment_url| ERP
  ERP -->|share link| PAY
  PAY -->|browser redirect first| RET
  RET -->|GET by-reference| INT
  INT -.->|webhook later async| WH

Send the integration token on every request:

Authorization: Bearer YOUR_CLIENT_EXTERNAL_API_TOKEN
Content-Type: application/json
Accept: application/json

Token requirements

• Token name must be client-external-api.
• Other API tokens return HTTP 403.
• Required abilities: client_invoices.create, client_invoices.view. Settlement endpoints additionally require client_settlements.view — already granted by default, no extra setup needed.

Example

curl -X POST "https://integration.rsompay.com/api/external/v1/invoices" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d @invoice.json

Successful responses:

{
  "status": true,
  "message": "Mission completed successfully",
  "data": { }
}

Paginated GET /transactions adds meta: total, per_page, current_page, last_page.

POST /invoices

Request fields

Root body

Customer object (customer)

Items array (items[])

Each array element is one line item. At least one item is required.

Behaviour

• Idempotent: Same external_id → 201, same invoice, no duplicate.
• Initial status: issued.
• Amount: No root amount field — each line requires unit_price. data.amount and data.totals.grand_total are computed from lines (must be > 0).

Totals example

One line: qty 1, unit 100, discount 10, tax 15% → grand_total: 103.5

Sample request

{
  "external_id": "INV-PARTNER-001",
  "notification_url": "https://partner.example.com/webhooks/rsom",
  "return_url": "https://partner.example.com/payment/return",
  "currency_code": "SAR",
  "due_date": "2026-12-31",
  "issued_date": "2026-05-18",
  "payment_method": "credit_card",
  "notes": "Optional invoice note",
  "customer": {
    "id": "CUST-9",
    "fullname": "Ahmed Ali",
    "email": "customer@example.com",
    "phone": "+966501234567"
  },
  "items": [
    {
      "description": "Service fee",
      "item_type": "service",
      "quantity": 1,
      "unit_price": 100,
      "discount_amount": 10,
      "tax_rate": 15,
      "reference_id": "LINE-1"
    }
  ]
}

Sample response (201)

{
  "status": true,
  "message": "Mission completed successfully",
  "data": {
    "external_id": "INV-PARTNER-001",
    "reference_number": "INV-42-001",
    "status": "issued",
    "amount": 103.5,
    "payment_url": "https://payment.rsompay.com/pay/invoice/...",
    "customer": {
      "id": "CUST-9",
      "fullname": "Ahmed Ali",
      "email": "customer@example.com",
      "phone": "+966501234567"
    },
    "totals": {
      "subtotal": 100,
      "discount_total": 10,
      "tax_total": 13.5,
      "grand_total": 103.5
    },
    "items": [
      {
        "description": "Service fee",
        "item_type": "service",
        "quantity": 1,
        "unit_price": 100,
        "discount_amount": 10,
        "tax_rate": 15,
        "tax_amount": 13.5,
        "total_amount": 103.5,
        "reference_id": "LINE-1"
      }
    ]
  }
}

GET /invoices/by-reference?{parameter}={value}

Look up an invoice by your reference. Use this after webhooks or before fulfilling an order.

Provide exactly one query parameter:

Examples

GET /invoices/by-reference?external_id=INV-PARTNER-001
GET /invoices/by-reference?reference_number=INV-42-001

Sample response (200)

{
  "status": true,
  "message": "Mission completed successfully",
  "data": {
    "external_id": "INV-PARTNER-001",
    "reference_number": "INV-42-001",
    "status": "paid",
    "amount": 103.5,
    "payment_url": "https://payment.rsompay.com/pay/invoice/...",
    "customer": {
      "id": "CUST-9",
      "fullname": "Ahmed Ali",
      "email": "customer@example.com",
      "phone": "+966501234567"
    },
    "totals": {
      "subtotal": 100,
      "discount_total": 10,
      "tax_total": 13.5,
      "grand_total": 103.5
    },
    "items": [
      {
        "description": "Service fee",
        "item_type": "service",
        "quantity": 1,
        "unit_price": 100,
        "discount_amount": 10,
        "tax_rate": 15,
        "tax_amount": 13.5,
        "total_amount": 103.5,
        "reference_id": "LINE-1"
      }
    ]
  }
}

Errors

List customer payments across your invoices.

GET /transactions?customer_id={id}&page=1&per_page=20

Sample response (200)

Same envelope as other endpoints (status, message, data). data is an array of payment records; paginated responses include meta. payment_method reflects how the customer paid — e.g. card or tamara. refund_status is only present once a refund has been requested on that transaction — poll it to track asynchronous refund confirmation.

{
  "status": true,
  "message": "Mission completed successfully",
  "data": [
    {
      "reference": "TX-REF-1",
      "status": "completed",
      "refund_status": null,
      "amount": 103.5,
      "currency_code": "SAR",
      "payment_method": "card",
      "invoice_external_id": "INV-PARTNER-001",
      "captured_at": "2026-05-18 12:00:00",
      "created_at": "2026-05-18 11:55:00"
    },
    {
      "reference": "TX-REF-2",
      "status": "completed",
      "refund_status": "confirmed",
      "amount": 250,
      "currency_code": "SAR",
      "payment_method": "tamara",
      "invoice_external_id": "INV-PARTNER-002",
      "captured_at": "2026-05-17 15:30:00",
      "created_at": "2026-05-17 15:28:00"
    }
  ],
  "meta": {
    "total": 2,
    "per_page": 20,
    "current_page": 1,
    "last_page": 1
  }
}

RsomPay POSTs to your notification_url after payment activity. No webhook is sent when the invoice is created. Delivery is asynchronous — respond with HTTP 2xx quickly.

7.1 Events

settlement.* events are sent to your account-level notification URL (configured once for your integration), not to a per-invoice notification_url — a settlement batch aggregates many transactions, not a single invoice. Ask your integration contact to register this URL.

7.2 HTTP request

POST {notification_url}
Content-Type: application/json
X-Rsom-Signature: a1b2c3d4e5f6...

Event details are in the JSON body. For authenticity, read header X-Rsom-Signature (see §7.5).

7.3 Payload

{
  "event": "payment.completed",
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "occurred_at": "2026-05-18T12:00:00+00:00",
  "customer": { "id": "CUST-9", "fullname": "Ahmed Ali", ... },
  "totals": { "subtotal": 100, "discount_total": 10, "tax_total": 13.5, "grand_total": 103.5 },
  "invoice": {
    "external_id": "INV-PARTNER-001",
    "reference_number": "INV-42-001",
    "status": "paid",
    "amount": 103.5,
    "payment_url": "https://payment.rsompay.com/pay/invoice/..."
  },
  "payment": {
    "uuid": "660e8400-e29b-41d4-a716-446655440001",
    "payment_method": "card",
    "status": "completed",
    "amount": 103.5,
    "paid_at": "2026-05-18 12:00:00"
  }
}

payment_method reflects how the customer paid — e.g. card (Mada/Visa/Mastercard), tamara (Tamara BNPL). Card payments may also return a specific brand when available (e.g. mada, visa).

payment.failed and payment.expired both carry an additional payment.reason field so you can distinguish a gateway decline from a checkout-session expiry from a customer cancellation:

{
  "event": "payment.expired",
  "event_id": "770e8400-e29b-41d4-a716-446655440002",
  "occurred_at": "2026-08-03T12:00:00+00:00",
  "invoice": { "external_id": "INV-PARTNER-001", "reference_number": "INV-42-001", "status": "failed", ... },
  "payment": {
    "uuid": "660e8400-e29b-41d4-a716-446655440001",
    "payment_method": "card",
    "status": "failed",
    "amount": 103.5,
    "paid_at": "2026-08-03 12:00:00",
    "reason": "dhamen_invoice_payment_expired"
  }
}

payment.refunded carries a transaction object instead of payment — the refund state lives on the underlying transaction, not the invoice status:

{
  "event": "payment.refunded",
  "event_id": "880e8400-e29b-41d4-a716-446655440003",
  "occurred_at": "2026-08-03T12:00:00+00:00",
  "invoice": { "external_id": "INV-PARTNER-001", "reference_number": "INV-42-001", "status": "issued", ... },
  "transaction": {
    "uuid": "990e8400-e29b-41d4-a716-446655440004",
    "reference": "TXN-42-001",
    "status": "completed",
    "settlement_status": "reversed",
    "gross_amount": 103.5,
    "net_amount": 101.5
  }
}

settlement.updated/settlement.paid carry a settlement object instead of invoice/payment (no single invoice is involved):

{
  "event": "settlement.paid",
  "event_id": "aa0e8400-e29b-41d4-a716-446655440005",
  "occurred_at": "2026-08-03T12:00:00+00:00",
  "settlement": {
    "uuid": "bb0e8400-e29b-41d4-a716-446655440006",
    "batch_no": "STL-20260803120000-AB12",
    "status": "settled",
    "channel": "dhamen",
    "currency_code": "SAR",
    "net_total": 980.00,
    "transactions_count": 12,
    "settled_at": "2026-08-03 12:00:00",
    "failure_reason": null
  }
}

7.4 Implementation requirements

1. Respond 2xx within a few seconds.
2. Deduplicate by event_id in the JSON body.
3. Validate X-Rsom-Signature before trusting the body (see §7.5).

7.5 Webhook signature (X-Rsom-Signature)

RsomPay includes a signature on every webhook so you can confirm the request is genuine, computed with a signing secret unique to your account.

Verification:

expected_signature = HMAC_SHA256(your_signing_secret, timestamp + "." + raw_request_body)
# reject the webhook if expected_signature != X-Rsom-Signature

7.6 Retries

• Default maximum 5 delivery attempts per event.
• Backoff: approximately 1, 2, 5, 15, then 60 minutes.
• Timeout per attempt: 15 seconds.
• Same event_id across retries — deduplicate on your side.

1. Create invoice → receive payment_url.
2. Share link with your customer.
3. Customer pays on payment.rsompay.com.
4. Browser redirect → immediate HTTP redirect to your return_url with query parameters (UX only).
5. Confirm payment → GET /invoices/by-reference (primary) — call from your return_url handler or right after redirect.
6. Webhook (backup) → payment.completed / payment.failed arrives later, asynchronously on notification_url (after the redirect).

Confirming payment (recommended)

On your return_url page, use GET /invoices/by-reference as your main check before you fulfill an order:

GET /invoices/by-reference?external_id=INV-PARTNER-001

Confirm data.status is paid. Poll briefly if status is still issued or pending (payment may still be confirming).

return_url query parameters

https://partner.example.com/payment/return?status=success&external_id=INV-PARTNER-001&reference_number=INV-42-001&payment_reference=GW-123&amount_paid=103.5&currency_code=SAR&payment_method=card

On data.status and webhook invoice.status for external API invoices:

Refund completeness is also visible per-transaction via refund_status on GET /transactions (gateway confirmation state — requested/pending_gateway/confirmed/stuck/submit_failed — not the same thing as full vs. partial).

Common validation issues

Validation messages may be localized — rely on HTTP status and field keys.

1. Obtain client-external-api token from RsomPay.
2. Obtain webhook signing secret and verification steps from RsomPay IT (tech@bseeds.sa) for header X-Rsom-Signature (see §7.5).
3. Import the Postman collection.
4. POST /invoices with a unique external_id — save payment_url.
5. GET /invoices/by-reference?external_id=... — confirm status is issued.
6. Expose an HTTPS webhook endpoint (e.g. webhook.site for sandbox).
7. Complete a sandbox payment on payment_url.
8. UX: Browser lands on return_url with query parameters (happens before webhook).
9. Primary: GET /invoices/by-reference from your return handler — status is paid.
10. Backup: payment.completed webhook on notification_url arrives later (if delivered).

Refund a previously captured Dhamen payment on one of your invoices — in full or in part.

POST /invoices/{reference}/refund

{reference} is your invoice's external_id or its RsomPay reference_number (same identifiers accepted by GET /invoices/by-reference).

Request fields

Behaviour

• A refund can only be requested against a payment that is fully captured and not currently mid-settlement. If the payment is still pending settlement processing, the request is rejected with 403 until settlement finishes.
• A refund can never exceed the remaining refundable amount on the payment. Repeated partial refunds are summed — once the total reaches the original captured amount, further refund requests are rejected.
• Refunding the same request twice (e.g. retried after a network timeout) does not create a duplicate refund — retries are safe.
• The 200 response below means "refund request accepted", not "refund completed." RsomPay submits the refund to the payment gateway and waits for the gateway's own confirmation before the refund is final. Poll GET /transactions and check the refund_status field on the matching transaction to see the outcome:

  refund_status	Meaning
  pending_gateway	Submitted, awaiting gateway confirmation — not refunded yet.
  confirmed	Refund confirmed by the gateway — money has moved.
  stuck	No confirmation received after an extended period — under investigation by RsomPay. Contact support if you see this.
  submit_failed	The gateway rejected the request outright (see the error response below) — safe to correct and retry.

Sample request

{
  "amount": 50.00,
  "reason": "Customer requested partial refund"
}

Sample response (200)

{
  "status": true,
  "message": "Mission completed successfully",
  "data": {
    "reference": "DHAMEN-REFUND-9f2c1e6a-...",
    "refund_status": "pending_gateway",
    "amount": 50.00,
    "currency_code": "SAR",
    "created_at": "2026-07-28 10:15:00"
  }
}

Errors

Read-only settlement/payout status for reconciliation. Settlement batches are created and processed internally by RsomPay — this endpoint only exposes their status and constituent transactions, scoped to your own account. Requires the client_settlements.view permission (already granted on all external-partner accounts).

List settlements

GET /settlements?status=settled&page=1&per_page=15

Sample response (200)

{
  "status": true,
  "message": "Mission completed successfully",
  "data": [
    {
      "id": 42,
      "reference": "DHM-INS-12-0007",
      "status": "settled",
      "period_from": "2026-07-01",
      "period_to": "2026-07-15",
      "currency_code": "SAR",
      "gross_total": 1500,
      "fee_total": 75,
      "net_total": 1425,
      "transactions_count": 12,
      "bank_transfer_reference": "BANK-REF-001",
      "settled_at": "2026-07-18 09:00:00",
      "created_at": "2026-07-16 08:00:00"
    }
  ],
  "meta": { "total": 1, "per_page": 15, "current_page": 1, "last_page": 1 }
}

Get settlement detail

GET /settlements/{id}

id is the numeric id returned by the list endpoint. Returns 404 if the settlement doesn't exist or doesn't belong to your account — settlements are never shared across clients.

{
  "status": true,
  "message": "Mission completed successfully",
  "data": {
    "id": 42,
    "reference": "DHM-INS-12-0007",
    "status": "settled",
    "period_from": "2026-07-01",
    "period_to": "2026-07-15",
    "currency_code": "SAR",
    "gross_total": 1500,
    "fee_total": 75,
    "net_total": 1425,
    "transactions_count": 12,
    "bank_transfer_reference": "BANK-REF-001",
    "settled_at": "2026-07-18 09:00:00",
    "failure_reason": null,
    "items": [
      {
        "invoice_reference": "INV-42-000123",
        "status": "settled",
        "gross_amount": 125,
        "fee_amount": 6.25,
        "net_amount": 118.75,
        "settled_at": "2026-07-18 09:00:00",
        "transaction": {
          "reference": "TX-REF-1",
          "status": "completed",
          "payment_method": "card",
          "captured_at": "2026-07-16 08:05:00"
        }
      }
    ],
    "created_at": "2026-07-16 08:00:00"
  }
}

Let a returning customer reuse a card they saved on an earlier invoice, instead of entering it again. The saved card itself is always scoped to a customer identifier (the 10-digit national ID / CR you pass as customer.id) — the retrieval token described here is what proves you are the integration that customer's card actually belongs to, before RsomPay will ever surface or charge it again.

Lifecycle

1. First invoice for a customer: create it normally (section 4), no saved_card_token — there is nothing to reuse yet.
2. The customer pays with "save this card" offered on the hosted checkout page. Once saved, RsomPay fires recurring.card_saved to your notification_url (no secret in that payload).
3. Get the retrieval token either way: call POST /customers/{customer_external_id}/saved-card-token explicitly (below), or simply make your next authenticated call to GET /invoices/by-reference / POST /invoices for that customer — see "Auto-surfaced on status checks" below. Store it against your own customer record; either way, the plaintext is only ever returned once.
4. Every later invoice for that same customer: pass the stored token as customer.saved_card_token. RsomPay verifies it, and the hosted checkout page now offers the saved card — or skip the checkout page entirely and charge it yourself server-to-server with POST /invoices/{reference}/charge-saved-card (below).

POST /customers/{customer_external_id}/saved-card-token — issue / rotate

POST /customers/1055512345/saved-card-token

Requires permission client_saved_cards.manage on your access token, and at least one active saved card for this customer under your account.

Sample response (201)

{
  "status": true,
  "message": "Mission completed successfully",
  "data": {
    "saved_card_token": "rsp_sct_8f3a1c9d4e2b7f60a1c9d4e2b7f60a1c9d4e2b7f60a1c"
  }
}

Store the value as-is against your own customer record. Treat it like any other credential — keep it out of logs and never send it to the customer's browser; it only ever travels over your own server-to-server calls to RsomPay.

Auto-surfaced on status checks (no extra call needed)

The moment a card is saved (the same moment recurring.card_saved fires), RsomPay also pre-issues a token and holds it for you briefly. Your next authenticated GET /invoices/by-reference or POST /invoices response for that customer carries it automatically under a saved_card key — removing the need to call the issue endpoint above at all for the common case:

{
  "status": true,
  "data": {
    "external_id": "INV-PARTNER-002",
    "...": "...",
    "saved_card": {
      "saved_card_token": "rsp_sct_8f3a1c9d4e2b7f60a1c9d4e2b7f60a1c9d4e2b7f60a1c",
      "brand": "MADA",
      "last4": "4621"
    }
  }
}

You can still call POST /customers/{customer_external_id}/saved-card-token any time to explicitly (re)issue one — the two mechanisms share the same underlying token, and either one rotates it.

Charging an invoice directly — POST /invoices/{reference}/charge-saved-card

Merchant-initiated, server-to-server — no customer visit to checkout required. Create the invoice normally first (section 4, no saved_card_token needed at creation for this path), then charge it directly:

POST /invoices/INV-PARTNER-002/charge-saved-card

Requires permission client_invoices.charge on your access token.

Always charges the invoice's full remaining balance — partial amounts aren't supported here, same as everywhere else in this API.

{
  "idempotency_key": "chg-2026-09-001",
  "saved_card_token": "rsp_sct_8f3a1c9d4e2b7f60a1c9d4e2b7f60a1c9d4e2b7f60a1c"
}

Sample response (202)

{
  "status": true,
  "message": "Mission completed successfully",
  "data": {
    "external_id": "INV-PARTNER-002",
    "status": "issued",
    "...": "..."
  },
  "charge": {
    "reference": "sub-1234567890-AbCdEfGh",
    "idempotency_key": "chg-2026-09-001",
    "status": "pending"
  }
}

Using it — customer.saved_card_token on invoice creation

Add this one field to the customer object on POST /invoices (section 4):

{
  "external_id": "INV-PARTNER-002",
  "notification_url": "https://partner.example.com/webhooks/rsom",
  "return_url": "https://partner.example.com/payment/return",
  "customer": {
    "id": "1055512345",
    "fullname": "Sara Ali",
    "saved_card_token": "rsp_sct_8f3a1c9d4e2b7f60a1c9d4e2b7f60a1c9d4e2b7f60a1c"
  },
  "items": [{ "description": "Monthly service fee", "unit_price": 100 }]
}

Omit the field entirely for any customer you have not issued a token for — the invoice is created exactly as before, and no saved card is offered.

Webhooks

Signed exactly like the invoice webhooks — see section 7 for header and HMAC verification.

{
  "event": "recurring.card_saved",
  "event_id": "cc0e8400-e29b-41d4-a716-446655440007",
  "occurred_at": "2026-09-11T12:00:00+03:00",
  "customer_external_id": "1055512345",
  "mandate_uuid": "9f2b3c1a-7cfa-41fe-9b42-eb334f96c8e4",
  "brand": "MADA",
  "last4": "4621"
}

Errors

• 403 — missing the client_saved_cards.manage permission (issue endpoint) or client_invoices.charge (charge-saved-card endpoint).
• 404 — no active saved card exists for this customer under your account yet.
• 422 — saved_card_token is invalid, or does not match the customer it's being used for.
• 422 — (charge-saved-card only) the invoice is already paid, canceled, or refunded, or a charge is already in progress for it.

Bill a customer a fixed amount on a fixed cadence using a card they save once. RsomPay stores the card on the first payment, then charges every cycle automatically — or on your call.

Lifecycle

• incomplete — created; waiting for the customer to complete the first payment via first_payment_url.
• trialing — first payment done, in the free trial window (only when trial_days > 0).
• active — being billed each cycle.
• past_due — a cycle charge failed; RsomPay is retrying (automatic mode) or waiting for you (merchant_managed).
• paused — stopped after dunning was exhausted, the saved card became invalid, or you paused it. Resume with POST /{id}/resume.
• canceled — stopped for good.
• completed — reached its total_cycles / ends_at limit.

Billing modes

Within automatic, collection_method is either auto (charge the saved card) or manual (email the customer an invoice link each cycle). The first payment is always a hosted link, in every mode.

POST /subscriptions — create

POST /subscriptions

Idempotent on external_id per client — calling again with the same external_id returns the existing subscription with HTTP 200 instead of creating a duplicate (201 the first time).

Sample request

{
  "external_id": "SUB-PARTNER-001",
  "customer": { "name": "Sara Ali", "id_number": "1055512345", "email": "sara@example.com" },
  "title": "Pro plan — monthly",
  "amount": 149.00,
  "currency": "SAR",
  "interval": { "unit": "month", "count": 1 },
  "billing_mode": "automatic",
  "collection_method": "auto",
  "trial_days": 14,
  "notification_url": "https://partner.example.com/webhooks/rsom"
}

Sample response (201)

{
  "status": true,
  "message": "Mission completed successfully",
  "data": {
    "id": "9f2b3c1a-7cfa-41fe-9b42-eb334f96c8e4",
    "external_id": "SUB-PARTNER-001",
    "status": "incomplete",
    "billing_mode": "automatic",
    "collection_method": "auto",
    "customer": { "name": "Sara Ali", "id_number": "1055512345", "email": "sara@example.com", "phone": null },
    "title": "Pro plan — monthly",
    "amount": 149.0,
    "currency": "SAR",
    "interval": { "unit": "month", "count": 1 },
    "trial_days": 14,
    "current_period_end": null,
    "next_action_at": null,
    "cycles_completed": 0,
    "total_cycles": null,
    "cancel_at_period_end": false,
    "created_at": "2026-09-10T10:00:00+03:00"
  },
  "first_payment": {
    "first_payment_url": "https://payment.rsompay.com/pay/checkout/2b1a9f3c-...",
    "first_payment_expires_at": "2026-09-13T10:00:00+03:00"
  }
}

Send first_payment.first_payment_url to the customer. Once they pay, the subscription becomes active (or trialing) and the subscription.activated webhook fires.

Other endpoints

POST /subscriptions/{id}/charge — merchant-managed charge

Triggers one off-session charge on the saved card. Only valid when billing_mode = merchant_managed and the subscription is active or past_due.

POST /subscriptions/9f2b3c1a-.../charge
{ "idempotency_key": "chg-2026-09-001", "amount": 149.00, "description": "September" }

Responds 202 Accepted with the created cycle. The charge is not yet confirmed — the subscription.renewed webhook (success) or subscription.payment_failed webhook (failure) follows. On failure, the subscription goes past_due; call /charge again with a new key, or surface the pay link.

Webhooks

Every state change POSTs to the subscription's notification_url (or your account default), signed exactly like the invoice webhooks — see section 7 for header and HMAC verification (X-Rsom-Event, X-Rsom-Timestamp, X-Rsom-Signature).

{
  "event": "subscription.payment_failed",
  "event_id": "5c1a...",
  "occurred_at": "2026-10-01T09:00:00+03:00",
  "data": {
    "subscription": {
      "id": "9f2b3c1a-...",
      "external_id": "SUB-PARTNER-001",
      "status": "past_due",
      "billing_mode": "automatic",
      "customer_identifier": "1055512345",
      "amount": 149.0,
      "currency": "SAR",
      "interval": { "unit": "month", "count": 1 },
      "current_period_end": "2026-10-01T00:00:00+03:00",
      "next_action_at": "2026-10-02T00:00:00+03:00",
      "cycles_completed": 1
    },
    "event_data": { "sequence": 2, "attempt": 1, "reason": "gateway_rejected" }
  }
}

Errors

• 403 — subscriptions not enabled for your account, or missing permission.
• 404 — subscription id / external_id not found for your account.
• 422 — validation error, or an operation not allowed from the current status (e.g. charge on an automatic subscription, resume when the saved card is inactive, charge amount out of bounds).

API version

Guide version v1.4.0 — API base path /api/external/v1 (unchanged). See the Changelog for full version history.

Endpoints quick reference

Environments

Postman collection

Download Postman collection (JSON)

customer_id in Postman is only for GET /transactions, not invoice lookup.

OpenAPI specification

Download OpenAPI spec (YAML)

Machine-generated from the live route/validation definitions (Scribe) — the authoritative parameter shapes and types behind this hand-written guide. Regenerate after any External API change: php artisan scribe:generate in backend-api, then copy storage/app/private/scribe/openapi.yaml here.

Support

Changelog

Full version history with categorized details: Changelog.