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.

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",
  "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.

{
  "status": true,
  "message": "Mission completed successfully",
  "data": [
    {
      "reference": "TX-REF-1",
      "status": "completed",
      "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",
      "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

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

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.

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:

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

API version

Guide version v1.0.1 — 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.

Support

Changelog