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| RET
  INT -->|POST notification_url| WH
  ERP -->|GET by-reference| INT

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.
• Standard client-panel 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 / data.balance = sum of 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,
    "balance": 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"
      }
    ],
    "latest_payment": null
  }
}

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

Provide exactly one query parameter:

Examples

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

List customer payments across external API invoices. Shows the paid amount only — not fees, net settlement, or settlement status.

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

Response fields (each item in data)

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-Event: payment.completed
X-Rsom-Event-Id: 550e8400-e29b-41d4-a716-446655440000
X-Rsom-Timestamp: 1716033600
X-Rsom-Signature: a1b2c3d4e5f6...

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,
    "balance": 0,
    "payment_url": "https://payment.rsompay.com/pay/invoice/..."
  },
  "payment": {
    "uuid": "660e8400-e29b-41d4-a716-446655440001",
    "gateway": "dhamen",
    "status": "completed",
    "amount": 103.5,
    "paid_at": "2026-05-18 12:00:00"
  }
}

7.4 Implementation requirements

1. Respond 2xx within a few seconds.
2. Deduplicate by event_id.
3. Verify signature before trusting the body.

7.5 Headers and signature inputs

RsomPay sends the webhook as an HTTP POST to your notification_url. Metadata needed for verification is in the request headers; the event details are in the JSON body. Use the table below: each Key is the name to read; Value is where that value comes from.

Verify: Use the webhook signing secret as the HMAC key. Hash the exact string X-Rsom-Timestamp + "." + raw_body with HMAC-SHA256, encode as lowercase hex, then compare to X-Rsom-Signature using a timing-safe comparison.

const crypto = require('crypto');

function verifyRsomWebhook(rawBody, headers, webhookSigningSecret) {
  const timestamp = headers['x-rsom-timestamp'];
  const signature = headers['x-rsom-signature'];
  const expected = crypto.createHmac('sha256', webhookSigningSecret)
    .update(`${timestamp}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

import hmac, hashlib

def verify_rsom_webhook(raw_body: bytes, timestamp: str, signature: str,
                        webhook_signing_secret: str) -> bool:
    key = webhook_signing_secret.encode()
    message = f"{timestamp}.".encode() + raw_body
    expected = hmac.new(key, message, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

function verifyRsomWebhook(
    string $rawBody, string $timestamp, string $signature,
    string $webhookSigningSecret
): bool {
    $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $webhookSigningSecret);
    return hash_equals($expected, $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. Confirm payment → GET /invoices/by-reference (primary).
5. Webhook (backup) → payment.completed / payment.failed when delivered.
6. Browser redirect → immediate HTTP redirect to your return_url with query parameters (UX only).

Confirming payment (recommended)

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 and data.balance is 0.

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

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 admin Integration tab.
2. Obtain webhook signing secret for your integration partner from RsomPay technical support (tech@bseeds.sa) — this is the only value used to verify 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. Primary: GET /invoices/by-reference — status is paid, balance is 0.
9. Backup: payment.completed webhook (X-Rsom-Signature) if delivered.
10. UX: return_url query parameters in the browser (not settlement proof).

API version

This guide documents v1 (/api/external/v1).

Endpoints quick reference

Environments

Postman collection

Download Postman collection (JSON)

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

Support

Changelog