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.

A Payment is a fast, one-shot charge — separate from an Invoice. Use it when you just need to charge a customer now and don't need a long-lived billing document: a failed or abandoned Payment never creates an invoice and never appears in your invoice list.

4.1 Create payment

POST /payments

Two ways to charge, chosen by whether you send saved_card_token:

• New card (no saved_card_token): the response includes a checkout_url — redirect the customer there to enter their card once. return_url is required on this path.
• Saved card (saved_card_token present): charged instantly, server-to-server, no redirect. Requires the customer to already have an active saved card (see tokenization, §5). return_url is not required on this path.

Request fields

Sample request — new card

{
  "external_id": "PAY-PARTNER-001",
  "amount": 150,
  "notification_url": "https://partner.example.com/webhooks/rsom",
  "return_url": "https://partner.example.com/payment/return",
  "save_card": true,
  "customer": {
    "id": "CUST-9",
    "fullname": "Ahmed Ali",
    "email": "customer@example.com",
    "phone": "+966501234567"
  }
}

Sample response (201) — new card

{
  "status": true,
  "message": "Mission completed successfully",
  "data": {
    "external_id": "PAY-PARTNER-001",
    "status": "pending",
    "amount": 150.0,
    "currency_code": "SAR",
    "brand": null,
    "description": null,
    "checkout_url": "https://payment.rsompay.com/pay/checkout/...",
    "paid_at": null,
    "created_at": "2026-09-13 10:00:00",
    "updated_at": "2026-09-13 10:00:00"
  }
}

Sample request — saved card

{
  "external_id": "PAY-PARTNER-002",
  "amount": 75,
  "notification_url": "https://partner.example.com/webhooks/rsom",
  "saved_card_token": "rsp_sct_AbCdEf0123456789...",
  "customer": {
    "id": "CUST-9",
    "fullname": "Ahmed Ali"
  }
}

Sample response (201) — saved card

{
  "status": true,
  "message": "Mission completed successfully",
  "data": {
    "external_id": "PAY-PARTNER-002",
    "status": "pending",
    "amount": 75.0,
    "currency_code": "SAR",
    "brand": null,
    "description": null,
    "checkout_url": null,
    "paid_at": null,
    "created_at": "2026-09-13 10:05:00",
    "updated_at": "2026-09-13 10:05:00"
  }
}

Errors

4.2 Query payment status

GET /payments/by-reference?external_id={value}

Look up a payment by your external_id. Response shape is the same as POST /payments, with status reflecting the current state (pending, paid, failed, refunded, partially_refunded).

Errors

4.3 Refund payment

POST /payments/{reference}/refund

{reference} is the payment's external_id. Same request/response shape and rules as refunding an invoice (§6.6): omit amount for a full refund, provide it for a partial refund; the 200 response means "submitted", confirmed later by refund_status on the matching transaction (GET /transactions) or the webhook in §4.4.

Errors

4.4 Webhooks

Payment webhooks use the exact same delivery mechanism, signature (X-Rsom-Signature), and retry policy as invoice webhooks — see §8. Only the event names and payload shape differ. Card-save events (recurring.card_saved) are documented under tokenization (§5.2).

Sample payload — payment.direct.paid

{
  "event": "payment.direct.paid",
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "occurred_at": "2026-09-13T10:00:00+00:00",
  "payment": {
    "external_id": "PAY-PARTNER-001",
    "customer_external_id": "CUST-9",
    "customer_name": "Ahmed Ali",
    "status": "paid",
    "amount": 150.0,
    "currency_code": "SAR",
    "brand": "mada",
    "paid_at": "2026-09-13 10:00:05"
  }
}

Sample payload — payment.direct.refunded

{
  "event": "payment.direct.refunded",
  "event_id": "660e8400-e29b-41d4-a716-446655440001",
  "occurred_at": "2026-09-13T11:00:00+00:00",
  "payment": { "external_id": "PAY-PARTNER-001", "status": "refunded", "amount": 150.0, ... },
  "transaction": {
    "uuid": "770e8400-e29b-41d4-a716-446655440002",
    "reference": "REF-...",
    "status": "completed",
    "settlement_status": "reversed",
    "gross_amount": 150.0,
    "net_amount": 147.0
  }
}

Sample payload — recurring.card_saved

{
  "event": "recurring.card_saved",
  "event_id": "880e8400-e29b-41d4-a716-446655440003",
  "occurred_at": "2026-09-13T10:00:05+00:00",
  "customer_external_id": "CUST-9",
  "mandate_uuid": "990e8400-e29b-41d4-a716-446655440004",
  "brand": "mada",
  "last4": "4242"
}

5.1 Overview

Tokenization lets you charge a customer again later without them re-entering their card. RsomPay supports one flow: save a card while completing a payment, then retrieve a token for that saved card to charge it instantly on a future POST /payments call.

5.2 Save a card during a payment

Set save_card: true on the new-card path of POST /payments (no saved_card_token in the same request — the two are mutually exclusive). The customer enters their card once on the hosted checkout page as usual; nothing about the checkout experience changes.

{
  "external_id": "PAY-PARTNER-001",
  "amount": 150,
  "notification_url": "https://partner.example.com/webhooks/rsom",
  "return_url": "https://partner.example.com/payment/return",
  "save_card": true,
  "customer": { "id": "CUST-9", "fullname": "Ahmed Ali" }
}

Once the payment completes and the card is saved, RsomPay sends a recurring.card_saved webhook to the payment's notification_url — this is your signal to call §5.3 and obtain a usable token:

{
  "event": "recurring.card_saved",
  "event_id": "880e8400-e29b-41d4-a716-446655440003",
  "occurred_at": "2026-09-13T10:00:05+00:00",
  "customer_external_id": "CUST-9",
  "mandate_uuid": "990e8400-e29b-41d4-a716-446655440004",
  "brand": "mada",
  "last4": "4242"
}

5.3 Issue the saved-card token

POST /customers/{customer_external_id}/saved-card-token

Call this once you receive recurring.card_saved (§5.2). It returns the token you'll pass as saved_card_token — store it against your own customer record.

Request fields

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

Errors

5.4 Charge with a token, view it, or remove it

Pass the token from §5.3 as saved_card_token on POST /payments — the charge is instant and server-to-server, no checkout page involved. Full request/response shapes are documented in §4.1; only the token-related fields are repeated here.

{
  "external_id": "PAY-PARTNER-002",
  "amount": 75,
  "notification_url": "https://partner.example.com/webhooks/rsom",
  "saved_card_token": "rsp_sct_AbCdEf0123456789...",
  "customer": { "id": "CUST-9", "fullname": "Ahmed Ali" }
}

View saved cards

GET /customers/{customer_external_id}/saved-cards

Returns every active saved card for this customer — zero, one, or several — enough to let your customer pick which one to use (brand, last 4 digits), never the full card number.

{
  "status": true,
  "message": "Mission completed successfully",
  "data": [
    { "id": "b1b2c3d4-...", "brand": "mada", "last4": "4242", "created_at": "2026-09-01 10:00:00" },
    { "id": "c2c3d4e5-...", "brand": "apple_pay", "last4": "4242", "created_at": "2026-09-05 10:00:00" }
  ]
}

Remove the saved card

DELETE /customers/{customer_external_id}/saved-cards/{id}

{id} is the value returned by the list call above.

Errors

An Invoice is a long-lived billing document with line items — the customer can visit its payment_url and pay whenever they're ready. For a fast one-shot charge with no line items, see Payments (§4) instead.

6.1 Create invoice

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"
      }
    ]
  }
}

6.2 Query invoice status

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

6.3 Payment flow (confirming payment)

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) — see §6.7.

On your return_url page, use GET /invoices/by-reference as your main check before you fulfill an order. Confirm data.status is paid; poll briefly if it's still issued (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

6.4 Invoice statuses

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

6.5 Customer transactions

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
  }
}

6.6 Refund invoice

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

6.7 Webhooks

Invoice webhooks use the shared delivery mechanism, signature, and retry policy documented in Outbound webhooks (§8). No webhook is sent when the invoice is created — only after payment activity.

Sample payload — payment.completed

{
  "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
  }
}

A Subscription charges one of your customers a fixed amount on a fixed cadence, on a saved card. It builds on Tokenization (§5) — the customer's first payment always goes through a hosted checkout link that also saves their card, so every later cycle can be charged without the customer present.

7.1 Endpoints

{id} above is the subscription's id field (a UUID) from any response — not your external_id, which has its own lookup endpoint.

7.2 Create subscription

POST /subscriptions

Idempotent on external_id, scoped to your account: calling this again with an external_id you've already used returns the existing subscription (HTTP 200) instead of creating a duplicate. A genuinely new external_id returns 201.

Request fields

Sample request

{
  "external_id": "SUB-PARTNER-001",
  "customer": {
    "id_number": "1234567890",
    "name": "Ahmed Ali",
    "email": "customer@example.com",
    "phone": "+966501234567"
  },
  "title": "Monthly gym membership",
  "amount": 149.00,
  "interval": { "unit": "month", "count": 1 },
  "billing_anchor_day": 1,
  "trial_days": 7,
  "notification_url": "https://partner.example.com/webhooks/rsom"
}

Sample response (201)

{
  "status": true,
  "message": "Mission completed successfully",
  "data": { "id": "d290f1ee-6c54-4b01-90e6-d701748f0851", "external_id": "SUB-PARTNER-001", "status": "incomplete", "billing_mode": "automatic", "collection_method": "auto", "..." : "see §7.7 for the full object" },
  "first_payment": {
    "first_payment_url": "https://payment.rsompay.com/pay/checkout/...",
    "first_payment_expires_at": "2026-09-18T12:00:00+00:00"
  }
}

Redirect the customer to first_payment_url to collect the first charge and save their card. The subscription stays incomplete until that payment is confirmed — see §7.9 for the subscription.activated webhook.

7.3 Update subscription

PATCH /subscriptions/{id}

All fields are optional and applied to the next cycle only — never the one already running. Accepts amount, interval (unit/count), billing_anchor_day, billing_mode, collection_method. Sending billing_mode and collection_method together always resolves consistently: if the resulting mode is merchant_managed, collection_method ends up null regardless of what you sent.

7.4 Charge subscription (merchant_managed only)

POST /subscriptions/{id}/charge

Triggers one off-session charge on the saved card right now. Returns 202 — confirmation is asynchronous, via the subscription.renewed or subscription.payment_failed webhook (§7.9). Rejected with 422 on an automatic subscription.

// Request
{ "idempotency_key": "invoice-2026-10-cycle-4", "amount": 149.00 }

// Response (202) — a SubscriptionCycle, see §7.6's cycle fields
{
  "status": true,
  "message": "Mission completed successfully",
  "data": { "sequence": 4, "status": "charging", "origin": "merchant_charge", "amount": 149.0, "..." : "..." }
}

7.5 Pause, resume, cancel, change payment method

POST /subscriptions/{id}/pause     (no body)
POST /subscriptions/{id}/resume    (no body)
POST /subscriptions/{id}/cancel
POST /subscriptions/{id}/payment-method

Resuming requires the saved card behind the subscription to still be active — a deactivated card returns 422; use /payment-method first.

7.6 List, lookup, and cycles

GET /subscriptions accepts status (one of the values in §7.7's status table), billing_mode (automatic/merchant_managed), external_id, and perPage (max 100). Response shape:

{
  "status": true,
  "message": "Mission completed successfully",
  "data": [ /* array of subscription objects, §7.7 */ ],
  "pagination": { "current_page": 1, "last_page": 3, "per_page": 20, "total": 57, "has_more_pages": true }
}

GET /subscriptions/{id}/cycles returns one entry per billing period — sequence, status (scheduled/invoiced/charging/paid/failed/skipped/refunded), origin, period_start/period_end/due_at, amount, attempts, idempotency_key, paid_at, paid_via.

GET /subscriptions/{id}/payment-link returns whatever hosted link is currently open for this subscription under {"payment_url": "..."} — HTTP 200, or 204 with no body when nothing is currently due (e.g. an automatic/auto-collection subscription with no manual step pending).

7.7 The subscription object

Status values

7.8 Errors

7.9 Webhook events

Subscription events use the same delivery mechanism, envelope, and signature as every other webhook (§8) — sent to the subscription's own notification_url if set, otherwise your account-level one.

A few internal transitions (cycle_invoiced, cycle_charged, dunning_exhausted, collection_method_updated) are recorded on our side but not dispatched as webhooks — they're implementation detail, not partner-facing state changes.

{
  "event": "subscription.renewed",
  "event_id": "9c0e8400-e29b-41d4-a716-446655440099",
  "occurred_at": "2026-10-01T09:00:03+00:00",
  "data": {
    "subscription": {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "external_id": "SUB-PARTNER-001",
      "status": "active",
      "billing_mode": "automatic",
      "collection_method": "auto",
      "customer_identifier": "1234567890",
      "customer_name": "Ahmed Ali",
      "title": "Monthly gym membership",
      "amount": 149.0,
      "currency": "SAR",
      "interval": { "unit": "month", "count": 1 },
      "trial_days": 7,
      "current_period_end": "2026-11-01T00:00:00+00:00",
      "next_action_at": "2026-11-01T00:00:00+00:00",
      "cycles_completed": 4,
      "total_cycles": null,
      "cancel_at_period_end": false
    },
    "event_data": { "sequence": 4 }
  }
}

RsomPay POSTs outbound webhooks to notify you of activity — Invoice events (§6.7), Payment events (§4.4), and account-level Settlement events (below) all share the same delivery mechanism, signature, and retry policy documented here. Delivery is asynchronous — respond with HTTP 2xx quickly and process the payload in the background.

8.1 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 §8.4).

8.2 Payload envelope

Every event shares these top-level fields, plus a resource-specific object (invoice, payment, or settlement) documented alongside that resource:

{
  "event": "...",
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "occurred_at": "2026-05-18T12:00:00+00:00"
}

8.3 Settlement events

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

{
  "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
  }
}

8.4 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

8.5 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 §8.4).

8.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.

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 §8.4).
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 — use one of the test cards below.
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).

Test cards (sandbox only)

Cardholder name can be anything (e.g. Test) — it isn't validated in the sandbox. These numbers only work on the sandbox environment (§12, Environments) and never charge real money.

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"
  }
}

API version

Guide version v1.6.0 — API base path /api/external/v1 (unchanged).

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