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

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

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

API version

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

Support

Changelog