# Raïs API documentation

> Raïs is a payment platform for Algeria. Businesses accept CIB and Edahabia card payments through a REST API, a hosted checkout and webhooks; amounts are in Algerian dinars (DZD), always integers in centimes.

This file contains every page of the documentation. The index is at https://rais.app/llms.txt.

---

# Introduction

> What Raïs is, how a payment travels from your server to the bank and back, and the concepts you will meet.

Source: https://rais.app/docs

Raïs lets a business in Algeria accept CIB and Edahabia card payments in Algerian dinars. You create a payment from your server, send the payer to a hosted checkout, and learn the outcome through a signed webhook or the API. Raïs handles the card form, 3-D Secure with SATIM, receipts and refunds.

## How a payment works


A payment, end to end. Actors: Your server, Payer, Raïs, SATIM.

1. Your server to Raïs: POST /v1/payments
2. Raïs to Your server: payment with checkout_url
3. Your server to Payer: Redirect to checkout_url
4. Payer to Raïs: Enters the card on the hosted page
5. Raïs to SATIM: Authorisation and 3-D Secure
6. SATIM to Raïs: Approved or declined
7. Raïs to Payer: Redirect to success_url or cancel_url
8. Raïs to Your server: Webhook payment.succeeded (signed)
9. Your server to Raïs: GET /v1/payments/{id} to confirm


1. Your server creates a **payment** with the amount and your own reference. Raïs answers with a `checkout_url`.
2. You redirect the payer to that URL. They enter their card on the hosted page and confirm with 3-D Secure.
3. The result page shows the payer the outcome and a button back to your `success_url` or `cancel_url`; independently, Raïs delivers a signed **webhook** to your server.
4. Your server confirms the result (from the webhook, or by retrieving the payment) before it ships anything.

The browser redirect is only a convenience for the payer. The webhook and the API are the source of truth.

## Concepts

### Stores

A **store** is the merchant account that takes payments. It has a name, return URLs, branding, API keys and webhook endpoints. A business account starts with one store and can have several; every API key belongs to exactly one store, and a key only ever sees the payments of its own store.

### API keys

You call the API with a **secret key** sent as a bearer token. Sandbox keys start with `rais_sk_test_`, live keys with `rais_sk_live_`. Keys belong on your server: the API sends no CORS headers on purpose, so a browser or a mobile app cannot use one. See [Authentication](https://rais.app/docs/authentication.md).

### Test and live

The sandbox and live environments have the same API, the same URLs and the same objects. The **key decides** which environment a request belongs to. Sandbox payments are paid with SATIM's published test cards and never move money; live payments are real and need a verified business. See [Test cards and sandbox](https://rais.app/docs/testing.md) and [Going live](https://rais.app/docs/going-live.md).

### Payments

A payment is one attempt to collect an amount from a payer. Amounts are **integers in centimes**: `500000` is 5,000.00 DA. The only currency is `DZD` and the smallest payment is 50.00 DA. A payment is `pending` until it is paid, and ends `paid`, `failed`, `cancelled` or `expired`. See [Payments](https://rais.app/docs/payments.md).

### Refunds

You can refund all or part of a paid payment, as many times as you like, never beyond what was paid. See [Refunds](https://rais.app/docs/refunds.md).

### Pricing

A paid payment costs SATIM's fee plus Raïs's, a refund costs a flat 10.00 DA, and every price excludes VAT. A payment carries its `fees` and its `net`, a refund its own `fees`. See [Pricing and fees](https://rais.app/docs/pricing.md).

### Events and webhooks

Every change that matters creates an **event** such as `payment.succeeded`. Raïs delivers events to your webhook endpoints, signed, at least once, and keeps them readable through the API for 30 days. See [Webhooks](https://rais.app/docs/webhooks.md).

### Receipts

Every paid payment has a PDF receipt for the payer, available through a link on the payment and through a signed link you can request. See [Receipts](https://rais.app/docs/receipts.md).

## Conventions

| | |
| --- | --- |
| Base URL | `https://api.rais.app/v1` |
| Payer's pages | `https://pay.rais.app`: the hosted checkout and the receipts (`checkout_url`, `receipt_url`) |
| Format | JSON requests and responses, UTF-8 |
| Authentication | `Authorization: Bearer rais_sk_...` |
| Amounts | Integers in centimes (1 DA = 100) |
| Timestamps | Unix time in seconds |
| Ids | Payments, refunds and stores are UUIDs; events start with `evt_` |
| Errors | One envelope for every error, with a stable `code` and a `request_id` |
| Version | `2026-10-26`, in the `Rais-Version` header of every response |

## Where to go next


- [Quickstart](https://rais.app/docs/quickstart.md): create a test key, take a first payment and verify it.
- [Authentication](https://rais.app/docs/authentication.md): keys, scopes, rotation and IP allowlists.
- [Payments](https://rais.app/docs/payments.md): the payment object, statuses and everything you can set.
- [Webhooks](https://rais.app/docs/webhooks.md): receive and verify events.
- [API reference](https://rais.app/docs/api.md): every endpoint with examples in nine languages.
- [Use these docs with AI](https://rais.app/docs/ai-tools.md): llms.txt, Markdown pages and the OpenAPI file.

---

# Quickstart

> Create a store, get a test key, take a first test payment and verify it, in about ten minutes.

Source: https://rais.app/docs/quickstart

This guide takes you from nothing to a verified test payment. You will need a Raïs business account and a server that can run a few lines of code. No money moves in the sandbox.

## 1. Get a test key

A business account is created with one store, which can use the sandbox straight away. In the dashboard, open **Developers**, then **API keys**, press **Create key**, and choose your store and the **Test** mode in the dialog. A test key starts with `rais_sk_test_` and is shown **once**: copy it into your environment now.

~~~bash
export RAIS_SECRET_KEY="rais_sk_test_..."
~~~


> [!WARNING]
> **Keep the key on your server**
>
> Anybody who holds a secret key can create payments in your name. Never put it in a web page, a mobile app or a repository. See [Authentication](https://rais.app/docs/authentication.md).


## 2. Check the key

Retrieving your account is the simplest call: it works with any valid key and tells you which store and environment the key belongs to.


**Request**

```bash
curl https://api.rais.app/v1/account \
  -H "Authorization: Bearer rais_sk_test_..."
```

**Response** (`200`)

~~~json
{
  "object": "account",
  "id": "7d0b6a3e-1c52-4f8e-9a44-2b6e8f1d0c35",
  "name": "Boutique Alger",
  "livemode": false,
  "live_enabled": false,
  "currency": "DZD",
  "payment_page": "rais"
}
~~~


`livemode: false` confirms that this is a sandbox key.

## 3. Create a payment

Create the payment **from your server**, with the amount in centimes. `500000` is 5,000.00 DA. The `Idempotency-Key` header makes the request safe to repeat: if the connection drops and you send it again with the same key, you get the same payment back instead of a second one. See [Idempotency and retries](https://rais.app/docs/idempotency.md).


**Request**

```bash
curl https://api.rais.app/v1/payments \
  -H "Authorization: Bearer rais_sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: b7e1c1c6-6f0a-4d2f-9d8b-3a5c2f1e7a90" \
  -d '{
  "amount": 500000,
  "currency": "DZD",
  "description": "Order #1042",
  "reference": "order-1042",
  "customer": {
    "name": "Amina Benali",
    "email": "amina@example.dz",
    "phone": "+213550000000"
  },
  "success_url": "https://shop.example/thanks",
  "cancel_url": "https://shop.example/cart",
  "metadata": {
    "cart_id": "c_8812"
  },
  "expires_in": 3600
}'
```

**Response** (`201`)

~~~json
{
  "id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
  "object": "payment",
  "status": "pending",
  "amount": 500000,
  "currency": "DZD",
  "description": "Order #1042",
  "reference": "order-1042",
  "customer": {
    "id": null,
    "name": "Amina Benali",
    "email": "amina@example.dz",
    "phone": "+213550000000"
  },
  "items": [
    {
      "name": "Running shoes",
      "description": null,
      "quantity": 2,
      "unit_amount": 250000
    }
  ],
  "metadata": {
    "cart_id": "c_8812"
  },
  "livemode": false,
  "payment_page": "rais",
  "checkout_url": "https://pay.rais.app/pay/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
  "success_url": "https://shop.example/thanks",
  "cancel_url": "https://shop.example/cart",
  "expires_at": 1793003600,
  "created": 1793000000,
  "paid_at": null,
  "amount_refunded": 0,
  "refunded": false,
  "fees": null,
  "net": null,
  "receipt_url": null,
  "failure": null,
  "payment_method": null,
  "processor": {
    "name": "satim",
    "order_id": "V721uPPfNNofVQAAABL3",
    "approval_code": null,
    "response_code": null
  }
}
~~~


The payment is `pending`. Keep its `id` and `reference`; you will need them to match the result to your order.

## 4. Send the payer to the checkout

Redirect the payer to `checkout_url`. It is a hosted page, in English, French or Arabic, where they enter their card and confirm with 3-D Secure. When they are done, a result page shows the outcome and a button that takes them to your `success_url` or `cancel_url` with the payment id and a status added to the address. Some payers close the tab right after paying and never come back to your site: the webhook of step 6 still reaches you, which is why it matters. See [Hosted checkout and return URLs](https://rais.app/docs/checkout.md).

## 5. Pay with a test card

The checkout of a sandbox payment is marked "Test mode". Type SATIM's test card as you would a real one (the cards are in [Test cards and sandbox](https://rais.app/docs/testing.md)). This one always succeeds:

| Card number | Expiry (MM/YY) | CVV2 | 3-D Secure password |
| --- | --- | --- | --- |
| `6280 5811 1000 7215` | 01/27 | 373 | 123456 |

The other cards reproduce declines, expired cards and wrong passwords: see [Test cards and sandbox](https://rais.app/docs/testing.md).

## 6. Receive the webhook

Webhooks tell your server what happened without waiting for the payer's browser. In the dashboard, open **Developers**, then **Webhooks**, add an endpoint, choose your store and the **Test** mode in the dialog, and choose the events to receive (`payment.succeeded` is enough for now). Copy its **signing secret**: it starts with `whsec_`.

~~~bash
export RAIS_WEBHOOK_SECRET="whsec_..."
~~~

Two things to know while you develop:

- Raïs delivers from the internet, so your endpoint must be reachable from it. For a server on your computer, use a tunnel (ngrok, Cloudflare Tunnel and similar). Addresses such as `localhost` and private networks are refused.
- A sandbox endpoint may use `http://`. A live endpoint must use `https://`.

The **Send test event** button of the dashboard sends a fake `payment.succeeded` event to your endpoint, which is the quickest way to check that it answers.

## 7. Verify and confirm

Every webhook carries a `Rais-Signature` header. Verify it against the **raw body** before you trust anything in the request, then answer with a `2xx` status. When the payer comes back to your site, do not trust the address either: retrieve the payment and check its status.

The server below does all of it: it creates the payment and redirects, asks the API for the truth on the return page, and verifies the signature of the webhook.


**A complete server: create a payment, redirect, receive the webhook**

**Node.js**

```javascript
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const API = "https://api.rais.app/v1";
const SECRET_KEY = process.env.RAIS_SECRET_KEY; // rais_sk_test_...
const WEBHOOK_SECRET = process.env.RAIS_WEBHOOK_SECRET; // whsec_...

/**
 * rawBody: the request body exactly as received (Buffer or string), never re-serialised JSON.
 * header:  the value of the Rais-Signature header.
 */
export function verifySignature(rawBody, header, secret, toleranceSeconds = 300, now = Math.floor(Date.now() / 1000)) {
  const pairs = header.split(",").map((part) => part.trim().split("="));
  const timestamp = pairs.find(([key]) => key === "t")?.[1];
  const signatures = pairs.filter(([key]) => key === "v1").map(([, value]) => value);
  if (!/^\d+$/.test(timestamp ?? "") || signatures.length === 0) return false;
  if (Math.abs(now - Number(timestamp)) > toleranceSeconds) return false;

  const expected = createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest();
  return signatures.some((signature) => {
    const received = Buffer.from(signature, "hex");
    return received.length === expected.length && timingSafeEqual(received, expected);
  });
}

async function rais(path, init = {}) {
  const response = await fetch(`${API}${path}`, {
    ...init,
    headers: { Authorization: `Bearer ${SECRET_KEY}`, "Content-Type": "application/json", ...init.headers },
  });
  return { ok: response.ok, body: await response.json() };
}

const app = express();
const orders = new Map(); // order id -> { paymentId, amount }. Use your database in production.
const processed = new Set(); // ids of the events already handled. Use your database too.

app.get("/", (req, res) => {
  res.send('<form method="post" action="/checkout"><button>Pay 5,000.00 DA</button></form>');
});

// 1. Create the payment on your server, keep its id with the order, then send the payer to the hosted checkout.
app.post("/checkout", async (req, res) => {
  const orderId = "1042"; // your own order
  const amount = 500000; // 5,000.00 DA, in centimes
  const { ok, body: payment } = await rais("/payments", {
    method: "POST",
    headers: { "Idempotency-Key": `order-${orderId}` }, // one payment per order, even if this handler runs twice
    body: JSON.stringify({
      amount,
      description: `Order #${orderId}`,
      reference: `order-${orderId}`,
      success_url: "http://localhost:3000/thanks", // https:// is required for live payments
      cancel_url: "http://localhost:3000/",
    }),
  });
  if (!ok) return res.status(502).json(payment);
  orders.set(orderId, { paymentId: payment.id, amount });
  res.redirect(303, payment.checkout_url);
});

// 2. The payer comes back here. The address proves nothing: ask the API about the payment YOU created for this order.
app.get("/thanks", async (req, res) => {
  const order = orders.get(String(req.query.reference ?? "").replace(/^order-/, ""));
  if (!order) return res.status(404).send("Unknown order.");
  const { ok, body: payment } = await rais(`/payments/${order.paymentId}`);
  const paid = ok && payment.status === "paid" && payment.amount === order.amount;
  res.send(paid ? "Thank you, we received your payment." : "Payment not completed.");
});

// 3. Raïs calls this URL for every event. express.raw keeps the body exactly as it was signed.
app.post("/webhooks/rais", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifySignature(req.body, req.get("Rais-Signature") ?? "", WEBHOOK_SECRET)) return res.sendStatus(400);

  const event = JSON.parse(req.body.toString("utf8"));
  if (event.id.startsWith("evt_test_")) return res.sendStatus(200); // the dashboard's test event: never fulfil an order for it
  if (processed.has(event.id)) return res.sendStatus(200); // delivered twice: nothing to do
  processed.add(event.id);

  if (event.type === "payment.succeeded") {
    const payment = event.data.object;
    const orderId = [...orders].find(([, order]) => order.paymentId === payment.id)?.[0];
    if (orderId && payment.amount === orders.get(orderId).amount) console.log(`Order ${orderId} is paid (${payment.amount} centimes)`);
  }
  res.sendStatus(200); // answer quickly, do slow work afterwards
});

app.listen(3000, () => console.log("Listening on http://localhost:3000"));
```

**Python**

```python
import os

import requests
from flask import Flask, abort, redirect, request
import hashlib
import hmac
import time

API = "https://api.rais.app/v1"
SECRET_KEY = os.environ["RAIS_SECRET_KEY"]  # rais_sk_test_...
WEBHOOK_SECRET = os.environ["RAIS_WEBHOOK_SECRET"]  # whsec_...
AUTH = {"Authorization": f"Bearer {SECRET_KEY}"}

app = Flask(__name__)
orders = {}  # order id -> {"payment_id": ..., "amount": ...}. Use your database in production.
processed = set()  # ids of the events already handled. Use your database too.


def verify_signature(raw_body, header, secret, tolerance=300, now=None):
    """raw_body: the request body exactly as received (bytes). header: the Rais-Signature header."""
    timestamp, signatures = None, []
    for part in header.split(","):
        key, _, value = part.strip().partition("=")
        if key == "t":
            timestamp = value
        elif key == "v1":
            signatures.append(value)
    if timestamp is None or not timestamp.isascii() or not timestamp.isdigit() or not signatures:
        return False
    if abs((time.time() if now is None else now) - int(timestamp)) > tolerance:
        return False

    signed = timestamp.encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest().encode()
    return any(hmac.compare_digest(expected, signature.lower().encode()) for signature in signatures)


@app.get("/")
def home():
    return '<form method="post" action="/checkout"><button>Pay 5,000.00 DA</button></form>'


# 1. Create the payment on your server, keep its id with the order, then send the payer to the hosted checkout.
@app.post("/checkout")
def checkout():
    order_id = "1042"  # your own order
    amount = 500000  # 5,000.00 DA, in centimes
    response = requests.post(
        f"{API}/payments",
        headers={**AUTH, "Idempotency-Key": f"order-{order_id}"},  # one payment per order
        json={
            "amount": amount,
            "description": f"Order #{order_id}",
            "reference": f"order-{order_id}",
            "success_url": "http://localhost:3000/thanks",  # https:// is required for live payments
            "cancel_url": "http://localhost:3000/",
        },
        timeout=30,
    )
    if not response.ok:
        abort(502)
    payment = response.json()
    orders[order_id] = {"payment_id": payment["id"], "amount": amount}
    return redirect(payment["checkout_url"], code=303)


# 2. The payer comes back here. The address proves nothing: ask the API about the payment YOU created for this order.
@app.get("/thanks")
def thanks():
    order = orders.get(request.args.get("reference", "").removeprefix("order-"))
    if order is None:
        abort(404)
    payment = requests.get(f"{API}/payments/{order['payment_id']}", headers=AUTH, timeout=30).json()
    paid = payment.get("status") == "paid" and payment.get("amount") == order["amount"]
    return "Thank you, we received your payment." if paid else "Payment not completed."


# 3. Raïs calls this URL for every event. get_data() returns the body exactly as it was signed.
@app.post("/webhooks/rais")
def webhook():
    raw_body = request.get_data()
    if not verify_signature(raw_body, request.headers.get("Rais-Signature", ""), WEBHOOK_SECRET):
        abort(400)

    event = request.get_json(force=True)
    if event["id"].startswith("evt_test_"):
        return "", 200  # the dashboard's test event: never fulfil an order for it
    if event["id"] in processed:
        return "", 200  # delivered twice: nothing to do
    processed.add(event["id"])

    if event["type"] == "payment.succeeded":
        payment = event["data"]["object"]
        order_id = next((key for key, order in orders.items() if order["payment_id"] == payment["id"]), None)
        if order_id and payment["amount"] == orders[order_id]["amount"]:
            print(f"Order {order_id} is paid ({payment['amount']} centimes)", flush=True)
    return "", 200  # answer quickly, do slow work afterwards


if __name__ == "__main__":
    app.run(port=3000)
```

**PHP**

```php
<?php
// Run with: php -S localhost:3000 index.php
const API = 'https://api.rais.app/v1';
const ORDERS_FILE = __DIR__ . '/orders.json'; // use your database in production
$secretKey = getenv('RAIS_SECRET_KEY'); // rais_sk_test_...
$webhookSecret = getenv('RAIS_WEBHOOK_SECRET'); // whsec_...

function verifySignature(string $rawBody, string $header, string $secret, int $tolerance = 300, ?int $now = null): bool
{
    $timestamp = null;
    $signatures = [];
    foreach (explode(',', $header) as $part) {
        [$key, $value] = array_pad(explode('=', trim($part), 2), 2, '');
        if ($key === 't') {
            $timestamp = $value;
        } elseif ($key === 'v1') {
            $signatures[] = $value;
        }
    }
    if ($timestamp === null || !ctype_digit($timestamp) || $signatures === []) {
        return false;
    }
    if (abs(($now ?? time()) - (int) $timestamp) > $tolerance) {
        return false;
    }

    $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
    $valid = false;
    foreach ($signatures as $signature) {
        $valid = hash_equals($expected, strtolower($signature)) || $valid;
    }
    return $valid;
}

function rais(string $method, string $path, ?array $body = null, array $extraHeaders = []): array
{
    global $secretKey;
    $ch = curl_init(API . $path);
    $options = [
        CURLOPT_CUSTOMREQUEST => $method,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => array_merge(['Authorization: Bearer ' . $secretKey, 'Content-Type: application/json'], $extraHeaders),
    ];
    if ($body !== null) {
        $options[CURLOPT_POSTFIELDS] = json_encode($body);
    }
    curl_setopt_array($ch, $options);
    $response = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    return [$status, json_decode((string) $response, true) ?? []];
}

// order id => ['payment_id' => ..., 'amount' => ...]
function orders(): array
{
    return is_file(ORDERS_FILE) ? (json_decode(file_get_contents(ORDERS_FILE), true) ?? []) : [];
}

function saveOrder(string $orderId, array $order): void
{
    file_put_contents(ORDERS_FILE, json_encode([$orderId => $order] + orders()), LOCK_EX);
}

$path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
$method = $_SERVER['REQUEST_METHOD'];

if ($path === '/' && $method === 'GET') {
    echo '<form method="post" action="/checkout"><button>Pay 5,000.00 DA</button></form>';
} elseif ($path === '/checkout' && $method === 'POST') {
    // 1. Create the payment on your server, keep its id with the order, then send the payer to the hosted checkout.
    $orderId = '1042'; // your own order
    $amount = 500000; // 5,000.00 DA, in centimes
    [$status, $payment] = rais('POST', '/payments', [
        'amount' => $amount,
        'description' => "Order #$orderId",
        'reference' => "order-$orderId",
        'success_url' => 'http://localhost:3000/thanks', // https:// is required for live payments
        'cancel_url' => 'http://localhost:3000/',
    ], ["Idempotency-Key: order-$orderId"]); // one payment per order
    if ($status !== 201) {
        http_response_code(502);
        exit('Could not create the payment');
    }
    saveOrder($orderId, ['payment_id' => $payment['id'], 'amount' => $amount]);
    header('Location: ' . $payment['checkout_url'], true, 303);
} elseif ($path === '/thanks' && $method === 'GET') {
    // 2. The payer comes back here. The address proves nothing: ask the API about the payment YOU created for this order.
    $order = orders()[preg_replace('/^order-/', '', $_GET['reference'] ?? '')] ?? null;
    if ($order === null) {
        http_response_code(404);
        exit('Unknown order.');
    }
    [$status, $payment] = rais('GET', '/payments/' . rawurlencode($order['payment_id']));
    $paid = $status === 200 && ($payment['status'] ?? '') === 'paid' && ($payment['amount'] ?? 0) === $order['amount'];
    echo $paid ? 'Thank you, we received your payment.' : 'Payment not completed.';
} elseif ($path === '/webhooks/rais' && $method === 'POST') {
    // 3. Raïs calls this URL for every event. php://input is the body exactly as it was signed.
    $rawBody = file_get_contents('php://input');
    if (!verifySignature($rawBody, $_SERVER['HTTP_RAIS_SIGNATURE'] ?? '', $webhookSecret)) {
        http_response_code(400);
        exit;
    }
    $event = json_decode($rawBody, true);
    if (str_starts_with($event['id'], 'evt_test_')) {
        http_response_code(200); // the dashboard's test event: never fulfil an order for it
        exit;
    }
    // Delivered twice? Keep $event['id'] in your database and skip the ones you have seen.
    if ($event['type'] === 'payment.succeeded') {
        $payment = $event['data']['object'];
        foreach (orders() as $orderId => $order) {
            if ($order['payment_id'] === $payment['id'] && $order['amount'] === $payment['amount']) {
                error_log("Order $orderId is paid ({$payment['amount']} centimes)");
            }
        }
    }
    http_response_code(200); // answer quickly, do slow work afterwards
} else {
    http_response_code(404);
}
```

**Go**

```go
package main

import (
	"bytes"
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"io"
	"log"
	"math"
	"net/http"
	"net/url"
	"os"
	"strconv"
	"strings"
	"sync"
	"time"
)

type order struct {
	PaymentID string
	Amount    int
}

var (
	api           = "https://api.rais.app/v1"
	secretKey     = os.Getenv("RAIS_SECRET_KEY")     // rais_sk_test_...
	webhookSecret = os.Getenv("RAIS_WEBHOOK_SECRET") // whsec_...
	orders        sync.Map                           // order id -> order. Use your database in production.
	processed     sync.Map                           // ids of the events already handled. Use your database too.
)

// VerifySignature checks a Rais-Signature header against the raw request body.
func VerifySignature(rawBody []byte, header, secret string, tolerance time.Duration, now time.Time) bool {
	var timestamp string
	var signatures []string
	for _, part := range strings.Split(header, ",") {
		key, value, _ := strings.Cut(strings.TrimSpace(part), "=")
		switch key {
		case "t":
			timestamp = value
		case "v1":
			signatures = append(signatures, value)
		}
	}
	if timestamp == "" || strings.Trim(timestamp, "0123456789") != "" || len(signatures) == 0 {
		return false
	}
	seconds, err := strconv.ParseInt(timestamp, 10, 64)
	if err != nil || math.Abs(float64(now.Unix()-seconds)) > tolerance.Seconds() {
		return false
	}

	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(timestamp + "."))
	mac.Write(rawBody)
	expected := mac.Sum(nil)

	valid := false
	for _, signature := range signatures {
		if received, err := hex.DecodeString(signature); err == nil && hmac.Equal(received, expected) {
			valid = true
		}
	}
	return valid
}

func rais(method, path string, body any, headers map[string]string) (int, map[string]any, error) {
	var reader io.Reader
	if body != nil {
		encoded, err := json.Marshal(body)
		if err != nil {
			return 0, nil, err
		}
		reader = bytes.NewReader(encoded)
	}
	req, err := http.NewRequest(method, api+path, reader)
	if err != nil {
		return 0, nil, err
	}
	req.Header.Set("Authorization", "Bearer "+secretKey)
	req.Header.Set("Content-Type", "application/json")
	for name, value := range headers {
		req.Header.Set(name, value)
	}
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return 0, nil, err
	}
	defer res.Body.Close()
	var decoded map[string]any
	_ = json.NewDecoder(res.Body).Decode(&decoded)
	return res.StatusCode, decoded, nil
}

func main() {
	mux := http.NewServeMux()

	mux.HandleFunc("GET /{$}", func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprint(w, `<form method="post" action="/checkout"><button>Pay 5,000.00 DA</button></form>`)
	})

	// 1. Create the payment on your server, keep its id with the order, then send the payer to the hosted checkout.
	mux.HandleFunc("POST /checkout", func(w http.ResponseWriter, r *http.Request) {
		orderID := "1042" // your own order
		amount := 500000  // 5,000.00 DA, in centimes
		status, payment, err := rais("POST", "/payments", map[string]any{
			"amount":      amount,
			"description": "Order #" + orderID,
			"reference":   "order-" + orderID,
			"success_url": "http://localhost:3000/thanks", // https:// is required for live payments
			"cancel_url":  "http://localhost:3000/",
		}, map[string]string{"Idempotency-Key": "order-" + orderID}) // one payment per order
		if err != nil || status != http.StatusCreated {
			http.Error(w, "could not create the payment", http.StatusBadGateway)
			return
		}
		orders.Store(orderID, order{PaymentID: payment["id"].(string), Amount: amount})
		http.Redirect(w, r, payment["checkout_url"].(string), http.StatusSeeOther)
	})

	// 2. The payer comes back here. The address proves nothing: ask the API about the payment YOU created for this order.
	mux.HandleFunc("GET /thanks", func(w http.ResponseWriter, r *http.Request) {
		value, found := orders.Load(strings.TrimPrefix(r.URL.Query().Get("reference"), "order-"))
		if !found {
			http.NotFound(w, r)
			return
		}
		known := value.(order)
		status, payment, err := rais("GET", "/payments/"+url.PathEscape(known.PaymentID), nil, nil)
		if err == nil && status == http.StatusOK && payment["status"] == "paid" && payment["amount"] == float64(known.Amount) {
			fmt.Fprint(w, "Thank you, we received your payment.")
			return
		}
		fmt.Fprint(w, "Payment not completed.")
	})

	// 3. Raïs calls this URL for every event. ReadAll returns the body exactly as it was signed.
	mux.HandleFunc("POST /webhooks/rais", func(w http.ResponseWriter, r *http.Request) {
		rawBody, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
		if err != nil || !VerifySignature(rawBody, r.Header.Get("Rais-Signature"), webhookSecret, 300*time.Second, time.Now()) {
			w.WriteHeader(http.StatusBadRequest)
			return
		}
		var event struct {
			ID   string `json:"id"`
			Type string `json:"type"`
			Data struct {
				Object struct {
					ID     string `json:"id"`
					Amount int    `json:"amount"`
				} `json:"object"`
			} `json:"data"`
		}
		if err := json.Unmarshal(rawBody, &event); err != nil {
			w.WriteHeader(http.StatusBadRequest)
			return
		}
		if strings.HasPrefix(event.ID, "evt_test_") {
			w.WriteHeader(http.StatusOK) // the dashboard's test event: never fulfil an order for it
			return
		}
		if _, seen := processed.LoadOrStore(event.ID, true); seen {
			w.WriteHeader(http.StatusOK) // delivered twice: nothing to do
			return
		}
		if event.Type == "payment.succeeded" {
			orders.Range(func(orderID, value any) bool {
				if known := value.(order); known.PaymentID == event.Data.Object.ID && known.Amount == event.Data.Object.Amount {
					log.Printf("Order %s is paid (%d centimes)", orderID, known.Amount)
				}
				return true
			})
		}
		w.WriteHeader(http.StatusOK) // answer quickly, do slow work afterwards
	})

	log.Println("Listening on http://localhost:3000")
	log.Fatal(http.ListenAndServe(":3000", mux))
}
```


Install the dependencies, set the two variables above and run it:


**Node.js**

~~~bash
npm install express
node server.mjs
~~~

**Python**

~~~bash
pip install flask requests
python app.py
~~~

**PHP**

~~~bash
php -S localhost:3000 index.php
~~~

**Go**

~~~bash
go run main.go
~~~


Open `http://localhost:3000`, press the button, pay with the test card, and watch your terminal print the paid order.

## Next steps


- [Webhooks](https://rais.app/docs/webhooks.md): events, retries, secret rotation and the verification code in every language.
- [Payments](https://rais.app/docs/payments.md): statuses, metadata, items, expiry and cancellation.
- [Going live](https://rais.app/docs/going-live.md): business verification and the checklist before real payments.

---

# Authentication

> Secret API keys, the test and live environments, scopes, rotation and IP allowlists.

Source: https://rais.app/docs/authentication

Every request to the API carries a **secret key** as a bearer token. A key belongs to one store and one environment, can be limited to some operations, and can be restricted to the addresses your servers use.

## Send the key


**Request**

```bash
curl https://api.rais.app/v1/account \
  -H "Authorization: Bearer rais_sk_test_..."
```


The header is `Authorization: Bearer <key>`. There are no other credentials: no client id, no signature, no session. If the key is missing or wrong, the answer is `401` with the code `invalid_api_key`.

## Key format

| Key | Environment |
| --- | --- |
| `rais_sk_test_` followed by 43 characters | Sandbox |
| `rais_sk_live_` followed by 43 characters | Live |

Raïs stores only a one-way hash of your key, so it cannot show the key again after you create it. Copy it into your secret manager when it appears. If you lose it, create a new one and revoke the old one. The dashboard lists keys by their prefix and last four characters.

## Test and live

The environment of a request is decided by the key and nothing else: there is no header or parameter to switch.

| | Sandbox key | Live key |
| --- | --- | --- |
| Payments | Test payments, `livemode: false` | Real payments, `livemode: true` |
| Cards | SATIM test cards only | Real CIB and Edahabia cards |
| Money | Never moves, no balance changes | Credited to your balance |
| Availability | Always | After business verification: the dashboard creates no live key before |

Sandbox and live data are separate worlds. A sandbox key never sees a live payment and the other way round: asking for one answers `404`.

## Scopes

A key carries one or more scopes. A request that needs a scope the key lacks answers `403` with `insufficient_scope`. New keys get every scope; give a key only what its job needs.

| Scope | Allows |
| --- | --- |
| `payments:read` | Retrieve and list payments and refunds, and fetch receipts |
| `payments:write` | Create and cancel payments |
| `refunds:write` | Refund payments |
| `events:read` | Retrieve and list events |

`GET /account` works with any valid key, whatever its scopes, which makes it the right call for checking a key.

## Create, roll and revoke keys

In the dashboard, open **Developers**, then **API keys**.

- **Create.** Choose the store and the environment (**Test** or **Live**; **Live** is offered for a store approved for live payments only), a name and the scopes, and optionally an IP allowlist. The secret is shown once. A key has no expiry date: it works until you roll or revoke it.
- **Roll.** Replace a key without downtime: the new key has the same store, environment, scopes and allowlist. The old key stops working at once, or after a grace period of **1 hour, 24 hours or 7 days** that gives you time to deploy the new key first; the dashboard shows until when the old key is valid, and after that it is expired and answers `401 invalid_api_key`. The new secret is shown once, like any new key.
- **Revoke.** The key stops working for good. A revoked key is refused on the server that handles the revocation immediately and everywhere else within 10 seconds.

A store can have up to 50 keys in each environment: revoke the ones you no longer use.


> [!TIP]
> **Roll keys on a schedule**
>
> Rolling with a grace period needs no maintenance window: deploy the new key, check your logs for the old key's prefix going quiet, then let the grace period end.


## IP allowlist

A key can be limited to up to 50 IP addresses or CIDR ranges, IPv4 or IPv6, for example `203.0.113.7` or `198.51.100.0/24`. A request from any other address is refused exactly like an unknown key: the answer does not say why. Use the public address your server connects from, which behind a NAT gateway is the gateway's address.

## One key, one store

A key can only read and change the payments, refunds and events of **its own store** in **its own environment**.


> [!NOTE]
> **What a 404 means**
>
> `payment_not_found`, `refund_not_found` and `event_not_found` are returned when the object does not exist, belongs to another store, or belongs to the other environment. The three cases are deliberately indistinguishable, so a key cannot be used to find out what exists elsewhere.


Refunds follow the same rule: a key can refund only payments of its own store and environment. If you run several stores, give each one its own keys.

## Authentication errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `invalid_api_key` | The key is missing, malformed, unknown, revoked or expired; it is used from an address outside its allowlist; or its store is suspended, disabled or, for a live key, not approved for live payments. The answer is the same in every case, so that a key cannot be used to learn anything. |
| 403 | `insufficient_scope` | The key lacks the scope this endpoint needs. |
| 403 | `account_disabled`, `live_mode_not_enabled` | Listed in the OpenAPI document, but the key check answers `401 invalid_api_key` before they can happen. Handle a `403` like any other refusal and contact support if it persists. See [Going live](https://rais.app/docs/going-live.md). |
| 429 | `rate_limit_exceeded` | Too many requests from this key, or more than 30 failed authentications in a minute from one address. While an address is throttled for failed authentications, every request from it answers `429`, even with a valid key. Wait for `Retry-After`. |

A `401` carries a `WWW-Authenticate: Bearer realm="Rais API"` header. See [Errors](https://rais.app/docs/errors.md) for the envelope.

## Keeping keys safe

- Keep keys on your server, in environment variables or a secret manager. Never in a web page, a mobile app, a repository, a log or a support ticket.
- The API sends no CORS headers: a browser cannot call it with a key, by design. Give your front end the `checkout_url` of a payment instead.
- Use a separate key for each service, with only the scopes it needs, and an allowlist when your servers have fixed addresses.
- If a key may have leaked, roll or revoke it first and investigate afterwards. See [Security and safety](https://rais.app/docs/security.md).

---

# Payments

> Create, retrieve, list and cancel payments: amounts, statuses, metadata, items and expiry.

Source: https://rais.app/docs/payments

A **payment** is one attempt to collect an amount from a payer. You create it on your server, redirect the payer to its hosted checkout, and follow it until it ends. This guide covers everything you can set and read; the exact schema of every endpoint is in the [API reference](https://rais.app/docs/api.md).

## Create a payment


**Request**

```bash
curl https://api.rais.app/v1/payments \
  -H "Authorization: Bearer rais_sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: b7e1c1c6-6f0a-4d2f-9d8b-3a5c2f1e7a90" \
  -d '{
  "amount": 500000,
  "description": "Order #1042",
  "reference": "order-1042",
  "success_url": "https://shop.example/thanks",
  "cancel_url": "https://shop.example/cart"
}'
```

**Response** (`201`)

~~~json
{
  "id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
  "object": "payment",
  "status": "pending",
  "amount": 500000,
  "currency": "DZD",
  "description": "Order #1042",
  "reference": "order-1042",
  "customer": {
    "id": null,
    "name": "Amina Benali",
    "email": "amina@example.dz",
    "phone": "+213550000000"
  },
  "items": [
    {
      "name": "Running shoes",
      "description": null,
      "quantity": 2,
      "unit_amount": 250000
    }
  ],
  "metadata": {
    "cart_id": "c_8812"
  },
  "livemode": false,
  "payment_page": "rais",
  "checkout_url": "https://pay.rais.app/pay/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
  "success_url": "https://shop.example/thanks",
  "cancel_url": "https://shop.example/cart",
  "expires_at": 1793003600,
  "created": 1793000000,
  "paid_at": null,
  "amount_refunded": 0,
  "refunded": false,
  "fees": null,
  "net": null,
  "receipt_url": null,
  "failure": null,
  "payment_method": null,
  "processor": {
    "name": "satim",
    "order_id": "V721uPPfNNofVQAAABL3",
    "approval_code": null,
    "response_code": null
  }
}
~~~


Redirect the payer to `checkout_url`. The payment is `pending` until they pay. The payer's page lives on `https://pay.rais.app` and the API on `https://api.rais.app`: you call the API from your server, and only ever send the payer to the page.

## Amounts

Amounts are **integers in centimes**: 1 DA is 100 centimes, so `500000` is 5,000.00 DA. A float (`5000.5`) or a string (`"5000"`) is refused with `invalid_amount`.

- The smallest payment is 5000 centimes (50.00 DA), SATIM's minimum. A smaller amount, zero and negative numbers included, answers `amount_too_small`.
- The largest is 999999999999 centimes. A larger amount answers `amount_too_large`.
- The only currency is `DZD`, which is also the default. Any other value answers `currency_not_supported`.

Always compute the amount on your server from your own prices. An amount that comes from the browser can be changed by the payer.

## Parameters


- `amount` (integer, required unless `items` is given): the amount in centimes. When you send both, they must agree, or the answer is `amount_mismatch`.
- `currency` (string, optional): `DZD`.
- `description` (string, optional, at most 512 characters): what the payment is for. The payer sees it on the checkout and SATIM receives it.
- `reference` (string, optional, at most 64 characters): your own identifier of the order. Returned as is, and searchable with `GET /payments?reference=`.
- `customer` (object, optional): who is paying. Once the payment is paid, Raïs links it to a customer record made from these details and fills in `customer.id`; it is `null` while the payment is pending. A card is kept under that record only if the payer chooses to save it: see [Saved cards](https://rais.app/docs/security.md#saved-cards).
  - `name` (string, at most 255 characters): the payer's full name.
  - `email` (string, at most 255 characters): their e-mail address. A malformed address answers `invalid_email`.
  - `phone` (string, at most 50 characters): their phone number.
- `customer_id` (string, optional): the id of one of **your** customers, one of the store the key belongs to (any other id answers `customer_not_found`). The customer's page in the dashboard shows it, and a paid payment returns it as `customer.id`. It fills in the payer's name and e-mail. On the Raïs payment page it also lets the payer choose to save their card for next time, and pay with a card they saved earlier: they pick it and confirm with 3-D Secure (the card and its security code are stored encrypted, for your store only). Saved cards are kept per mode: a sandbox payment never offers a live card, nor a live payment a sandbox one.
- `items` (array, optional, at most 50 lines): what is being bought, shown on the receipt.
  - `name` (string, required): what is being bought.
  - `description` (string, optional): more detail.
  - `quantity` (integer, required): 1 or more.
  - `unit_amount` (integer, required): the price of one unit, in centimes.
- `success_url` (string, optional): where the payer goes after paying. See [Hosted checkout and return URLs](https://rais.app/docs/checkout.md).
- `cancel_url` (string, optional): where the payer goes if they cancel or the payment fails.
- `metadata` (object, optional): up to 20 pairs of your own. Keys are at most 40 characters; values must be strings of at most 500 characters.
- `payment_page` (string, optional): `rais` for Raïs' hosted checkout or `satim` for SATIM's own page. Defaults to your store's setting.
- `language` (string, optional): `en`, `fr` or `ar`, the language of the checkout and of the receipt.
- `expires_in` (integer, optional): seconds the payment stays payable, from 300 to 2592000 (30 days). Defaults to 86400 (24 hours).


Any field of the JSON body that the API does not know is refused with `parameter_unknown`, which catches typos such as `ammount`. Unknown **query** parameters are ignored instead: `GET /payments?stauts=paid` returns every payment, so check the spelling of your filters.

### Items

When you describe the order with `items`, the amount can be left out: it is the sum of `quantity` times `unit_amount` over the lines. Items appear on the receipt, so give each line a clear name.


**Request**

```bash
curl https://api.rais.app/v1/payments \
  -H "Authorization: Bearer rais_sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "name": "Running shoes",
      "quantity": 2,
      "unit_amount": 250000
    },
    {
      "name": "Delivery",
      "quantity": 1,
      "unit_amount": 80000
    }
  ],
  "success_url": "myapp://pay/result",
  "language": "fr"
}'
```


The payment above is for 580,000 centimes, that is 5,800.00 DA.

### Reference and metadata

Use `reference` for the identifier you search by, and `metadata` for anything else you want back with the payment, such as a cart id. Both come back on the payment, in `GET` requests and in events. Do not put secrets in either of them: `reference` is also added to the address the payer is sent back to.

## Statuses

| Status | Meaning |
| --- | --- |
| `pending` | Created and waiting for the payer. The payer may try again on the same link until `expires_at`. This is the only status in which a payment can be paid or cancelled. |
| `paid` | The money was received. `paid_at`, `fees`, `net`, `payment_method` and `receipt_url` are set. |
| `failed` | The bank declined the card, or the payment ended in an error. `failure` has a `code` (`payment_declined`, `processing_error` or `gateway_unavailable`) and a `message` for you, not for the payer. |
| `cancelled` | You cancelled it while it was pending. |
| `expired` | Nobody paid before `expires_at`. No event is sent when a payment expires. |
| `partially_refunded` | Part of the amount was returned. `amount_refunded` says how much. |
| `refunded` | All of the amount was returned. |
| `reversed` | SATIM reversed the authorisation after the payment. |

`pending` leads to `paid`, `failed`, `cancelled` or `expired`. A `paid` payment can become `partially_refunded`, then `refunded`, or `reversed`. Money states only move forward. A payment that ended `failed` because the bank declined the card, `cancelled` or `expired` cannot be paid later: create a new one.

One rare exception: a payment that ended `failed` with `failure.code` `processing_error` can still turn `paid`, when the gateway answered with an error at the moment the payer came back although the card had been charged. Raïs keeps asking the gateway about such payments (see below), and when it confirms the charge you receive `payment.succeeded`. Treat `payment.succeeded` as the final word even if you saw `payment.failed` first.

A payment is `expired` as soon as `expires_at` has passed without payment, even before anything else touches it. Nothing is sent when that happens, so do not wait for an event: when the order matters, compare `expires_at` with the clock, or retrieve the payment. A payment created in the dashboard with the expiry "Never" has `expires_at: null` and is payable until you cancel it.

### A paid payment

When a payment is `paid`, it looks like this (the same object a `payment.succeeded` event carries):

~~~json
{
  "id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
  "object": "payment",
  "status": "paid",
  "amount": 500000,
  "currency": "DZD",
  "description": "Order #1042",
  "reference": "order-1042",
  "customer": {
    "id": "910158b6-8677-4d31-8779-919c4ea6428a",
    "name": "Amina Benali",
    "email": "amina@example.dz",
    "phone": "+213550000000"
  },
  "items": [
    {
      "name": "Running shoes",
      "description": null,
      "quantity": 2,
      "unit_amount": 250000
    }
  ],
  "metadata": {
    "cart_id": "c_8812"
  },
  "livemode": false,
  "payment_page": "rais",
  "checkout_url": "https://pay.rais.app/pay/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
  "success_url": "https://shop.example/thanks",
  "cancel_url": "https://shop.example/cart",
  "expires_at": 1793003600,
  "created": 1793000000,
  "paid_at": 1793000300,
  "amount_refunded": 0,
  "refunded": false,
  "fees": {
    "satim": 3500,
    "rais": 1500,
    "total": 5000
  },
  "net": 495000,
  "receipt_url": "https://pay.rais.app/pay/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33/receipt.pdf",
  "failure": null,
  "payment_method": {
    "type": "card",
    "brand": "dahabia",
    "last4": "7215",
    "masked": "628058**7215"
  },
  "processor": {
    "name": "satim",
    "order_id": "V721uPPfNNofVQAAABL3",
    "approval_code": "913180",
    "response_code": "00"
  }
}
~~~

`payment_method` shows the card scheme (`cib`, `dahabia` or `unknown`), the last four digits and a masked number, never more than the first six and last four digits. `processor` holds what SATIM knows: its order id, the approval code and the response code (`00` means approved).

### What a payment costs

A paid payment carries what it cost you and what you receive:

- `fees` has the `satim` part, the `rais` part and their `total`, in centimes, **excluding VAT**. It is `null` until the payment is `paid`: a payment that is pending, failed, expired or cancelled costs nothing.
- `net` is `amount` minus `fees.total`, before any refund: what you receive for this payment. In the example above, 500000 − 5000 = 495000 centimes (4,950.00 DA).
- The fees are set once, when the payment is paid, and are **not returned** when it is refunded, in full or in part: each refund has its own fee (see [Refunds](https://rais.app/docs/refunds.md)).
- A sandbox payment shows the **simulated** fees it would have cost in live: nothing is charged and no balance changes. The example above is a sandbox payment.
- A payment paid before fees were introduced has `fees: null` and `net: null`: nothing is charged afterwards for it.

The price list, when a fee is charged and worked examples are in [Pricing and fees](https://rais.app/docs/pricing.md).

### What the payer can do before it ends

While a payment is `pending`, the payer can leave the page, come back to the same `checkout_url` and try again, until `expires_at`. Closing the tab, pressing **Back to**, a mistyped card number or a SATIM form error do not change the status. The result page the payer lands on after an unsuccessful attempt offers a **Try again** button for as long as the payment can still be paid. A card refused by the bank is different: the payment becomes `failed` at once and its link no longer takes a payment.

### When the payer pays and never comes back

Some payers pay and close the tab before Raïs sees the result. Raïs does not leave such a payment `pending`: a background check asks the payment gateway about unpaid payments, the first time about 2 minutes after the gateway session was opened, then again after 5 minutes, 15 minutes, 1 hour, 6 hours and 24 hours (each wait counted from the previous check), and stops 48 hours after the session was opened. When the gateway says the payment was paid, the payment becomes `paid` and `payment.succeeded` is sent, **without the payer ever returning to your site**. Reading the payment through the API also asks the gateway (at most every 15 seconds).

So never rely on the browser redirect alone: confirm the payment with the webhook or with `GET /payments/{id}`. See [Hosted checkout and return URLs](https://rais.app/docs/checkout.md).

## Retrieve a payment


**Request**

```bash
curl https://api.rais.app/v1/payments/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33 \
  -H "Authorization: Bearer rais_sk_test_..."
```


If the payment is still `pending`, Raïs asks the gateway for the outcome (at most every 15 seconds), so a payer who comes back from the checkout always sees the truth, even if their browser never reached Raïs. Retrieving a payment is the right way to confirm a result. A payment of another store or of the other environment answers `404`.

## List payments


**Request**

```bash
curl 'https://api.rais.app/v1/payments?status=paid&limit=3' \
  -H "Authorization: Bearer rais_sk_test_..."
```


Payments come back newest first, 20 at a time by default. Filter by `status`, by your own `reference`, or by creation time with `created_gte` and `created_lte` (Unix seconds). `status=pending` leaves out the payments that are past `expires_at`: ask for `status=expired` to see those. Payment links created in the dashboard are payments like any other and are listed here too. See [Pagination](https://rais.app/docs/pagination.md).

## Cancel a payment

Cancel a payment that is no longer needed so that its checkout cannot be used.


**Request**

```bash
curl -X POST https://api.rais.app/v1/payments/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33/cancel \
  -H "Authorization: Bearer rais_sk_test_..."
```


Only a `pending` payment can be cancelled. Any other status answers `409` with `payment_not_cancellable`: a payment that is already `paid` has to be refunded instead. The same answer comes back while the payer is in the middle of a 3-D Secure step for that payment: try again in a moment. A successful cancellation emits a `payment.cancelled` event.

## Retrying safely

Send an `Idempotency-Key` with every payment you create. If a request times out and you send it again with the same key, you get the original payment back and nothing is created twice. See [Idempotency and retries](https://rais.app/docs/idempotency.md).

## What to read next


- [Hosted checkout and return URLs](https://rais.app/docs/checkout.md): the page your payer sees and where they go afterwards.
- [Webhooks](https://rais.app/docs/webhooks.md): learn the outcome without polling.
- [Refunds](https://rais.app/docs/refunds.md): return money for a paid payment.

---

# Pricing and fees

> What a payment and a refund cost, when a fee is charged, worked examples and the fee fields of the API.

Source: https://rais.app/docs/pricing

Raïs charges a fee on each **paid payment** and on each **refund**, and nothing else: no subscription, no setup fee, no fee on a payment that fails, and no fee on a withdrawal. Every figure on this page excludes VAT (HT, *hors taxes*). The public prices, with a calculator, are on the [pricing page](https://rais.app/pricing).

## The price list

|  | SATIM | Raïs | Total |
| --- | --- | --- | --- |
| A payment | 0.7% of the amount, never less than 10.00 DA and never more than 300.00 DA | 0.3% of the amount, with no minimum and no maximum, on top of SATIM's | Both added |
| A refund | 8.00 DA | 2.00 DA | 10.00 DA, whatever the amount |

A payment therefore costs about 1% of its amount for an ordinary amount: SATIM's 0.7% plus Raïs's 0.3%. SATIM's minimum makes the smallest payments cost more in proportion: the minimum payment, 50.00 DA, costs 10.15 DA.

## How a fee is worked out

Fees are whole centimes, worked out with integers (never floating point): a percentage is a number of basis points, and the share of an amount is `(amount × basis points + 5000) ÷ 10000`, a half rounded up. SATIM's part is 70 basis points, kept between 10.00 DA and 300.00 DA; Raïs's is 30 basis points. A fee never exceeds the amount it is taken from: SATIM's part is taken first.

## Examples

| Amount | SATIM | Raïs | Total fee | You receive |
| --- | --- | --- | --- | --- |
| 50.00 DA | 10.00 DA | 0.15 DA | 10.15 DA | 39.85 DA |
| 1,000.00 DA | 10.00 DA | 3.00 DA | 13.00 DA | 987.00 DA |
| 5,000.00 DA | 35.00 DA | 15.00 DA | 50.00 DA | 4,950.00 DA |
| 10,000.00 DA | 70.00 DA | 30.00 DA | 100.00 DA | 9,900.00 DA |
| 50,000.00 DA | 300.00 DA | 150.00 DA | 450.00 DA | 49,550.00 DA |
| 100,000.00 DA | 300.00 DA | 300.00 DA | 600.00 DA | 99,400.00 DA |
| 500,000.00 DA | 300.00 DA | 1,500.00 DA | 1,800.00 DA | 498,200.00 DA |

At 1,000.00 DA SATIM's minimum applies: 0.7% would be 7.00 DA, so SATIM's part is 10.00 DA. At 50,000.00 DA its maximum applies: 0.7% would be 350.00 DA, so SATIM's part is 300.00 DA, while Raïs's part keeps growing with the amount.

A refund costs 10.00 DA (8.00 DA for SATIM and 2.00 DA for Raïs) whether it refunds 1.00 DA or 50,000.00 DA.

## When a fee is charged

| What happens | What it costs |
| --- | --- |
| A payment is **paid** | Its fees are charged, once, when it is paid. They are set on the payment (`fees`, `net`) and, for a live payment, taken from your balance as a separate line of your ledger. |
| A payment **fails**, is declined, expires or is cancelled | Nothing. |
| A payment is **refunded**, in full or in part | The fees of the payment are **not returned**. The refund has its own fee. |
| A refund **succeeds** | Its fee, 10.00 DA, is charged. |
| A refund **fails** | Nothing. A refund that does not go through costs nothing. |
| A refund is **pending** (the gateway's answer was lost) | Its fee is reserved on your balance with its amount, and only charged if the refund goes through. |
| A **withdrawal** to your bank account | Nothing. |

## Fees in the API

A payment carries what it cost you and what you receive. `fees` is `null` until the payment is `paid`; `net` is `amount` minus `fees.total`, before any refund:

~~~json
{
  "id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
  "amount": 500000,
  "fees": {
    "satim": 3500,
    "rais": 1500,
    "total": 5000
  },
  "net": 495000
}
~~~

A refund carries its own `fees` once it has `succeeded` (`null` while it is `pending` and when it `failed`):

~~~json
{
  "id": "0c8a1d52-6e7b-4f0a-9b3d-7d2e4a8c5f10",
  "amount": 150000,
  "status": "succeeded",
  "fees": {
    "satim": 800,
    "rais": 200,
    "total": 1000
  }
}
~~~

| Field | Meaning |
| --- | --- |
| `fees.satim` | SATIM's part, in centimes, excluding VAT. |
| `fees.rais` | Raïs's part, in centimes, excluding VAT. |
| `fees.total` | `satim` + `rais`: what the payment or the refund costs. |
| `net` | On a payment: `amount` minus `fees.total`. What you receive for it, before any refund. |

The same objects travel in the events and the webhooks: a `payment.succeeded` event carries the payment with its `fees` and `net`, and a `refund.succeeded` event the refund with its `fees`. See [Webhooks](https://rais.app/docs/webhooks.md) and the [payment](https://rais.app/docs/api/objects/payment.md) and [refund](https://rais.app/docs/api/objects/refund.md) objects.

What you keep from a payment that was refunded is its `net`, minus the amount refunded, minus the `fees.total` of each refund that succeeded. For the payment above refunded by 1,500.00 DA: 4,950.00 DA − 1,500.00 DA − 10.00 DA = 3,440.00 DA.

## Your balance and refunds

A live payment is credited to your balance in full, and its fees are taken from the balance right after, so the balance moves by the payment's `net`. A live refund is taken from your balance with its fee: **the balance must cover the amount of the refund and its fee**, otherwise the answer is `insufficient_balance` ("The store's balance is not sufficient to cover this refund and its fee."). Because the fee of the payment is not returned, a store that has received a single payment can refund at most its balance minus 10.00 DA. See [Refunds](https://rais.app/docs/refunds.md#what-a-refund-costs).

## Test mode

The sandbox shows the same figures, marked as **simulated**: a paid sandbox payment has its `fees` and `net`, and a succeeded sandbox refund has its `fees`, exactly as in live. Nothing is charged, no balance changes and no ledger line is written. See [Test cards and sandbox](https://rais.app/docs/testing.md).

## Payments from before fees

A payment paid before fees were introduced has `fees: null` and `net: null`: nothing is charged afterwards for it, and the dashboard shows no fee for it.

## What is not included

Every price excludes VAT: the amounts in `fees` are the HT prices above. The price list is versioned (`2026-10`): the fees of a payment are fixed when it is paid, with the price list of that day.

---

# Hosted checkout and return URLs

> Send the payer to the hosted page, bring them back to your site or app, and confirm the result on your server.

Source: https://rais.app/docs/checkout

When you create a payment, Raïs returns a `checkout_url`. That address is a hosted payment page: you never handle card details. This guide describes what the payer sees, where they go afterwards and how to confirm the result.

## Where the page lives

The payer's pages live on `https://pay.rais.app`: `checkout_url` is `https://pay.rais.app/pay/{payment_id}`, and the `receipt_url` of a paid payment is `https://pay.rais.app/pay/{payment_id}/receipt.pdf`. The API lives on `https://api.rais.app` (every endpoint is under `https://api.rais.app/v1`): call it from your server, never from the payer's browser.

Use the `checkout_url` you are given as it is, and do not build it yourself. If your site or your app restricts where it may redirect, or which hosts an in-app browser may open, allow `https://pay.rais.app`.

## The hosted page

Redirect the payer to `checkout_url` with a normal HTTP redirect (status 303 after a POST) or a link. The page:

- shows your store name and logo (upload the logo in the dashboard, under the store's **Settings**; a store without one shows its initial), the amount with commas between the thousands and a dot before the decimals (`5,000.00 DA`), the description and your reference;
- is available in English, French and Arabic, with right-to-left layout for Arabic. Set the language with `language` when you create the payment;
- collects the card number, expiry, CVC and name, then runs 3-D Secure through SATIM;
- lets the payer leave through a **Back to** link that returns to your `cancel_url`;
- marks a sandbox payment with a "Test mode" banner. It never lists test cards (they are in [Test cards and sandbox](https://rais.app/docs/testing.md)), and a live payment never shows any test wording.

The page sets a strict content security policy and forbids being framed: it cannot be embedded in an `<iframe>`. Redirect the payer, or open the page in a browser tab or a secure in-app browser. See [Mobile and app integrations](https://rais.app/docs/mobile.md).

### Raïs page or SATIM page

`payment_page` chooses where the card is entered. `rais` is Raïs' own checkout, described above. `satim` sends the payer to SATIM's payment page; they come back to a Raïs result page that shows the outcome. Return URLs and parameters work the same way for both. When you omit it, your store's default applies.

## Return URLs

`success_url` and `cancel_url` say where the payer goes when they leave the checkout. Set them on each payment; a payment without them uses the defaults of your store, and with neither, the result page tells the payer they can close it.

| URL | Used when |
| --- | --- |
| `success_url` | The payment was paid. |
| `cancel_url` | The payment failed, was cancelled, or the payer pressed **Back to**. |

An address is accepted when it:

- starts with `https://`, in both environments, or `http://`, in the **sandbox only**;
- or uses your **own app scheme**, such as `myapp://pay/result`, in both environments (a scheme of 2 to 31 characters: letters, digits, `+`, `.` and `-`);
- has at most 512 characters, no spaces, no non-ASCII characters (percent-encode them), no backslashes and no credentials (`user:password@host`).

`javascript:`, `data:`, `file:`, `vbscript:`, `blob:`, `about:` and `ftp:` are never accepted. An invalid address answers `invalid_url` with the parameter name.

### What Raïs adds to the address

Raïs **merges** four parameters into your address and keeps everything else as you wrote it: your own query parameters, a fragment, and a custom scheme.

| Parameter | Value |
| --- | --- |
| `payment_id` | The id of the payment. |
| `status` | `paid`, `failed` or `cancelled`: what the payer's browser saw. `failed` does not always close the payment (see below). Never trust it on its own. |
| `reference` | Your `reference`, only when the payment has one. |
| `order_number` | The Raïs order number of the payer's attempt. Each new attempt on the same payment gets a new one: identify the payment with `payment_id`. |

A parameter of yours with one of these names is replaced, so an address cannot pre-fill the result.

Raïs also adds `lang` (`en`, `fr` or `ar`), the language the payer used on the checkout, so your page can keep it, unless your address already has a `lang` of its own. A payer who picked the light or dark theme on the checkout is sent back with `theme=light` or `theme=dark` too (on the **Return to** and **Back to** links, never when the theme is on Auto). Both are only a convenience for your page and say nothing about the payment.

| You set | The payer is sent to |
| --- | --- |
| `https://shop.example/thanks` | `https://shop.example/thanks?payment_id=5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33&status=paid&reference=order-1042&order_number=RS12AB34CD` |
| `https://shop.example/thanks?cart=7#top` | `https://shop.example/thanks?cart=7&payment_id=5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33&status=paid&reference=order-1042&order_number=RS12AB34CD#top` |
| `myapp://pay/result?x=1` | `myapp://pay/result?x=1&payment_id=5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33&status=paid&reference=order-1042&order_number=RS12AB34CD` |

The older `orderId` parameter is no longer sent.

### `status=failed` does not always end the payment

`status` describes what the payer's browser saw. A payer who leaves the card form, or whose attempt did not go through, comes back with `status=failed` (or `cancelled` after pressing **Back to**) although the payment is still `pending`: they can open the payment page again, press **Try again** and pay a minute later. So do not cancel your order because of the address. Wait for the `payment.failed` or `payment.cancelled` event, for `expires_at`, or retrieve the payment and look at its `status`.

## What the payer sees afterwards

Whatever the outcome, the payer first lands on a Raïs result page in the language of the payment, and **stays on it**: the page never sends the payer anywhere by itself, so they can read the details of the payment. A button leads back to your site.

| Outcome | Behaviour |
| --- | --- |
| Paid, with a return URL | The page shows the payment details (including the **Raïs order ID**, never the name on the card) and a button labelled **Return to** your store name. There is no automatic redirect and no countdown. |
| Paid, without a return URL | The page says the payer can close it. |
| Failed or cancelled | The page shows what happened, with no order ID. A **Try again** button leads back to the payment page for as long as the payment can still be paid, and a **Return to** button leads to your `cancel_url` when there is one. |
| Opened again later | A paid payment shows its paid page again. A refunded one shows "Payment refunded". An expired one shows an expired page. |

A paid result page shows the payment method as **CIB/Edahabia** and never a card number. It also offers **Download receipt (PDF)**, and on one row **Print** and **Email receipt**: the receipt goes to the payer's e-mail address when the payment has one, otherwise the payer types one; a receipt is e-mailed once per payment. See [Receipts](https://rais.app/docs/receipts.md).

## Never trust the redirect

The address the payer returns to can be opened by anybody, and the parameters in it can be typed by hand. `status=paid` proves nothing. And the redirect may never happen: a payer who pays and closes the tab never reaches your site, and Raïs still settles the payment in the background and sends `payment.succeeded` (see [Payments](https://rais.app/docs/payments.md#when-the-payer-pays-and-never-comes-back)). Before you ship anything, confirm the payment from your server, with one of these:

1. **The webhook.** A signed `payment.succeeded` event is the best trigger. See [Webhooks](https://rais.app/docs/webhooks.md).
2. **The API.** Retrieve the payment by the `payment_id` you stored when you created it, and check `status`, `amount` and `reference` against your order.

~~~javascript
// GET /thanks?payment_id=...&status=paid
const stored = await db.orders.findByPaymentId(req.query.payment_id); // the id you saved at creation
const response = await fetch(`https://api.rais.app/v1/payments/${stored.paymentId}`, {
  headers: { Authorization: `Bearer ${process.env.RAIS_SECRET_KEY}` },
});
const payment = await response.json();

if (payment.status === "paid" && payment.amount === stored.amount) {
  // fulfil the order, once
}
~~~

Use the id you saved, not the one in the address, and make fulfilment idempotent: the webhook and the return page may both arrive.


> [!TIP]
> **Pending is not failure**
>
> If the payer is back before the result reached you, `status` can still be `pending`. Show a "we are confirming your payment" page and wait for the webhook rather than treating it as a failure.


## Expired and unavailable payments

A payment that passed `expires_at` unpaid, was cancelled, or was declined by the bank opens a page that says it can no longer be paid (with a **Contact the merchant** button), and cannot be paid. A payment of a suspended store shows an unavailable page. In every case, create a new payment when the payer wants to try again.

A payment link stays payable until its own `expires_at`, however long the payer takes: if the gateway's own payment session ran out meanwhile, the checkout opens a new one by itself when the payer starts paying. A payment without an expiry, such as a link created in the dashboard with "Never", is never closed because of its age.

---

# Mobile and app integrations

> iOS, Android, Flutter and React Native: open the checkout in a secure in-app browser and return with a deep link.

Source: https://rais.app/docs/mobile

A mobile app takes payments the same way a website does: your **server** creates the payment, and the app opens the `checkout_url` in a secure browser and comes back through a deep link. The app never talks to the Raïs API and never holds a key.


> [!CAUTION]
> **Never ship a secret key in an app**
>
> Anything inside an app can be extracted: strings in the binary, network traffic, a rooted device. A secret key in an app lets anybody create payments and refunds in your name. Create payments on your server only.


## The flow

1. The app asks **your server** to start a payment for an order or a cart.
2. Your server computes the amount, creates the payment with Raïs (see [Payments](https://rais.app/docs/payments.md)) using your secret key, stores the payment id with the order, and returns the `checkout_url` to the app.
3. The app opens `checkout_url` in a system browser session. The payer enters their card and confirms with 3-D Secure.
4. Raïs sends the payer to your `success_url` or `cancel_url`, which is a deep link into your app, with `payment_id` and `status` added.
5. The app **asks your server** for the real status of the order. Your server knows the answer from the signed webhook or by retrieving the payment.

## Return with a deep link

Set `success_url` and `cancel_url` to an address on your own app scheme. Raïs accepts any custom scheme in both environments and keeps it exactly as you wrote it, adding the result parameters:

```
myapp://pay/result?payment_id=5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33&status=paid&reference=order-1042&order_number=RS12AB34CD
```


**Request**

```bash
curl https://api.rais.app/v1/payments \
  -H "Authorization: Bearer rais_sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 500000,
  "reference": "order-1042",
  "success_url": "myapp://pay/result",
  "cancel_url": "myapp://pay/cancelled",
  "language": "fr"
}'
```


After a successful payment the result page stays on screen, so the payer can read the details, and its **Return to** button opens the deep link. The page does not redirect by itself. If you prefer https links that open your app (universal links on iOS, app links on Android), use an https address that your site redirects to the app.

## Open the checkout

Use the secure browser of the platform, not a plain `WebView`. It shares the system's security features, shows the address to the payer and handles 3-D Secure pages the way banks expect.


**iOS (Swift)**

Use `ASWebAuthenticationSession`. It opens a secure sheet and returns to your app when the browser navigates to your scheme.

~~~swift
import AuthenticationServices

final class CheckoutPresenter: NSObject, ASWebAuthenticationPresentationContextProviding {
    private var session: ASWebAuthenticationSession?

    /// checkoutURL comes from YOUR server, which created the payment.
    func pay(checkoutURL: URL, completion: @escaping (_ paymentId: String?) -> Void) {
        let session = ASWebAuthenticationSession(url: checkoutURL, callbackURLScheme: "myapp") { callbackURL, _ in
            guard let callbackURL,
                  let items = URLComponents(url: callbackURL, resolvingAgainstBaseURL: false)?.queryItems else {
                completion(nil) // the payer closed the sheet
                return
            }
            completion(items.first { $0.name == "payment_id" }?.value)
        }
        session.presentationContextProvider = self
        session.start()
        self.session = session
    }

    func presentationAnchor(for session: ASWebAuthenticationSession) -> ASPresentationAnchor {
        UIApplication.shared.connectedScenes
            .compactMap { ($0 as? UIWindowScene)?.keyWindow }
            .first ?? ASPresentationAnchor()
    }
}
~~~

**Android (Kotlin)**

Use Chrome Custom Tabs from `androidx.browser:browser`, and an activity that receives your scheme.

~~~kotlin
import android.content.Context
import android.net.Uri
import androidx.browser.customtabs.CustomTabsIntent

fun openCheckout(context: Context, checkoutUrl: String) {
    CustomTabsIntent.Builder().build().launchUrl(context, Uri.parse(checkoutUrl))
}
~~~

~~~xml
<activity android:name=".PaymentResultActivity" android:exported="true" android:launchMode="singleTask">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="myapp" android:host="pay" />
    </intent-filter>
</activity>
~~~

~~~kotlin
import android.content.Intent
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity

class PaymentResultActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        handle(intent)
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        handle(intent)
    }

    private fun handle(intent: Intent) {
        val paymentId = intent.data?.getQueryParameter("payment_id") ?: return
        // Ask YOUR server for the real status. Never trust ?status= from the link.
        confirmWithServer(paymentId)
    }

    private fun confirmWithServer(paymentId: String) { /* call your API */ }
}
~~~

**Flutter**

Use `flutter_web_auth_2`, which wraps `ASWebAuthenticationSession` and Custom Tabs. Follow its Android setup for the callback activity of your scheme.

~~~dart
import 'package:flutter/services.dart';
import 'package:flutter_web_auth_2/flutter_web_auth_2.dart';

/// checkoutUrl comes from YOUR server, which created the payment.
Future<String?> payWithRais(String checkoutUrl) async {
  try {
    final result = await FlutterWebAuth2.authenticate(
      url: checkoutUrl,
      callbackUrlScheme: 'myapp',
    );
    return Uri.parse(result).queryParameters['payment_id'];
  } on PlatformException {
    return null; // the payer closed the browser
  }
}
~~~

**React Native**

With Expo, `expo-web-browser` opens the right secure browser on each platform and `expo-linking` reads the result. In a bare React Native app, `react-native-inappbrowser-reborn` offers `InAppBrowser.openAuth` with the same shape.

~~~typescript
import * as Linking from "expo-linking";
import * as WebBrowser from "expo-web-browser";

// checkoutUrl comes from YOUR server, which created the payment.
export async function payWithRais(checkoutUrl: string): Promise<string | null> {
  const redirectUrl = Linking.createURL("pay/result"); // myapp://pay/result in a built app
  const result = await WebBrowser.openAuthSessionAsync(checkoutUrl, redirectUrl);
  if (result.type !== "success") return null; // the payer closed the browser

  const { queryParams } = Linking.parse(result.url);
  return typeof queryParams?.payment_id === "string" ? queryParams.payment_id : null;
}
~~~


## The server side of the app

Your server owns the amount, the keys and the confirmation. A minimal version has two endpoints: one that starts the payment and one that tells the app the status of an order.

~~~javascript
// POST /api/checkout  (authenticated by your own login)
const order = await orders.createFor(req.user, req.body.cartId); // the amount is computed here
const response = await fetch("https://api.rais.app/v1/payments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RAIS_SECRET_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `order-${order.id}`,
  },
  body: JSON.stringify({
    amount: order.amount,
    reference: `order-${order.id}`,
    success_url: "myapp://pay/result",
    cancel_url: "myapp://pay/cancelled",
  }),
});
const payment = await response.json();
await orders.attachPayment(order.id, payment.id);
res.json({ checkoutUrl: payment.checkout_url });

// GET /api/orders/:id/status  (what the app asks after the deep link or when it comes back)
// Answer from your database, which the signed webhook updates. If the order is still pending, retrieve the payment.
~~~

## Handle every ending

- **Success deep link.** Treat `status=paid` as a hint to refresh. Ask your server; show the order as paid only when it says so.
- **Cancel deep link.** The payer pressed **Back to**, or the attempt did not go through. The payment may still be `pending`: let them try again by reopening the same `checkout_url` until `expires_at`, and create a new payment when it is no longer `pending`.
- **The payer closes the browser.** You get no deep link. When the app comes back to the foreground, ask your server for the status of the order: the payment may have succeeded.
- **The app is killed during payment.** The webhook still reaches your server. When the app restarts, show the current status of the order.

## Checklist

- No Raïs key, and no key-like string, anywhere in the app.
- The amount is computed on your server, never sent by the app.
- The deep link carries no authority: the order is confirmed by your server, not by `?status=paid`.
- The app handles a closed browser and a killed process.
- You tested with sandbox keys and the [test cards](https://rais.app/docs/testing.md). The sandbox accepts `http://` return addresses for local servers; live payments need `https://` or your app scheme.

---

# Webhooks

> Receive signed events, verify them, handle retries and keep your endpoint healthy.

Source: https://rais.app/docs/webhooks

A **webhook** is an HTTP request that Raïs sends to your server when something happens to a payment or a refund. Use webhooks as your source of truth for results: they arrive even when the payer closes the browser before returning to your site.

Every webhook is **signed**, delivered **at least once**, and retried for about 20 hours if your server does not answer with a success status.

## Set up an endpoint

In the dashboard, open **Developers**, then **Webhooks**, and add an endpoint:

- **URL.** Where Raïs sends events. It must be `https://` for a live endpoint; a sandbox endpoint may use `http://`. It cannot contain a user name or password, and it must resolve to a public address: `localhost`, private networks and the like are refused. For a server on your computer, use a tunnel.
- **Events.** **All events** (including the ones added later) or **Selected events**, such as `payment.succeeded` only.
- **Store and environment.** Chosen in the dialog: the store, then **Test** or **Live** (**Live** is offered for a store approved for live payments only). A test endpoint receives only test events, a live endpoint only live ones.

A store can have up to 20 endpoints in each environment.

The dashboard shows the endpoint's **signing secret**, which starts with `whsec_`. You need it to verify signatures. Treat it like a password.

## Event types

| Type | Sent when |
| --- | --- |
| `payment.succeeded` | The payer paid. `data.object` is the payment with `status: "paid"`, its `fees` and its `net`. |
| `payment.failed` | The bank declined the card (`failure.code: payment_declined`), or the payment ended in an error. A decline is final: that payment is never paid afterwards, the payer needs a new payment. |
| `payment.cancelled` | You cancelled a pending payment (`POST /payments/{id}/cancel`). |
| `payment.reversed` | SATIM reversed an authorisation after the payment. Treat the money as returned. |
| `refund.succeeded` | A refund went through. `data.object` is the refund, with its `fees`. |
| `refund.failed` | The bank refused a refund. `data.object` is the refund with its `failure`. |

New event types may be added over time. Ignore the ones you do not handle, but still answer them with a `2xx` status.

Two things are not events. Nothing is sent when a payment **expires**: it simply reads as `expired` once `expires_at` has passed, so keep your own timer or retrieve the payment. And a payment can send `payment.failed` and, rarely, `payment.succeeded` afterwards, when the gateway later confirms a charge it first reported as an error: act on the latest event, or retrieve the payment.

## The event

The body is a JSON object, the same one the [events API](https://rais.app/docs/api/retrieve-event.md) returns. `data.object` is the complete payment or refund as it was when the event happened.

~~~json
{
  "id": "evt_Qm9dMhJ0k8s2Wv7Yc3XnLpAb",
  "object": "event",
  "api_version": "2026-10-26",
  "created": 1793000300,
  "livemode": false,
  "type": "payment.succeeded",
  "data": {
    "object": {
      "id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
      "object": "payment",
      "status": "paid",
      "amount": 500000,
      "currency": "DZD",
      "description": "Order #1042",
      "reference": "order-1042",
      "customer": {
        "id": "910158b6-8677-4d31-8779-919c4ea6428a",
        "name": "Amina Benali",
        "email": "amina@example.dz",
        "phone": "+213550000000"
      },
      "items": [
        {
          "name": "Running shoes",
          "description": null,
          "quantity": 2,
          "unit_amount": 250000
        }
      ],
      "metadata": {
        "cart_id": "c_8812"
      },
      "livemode": false,
      "payment_page": "rais",
      "checkout_url": "https://pay.rais.app/pay/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
      "success_url": "https://shop.example/thanks",
      "cancel_url": "https://shop.example/cart",
      "expires_at": 1793003600,
      "created": 1793000000,
      "paid_at": 1793000300,
      "amount_refunded": 0,
      "refunded": false,
      "fees": {
        "satim": 3500,
        "rais": 1500,
        "total": 5000
      },
      "net": 495000,
      "receipt_url": "https://pay.rais.app/pay/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33/receipt.pdf",
      "failure": null,
      "payment_method": {
        "type": "card",
        "brand": "dahabia",
        "last4": "7215",
        "masked": "628058**7215"
      },
      "processor": {
        "name": "satim",
        "order_id": "V721uPPfNNofVQAAABL3",
        "approval_code": "913180",
        "response_code": "00"
      }
    }
  }
}
~~~


- `id` (string): the unique id of the event, starting with `evt_`. It never changes across retries: use it to de-duplicate.
- `object` (string): always `event`.
- `api_version` (string): the API version the payload is rendered with.
- `created` (integer): when the event happened, in Unix seconds.
- `livemode` (boolean): `false` for a sandbox event.
- `type` (string): what happened. See the table above.
- `data.object` (object): the [payment](https://rais.app/docs/api/objects/payment.md) or [refund](https://rais.app/docs/api/objects/refund.md) the event is about.


In a `payment.succeeded` event, `data.object.receipt_url` is the payer's PDF receipt: a link that works in any browser without a key. See [Receipts](https://rais.app/docs/receipts.md). `data.object.fees` and `data.object.net` say what the payment cost you and what you receive (see [Pricing and fees](https://rais.app/docs/pricing.md)); an event of a sandbox payment carries the simulated fees.

A `refund.succeeded` event carries the refund with its own `fees`, a flat fee whatever the amount (`fees` is `null` in a `refund.failed` event: a refund that failed costs nothing):

~~~json
{
  "id": "evt_Rt4kVx2Zq8Hn5Lw0Yc7PbMdE",
  "object": "event",
  "api_version": "2026-10-26",
  "created": 1793000900,
  "livemode": false,
  "type": "refund.succeeded",
  "data": {
    "object": {
      "id": "0c8a1d52-6e7b-4f0a-9b3d-7d2e4a8c5f10",
      "object": "refund",
      "payment_id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
      "amount": 150000,
      "currency": "DZD",
      "status": "succeeded",
      "reason": "Customer returned one item",
      "failure": null,
      "fees": {
        "satim": 800,
        "rais": 200,
        "total": 1000
      },
      "livemode": false,
      "created": 1793000900
    }
  }
}
~~~

The body is compact JSON and pure ASCII: a character such as `é` arrives as `\u00e9`. This matters for the signature, which covers the exact bytes.

## Headers

```http
POST /webhooks/rais HTTP/1.1
Content-Type: application/json
User-Agent: Rais-Webhooks/1
Rais-Signature: t=1700000000,v1=ddb9f8a187313afb17555011222152be4f076bf39218f86a28f0a93714651a6c
Rais-Event-Id: evt_Qm9dMhJ0k8s2Wv7Yc3XnLpAb
Rais-Delivery-Id: 3f6e2d10-5a4b-4c7e-8d21-9b0c1e2f3a44
Rais-Attempt: 1
Rais-Livemode: false
```

| Header | Value |
| --- | --- |
| `Rais-Signature` | The signature: `t=<unix seconds>,v1=<hex>`. See below. |
| `Rais-Event-Id` | The id of the event. Stable across retries and resends: de-duplicate on it. |
| `Rais-Delivery-Id` | The id of this delivery. The same on every retry of it. |
| `Rais-Attempt` | `1` for the first attempt, `2` for the first retry, and so on. |
| `Rais-Livemode` | `true` or `false`. |

## Verify the signature

Anyone who knows your endpoint address can send it a request. The signature proves that a request comes from Raïs and was not changed on the way. **Verify it before you do anything else.**

The header looks like `t=1700000000,v1=ddb9...`. To verify it:

1. Take the timestamp `t` and every `v1` value from the header.
2. Compute the **HMAC-SHA256**, as lowercase hex, of the text `t`, a dot, and the **raw request body**, with your signing secret (the complete `whsec_...` string) as the key.
3. Compare the result with each `v1` value in **constant time**. One match is enough.
4. Reject the request when `t` is more than 300 seconds away from your clock, in either direction. This stops an attacker from replaying a captured request later.

~~~text
signed_payload = t + "." + raw_body
v1             = hex(HMAC_SHA256(key = signing secret, message = signed_payload))
~~~


> [!WARNING]
> **Sign the raw body, not parsed JSON**
>
> The signature covers the exact bytes Raïs sent. If your framework parses the JSON first and you serialise it again, spacing and key order change and the signature no longer matches. Read the body as bytes, verify, and only then parse it.


Each retry is signed again with a fresh timestamp, so a retry never fails the tolerance check because of its age.


**Verify a Rais-Signature header**

**Node.js**

```javascript
import { createHmac, timingSafeEqual } from "node:crypto";

/**
 * rawBody: the request body exactly as received (Buffer or string), never re-serialised JSON.
 * header:  the value of the Rais-Signature header.
 */
export function verifySignature(rawBody, header, secret, toleranceSeconds = 300, now = Math.floor(Date.now() / 1000)) {
  const pairs = header.split(",").map((part) => part.trim().split("="));
  const timestamp = pairs.find(([key]) => key === "t")?.[1];
  const signatures = pairs.filter(([key]) => key === "v1").map(([, value]) => value);
  if (!/^\d+$/.test(timestamp ?? "") || signatures.length === 0) return false;
  if (Math.abs(now - Number(timestamp)) > toleranceSeconds) return false;

  const expected = createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest();
  return signatures.some((signature) => {
    const received = Buffer.from(signature, "hex");
    return received.length === expected.length && timingSafeEqual(received, expected);
  });
}

// Check it against the official test vector: this prints true.
const body = "{\"id\":\"evt_test_000000000000000000\",\"object\":\"event\",\"api_version\":\"2026-10-26\",\"created\":1700000000,\"livemode\":false,\"type\":\"payment.succeeded\",\"data\":{\"object\":{\"id\":\"pay_test_000000000000\",\"object\":\"payment\",\"amount\":150000,\"currency\":\"DZD\",\"status\":\"succeeded\"}}}";
console.log(verifySignature(body, "t=1700000000,v1=ddb9f8a187313afb17555011222152be4f076bf39218f86a28f0a93714651a6c", "whsec_test_not_a_real_secret", 300, 1700000000));
```

**Python**

```python
import hashlib
import hmac
import time


def verify_signature(raw_body, header, secret, tolerance=300, now=None):
    """raw_body: the request body exactly as received (bytes). header: the Rais-Signature header."""
    timestamp, signatures = None, []
    for part in header.split(","):
        key, _, value = part.strip().partition("=")
        if key == "t":
            timestamp = value
        elif key == "v1":
            signatures.append(value)
    if timestamp is None or not timestamp.isascii() or not timestamp.isdigit() or not signatures:
        return False
    if abs((time.time() if now is None else now) - int(timestamp)) > tolerance:
        return False

    signed = timestamp.encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest().encode()
    return any(hmac.compare_digest(expected, signature.lower().encode()) for signature in signatures)


# Check it against the official test vector: this prints True.
body = b'{"id":"evt_test_000000000000000000","object":"event","api_version":"2026-10-26","created":1700000000,"livemode":false,"type":"payment.succeeded","data":{"object":{"id":"pay_test_000000000000","object":"payment","amount":150000,"currency":"DZD","status":"succeeded"}}}'
print(verify_signature(body, "t=1700000000,v1=ddb9f8a187313afb17555011222152be4f076bf39218f86a28f0a93714651a6c", "whsec_test_not_a_real_secret", 300, 1700000000))
```

**PHP**

```php
<?php

function verifySignature(string $rawBody, string $header, string $secret, int $tolerance = 300, ?int $now = null): bool
{
    $timestamp = null;
    $signatures = [];
    foreach (explode(',', $header) as $part) {
        [$key, $value] = array_pad(explode('=', trim($part), 2), 2, '');
        if ($key === 't') {
            $timestamp = $value;
        } elseif ($key === 'v1') {
            $signatures[] = $value;
        }
    }
    if ($timestamp === null || !ctype_digit($timestamp) || $signatures === []) {
        return false;
    }
    if (abs(($now ?? time()) - (int) $timestamp) > $tolerance) {
        return false;
    }

    $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
    $valid = false;
    foreach ($signatures as $signature) {
        $valid = hash_equals($expected, strtolower($signature)) || $valid;
    }
    return $valid;
}

// Check it against the official test vector: this prints bool(true).
$body = '{"id":"evt_test_000000000000000000","object":"event","api_version":"2026-10-26","created":1700000000,"livemode":false,"type":"payment.succeeded","data":{"object":{"id":"pay_test_000000000000","object":"payment","amount":150000,"currency":"DZD","status":"succeeded"}}}';
var_dump(verifySignature($body, 't=1700000000,v1=ddb9f8a187313afb17555011222152be4f076bf39218f86a28f0a93714651a6c', 'whsec_test_not_a_real_secret', 300, 1700000000));
```

**Go**

```go
package main

import (
	"fmt"
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"math"
	"strconv"
	"strings"
	"time"
)

// VerifySignature checks a Rais-Signature header against the raw request body.
func VerifySignature(rawBody []byte, header, secret string, tolerance time.Duration, now time.Time) bool {
	var timestamp string
	var signatures []string
	for _, part := range strings.Split(header, ",") {
		key, value, _ := strings.Cut(strings.TrimSpace(part), "=")
		switch key {
		case "t":
			timestamp = value
		case "v1":
			signatures = append(signatures, value)
		}
	}
	if timestamp == "" || strings.Trim(timestamp, "0123456789") != "" || len(signatures) == 0 {
		return false
	}
	seconds, err := strconv.ParseInt(timestamp, 10, 64)
	if err != nil || math.Abs(float64(now.Unix()-seconds)) > tolerance.Seconds() {
		return false
	}

	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(timestamp + "."))
	mac.Write(rawBody)
	expected := mac.Sum(nil)

	valid := false
	for _, signature := range signatures {
		if received, err := hex.DecodeString(signature); err == nil && hmac.Equal(received, expected) {
			valid = true
		}
	}
	return valid
}

func main() {
	// Check it against the official test vector: this prints true.
	body := []byte(`{"id":"evt_test_000000000000000000","object":"event","api_version":"2026-10-26","created":1700000000,"livemode":false,"type":"payment.succeeded","data":{"object":{"id":"pay_test_000000000000","object":"payment","amount":150000,"currency":"DZD","status":"succeeded"}}}`)
	now := time.Unix(1700000000, 0)
	fmt.Println(VerifySignature(body, "t=1700000000,v1=ddb9f8a187313afb17555011222152be4f076bf39218f86a28f0a93714651a6c", "whsec_test_not_a_real_secret", 300*time.Second, now))
}
```

**Java**

```java
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.ArrayList;
import java.util.List;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class RaisSignature {
    public static boolean verify(byte[] rawBody, String header, String secret, long toleranceSeconds, long nowSeconds)
            throws Exception {
        String timestamp = null;
        List<String> signatures = new ArrayList<>();
        for (String part : header.split(",")) {
            String[] pair = part.trim().split("=", 2);
            if (pair.length != 2) continue;
            if (pair[0].equals("t")) timestamp = pair[1];
            else if (pair[0].equals("v1")) signatures.add(pair[1]);
        }
        if (timestamp == null || !timestamp.matches("[0-9]{1,18}") || signatures.isEmpty()) return false;
        if (Math.abs(nowSeconds - Long.parseLong(timestamp)) > toleranceSeconds) return false;

        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        mac.update((timestamp + ".").getBytes(StandardCharsets.US_ASCII));
        StringBuilder expected = new StringBuilder();
        for (byte b : mac.doFinal(rawBody)) expected.append(String.format("%02x", b));

        boolean valid = false;
        for (String signature : signatures) {
            valid |= MessageDigest.isEqual(
                expected.toString().getBytes(StandardCharsets.US_ASCII),
                signature.toLowerCase().getBytes(StandardCharsets.US_ASCII));
        }
        return valid;
    }

    public static void main(String[] args) throws Exception {
        // Check it against the official test vector: this prints true.
        String body = "{\"id\":\"evt_test_000000000000000000\",\"object\":\"event\",\"api_version\":\"2026-10-26\",\"created\":1700000000,\"livemode\":false,\"type\":\"payment.succeeded\",\"data\":{\"object\":{\"id\":\"pay_test_000000000000\",\"object\":\"payment\",\"amount\":150000,\"currency\":\"DZD\",\"status\":\"succeeded\"}}}";
        System.out.println(verify(body.getBytes(StandardCharsets.UTF_8), "t=1700000000,v1=ddb9f8a187313afb17555011222152be4f076bf39218f86a28f0a93714651a6c", "whsec_test_not_a_real_secret", 300, 1700000000L));
    }
}
```

**C#**

```csharp
using System.Security.Cryptography;
using System.Text;

static bool VerifySignature(byte[] rawBody, string header, string secret, int toleranceSeconds = 300, long? nowSeconds = null)
{
    string? timestamp = null;
    var signatures = new List<string>();
    foreach (var part in header.Split(','))
    {
        var pair = part.Trim().Split('=', 2);
        if (pair.Length != 2) continue;
        if (pair[0] == "t") timestamp = pair[1];
        else if (pair[0] == "v1") signatures.Add(pair[1]);
    }
    if (timestamp is null || timestamp.Length is 0 or > 18 || !timestamp.All(c => c is >= '0' and <= '9') || signatures.Count == 0) return false;
    var now = nowSeconds ?? DateTimeOffset.UtcNow.ToUnixTimeSeconds();
    if (Math.Abs(now - long.Parse(timestamp)) > toleranceSeconds) return false;

    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var signed = Encoding.ASCII.GetBytes(timestamp + ".").Concat(rawBody).ToArray();
    var expected = hmac.ComputeHash(signed);

    var valid = false;
    foreach (var signature in signatures)
    {
        try { valid |= CryptographicOperations.FixedTimeEquals(Convert.FromHexString(signature), expected); }
        catch (FormatException) { }
    }
    return valid;
}

// Check it against the official test vector: this prints True.
var body = "{\"id\":\"evt_test_000000000000000000\",\"object\":\"event\",\"api_version\":\"2026-10-26\",\"created\":1700000000,\"livemode\":false,\"type\":\"payment.succeeded\",\"data\":{\"object\":{\"id\":\"pay_test_000000000000\",\"object\":\"payment\",\"amount\":150000,\"currency\":\"DZD\",\"status\":\"succeeded\"}}}";
Console.WriteLine(VerifySignature(Encoding.UTF8.GetBytes(body), "t=1700000000,v1=ddb9f8a187313afb17555011222152be4f076bf39218f86a28f0a93714651a6c", "whsec_test_not_a_real_secret", 300, 1700000000));
```

**Swift**

```swift
import CryptoKit
import Foundation

func verifySignature(rawBody: Data, header: String, secret: String, tolerance: TimeInterval = 300, now: Date = Date()) -> Bool {
    var timestamp: String?
    var signatures: [String] = []
    for part in header.split(separator: ",") {
        let pair = part.trimmingCharacters(in: .whitespaces).split(separator: "=", maxSplits: 1).map(String.init)
        guard pair.count == 2 else { continue }
        if pair[0] == "t" { timestamp = pair[1] } else if pair[0] == "v1" { signatures.append(pair[1]) }
    }
    guard let timestamp, !timestamp.isEmpty, timestamp.allSatisfy({ $0.isASCII && $0.isNumber }),
          let seconds = TimeInterval(timestamp), !signatures.isEmpty,
          abs(now.timeIntervalSince1970 - seconds) <= tolerance else { return false }

    var signed = Data("\(timestamp).".utf8)
    signed.append(rawBody)
    let key = SymmetricKey(data: Data(secret.utf8))
    return signatures.contains { signature in
        guard let received = hexData(signature) else { return false }
        return HMAC<SHA256>.isValidAuthenticationCode(received, authenticating: signed, using: key)
    }
}

func hexData(_ hex: String) -> Data? {
    guard hex.count % 2 == 0 else { return nil }
    var data = Data()
    var index = hex.startIndex
    while index < hex.endIndex {
        let next = hex.index(index, offsetBy: 2)
        guard let byte = UInt8(hex[index..<next], radix: 16) else { return nil }
        data.append(byte)
        index = next
    }
    return data
}

// Check it against the official test vector: this prints true.
let body = Data(#"{"id":"evt_test_000000000000000000","object":"event","api_version":"2026-10-26","created":1700000000,"livemode":false,"type":"payment.succeeded","data":{"object":{"id":"pay_test_000000000000","object":"payment","amount":150000,"currency":"DZD","status":"succeeded"}}}"#.utf8)
print(verifySignature(rawBody: body, header: "t=1700000000,v1=ddb9f8a187313afb17555011222152be4f076bf39218f86a28f0a93714651a6c", secret: "whsec_test_not_a_real_secret", now: Date(timeIntervalSince1970: 1700000000)))
```

**Kotlin**

```kotlin
import java.security.MessageDigest
import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec
import kotlin.math.abs

fun verifySignature(
    rawBody: ByteArray,
    header: String,
    secret: String,
    toleranceSeconds: Long = 300,
    nowSeconds: Long = System.currentTimeMillis() / 1000,
): Boolean {
    var timestamp: String? = null
    val signatures = mutableListOf<String>()
    for (part in header.split(",")) {
        val pair = part.trim().split("=", limit = 2)
        if (pair.size != 2) continue
        when (pair[0]) {
            "t" -> timestamp = pair[1]
            "v1" -> signatures.add(pair[1])
        }
    }
    val sent = timestamp ?: return false
    if (sent.isEmpty() || sent.length > 18 || !sent.all { it in '0'..'9' } || signatures.isEmpty()) return false
    if (abs(nowSeconds - sent.toLong()) > toleranceSeconds) return false

    val mac = Mac.getInstance("HmacSHA256")
    mac.init(SecretKeySpec(secret.toByteArray(), "HmacSHA256"))
    mac.update("$sent.".toByteArray())
    val expected = mac.doFinal(rawBody).joinToString("") { "%02x".format(it) }

    var valid = false
    for (signature in signatures) {
        valid = valid or MessageDigest.isEqual(expected.toByteArray(), signature.lowercase().toByteArray())
    }
    return valid
}

fun main() {
    // Check it against the official test vector: this prints true.
    val body = "{\"id\":\"evt_test_000000000000000000\",\"object\":\"event\",\"api_version\":\"2026-10-26\",\"created\":1700000000,\"livemode\":false,\"type\":\"payment.succeeded\",\"data\":{\"object\":{\"id\":\"pay_test_000000000000\",\"object\":\"payment\",\"amount\":150000,\"currency\":\"DZD\",\"status\":\"succeeded\"}}}"
    println(verifySignature(body.toByteArray(), "t=1700000000,v1=ddb9f8a187313afb17555011222152be4f076bf39218f86a28f0a93714651a6c", "whsec_test_not_a_real_secret", 300, 1700000000L))
}
```


Each program above ends with a check against the official test vector and prints `true`. Use the same vectors to test your own implementation. The secret is a fake one that exists only for this purpose, and the body is a short fixed example chosen for the check: a real event carries the complete payment object (a paid payment has the status `paid`).

|  | Secret | Timestamp | Expected header |
| --- | --- | --- | --- |
| 1 | `whsec_test_not_a_real_secret` | `1700000000` | `t=1700000000,v1=ddb9f8a187313afb17555011222152be4f076bf39218f86a28f0a93714651a6c` |
| 2 | `whsec_test_not_a_real_secret` | `1700000123` | `t=1700000123,v1=d5706b801c65362d38ec4bc85d7cc163780cb28914865873c7c9e30e73312b42` |
| 3 | `whsec_test_not_a_real_secret` and `whsec_test_previous_secret` | `1700000000` | `t=1700000000,v1=ddb9f8a187313afb17555011222152be4f076bf39218f86a28f0a93714651a6c,v1=f579a5c29052f92cc26eb93acb1028e858b2e9e0980243792f4a09ef9a073f05` |

Vector 1 signs this body (it is not a realistic event: its ids are made up and its payment says `status: succeeded`, where a real payment says `paid`; only its bytes matter to the signature):

~~~text
{"id":"evt_test_000000000000000000","object":"event","api_version":"2026-10-26","created":1700000000,"livemode":false,"type":"payment.succeeded","data":{"object":{"id":"pay_test_000000000000","object":"payment","amount":150000,"currency":"DZD","status":"succeeded"}}}
~~~

Vector 2 signs a body with escapes (`\u00e9`) exactly as received. Vector 3 signs vector 1's body with two secrets, which is what a header looks like while a secret is being rotated: both signatures are present, and a receiver holding either secret matches one of them.

### Getting the raw body

| Framework | Raw body |
| --- | --- |
| Express | `express.raw({ type: "application/json" })` on the webhook route; `req.body` is a `Buffer` |
| Next.js route handler | `await request.text()` |
| Flask | `request.get_data()` |
| Django | `request.body` |
| FastAPI | `await request.body()` |
| Laravel and plain PHP | `$request->getContent()` or `file_get_contents('php://input')` |
| Go | `io.ReadAll(r.Body)` |
| Spring Boot | `@RequestBody byte[] body` |
| ASP.NET Core | Read `Request.Body` into a string or byte array before model binding |

## Answer quickly

Answer with any `2xx` status as soon as you have stored the event, and do slow work afterwards. Everything else is a failure and is retried:

- A `4xx` or `5xx` status, a closed connection or no answer within 10 seconds.
- A `3xx` status. Raïs never follows redirects: configure the final address.

Raïs keeps the first kilobyte of your answer to show in the dashboard. It does not use it otherwise.

## Retries

If an attempt fails, Raïs tries again, up to 8 attempts in all.

| Attempt | Sent |
| --- | --- |
| 1 | Right away |
| 2 | 30 seconds after attempt 1 failed |
| 3 | 2 minutes after attempt 2 failed |
| 4 | 10 minutes after attempt 3 failed |
| 5 | 30 minutes after attempt 4 failed |
| 6 | 2 hours after attempt 5 failed |
| 7 | 6 hours after attempt 6 failed |
| 8 | 12 hours after attempt 7 failed |

That covers about 20 hours and 43 minutes. When your server answers `429` or `503` with a `Retry-After` header, the next attempt waits at least that long, up to 1 hour. When every attempt fails, the delivery is marked failed; you can resend it from the dashboard once your endpoint is fixed.

## Handle each event once

Delivery is **at least once**: the same event can reach you more than once, for example when your answer is lost. De-duplicate on the event `id`, and make the work and the record of it one atomic step:

~~~javascript
// The dashboard's "Send test event" has an id that starts with evt_test_: acknowledge it, never fulfil an order for it.
if (event.id.startsWith("evt_test_")) return res.sendStatus(200);

await db.transaction(async (tx) => {
  const first = await tx.query(
    "INSERT INTO processed_events (id) VALUES ($1) ON CONFLICT DO NOTHING",
    [event.id],
  );
  if (first.rowCount === 0) return; // seen before: nothing to do
  await fulfil(tx, event.data.object); // both happen, or neither
});
res.sendStatus(200);
~~~

Events can also arrive **out of order**: a retry of an older event may come after a newer one. When the order matters, compare `created`, or retrieve the payment and act on its current `status`.

## Keep the endpoint healthy

Raïs counts the deliveries that failed every attempt. After **20 in a row**, it switches the endpoint off and records why. A success resets the counter. Fix your endpoint, then enable it again in the dashboard; events that happened meanwhile are not lost, you can read them with the [events API](https://rais.app/docs/api/list-events.md) for 30 days.

Watch the delivery log of the dashboard, and alert on failures, so that you notice a broken endpoint long before it is disabled.

## Rotate the signing secret

Roll the secret from the dashboard when someone who knew it leaves, or you suspect a leak. For the next 24 hours Raïs signs each webhook with both the new and the previous secret, so the header carries two `v1` values. A receiver that holds either secret verifies the request, which lets you deploy the new secret without missing an event. The code above already accepts any matching `v1`. After 24 hours only the new secret signs, so deploy it within that time.

## Test your endpoint

- **Send test event.** The dashboard sends a fake `payment.succeeded` event (its id starts with `evt_test_`, the payment is marked as a test and nothing is charged) to the endpoint. It gets one attempt, is never retried and does not count against the endpoint's health. It is signed like any other event. The fake payment does not exist: retrieving its id answers `404`. The event is listed by `GET /events` like the others, so skip the ids that start with `evt_test_` when you read them.
- **A sandbox payment.** Pay a sandbox payment with a [test card](https://rais.app/docs/testing.md) and watch a real event arrive.
- **Failures.** Answer `500` once, and check that the retry reaches you with `Rais-Attempt: 2` and the same `Rais-Event-Id`.
- **Resend.** Press **Resend** next to any past delivery in the **Deliveries** list of the endpoint, for example after a fix.

### Recognise the test event

The test event looks like a paid payment, and it is signed like a real one, so it will go through your signature check. It must **never** make your system fulfil an order. These fields identify it; any one of them is enough, and the first is the simplest:

~~~json
{
  "id": "evt_test_O0GCOwC2qTkEcypSFkt2V2t2",
  "type": "payment.succeeded",
  "data": {
    "object": {
      "status": "paid",
      "amount": 10000,
      "description": "Test payment sent by the 'Send test webhook' button. Nothing was charged.",
      "reference": "rais_webhook_test",
      "metadata": { "rais_test_event": "true" }
    }
  }
}
~~~

- the event `id` starts with `evt_test_`;
- `data.object.metadata.rais_test_event` is `"true"` and `data.object.reference` is `rais_webhook_test`;
- the payment id in `data.object.id` is made up: retrieving it answers `404`.

Its `livemode` is the one of the endpoint, so a test event sent to a **live** endpoint says `livemode: true`: do not use `livemode` to tell it apart. Acknowledge it with a `2xx` and do nothing else.

## Read events through the API

Events are also available for 30 days through `GET /events`, filtered by type and paginated. Use it to catch up after downtime.


**Request**

```bash
curl 'https://api.rais.app/v1/events?type=payment.succeeded&limit=3' \
  -H "Authorization: Bearer rais_sk_test_..."
```


## The legacy format

Stores that configured a webhook URL **before API keys existed** keep receiving the request they always did, unchanged, so existing integrations keep verifying it. New integrations should use the format described above.

|  | Legacy format |
| --- | --- |
| Event header | `X-Rais-Event: invoice.<status>`, for example `invoice.paid` |
| Timestamp | `X-Rais-Timestamp: <unix seconds>` |
| Signature | `X-Rais-Signature: sha256=<hex>`, only when the store has a secret |
| Signed text | `<timestamp>.<body>`, HMAC-SHA256 with the store's secret |
| Body | The invoice, as compact JSON with the keys sorted |
| Also sent | `Rais-Event-Id`, `Rais-Delivery-Id`, `Rais-Attempt` and `Rais-Livemode`, as above |

Legacy endpoints receive `payment.succeeded` as `invoice.paid`, `payment.failed` as `invoice.declined` or `invoice.error`, `payment.cancelled` as `invoice.cancelled`, `payment.reversed` as `invoice.reversed`, and `refund.succeeded` as `invoice.refunded` or `invoice.partially_refunded`. `refund.failed` is not sent to them. Delivery, retries and health work as described above.


> [!NOTE]
> **Verifying a legacy request**
>
> Compute `hex(HMAC_SHA256(secret, timestamp + "." + body))` over the raw body and compare it with the value after `sha256=`, in constant time, exactly as for the current format. Keep the timestamp check too.

---

# Refunds

> Refund all or part of a payment, and follow the refund to its end.

Source: https://rais.app/docs/refunds

A refund returns all or part of a **paid** payment to the payer's card. You can refund through the API with a key that has the `refunds:write` scope, or from the dashboard.

## Refund a payment

Without an `amount`, everything that can still be refunded is refunded. With one, it is that many centimes.


**Request**

```bash
curl https://api.rais.app/v1/payments/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33/refunds \
  -H "Authorization: Bearer rais_sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4b0f8a7a-6a5e-4d0f-9f55-2c3e8d1a9b10" \
  -d '{
  "amount": 150000,
  "reason": "Customer returned one item"
}'
```

**Response** (`201`)

~~~json
{
  "id": "0c8a1d52-6e7b-4f0a-9b3d-7d2e4a8c5f10",
  "object": "refund",
  "payment_id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
  "amount": 150000,
  "currency": "DZD",
  "status": "succeeded",
  "reason": "Customer returned one item",
  "failure": null,
  "fees": {
    "satim": 800,
    "rais": 200,
    "total": 1000
  },
  "livemode": false,
  "created": 1793000900
}
~~~


The refund is carried out with the gateway **before** the API answers, so the answer is the outcome. After a successful refund the payment's `amount_refunded` grows, its status becomes `partially_refunded` or `refunded`, and a `refund.succeeded` event is sent. Always send an `Idempotency-Key`: if the connection drops, repeating the request can never refund twice. See [Idempotency and retries](https://rais.app/docs/idempotency.md).

## What a refund costs

Every refund has its own fee, **10.00 DA** excluding VAT (SATIM 8.00 DA plus Raïs 2.00 DA), whatever the amount: refunding 1.00 DA costs as much as refunding 100,000.00 DA. The refund object carries it in `fees`, with the `satim` and `rais` parts and their `total`, in centimes.

- The fee is charged when the refund **succeeded**. `fees` is `null` while the refund is `pending`, and when it `failed`: a refund that does not happen costs nothing.
- The fee of the **payment itself is not returned**, in full or in part: refunding a payment never gives back what it cost. What you keep is `net` of the payment, minus the amount refunded, minus the fee of each refund.
- A **live** refund is taken out of your balance together with its fee: the balance must cover the amount **and** the fee. While a refund is `pending`, both are reserved.
- A **sandbox** refund shows the simulated fee, moves no money and needs no balance.

See [Pricing and fees](https://rais.app/docs/pricing.md) for the whole price list.

## Rules

- Only a payment with the status `paid` or `partially_refunded` can be refunded. Any other status answers `409` with `payment_not_refundable`.
- The smallest refund is 100 centimes (1.00 DA). A smaller one answers `amount_too_small`.
- A payment can be refunded several times, never beyond what was paid. Asking for more than what is left answers `refund_exceeds_balance`; refunds that are still pending count as already taken.
- A **live** refund is paid out of your store's balance, which must cover the refund **and its fee** (10.00 DA): otherwise the answer is `insufficient_balance`, "The store's balance is not sufficient to cover this refund and its fee." Nothing is refunded and nothing is taken: a top-up of the balance is needed, or refund a smaller amount that the balance covers. A full refund is therefore not possible while the balance falls short of the amount and the fee, and the refund dialog of the dashboard says what the balance can cover and how much is missing. Because the fee of the payment is not returned either, a store that has received a single payment can refund at most its balance minus 10.00 DA. A sandbox refund moves no money and never touches a balance.
- `reason` is for your records, up to 255 characters.

## Who can refund what

| | |
| --- | --- |
| An API key | Only payments of **its own store**, in **its own environment**. Any other payment answers `404`, whether it exists or not. The key needs `refunds:write`. |
| The dashboard | The owners and admins of the business, for the payments of the stores of their business. Developers, accountants and viewers cannot refund. |

## Statuses

| Status | HTTP | Meaning |
| --- | --- | --- |
| `succeeded` | 201 | The bank refunded the amount. |
| `failed` | 402 | The bank refused. The error is `refund_declined`; the refund object, which you can still read in `GET /refunds`, has a `failure` with the reason. Nothing was refunded. When the gateway could not be reached at all, the refund is recorded as failed too and the answer is `503 gateway_unavailable`. |
| `pending` | 202 | The request reached the gateway but its answer was lost. The amount stays reserved until the refund is checked. |

### Pending refunds

A `pending` refund means that Raïs does not know yet whether the money went back. **Do not repeat the refund with a new `Idempotency-Key`**: that could refund twice. The amount stays reserved on the payment, and for a live refund on your balance (together with the refund's fee, which is only charged if the refund goes through), while the refund is `pending`. Raïs never guesses the outcome and has no automatic check for it: a pending refund is settled by hand with the payment gateway. Read the refund to see where it stands, and contact support with the refund id and the `Rais-Request-Id` of the request if it is still `pending` after a few minutes. Do not wait for an event to settle it.


**Request**

```bash
curl https://api.rais.app/v1/refunds/0c8a1d52-6e7b-4f0a-9b3d-7d2e4a8c5f10 \
  -H "Authorization: Bearer rais_sk_test_..."
```


## Timing

The refund itself is immediate: the API answers once the gateway has. How quickly the amount shows on the payer's statement is up to their bank, and Raïs cannot speed it up. Tell your customers that it may not appear at once.

## List refunds

List the refunds of your store, or only those of one payment.


**Request**

```bash
curl 'https://api.rais.app/v1/refunds?payment=5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33' \
  -H "Authorization: Bearer rais_sk_test_..."
```


## Receipts after a refund

The payer's receipt is regenerated after a refund, so it always shows the refunds made so far, and the refunded payment is marked refunded or partially refunded on its result page. See [Receipts](https://rais.app/docs/receipts.md).

## Errors

| Status | Code | When |
| --- | --- | --- |
| 404 | `payment_not_found` | No such payment for this key. |
| 409 | `payment_not_refundable` | The payment is not paid. |
| 400 | `amount_too_small` | Less than 100 centimes. |
| 400 | `refund_exceeds_balance` | More than what is still refundable. |
| 400 | `insufficient_balance` | Your balance cannot cover a live refund and its fee: top it up, or refund a smaller amount. |
| 402 | `refund_declined` | The bank refused the refund. |
| 409 | `idempotency_in_progress` | The first request with this key is still running. |
| 422 | `idempotency_key_reused` | The key was used with different parameters. |
| 503 | `gateway_unavailable` | The gateway cannot be reached. Nothing was refunded: retry. |

---

# Receipts

> PDF receipts of paid payments: how to get a signed link and what a receipt contains.

Source: https://rais.app/docs/receipts

Every payment that was paid has a **PDF receipt** for the payer. You can give the payer a link to it, or fetch a signed link yourself to attach the PDF to an e-mail or an order page.

## Which payments have a receipt

A receipt exists for payments with the status `paid`, `partially_refunded` and `refunded`. A pending, failed, cancelled, expired or reversed payment has none.

## The payer's link

Once a payment is paid, its `receipt_url` is set. It is a link to the PDF, on the payer's address (`https://pay.rais.app`, next to the checkout), that works in any browser, with no key, and is the same link as the **Download receipt (PDF)** button of the result page.

~~~json
{
  "id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
  "status": "paid",
  "receipt_url": "https://pay.rais.app/pay/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33/receipt.pdf"
}
~~~

The link contains the payment's id, which cannot be guessed, and is the only thing that grants access: share it only with the payer. It is rate limited per client address, so a script cannot hammer it, and it answers `404` for a payment that has no receipt. The `payment.succeeded` webhook carries the same `receipt_url` in `data.object`.

## A signed link for your server

`GET /payments/{id}/receipt` returns a signed link to the PDF, valid for 15 minutes. It needs the `payments:read` scope.


**Request**

```bash
curl https://api.rais.app/v1/payments/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33/receipt \
  -H "Authorization: Bearer rais_sk_test_..."
```

**Response** (`200`)

~~~json
{
  "object": "receipt",
  "url": "https://files.example.com/receipts/2026/10/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33.pdf?X-Amz-Expires=900&X-Amz-Signature=...",
  "expires_at": 1793000900
}
~~~


The `url` is an HTTPS link to the file, signed for 15 minutes. Treat it as opaque: its host and parameters are not part of the contract. Ask for a new link whenever you need one instead of storing it: after `expires_at` it stops working.

| Status | Code | When |
| --- | --- | --- |
| 404 | `payment_not_found` | No such payment for this key, the payment is of the other environment, or it has not been paid. All three look the same. |
| 503 | `gateway_unavailable` | The receipt cannot be produced right now. Retry shortly; the answer has a `Retry-After` header. |

## What a receipt contains

A receipt is an A4 PDF in the language of the payment page: English, French or Arabic, laid out right to left for Arabic.

- The receipt number, the amount paid and the payment date.
- The **merchant**: your store name, the contact e-mail of your store and, when your business is verified, its legal identity (NIF, RC and NIS where known).
- The **payer**: name and e-mail, when you provided them. The name on the card is never printed.
- The **items** with quantity, unit price and amount, or a single line when you sent none.
- The **payment details**: the payment method (always **CIB/Edahabia**), the approval code, the Raïs order ID, the Raïs order number, your reference, the bank response and the currency. No card number is printed, not even its last digits.
- Every **refund** made so far, with its date, reason and amount, and the net amount.
- A QR code and a link to the payment page, and the SATIM support number, 3020.

Give your items clear names and send the payer's details: they go straight onto the receipt.

## After a refund

The receipt is regenerated when a refund succeeds, so a link always shows the refunds made so far. See [Refunds](https://rais.app/docs/refunds.md).

## Sandbox receipts

A receipt of a sandbox payment is a real PDF with the same layout, marked **TEST MODE — NOT A REAL PAYMENT** so that it cannot be mistaken for proof of a live payment.

---

# Test cards and sandbox

> SATIM test cards, what the sandbox does and does not do, and how to rehearse failures.

Source: https://rais.app/docs/testing

The sandbox lets you build and test a complete integration without moving any money. It is the same API as live: only the key changes.

## What the sandbox does

- A **sandbox key** (`rais_sk_test_...`) creates test payments with `livemode: false`. The API, the objects, the errors, the events and the webhooks are the same as in live.
- Test payments are paid on the real hosted checkout with **SATIM's test cards**, typed as a real card is (see [Test cards](#test-cards)). The checkout of a sandbox payment shows a "Test mode" banner. It does not list the cards, and it lets an expired card or a wrong check digit through to SATIM, so that every case below can be rehearsed.
- **No money moves.** A sandbox payment never credits a balance and never writes to the ledger; a sandbox refund never debits one.
- **Fees are simulated.** A paid sandbox payment and a succeeded sandbox refund show the fees they would cost in live, in `fees` (and `net` on the payment): nothing is charged. See [Pricing and fees](https://rais.app/docs/pricing.md).
- Sandbox events go to **sandbox webhook endpoints** only, and sandbox receipts are marked **TEST MODE — NOT A REAL PAYMENT**.
- Sandbox and live data never mix: a sandbox key cannot see a live payment, and the other way round.

A **live** payment never shows a test banner or any test wording, in any state.

## What it does not do

- It does not let you choose the outcome through the API: the card you use decides it.
- It does not speed up time. To rehearse expiry, create a payment with `expires_in: 300` and wait.
- It still goes through SATIM's test system, so an outage over there can answer `gateway_unavailable`, as in live.

## Test cards

Use any of these cards on the checkout of a **sandbox** payment. Type the number, the expiry (month and two digits of the year, as in the table) and the CVV2 in the card form (the name can be any name in Latin letters), then enter the 3-D Secure password of the card when the bank step asks for it. The checkout does not list the cards.

| Card number | Expiry (MM/YY) | CVV2 | 3DS password | Result |
| --- | --- | --- | --- | --- |
| `6280 5811 1000 7215` | 01/27 | 373 | 123456 | Valid card: the payment succeeds |
| `6280 5806 1006 1011` | 01/27 | 992 | 123456 | Valid credit card: the payment succeeds |
| `6280 5811 1000 6712` | 01/27 | 897 | 123456 | Declined: card temporarily blocked |
| `6280 5811 1000 6316` | 01/27 | 657 | 123456 | Declined: lost card |
| `6280 5811 1000 6415` | 01/27 | 958 | 123456 | Declined: stolen card |
| `6280 5811 1000 6613` | 01/26 | 411 | 123456 | Declined: incorrect expiration date |
| `6280 5811 1000 3927` | 01/25 | 834 | 123456 | Refused by the form ("PAN is invalid"): the payment stays pending |
| `6280 5806 1006 1219` | 01/27 | 049 | 123456 | Declined: card limit reached |
| `6280 5806 1006 1110` | 01/27 | 260 | 123456 | Declined: insufficient funds |
| `6280 5811 1000 6514` | 01/27 | 205 | 123456 | Declined: incorrect CVV2 |
| `6280 5806 1006 1318` | 01/27 | 930 | 666666 | Declined: card blocked for e-payments, before the password is asked |
| `6280 5811 1000 7017` | 01/27 | 632 | 123456 | Declined: card blocked for e-payments, before the password is asked |
| `6280 5811 1000 7116` | 01/27 | 040 | 123456 | Declined: inactive card |
| `6280 5811 1000 7314` | 01/27 | 821 | 123456 | Declined: card limit reached |
| `6280 5806 1005 6615` | 12/22 | 428 | 123456 | Approved: SATIM's test platform does not refuse this card, so the payment succeeds |

The first two cards pay successfully. Most of the others reproduce the failures a real payer meets: a blocked, lost or stolen card, a wrong expiry date or CVV2, a card without funds or over its limit. A declined card ends the payment with the status `failed`, a `failure` object that carries `payment_declined` and SATIM's message, and a `payment.failed` event. Three of the cards do not behave as their name suggests, as observed on SATIM's test platform:

- **Card no longer exists at the issuer** is refused by the payment form itself ("PAN is invalid"). No attempt reaches the bank, so the payment stays `pending` and the payer can try another card.
- **Password attempts exceeded** and **Card not authorised for online payment** are both refused as "Card blocked for e-payments" before the 3-D Secure password is asked.
- **Expired card** is **approved**: SATIM's test platform does not refuse it, so the payment succeeds. Do not use it to test a decline.

The wording of `failure.message` is SATIM's and can change: branch on `failure.code`.


> [!NOTE]
> **The wrong expiry card**
>
> The card "Incorrect expiration date" fails because the checkout is filled with an expiry that does not match the card, which is how SATIM's certification scenario works. Enter `01/26`, the expiry in the table: the checkout of a sandbox payment lets it through.


These are the cards SATIM publishes for its certification environment. They work only there.

## Rehearse your integration

Run through these cases before you go live:

1. **Success.** Pay with the first card. Check that your webhook arrives, that you mark the order paid once, and that the return page confirms through the API.
2. **Decline.** Pay with a card that is declined, such as the blocked card, and show the payer a useful message. Check the `payment.failed` event. A declined card closes the payment: the payer cannot pay on the same link.
3. **Abandon.** Open the checkout and press **Back to** your store, then close the page. Check what your cancel page shows: the address carries `status=cancelled` although the payment is still `pending` and can be paid until it expires.
4. **Expire.** Create a payment with `expires_in: 300`, wait five minutes, and retrieve it: its status is `expired`.
5. **Cancel.** Create a payment and cancel it with the API before it is paid.
6. **Refund.** Refund part of a paid payment, then the rest. Watch the status go to `partially_refunded` and then `refunded`, and read the `fees` of each refund (simulated in the sandbox).
7. **Webhook failures.** Make your endpoint answer `500` once, and check that the retry arrives with `Rais-Attempt: 2` and the same event id. Send the same event twice and check that you process it once.
8. **Retries.** Send the same `POST /payments` twice with one `Idempotency-Key`. You should get the same payment, with `Idempotent-Replayed: true` the second time.

When all of it works, follow [Going live](https://rais.app/docs/going-live.md).

---

# Going live

> Business verification, live keys and the checklist to run before the first real payment.

Source: https://rais.app/docs/going-live

Going live is a change of **key**, not of code: the same API, the same URLs and the same objects. Before that, your business has to be verified, and a few settings have to be real.

## 1. Verify your business

Live payments need a verified business. The sandbox stays available while you do it. In the dashboard, open **Verification**; it takes you through five steps and you can save and come back later:

1. **Business details.**
2. **Legal documents.** Your commercial register, NIF and NIS numbers, each with its document (type each number as it is written on the document), and the agreement (agrément) if your activity needs one.
3. **Owners.** The legal representative and every other owner of 25% or more, each with an identity document.
4. **Merchant agreement.** Read the Raïs merchant agreement, then sign it, drawn or typed, as an owner or administrator of the business. The signed copy stays available as a PDF, and the text can be read without signing in.
5. **Review and submit.**

Files can be PDF, JPEG, PNG or WEBP, up to 10 MB each. The Raïs team reviews the application and tells you the outcome; if something is missing, the review message says what to change and you can resubmit.

Until your business is approved:

- `GET /account` shows `live_enabled: false`.
- The dashboard creates no live key and no live webhook endpoint. A live key can only exist for an approved store, and it stops working the moment the store is no longer approved: the API then answers `401 invalid_api_key`, like for any key it refuses.
- Everything in the sandbox keeps working.

## 2. Create a live key

When the business is approved, open **Developers**, then **API keys**, press **Create key** and choose **Live** in the dialog: the key starts with `rais_sk_live_`. Store it in your production secret manager, next to nothing else. Keep the sandbox key for staging.


**Request**

```bash
curl https://api.rais.app/v1/account \
  -H "Authorization: Bearer rais_sk_test_..."
```


With the live key, `livemode` is `true` and `live_enabled` is `true`. See [Authentication](https://rais.app/docs/authentication.md).

## 3. Register a live webhook endpoint

Sandbox endpoints do not receive live events. In **Developers**, then **Webhooks**, add an endpoint, choose **Live** in the dialog, give it an `https://` address, and keep its own signing secret. Check that your server:

- verifies the signature on the raw body, and rejects old timestamps;
- answers `2xx` within 10 seconds, and does slow work afterwards;
- processes each event once, using its `id`.

See [Webhooks](https://rais.app/docs/webhooks.md).

## 4. Use https everywhere

- **Webhook endpoints.** A live endpoint must use `https://`.
- **Return URLs.** `success_url` and `cancel_url` of a live payment must use `https://`, or your own app scheme. `http://` is accepted in the sandbox only. Store defaults follow the same rule.
- **Your own pages.** The pages the payer returns to should be https too.

## 5. Checklist


> [!TIP]
> **Before the first real payment**
>
> - The business is approved and `GET /account` shows `live_enabled: true`.
> - The live key is in your secret manager and not in code, logs, mobile apps or tickets.
> - Payments are created on your server, with the amount computed there.
> - Every payment creation and every refund sends an `Idempotency-Key`.
> - The live webhook endpoint is registered, verified and idempotent.
> - Return pages confirm the payment with the API or the webhook, never from the address, and do not cancel the order because of `status=failed`: the payer may try again.
> - Unpaid orders are closed by your own timer or by retrieving the payment after `expires_at`: nothing is sent when a payment expires.
> - You know what a payment and a refund cost (see [Pricing and fees](https://rais.app/docs/pricing.md)), and your balance can cover the refunds you may issue: a live refund and its fee are taken from it.
> - Errors are handled by type, `429` and `5xx` are retried with backoff, and request ids are logged. See [Errors](https://rais.app/docs/errors.md).
> - You alert on failed webhook deliveries.
> - Your terms and refund policy are published for your customers.


## 6. Take a first real payment

Create a payment for the smallest amount, 50.00 DA, with a real card. Check that the payment is `paid`, that your webhook arrived and was processed once, and that the receipt opens. Then refund it, and check the `refund.succeeded` event. A live refund comes out of your store's balance together with its fee (10.00 DA), so the balance must cover both: a store that has just received one payment can refund at most its balance minus 10.00 DA.

## Test and live compared

|  | Sandbox | Live |
| --- | --- | --- |
| Key | `rais_sk_test_...` | `rais_sk_live_...` |
| Base URL | Same | Same |
| Availability | Always | After business verification |
| Cards | SATIM test cards | Real CIB and Edahabia cards |
| Money and balances | Nothing moves | Credited and debited |
| Fees | Shown, simulated: nothing is charged | Charged on each paid payment and each refund |
| Return URLs | `https://`, `http://` or your app scheme | `https://` or your app scheme |
| Webhook endpoints | `https://` or `http://` | `https://` only |
| Receipts | Marked as a test | Official |
| Test wording on the checkout | "Test mode" banner | Never shown |

## Rate limits

Each key may send 60 requests a second, in bursts of up to 120. See [Rate limits](https://rais.app/docs/rate-limits.md).

---

# Errors

> The error envelope, every error code, request ids and what to do about each kind of error.

Source: https://rais.app/docs/errors

Every response that is not a success has the **same envelope**, whatever went wrong. The HTTP status tells you the class of problem, `type` how to react, and `code` exactly what happened.

## The error envelope

~~~json
{
  "error": {
    "type": "invalid_request_error",
    "code": "amount_too_small",
    "message": "The minimum amount is 50.00 DA (5000 centimes).",
    "param": "amount",
    "request_id": "req_8f3a1c9d2b7e4a60"
  }
}
~~~


- `type` (string): the category of the error. It decides how you react.
- `code` (string): a stable, machine-readable identifier. Branch on this, never on the message.
- `message` (string): an explanation for developers. Do not show it to payers, and do not parse it.
- `param` (string, nullable): the request parameter the error is about, such as `amount` or `customer.email`. Nested names use dots and brackets: `items[0].quantity`.
- `request_id` (string): the id of the request, also in the `Rais-Request-Id` response header.


## Request ids

Every response, errors included, carries a `Rais-Request-Id` header such as `req_8f3a1c9d2b7e4a60c5d1`, and the `Rais-Version` header. Log the request id of every call that fails, and quote it when you contact support: it finds the exact request on our side. Raïs logs each request with its id but never its headers, query string or body. The id is the same in the header and in `error.request_id`.

## Types

| Type | Status | What to do |
| --- | --- | --- |
| `authentication_error` | 401 | Fix the key. See [Authentication](https://rais.app/docs/authentication.md). |
| `permission_error` | 403 | The key is valid but not allowed: a missing scope. (A suspended store, or live mode before verification, answer `401` instead: see [Authentication](https://rais.app/docs/authentication.md#authentication-errors).) |
| `invalid_request_error` | 400, 405, 409 | Fix the request. The `param` names the field. Do not retry as it is. |
| `not_found_error` | 404 | The object does not exist for this key. See [Authentication](https://rais.app/docs/authentication.md). |
| `idempotency_error` | 409, 422 | The `Idempotency-Key` conflicts with another request. See [Idempotency and retries](https://rais.app/docs/idempotency.md). |
| `rate_limit_error` | 429 | Wait for the `Retry-After` header, then retry. See [Rate limits](https://rais.app/docs/rate-limits.md). |
| `payment_error` | 402, 502 | The payment gateway or the bank refused. Nothing was changed on your side of the line. |
| `api_error` | 500, 503 | A problem on our side or the gateway's. Retry later with the same `Idempotency-Key`. |

## Error codes


| Code | HTTP status | Type | Meaning |
| --- | --- | --- | --- |
| `amount_mismatch` | 400 | `invalid_request_error` | The amount is not an integer, is outside 5000...999999999999 centimes, or disagrees with `items`. |
| `amount_too_large` | 400 | `invalid_request_error` | The amount is not an integer, is outside 5000...999999999999 centimes, or disagrees with `items`. |
| `amount_too_small` | 400 | `invalid_request_error` | The amount is not an integer, is outside 5000...999999999999 centimes, or disagrees with `items`. |
| `currency_not_supported` | 400 | `invalid_request_error` | Only `DZD`. |
| `customer_not_found` | 400 | `invalid_request_error` | A field is invalid (see `param`). |
| `insufficient_balance` | 400 | `invalid_request_error` | The refund is more than what is left on the payment, or than your balance can cover (the refund plus its fee). |
| `invalid_amount` | 400 | `invalid_request_error` | The amount is not an integer, is outside 5000...999999999999 centimes, or disagrees with `items`. |
| `invalid_cursor` | 400 | `invalid_request_error` | The header or the `starting_after` value is invalid. |
| `invalid_email` | 400 | `invalid_request_error` | A field is invalid (see `param`). |
| `invalid_idempotency_key` | 400 | `invalid_request_error` | The header or the `starting_after` value is invalid. |
| `invalid_json` | 400 | `invalid_request_error` | The request body or query is malformed. |
| `invalid_metadata` | 400 | `invalid_request_error` | A field is invalid (see `param`). |
| `invalid_parameter` | 400 | `invalid_request_error` | The request body or query is malformed. |
| `invalid_url` | 400 | `invalid_request_error` | A field is invalid (see `param`). |
| `parameter_missing` | 400 | `invalid_request_error` | The request body or query is malformed. |
| `parameter_unknown` | 400 | `invalid_request_error` | The request body or query is malformed. |
| `refund_exceeds_balance` | 400 | `invalid_request_error` | The refund is more than what is left on the payment, or than your balance can cover (the refund plus its fee). |
| `invalid_api_key` | 401 | `authentication_error` | The key is missing, unknown, revoked, expired, not allowed from this IP address, or its store cannot use it. |
| `refund_declined` | 402 | `payment_error` | The bank refused the refund. |
| `account_disabled` | 403 | `permission_error` | The store is suspended or disabled. |
| `insufficient_scope` | 403 | `permission_error` | The key lacks the scope the endpoint needs. |
| `live_mode_not_enabled` | 403 | `permission_error` | Complete business verification to take live payments. |
| `event_not_found` | 404 | `not_found_error` | Nothing there (or it belongs to another store or environment). |
| `payment_not_found` | 404 | `not_found_error` | Nothing there (or it belongs to another store or environment). |
| `refund_not_found` | 404 | `not_found_error` | Nothing there (or it belongs to another store or environment). |
| `route_not_found` | 404 | `not_found_error` | Nothing there (or it belongs to another store or environment). |
| `method_not_allowed` | 405 | `invalid_request_error` | Wrong HTTP method. |
| `idempotency_in_progress` | 409 | `idempotency_error` | The first request with this key is still running. |
| `payment_not_cancellable` | 409 | `invalid_request_error` | The payment is not in a state that allows it. |
| `payment_not_refundable` | 409 | `invalid_request_error` | The payment is not in a state that allows it. |
| `idempotency_key_reused` | 422 | `idempotency_error` | The key was used with different parameters. |
| `rate_limit_exceeded` | 429 | `rate_limit_error` | Too many requests (60 per second, bursts of 120, per key) or too many failed authentications. |
| `internal_error` | 500 | `api_error` | Our fault. Quote the `request_id`. |
| `gateway_rejected` | 502 | `payment_error` | The payment gateway refused to create the payment. |
| `gateway_unavailable` | 503 | `api_error` | The gateway cannot be reached; retry later. Nothing was created or refunded. |


More codes can appear while a request is being read. They are produced by the validation of the request itself, so they are not tied to one endpoint:

| Code | HTTP status | Meaning |
| --- | --- | --- |
| `invalid_request_body` | 400 | The body is missing or is not a JSON object, for example an array. |
| `parameter_out_of_range` | 400 | A number is below or above what the parameter accepts, for example `limit=0` or `expires_in: 299`. `param` names it. |
| `parameter_too_long` | 400 | A text or a list is longer than allowed, for example a `reference` of 65 characters or 51 `items`. `param` names it. |
| `parameter_too_short` | 400 | A text or a list is shorter than required. |
| `invalid_request` | 400 | A request that is invalid in a way no other code describes. Read `message`. |

## Handling errors

~~~javascript
async function rais(path, init) {
  const response = await fetch(`https://api.rais.app/v1${path}`, init);
  const body = await response.json();
  if (response.ok) return body;

  const { error } = body;
  console.error("Raïs error", error.code, error.request_id); // always log the request id

  if (error.type === "rate_limit_error" || error.type === "api_error") {
    // transient: retry with backoff, reusing the same Idempotency-Key
    throw Object.assign(new Error(error.code), { retryable: true, retryAfter: response.headers.get("Retry-After") });
  }
  throw Object.assign(new Error(error.code), { retryable: false, param: error.param });
}
~~~

## Retry guidance

| Situation | Retry? |
| --- | --- |
| Network error or timeout | Yes, with the **same** `Idempotency-Key`. The first request may have succeeded. |
| `429` `rate_limit_exceeded` | Yes, after `Retry-After` seconds. |
| `500` `internal_error` | Yes, with backoff, and the same `Idempotency-Key`. |
| `503` `gateway_unavailable` | Yes. Nothing was created or refunded. Wait the `Retry-After` seconds. |
| `409` `idempotency_in_progress` | Yes, after `Retry-After` seconds: the first request is still running. |
| `502` `gateway_rejected` | Not as it is: the gateway refused the payment. Read `message`. |
| `402` `refund_declined` | No. The bank refused. Do not send it again unchanged. |
| Other `4xx` | No. Fix the request. |

Back off exponentially (1 s, 2 s, 4 s ...) with some random jitter, and give up after a few attempts. Never retry a `POST` without an `Idempotency-Key`.

---

# Idempotency and retries

> Retry a request after a timeout without creating a payment or a refund twice.

Source: https://rais.app/docs/idempotency

Networks fail. A request can time out after Raïs has already created the payment, and a client that sends it again would create a second one. An **idempotency key** makes the retry safe: the same key with the same request returns the original answer, and nothing happens twice.

## Send a key

Add an `Idempotency-Key` header to `POST /payments` and `POST /payments/{id}/refunds`.


**Request**

```bash
curl https://api.rais.app/v1/payments \
  -H "Authorization: Bearer rais_sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{
  "amount": 500000,
  "reference": "order-1042"
}'
```


The key is any value of 255 printable ASCII characters or fewer. A random UUID works. A key derived from your own record, such as `order-1042`, gives you "one payment per order" for free. Generate the key **before** the first attempt and keep it with the order, so every retry reuses it.

## What happens when you repeat a request

| You send | Raïs answers |
| --- | --- |
| The same key and the same request | The **original answer**, with the original status code and the header `Idempotent-Replayed: true`. Nothing is created or refunded again. The content is the same; the keys of the JSON object may come in a different order. |
| The same key and a different request | `422` with `idempotency_key_reused`. |
| The same key while the first request is still running | `409` with `idempotency_in_progress` and a `Retry-After` header. Retry in a moment. |
| A key longer than 255 characters or with unusual characters | `400` with `invalid_idempotency_key`. |

A few details that matter:

- **Same request** means the same method, the same path and the same JSON body. Spacing and the order of keys do not matter.
- **Only successful requests are remembered.** A request that failed leaves nothing behind, so you can fix the problem and send it again with the same key.
- **Keys live 24 hours.** After that, the same key starts a new operation.
- **Sandbox and live are separate.** The same text used with a sandbox key and with a live key makes two different keys. Keys are also scoped to your store: two stores can use the same text without ever meeting.
- **A replay is a snapshot.** It returns the answer the first request got, for example a `pending` payment, even if the payment has been paid since. Retrieve the payment to see its current state.
- **A crashed request is not a duplicate.** If a request dies half-way, repeating it finds what it created instead of creating it again.

## Retry in code

Retry on network errors, `429`, `409 idempotency_in_progress`, `500` and `503`, with exponential backoff, and always with the same key.

~~~javascript
async function createPayment(body, idempotencyKey) {
  for (let attempt = 1; attempt <= 4; attempt++) {
    try {
      const response = await fetch("https://api.rais.app/v1/payments", {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.RAIS_SECRET_KEY}`,
          "Content-Type": "application/json",
          "Idempotency-Key": idempotencyKey, // the same on every attempt
        },
        body: JSON.stringify(body),
      });
      const retryable = response.status === 429 || response.status === 409 || response.status >= 500;
      if (!retryable || attempt === 4) return response;

      const wait = Number(response.headers.get("Retry-After")) || 2 ** attempt;
      await new Promise((resolve) => setTimeout(resolve, wait * 1000));
    } catch (error) {
      if (attempt === 4) throw error; // a network error: the request may or may not have arrived
      await new Promise((resolve) => setTimeout(resolve, 2 ** attempt * 1000));
    }
  }
}
~~~

## Reads and cancellations

`GET` requests are safe to repeat as they are. Cancelling a payment twice answers `409 payment_not_cancellable` the second time: treat a payment that is already `cancelled` as done.

## Webhooks are at least once

The other half of reliability is on your side of the line: Raïs delivers each webhook until you acknowledge it, so the same event can arrive twice. De-duplicate on the event `id`. See [Webhooks](https://rais.app/docs/webhooks.md).

---

# Rate limits

> How many requests a key may send, what a 429 means and how to back off.

Source: https://rais.app/docs/rate-limits

The API limits how fast one key can send requests, so that a runaway loop on one integration cannot slow the others down. A request over the limit is refused with `429`, and nothing is processed.

## The limits

| Limit | Value |
| --- | --- |
| Requests per key | 60 per second on average, in bursts of up to 120 |
| Failed authentications | 30 per minute from one IP address |
| Payer receipt links (`receipt_url`) | 30 per minute from one client address |

The request budget is a token bucket: it holds up to 120 requests, and refills 60 every second. Every key has its own budget, so a sandbox key and a live key, or two services with two keys, never use each other's. The numbers may change: rely on the `Retry-After` header, not on these values. The API sends no `X-RateLimit-*` headers: a `429` and its `Retry-After` are the only signal.

## When you hit a limit

The answer is `429` with the code `rate_limit_exceeded` and a `Retry-After` header, in seconds:

~~~http
HTTP/1.1 429 Too Many Requests
Retry-After: 1
Rais-Request-Id: req_8f3a1c9d2b7e4a60c5d1

{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Too many requests. Slow down and retry after the delay in the Retry-After header.","param":null,"request_id":"req_8f3a1c9d2b7e4a60c5d1"}}
~~~

Repeated requests with keys that do not exist or are malformed are throttled too, per IP address: after 30 failures in a minute, the address answers `429` with the message "Too many failed authentication attempts. Retry later." for the rest of that minute. **While an address is throttled, every request from it is refused, even with a valid key.** A correct integration never meets this, unless a stale or revoked key is still being retried somewhere, for example by a job nobody stopped: when you revoke or roll a key, make sure the old one is no longer in use.

## Stay below the limits

- **Use webhooks, not polling.** One webhook replaces hundreds of `GET` requests. See [Webhooks](https://rais.app/docs/webhooks.md).
- **Back off.** On `429`, wait for `Retry-After`, then retry, with the same `Idempotency-Key` for `POST` requests. See [Idempotency and retries](https://rais.app/docs/idempotency.md).
- **Spread batch work.** A job that refunds or lists thousands of items should pace itself instead of sending a burst.
- **Page efficiently.** Use `limit=100` and walk the list with cursors. See [Pagination](https://rais.app/docs/pagination.md).
- **One key per service.** Services that share a key share its budget.

~~~python
import time
import requests

def get_with_backoff(url, headers, attempts=5):
    for attempt in range(attempts):
        response = requests.get(url, headers=headers, timeout=30)
        if response.status_code != 429:
            return response
        time.sleep(float(response.headers.get("Retry-After", 2 ** attempt)))
    return response
~~~

---

# Pagination

> Walk through lists of payments, refunds and events with cursors.

Source: https://rais.app/docs/pagination

Every endpoint that returns a collection, `GET /payments`, `GET /refunds` and `GET /events`, uses the same cursor-based pagination. Results come **newest first**.

## The list envelope

~~~json
{
  "object": "list",
  "data": [
    { "id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33", "object": "payment", "status": "paid" }
  ],
  "has_more": true,
  "next_cursor": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33"
}
~~~


- `object` (string): always `list`.
- `data` (array): the objects of this page.
- `has_more` (boolean): `true` when older objects remain.
- `next_cursor` (string, nullable): pass it as `starting_after` to get the next page. `null` on the last page.


## Parameters


- `limit` (integer, optional): how many objects to return, from 1 to 100. Defaults to 20.
- `starting_after` (string, optional): the cursor of the page to return, which is the `next_cursor` of the previous page (the id of its last object).


A cursor that is not the id of an object of your store answers `400` with `invalid_cursor`. A cursor that is not a valid id does too. A `limit` below 1 or above 100 answers `400` with `parameter_out_of_range`.

## Walk through every page


**Request**

```bash
curl 'https://api.rais.app/v1/payments?limit=2' \
  -H "Authorization: Bearer rais_sk_test_..."
```


Send the first request without a cursor. While `has_more` is `true`, send the next one with `starting_after` set to `next_cursor`.

~~~javascript
async function* allPayments(query = "") {
  let cursor = null;
  do {
    const url = new URL("https://api.rais.app/v1/payments");
    url.searchParams.set("limit", "100");
    if (cursor) url.searchParams.set("starting_after", cursor);
    for (const [key, value] of new URLSearchParams(query)) url.searchParams.set(key, value);

    const response = await fetch(url, { headers: { Authorization: `Bearer ${process.env.RAIS_SECRET_KEY}` } });
    const page = await response.json();
    yield* page.data;
    cursor = page.has_more ? page.next_cursor : null;
  } while (cursor);
}

for await (const payment of allPayments("status=paid")) console.log(payment.id);
~~~

~~~python
import os
import requests

def all_payments(**filters):
    cursor = None
    while True:
        params = {"limit": 100, **filters}
        if cursor:
            params["starting_after"] = cursor
        page = requests.get(
            "https://api.rais.app/v1/payments",
            params=params,
            headers={"Authorization": f"Bearer {os.environ['RAIS_SECRET_KEY']}"},
            timeout=30,
        ).json()
        yield from page["data"]
        if not page["has_more"]:
            return
        cursor = page["next_cursor"]

for payment in all_payments(status="paid"):
    print(payment["id"])
~~~

## Good to know

- Pages are stable: new objects appear at the start of the list and never shift the pages you are still walking through.
- Filters work with pagination. For payments: `status`, `reference`, `created_gte` and `created_lte` (Unix seconds). For refunds: `payment`. For events: `type`. A filter with an invalid value answers `400 invalid_parameter`, but a parameter the API does not know is **ignored**: `?stauts=paid` returns the unfiltered list.
- Events can be listed for 30 days only.
- Pass the cursor exactly as received. Do not build one yourself.

---

# Versioning

> The Rais-Version header, what counts as a breaking change and how upgrades work.

Source: https://rais.app/docs/versioning

The Raïs API is versioned by date. The current version is **2026-10-26**.

## Where the version appears

- Every response, errors included, carries it in the `Rais-Version` header:

~~~http
HTTP/1.1 200 OK
Rais-Version: 2026-10-26
Rais-Request-Id: req_8f3a1c9d2b7e4a60
~~~

- Every [event](https://rais.app/docs/webhooks.md) carries it as `api_version`, which tells you what shape its payload has.
- The [OpenAPI document](/openapi.json) states it as `info.version`.

## Breaking and non-breaking changes

Changes that could break an integration will only ever come with a **new version**. They are announced in the [changelog](https://rais.app/docs/changelog.md) before they apply.

These changes are **not** breaking, and can happen within a version at any time:

- a new endpoint, a new optional request parameter, a new response field;
- a new value of an enumeration, for example a new event type or a new payment status;
- a new error code, or a new header;
- a change to the wording of an error `message`;
- longer ids, and a different order of the keys of an object.

These are breaking, and need a new version: removing or renaming a field, changing its type or its meaning, making an optional parameter required, and removing an endpoint or an event.

## Write tolerant code

- Ignore response fields you do not know.
- Do not fail on an event type, a status or an error code you do not know: handle the unknown value with a sensible default, and answer unknown events with a `2xx` status.
- Branch on error `code`, never on `message`.
- Do not depend on the order of the keys of a JSON object.

## Upgrading

When a new version is released, the changelog says what changes, why, and from when. Read it before you upgrade, test with sandbox keys, and watch the `Rais-Version` header of your responses in your logs.

---

# Security and safety

> How to handle keys, verify webhooks, protect personal data, and what Raïs does with card data.

Source: https://rais.app/docs/security

A payment integration holds three kinds of secrets: your API keys, your webhook signing secrets and your customers' data. This page says what Raïs does about each of them, and what is left to you.

## Card data never touches your servers

The payer types their card on a page hosted by **Raïs** (or by **SATIM**, with `payment_page: satim`), over HTTPS. The card number, expiry and security code go from the payer's browser to that page and on to SATIM. They never pass through your website, your server or your mobile app, so you never have to receive, store, transmit or protect them. What your systems receive is a payment object with the brand, the last four digits and a masked number.

Every card payment is authenticated with **3-D Secure** by SATIM: the payer confirms with a one-time password from their bank, which proves that they hold the card.

The hosted checkout cannot be embedded in another page (it forbids being framed), restricts what the browser may load with a strict content security policy, and is served with `no-store` caching.

## What Raïs does

| Area | What Raïs does |
| --- | --- |
| Transport | The API and the hosted checkout are served over HTTPS. API responses carry a `Strict-Transport-Security` header, `Cache-Control: no-store`, `X-Content-Type-Options: nosniff` and a content security policy that forbids loading anything. |
| API keys | A key has 256 bits of randomness and is shown once. Raïs stores only its SHA-256 hash, so it cannot show it again and a database leak does not reveal it. Keys have scopes and an optional IP allowlist, have no expiry date, and can be rolled and revoked. |
| Isolation | A key belongs to one store and one environment. It cannot read, cancel, capture or refund the payments, refunds and events of another store or of the other environment: the answer is `404`, as if they did not exist. |
| Webhooks | Every webhook of the current format is signed with HMAC-SHA256 over a timestamp and the raw body, and is never sent unsigned. Raïs checks the target address before every attempt, refuses loopback, private and internal addresses, never follows a redirect, and switches off an endpoint that keeps failing. |
| Rate limiting | Each key is limited to 60 requests a second (bursts of 120), and an address that sends 30 failed authentications in a minute is throttled. Every failure of authentication gets the same answer, so a key cannot be guessed from the errors. |
| Retries | Idempotency keys make a repeated request safe: nothing is created or refunded twice. |
| Stored cards | Cards kept for a customer (see below) and the card details of a payment in progress are stored encrypted with AES-256-GCM. Every value has its own data key, wrapped by a master key that is kept outside the database, so a copy of the database alone is of no use. |
| Your account | Dashboard accounts can turn on two-factor authentication with an authenticator app, and come with backup codes. Team members have roles: only owners, admins and developers manage API keys and webhooks, and only owners and admins refund payments and change store settings. |
| Audit log | Sensitive actions are written to an append-only audit log with who did them and when: creating, rolling and revoking keys, changing webhook endpoints, rolling a signing secret, refunds from the dashboard, store changes. Secrets are never written to it. |
| Verification | Live payments need a verified business: Raïs reviews the company's documents and the identity of its owners before a store can take live payments. |
| Logs | Raïs logs each API request once, with its request id, method, path, status, duration, key prefix and client address. It never logs headers, query strings or bodies, which is where secrets and personal data would be. |

Raïs does not claim a PCI DSS or SOC 2 certification, and nothing in these pages should be read as one.

## API keys

- Keep secret keys on your server, in a secret manager or environment variables. Never in front-end code, mobile apps, repositories, logs or support tickets.
- The API sends no CORS headers: browsers cannot use a key, by design.
- Give each service its own key, with the **fewest scopes** it needs, and an **IP allowlist** when your servers have fixed addresses.
- **Roll** keys on a schedule and when people who knew them leave. Rolling with a grace period needs no downtime.
- If a key may have leaked: roll or revoke it **first**, then review recent payments and refunds in the dashboard, and contact salam@rais.app with the request ids you care about.

See [Authentication](https://rais.app/docs/authentication.md).

## Webhooks

- **Verify every signature** on the raw body, in constant time, before you read anything else. Reject a request without a valid `Rais-Signature`.
- **Check the timestamp.** A tolerance of 300 seconds stops an attacker from replaying a captured request later. Keep your server's clock accurate (NTP).
- **De-duplicate on the event `id`**, because delivery is at least once. A replay inside the tolerance window then does nothing.
- **Use https.** A live endpoint must use it; sandbox endpoints should too.
- **Do not rely on the sender's IP address.** The signature is the proof.
- **Rotate the signing secret** when it may have been exposed. During the 24 hours that follow, both secrets sign, so nothing is missed.
- The legacy format, kept for stores that configured a webhook URL before API keys existed, is signed only when the store has a secret: set one, and verify it.

See [Webhooks](https://rais.app/docs/webhooks.md).

## Threats and defences

| Threat | Defence |
| --- | --- |
| A stolen key | Scopes, IP allowlist, rolling and revocation; keys are stored only as a one-way hash at Raïs. |
| A forged webhook | The HMAC signature, which only Raïs and you can compute. |
| A replayed webhook | The signed timestamp with a 5 minute tolerance, and de-duplication on the event id. |
| A duplicated request | The `Idempotency-Key` header. |
| A forged return redirect | Never trust the address. Confirm with the API or the webhook. |
| A tampered amount | Compute amounts on your server only; never accept an amount from a browser or an app. |
| Clickjacking on the checkout | The checkout refuses to be framed. |
| Key guessing | Throttling of repeated failed authentications (30 a minute per address) and one generic answer for every kind of failure. |
| A payer's data in the wrong hands | Send only the personal data you need, and treat what you receive like any customer data. |

## TLS

The API and the hosted checkout are served over HTTPS. Call `https://api.rais.app` for the API, send the payer to the `https://pay.rais.app` address of the `checkout_url`, keep certificate verification on in your HTTP client, and never use `http://` for live traffic.

## Personal data

Payments carry personal data: the payer's name, e-mail and phone number when you send them, and the card details SATIM returns.

**What Raïs stores about a payment:** its amount, currency, status, description, reference and metadata; the payer details you provided; the card brand, the masked card number (never more than the first six and last four digits), the cardholder name and the approval code that SATIM reports; the SATIM order id; its receipt as a file; and the events about it, which the API serves for 30 days.

**What Raïs does not give you:** a full card number, an expiry date or a security code. They are not in the API, in events or in receipts.

## Saved cards

A payer can choose to keep a card for next time. It is always their choice, and it works on the Raïs payment page only: the SATIM page collects the card itself, so nothing can be saved there. This is how it works:

- Create the payment with the `customer_id` of one of your customers: that names whose cards they are. A payment without it never offers to save a card.
- On the Raïs payment page the payer then sees a box to save the card for next time. It is not ticked: nothing is saved unless they tick it themselves.
- The card is kept, encrypted, only once the payment is paid, for that customer and for your store only. Its security code is kept with it, sealed in its own field, so the payer does not have to type it again. The box says so in plain words before they tick it.
- On a later payment with the same `customer_id`, the checkout lists their saved cards as masked numbers. The payer picks one and confirms with 3-D Secure, every time, like for any other card payment.
- A saved card can only pay for its own customer, and only in the store and the mode that saved it: a card saved on a sandbox payment is never offered on a live payment, nor a live card on a sandbox one. No API call returns it or charges it. In your dashboard you see a card's brand, last four digits and expiry, and you can remove it: it is then erased for good. Deleting a customer erases their cards too.
- Customers come from the dashboard (Customers: add one by hand, or find the ones Raïs made), or from your payments: when a payment that carries `customer.name` or `customer.email` is paid, Raïs makes a customer record from it and returns its id as `customer.id`. Pass that id as `customer_id` on the next payment.

Say in your own terms that payers may choose to keep a card for faster payments.

## Personal data: your part

- Send only the personal data you need. A name and an e-mail address are enough for a receipt.
- Never put card numbers, passwords, tokens or other secrets in `description`, `reference` or `metadata`: the description is sent to SATIM and printed on the receipt, and the reference is added to the address the payer returns to.
- Treat payer data in your database, logs and exports with the same care as any customer data, and delete it when you no longer need it.

The [Privacy policy](/privacy) describes how Raïs handles personal data.

## Safe integration checklist

- Secret keys only on servers, one per service, scopes minimal.
- Amounts computed on the server.
- Idempotency keys on every `POST` that creates something.
- Webhook signatures verified on the raw body; events processed once.
- Payments confirmed from the API or a webhook, never from a redirect.
- https for every live address.
- Request ids logged, secrets never logged.
- Keys and secrets rolled on a schedule.
- Two-factor authentication on every dashboard account that can manage keys or refund.

## Reporting a problem

If you find a vulnerability, write to salam@rais.app with a description and steps to reproduce it. Please do not access data that is not yours, and do not test against real payers.

---

# FAQ and troubleshooting

> Answers to the questions integrations raise, and what to check when something does not work.

Source: https://rais.app/docs/faq

## General

### Which currencies and cards are supported?

Payments are in Algerian dinars (`DZD`) only. Payers pay with CIB and Edahabia cards, processed by SATIM.

### How much does Raïs cost?

A paid payment costs SATIM's fee (0.7% of the amount, never less than 10.00 DA and never more than 300.00 DA) plus Raïs's (0.3%); a refund costs 10.00 DA. There is no subscription and no setup fee, a failed payment costs nothing, and every figure excludes VAT. See [Pricing and fees](https://rais.app/docs/pricing.md).

### What are the smallest and largest payments?

The smallest payment is 50.00 DA (5000 centimes), SATIM's minimum. The largest is 999999999999 centimes. The smallest refund is 1.00 DA.

### Can I call the API from a browser or a mobile app?

No. Secret keys must never leave your server, and the API sends no CORS headers on purpose. Create payments on your server and give the browser or the app the `checkout_url`. See [Mobile and app integrations](https://rais.app/docs/mobile.md).

### Where do I create keys and webhook endpoints?

In the dashboard, under **Developers**: **API keys**, **Webhooks** and **Events**.

## Payments

### Why do I get `invalid_amount`?

Amounts are integers in centimes. `5000.5`, `"5000"` and `1500.00` are refused. To charge 1,500 DA, send `150000`.

### Why do I get `parameter_unknown`?

The request has a field the API does not know, usually a typo. The `param` in the error names it.

### How long can a payer take to pay?

A payment stays payable for 24 hours by default. Set `expires_in` to anything from 300 seconds to 30 days. After that its status is `expired` and it cannot be paid.

### The payer came back but the payment is still `pending`

Your server may be asking before the result has reached Raïs. Retrieving a pending payment asks the gateway for the outcome, so retry after a moment, and rely on the webhook. If the payer abandoned the page, it stays `pending` until it expires. Nothing is sent when it expires: see the next question.

### How do I know that a payment expired?

There is no event for it. A payment that nobody paid reads as `expired` as soon as `expires_at` has passed: retrieve it, or compare `expires_at` with the clock. Close the matching order in your own system at that time.

### The payer paid and closed the page. Will I still be told?

Yes. Raïs asks the gateway about unpaid payments in the background, starting about two minutes after the payment session opened and for up to 48 hours, and sends `payment.succeeded` when the gateway says it was paid. See [Payments](https://rais.app/docs/payments.md#when-the-payer-pays-and-never-comes-back).

### My filter has no effect

Unknown **query** parameters are ignored, so `GET /payments?stauts=paid` returns every payment. Check the spelling: the filters are `status`, `reference`, `created_gte` and `created_lte`.

### A payment failed. Can the payer try again?

It depends on why it failed. If the **bank declined the card** (`failed` with `failure.code: payment_declined`), the payment is final: create a new payment, with a new `Idempotency-Key`. If the payer only left the page, pressed **Back to** or met an error before paying, the payment is still `pending`: the same `checkout_url` keeps working until `expires_at`, and the result page offers a **Try again** button. A `cancelled` or `expired` payment is final too.

### Can I send the payment link by e-mail or SMS?

Yes. `checkout_url` is a plain link to the hosted page: share it with the payer. Anyone who holds it can pay it, so send it only to the payer.

## Webhooks

### The signature does not match

The usual causes, in order:

1. You verified **parsed and re-serialised JSON** instead of the raw body. Read the bytes before any parsing.
2. A proxy or a framework changed the body (decoded it, re-encoded it, or added a newline).
3. You used the secret of **another endpoint** or another environment: sandbox and live endpoints have different secrets.
4. You compared the whole header with the hex digest. The header has `t=` and `v1=` parts.
5. Your clock is more than 300 seconds off.

Test your code with the [official test vectors](https://rais.app/docs/webhooks.md#verify-the-signature).

### No webhook arrives

Check, in this order: the endpoint is **enabled** (after 20 consecutive failed deliveries it is switched off); it subscribes to the event type; its **environment** matches the payment (sandbox endpoints get sandbox events only); the address is reachable from the internet and not `localhost` or a private address; a live endpoint uses `https://`; and your server answers with `2xx` and not a redirect. The delivery log of the dashboard shows each attempt and what your server answered.

### I received the same event twice

Delivery is at least once. De-duplicate on the event `id`. See [Webhooks](https://rais.app/docs/webhooks.md#handle-each-event-once).

### How long do retries go on?

Up to 8 attempts over about 20 hours, then the delivery is marked failed and can be resent from the dashboard.

## Checkout and return URLs

### `status=paid` is in the address, but the API says `pending`

Believe the API. The address can be opened by anybody, with any parameters. See [Hosted checkout and return URLs](https://rais.app/docs/checkout.md#never-trust-the-redirect).

### `status=failed` is in the address, but the API says `pending`

The payer's attempt did not go through, but the payment is not over: they can press **Try again** and pay until `expires_at`. Do not cancel the order because of the address. See [Hosted checkout and return URLs](https://rais.app/docs/checkout.md#status-failed-does-not-always-end-the-payment).

### The payer was not sent back to my site

The result page never sends the payer back by itself: it stays on screen so they can read the payment's details, and a **Return to** button opens your `success_url` or `cancel_url`. The button is missing when the payment has no `success_url` or `cancel_url` and your store has no default, or when the address does not pass the rules for the environment (for example `http://` on a live payment), in which case Raïs does not use it.

### The checkout does not show in my iframe

It cannot be embedded: it forbids being framed, to protect payers. Redirect to it or open it in a browser tab.

### The deep link does not open my app

Check that the scheme in `success_url` matches the one your app registers, that the payer's browser session is allowed to open it (use `ASWebAuthenticationSession` or Custom Tabs, not a plain web view), and that you did not add a space or a non-ASCII character to the address.

## Refunds and receipts

### `payment_not_refundable`

Only `paid` and `partially_refunded` payments can be refunded.

### My refund is `pending`

The gateway's answer was lost, and the amount is reserved until the refund is settled by hand. Do not repeat it with a new key, and contact support with the refund id. See [Refunds](https://rais.app/docs/refunds.md#pending-refunds).

### The receipt answers 404

Only paid, partially refunded and refunded payments have a receipt, and a key only sees receipts of its own store and environment. See [Receipts](https://rais.app/docs/receipts.md).

### `insufficient_balance`

A live refund is taken out of your store's balance together with its fee (10.00 DA), so the balance must cover both: "The store's balance is not sufficient to cover this refund and its fee." Top up your balance, wait for payments to come in, or refund a smaller amount. See [Refunds](https://rais.app/docs/refunds.md#what-a-refund-costs).

### Are the fees returned when I refund a payment?

No. The fee of a payment is not returned when it is refunded, in full or in part, and the refund has its own fee of 10.00 DA. See [Pricing and fees](https://rais.app/docs/pricing.md).

## Going live

### My live key answers `401 invalid_api_key`

The key is unknown, revoked or expired, it is used from an address outside its allowlist, or its store is not approved for live payments (any more). The business has to be verified before a live key can exist: see [Going live](https://rais.app/docs/going-live.md). The API never says which of these it is.

### I used a live key with a sandbox payment id

Sandbox and live are separate. The payment is not found (`404`) because it belongs to the other environment.

### Is Raïs PCI DSS or SOC 2 certified?

Raïs does not claim either certification. What the documentation states is what the platform does: the card is typed on a page hosted by Raïs or SATIM and never reaches your servers, keys are stored hashed, saved cards are encrypted. See [Security and safety](https://rais.app/docs/security.md).

## Quick reference

| You see | Probably | Do |
| --- | --- | --- |
| `401 invalid_api_key` | A wrong, revoked or expired key, a call from an address outside the allowlist, or a store that is suspended or not approved for live payments | Check the key, its environment and the store |
| `403 insufficient_scope` | The key lacks the scope | Create a key with the scope |
| `400 invalid_amount` | A float or a string | Send an integer in centimes |
| `400 amount_too_small` | Less than 50.00 DA | Raise the amount |
| `400 invalid_url` | A bad return URL for the environment | Use https, or your app scheme |
| `404 payment_not_found` | Another store or environment, or a bad id | Use the key of the right store and environment |
| `409 payment_not_cancellable` | The payment is not pending | Refund it instead if it is paid |
| `400 insufficient_balance` | A live refund and its fee are more than your balance | Top up your balance, or refund less |
| `422 idempotency_key_reused` | The same key with different parameters | Use a new key for a new request |
| `429 rate_limit_exceeded` | Too many requests, or too many failed authentications from this address | Wait for Retry-After, and stop using revoked keys |
| `503 gateway_unavailable` | The gateway cannot be reached | Retry shortly with the same key |

Still stuck? Write to salam@rais.app with the `Rais-Request-Id` of the request that failed.

---

# Use these docs with AI

> Open any page in ChatGPT or Claude, copy it as Markdown, or give an assistant llms.txt and the OpenAPI file.

Source: https://rais.app/docs/ai-tools

Every page of these docs is also available as plain Markdown, and the whole documentation has machine-readable indexes, so you can use it in the AI tools you already work with.

## On every page

The **Copy page** button and the menu next to it, at the top of each page, do these things:

- **Copy page** (also **Copy page as Markdown**) copies the page as Markdown, ready to paste into a chat or an editor.
- **View as Markdown** opens the Markdown version of the page: add `.md` to any docs address, for example `https://rais.app/docs/payments.md`.
- **Open in ChatGPT** and **Open in Claude** start a conversation that asks the assistant to read the Markdown address of the page, so you can ask questions about it. The address in the prompt is always the public one on rais.app.
- **Copy llms.txt URL** and **Copy OpenAPI URL** copy the address of the two files below, to give to a tool that asks for one.

## Files for assistants

| File | What it is |
| --- | --- |
| [`/llms.txt`](https://rais.app/llms.txt) | An index of the documentation: one line per page, with its title, its Markdown address and a one-sentence description. The place an assistant should start. |
| [`/llms-full.txt`](https://rais.app/llms-full.txt) | Every page of the documentation in a single Markdown file. Use it when you want an assistant to answer from all of it. |
| [`/openapi.json`](https://rais.app/openapi.json) | The OpenAPI 3.1 description of every endpoint, with schemas and examples. Use it to generate a client, a Postman collection or tests. |
| `/docs/<page>.md` | One page as Markdown. API reference pages too, for example `/docs/api/create-payment.md`. |

All of them are public, need no authentication, and are the same content as the pages you read here: they are generated from it. The OpenAPI file describes the same API the pages document, and carries the production address `https://api.rais.app/v1` as its server.

## Prompts that work

- "Read https://rais.app/docs/webhooks.md and write a Laravel controller that verifies the Rais-Signature header and marks an order as paid once."
- "Using https://rais.app/openapi.json, generate a typed Python client for the payments and refunds endpoints."
- "Read https://rais.app/llms.txt, then explain what I need to do before I can take live payments."

## Be careful

- Check generated code against the [API reference](https://rais.app/docs/api.md). The details that assistants get wrong most often are **amounts** (integers in centimes: `500000` is 5,000.00 DA), the **raw body** in signature verification, and the idempotency key.
- **Never paste a secret key** or a webhook signing secret into an AI tool, an issue or a chat. Use placeholders such as `rais_sk_test_...`.
- Assistants can be out of date. When an answer disagrees with these pages, the pages are right.

---

# API reference

> Every endpoint of the Raïs API: parameters, request and response objects, examples in nine languages and the errors each can return.

Source: https://rais.app/docs/api

The Raïs API is a REST API with predictable URLs, JSON request and response bodies, and standard HTTP status codes. Use it from your server to create payments, follow them, refund them and read events.

## Base URL

```text
https://api.rais.app/v1
```

The sandbox and live environments share the base URL: the **key** you send decides which one a request belongs to. Keys start with `rais_sk_test_` for the sandbox and `rais_sk_live_` for live.

## Authentication

Send your secret key as a bearer token:


**Request**

```bash
curl https://api.rais.app/v1/account \
  -H "Authorization: Bearer rais_sk_test_..."
```


See [Authentication](https://rais.app/docs/authentication.md) for scopes, rotation and IP allowlists.

## Requests and responses

- Request bodies are JSON (`Content-Type: application/json`). Unknown fields are refused, which catches typos.
- **Amounts** are integers in centimes: `500000` is 5,000.00 DA. The only currency is `DZD`.
- **Timestamps** are Unix time in seconds.
- **Ids** of payments, refunds and stores are UUIDs. Events have ids starting with `evt_`.
- Every object has an `object` field that names its type.
- Lists use cursors, newest first. See [Pagination](https://rais.app/docs/pagination.md).
- `POST` requests that create something accept an `Idempotency-Key`. See [Idempotency and retries](https://rais.app/docs/idempotency.md).
- Every response carries `Rais-Request-Id` and `Rais-Version: 2026-10-26` headers.
- There are no CORS headers: the API is for servers. See [Security and safety](https://rais.app/docs/security.md).

## Errors

Every error uses one envelope with a `type`, a stable `code`, a `message`, the offending `param` and a `request_id`. See [Errors](https://rais.app/docs/errors.md).

## Endpoints


| Method | Path | Description |
| --- | --- | --- |
| `GET` | `/v1/account` | [Retrieve your account](https://rais.app/docs/api/retrieve-account.md) |
| `POST` | `/v1/payments` | [Create a payment](https://rais.app/docs/api/create-payment.md) |
| `GET` | `/v1/payments` | [List payments](https://rais.app/docs/api/list-payments.md) |
| `GET` | `/v1/payments/{payment_id}` | [Retrieve a payment](https://rais.app/docs/api/retrieve-payment.md) |
| `POST` | `/v1/payments/{payment_id}/cancel` | [Cancel a payment](https://rais.app/docs/api/cancel-payment.md) |
| `POST` | `/v1/payments/{payment_id}/refunds` | [Refund a payment](https://rais.app/docs/api/create-refund.md) |
| `GET` | `/v1/refunds/{refund_id}` | [Retrieve a refund](https://rais.app/docs/api/retrieve-refund.md) |
| `GET` | `/v1/refunds` | [List refunds](https://rais.app/docs/api/list-refunds.md) |
| `GET` | `/v1/events/{event_id}` | [Retrieve an event](https://rais.app/docs/api/retrieve-event.md) |
| `GET` | `/v1/events` | [List events](https://rais.app/docs/api/list-events.md) |
| `GET` | `/v1/payments/{payment_id}/receipt` | [Retrieve the receipt of a payment](https://rais.app/docs/api/retrieve-payment-receipt.md) |


## Objects


- [Payment](https://rais.app/docs/api/objects/payment.md): one attempt to collect an amount from a payer.
- [Refund](https://rais.app/docs/api/objects/refund.md): money returned for a paid payment.
- [Event](https://rais.app/docs/api/objects/event.md): what happened to a payment or a refund.
- [Account](https://rais.app/docs/api/objects/account.md): the store behind your key.
- [Receipt](https://rais.app/docs/api/objects/receipt.md): a signed link to a payer's PDF receipt.
- [Error](https://rais.app/docs/api/objects/error.md): the envelope of every failure.


## The OpenAPI document

The complete description of the API is published as an OpenAPI 3.1 document at [https://rais.app/openapi.json](/openapi.json). This reference is generated from it, so the two cannot disagree. Use it to generate clients, tests and mocks.

---

# Create a payment

> Creates a payment and registers it with the payment gateway.

Source: https://rais.app/docs/api/create-payment

`POST /v1/payments`

Required scope: `payments:write`.

Redirect the payer to the returned `checkout_url`; when they have paid, `status` becomes `paid` (read the payment, or listen for the `payment.succeeded` event).

A **sandbox** key creates a test payment (`livemode: false`); a **live** key a real one, which requires your store to have completed business verification (`live_mode_not_enabled` otherwise). Send an `Idempotency-Key` header so that retrying after a timeout can never create two payments.

## Request

### Headers

- `Idempotency-Key` (string, optional): A unique value (at most 255 characters, a UUID is ideal) that makes the request safe to repeat: the same key with the same request returns the original answer without creating anything twice.

### Body

Required, JSON.

- `amount` (integer, optional): The amount to collect, as an INTEGER in centimes: 500000 is 5,000.00 DA. Between 5000 (50 DA, SATIM's minimum) and 999999999999. Floats and strings are refused. Optional when `items` is given (the amount is then the sum of quantity x unit_amount); if both are given they must agree.
- `currency` (string, optional): The currency. Only `DZD` (Algerian dinar) is supported; it is the default. At most 32 characters.
- `description` (string, optional): What the payment is for. Shown to the payer and sent to SATIM. At most 512 characters.
- `reference` (string, optional): Your own identifier of the order. Returned as is, and searchable with `GET /payments?reference=`. At most 64 characters.
- `customer` (object, optional): Who is paying. Explicit values take precedence over those of `customer_id`.
  - `name` (string, optional): The payer's full name. At most 255 characters.
  - `email` (string, optional): The payer's e-mail address. At most 255 characters.
  - `phone` (string, optional): The payer's phone number. At most 50 characters.
- `customer_id` (string (uuid), optional): The id of one of YOUR customers (of the store AND the mode the key belongs to: a sandbox key sees sandbox customers and a live key live ones; any other id answers `customer_not_found`). Fills in the payer's name and e-mail. On the Raïs payment page it also lets the payer choose to save their card for next time and pay with a card they saved earlier: they pick it and confirm with 3-D Secure (the card and its security code are stored encrypted, for your store only). Saved cards are kept per mode: a sandbox payment never offers a live card, nor a live payment a sandbox one.
- `items` (array of object, optional): What is being bought, at most 50 lines. Shown on the receipt. At most 50 items.
  - `name` (string, required): What is being bought. At most 255 characters.
  - `description` (string, optional): More detail, shown on the receipt. At most 512 characters.
  - `quantity` (integer, required): How many units (an integer, at least 1). Between 1 and 1000000.
  - `unit_amount` (integer, required): Price of ONE unit, in centimes (an integer). Between 0 and 999999999999.
- `success_url` (string, optional): Where the payer is sent after a successful payment. `https://` (live and sandbox), `http://` (sandbox only) or your app's own scheme such as `myapp://pay/result`. At most 512 characters, no credentials, no spaces.
- `cancel_url` (string, optional): Where the payer is sent if they cancel or the payment fails. Same rules as `success_url`.
- `metadata` (object, optional): Up to 20 key/value pairs of your own. Keys are at most 40 characters; values must be strings of at most 500 characters.
- `payment_page` (string, optional): Which page the payer pays on: `rais` (Raïs' own page) or `satim` (SATIM's). Defaults to your store's setting. One of `rais`, `satim`.
- `language` (string, optional): The language the payment page opens in. A payer who picks another language on the page (the switcher in its header) keeps their choice for every payment page. Omitted: the page follows the payer's browser (English, French or Arabic). One of `en`, `fr`, `ar`.
- `expires_in` (integer, optional): Seconds the payment stays payable: 300 to 2592000 (30 days). Defaults to 86400 (24 hours). Between 300 and 2592000.

### Example request

```bash
curl https://api.rais.app/v1/payments \
  -H "Authorization: Bearer rais_sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: b7e1c1c6-6f0a-4d2f-9d8b-3a5c2f1e7a90" \
  -d '{
  "amount": 500000,
  "currency": "DZD",
  "description": "Order #1042",
  "reference": "order-1042",
  "customer": {
    "name": "Amina Benali",
    "email": "amina@example.dz",
    "phone": "+213550000000"
  },
  "success_url": "https://shop.example/thanks",
  "cancel_url": "https://shop.example/cart",
  "metadata": {
    "cart_id": "c_8812"
  },
  "expires_in": 3600
}'
```

## Response

### 201: The payment was created. `status` is `pending` until the payer pays.

Returns the [Payment object](https://rais.app/docs/api/objects/payment.md).

```json
{
  "id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
  "object": "payment",
  "status": "pending",
  "amount": 500000,
  "currency": "DZD",
  "description": "Order #1042",
  "reference": "order-1042",
  "customer": {
    "id": null,
    "name": "Amina Benali",
    "email": "amina@example.dz",
    "phone": "+213550000000"
  },
  "items": [
    {
      "name": "Running shoes",
      "description": null,
      "quantity": 2,
      "unit_amount": 250000
    }
  ],
  "metadata": {
    "cart_id": "c_8812"
  },
  "livemode": false,
  "payment_page": "rais",
  "checkout_url": "https://pay.rais.app/pay/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
  "success_url": "https://shop.example/thanks",
  "cancel_url": "https://shop.example/cart",
  "expires_at": 1793003600,
  "created": 1793000000,
  "paid_at": null,
  "amount_refunded": 0,
  "refunded": false,
  "fees": null,
  "net": null,
  "receipt_url": null,
  "failure": null,
  "payment_method": null,
  "processor": {
    "name": "satim",
    "order_id": "V721uPPfNNofVQAAABL3",
    "approval_code": null,
    "response_code": null
  }
}
```

## Errors

| Status | Code | Example message |
| --- | --- | --- |
| 400 | `invalid_json` | The request body is not valid JSON. |
| 400 | `parameter_missing` | Provide `amount`, or `items` to compute it. |
| 400 | `parameter_unknown` | Unknown parameter. |
| 400 | `invalid_amount` | amount must be an integer number of centimes (500000 is 5,000.00 DA). |
| 400 | `amount_too_small` | The minimum amount is 50.00 DA (5000 centimes). |
| 400 | `amount_too_large` | The maximum amount is 9,999,999,999.99 DA (999999999999 centimes). |
| 400 | `amount_mismatch` | amount (400000) does not equal the sum of the items (500000). |
| 400 | `currency_not_supported` | Only DZD is supported. |
| 400 | `invalid_url` | Live payments require an https:// URL. |
| 400 | `invalid_metadata` | metadata can hold at most 20 keys. |
| 400 | `invalid_email` | The e-mail address is not valid. |
| 400 | `customer_not_found` | No such customer. |
| 400 | `invalid_idempotency_key` | The Idempotency-Key header must be 1 to 255 printable ASCII characters. |
| 401 | `invalid_api_key` | Invalid API key provided. |
| 403 | `insufficient_scope` | This API key does not have the 'payments:write' permission. |
| 403 | `account_disabled` | This store is suspended or disabled. |
| 403 | `live_mode_not_enabled` | Complete business verification to take live payments. |
| 409 | `idempotency_in_progress` | A request with this Idempotency-Key is still being processed. Retry in a moment. |
| 422 | `idempotency_key_reused` | This Idempotency-Key was already used with different request parameters. |
| 429 | `rate_limit_exceeded` | Too many requests. Slow down and retry after the delay in the Retry-After header. |
| 500 | `internal_error` | Something went wrong on our side. Quote the request id to support. |
| 502 | `gateway_rejected` | The payment gateway refused to create the payment. |
| 503 | `gateway_unavailable` | The payment gateway is temporarily unavailable. Please try again later. |

See [Errors](https://rais.app/docs/errors.md) for every code and how to react.

## Related guides

- [Payments](https://rais.app/docs/payments.md)
- [Hosted checkout and return URLs](https://rais.app/docs/checkout.md)
- [Idempotency and retries](https://rais.app/docs/idempotency.md)

---

# List payments

> Returns the payments of your store in the environment of the key, newest first, 20 at a time by default.

Source: https://rais.app/docs/api/list-payments

`GET /v1/payments`

Required scope: `payments:read`.

Filter by `status`, by your own `reference`, or by creation time (Unix seconds); page with `starting_after`.

## Request

### Query parameters

- `status` (string, optional): Only payments with this status. One of `pending`, `paid`, `failed`, `cancelled`, `expired`, `refunded`, `partially_refunded`, `reversed`.
- `reference` (string, optional): Only payments with exactly this `reference`. At most 64 characters.
- `created_gte` (integer, optional): Only payments created at or after this Unix time (seconds). Between 0 and 253402300799.
- `created_lte` (integer, optional): Only payments created at or before this Unix time (seconds). Between 0 and 253402300799.
- `limit` (integer, optional): How many objects to return: 1 to 100 (default 20). Between 1 and 100. Default `20`.
- `starting_after` (string, optional): The cursor of the page to return: pass the `next_cursor` of the previous page (the id of its last object). At most 100 characters.

### Example request

```bash
curl 'https://api.rais.app/v1/payments?status=paid&limit=3' \
  -H "Authorization: Bearer rais_sk_test_..."
```

## Response

### 200: A page of payments.

- `object` (string): Always `list`. Always `list`.
- `data` (array of Payment): The payments of this page, newest first.
- `has_more` (boolean): True when there are older payments: pass `next_cursor` as `starting_after`.
- `next_cursor` (string, nullable): The value to pass as `starting_after` to get the next page; null on the last page.

```json
{
  "object": "list",
  "data": [
    {
      "id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
      "object": "payment",
      "status": "pending",
      "amount": 500000,
      "currency": "DZD",
      "description": "Order #1042",
      "reference": "order-1042",
      "customer": {
        "id": null,
        "name": "Amina Benali",
        "email": "amina@example.dz",
        "phone": "+213550000000"
      },
      "items": [
        {
          "name": "Running shoes",
          "description": null,
          "quantity": 2,
          "unit_amount": 250000
        }
      ],
      "metadata": {
        "cart_id": "c_8812"
      },
      "livemode": false,
      "payment_page": "rais",
      "checkout_url": "https://pay.rais.app/pay/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
      "success_url": "https://shop.example/thanks",
      "cancel_url": "https://shop.example/cart",
      "expires_at": 1793003600,
      "created": 1793000000,
      "paid_at": null,
      "amount_refunded": 0,
      "refunded": false,
      "fees": null,
      "net": null,
      "receipt_url": null,
      "failure": null,
      "payment_method": null,
      "processor": {
        "name": "satim",
        "order_id": "V721uPPfNNofVQAAABL3",
        "approval_code": null,
        "response_code": null
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

## Errors

| Status | Code | Example message |
| --- | --- | --- |
| 400 | `invalid_parameter` | Invalid value. |
| 400 | `invalid_cursor` | No such payment: the starting_after cursor is unknown. |
| 401 | `invalid_api_key` | Invalid API key provided. |
| 403 | `insufficient_scope` | This API key does not have the 'payments:write' permission. |
| 403 | `account_disabled` | This store is suspended or disabled. |
| 403 | `live_mode_not_enabled` | Complete business verification to take live payments. |
| 429 | `rate_limit_exceeded` | Too many requests. Slow down and retry after the delay in the Retry-After header. |
| 500 | `internal_error` | Something went wrong on our side. Quote the request id to support. |

See [Errors](https://rais.app/docs/errors.md) for every code and how to react.

## Related guides

- [Pagination](https://rais.app/docs/pagination.md)

---

# Retrieve a payment

> Returns a payment of your store.

Source: https://rais.app/docs/api/retrieve-payment

`GET /v1/payments/{payment_id}`

Required scope: `payments:read`.

If the payment is still `pending`, the gateway is asked for the outcome (at most every 15 seconds), so a payer coming back from the payment page always sees the truth even if their browser never reached us. A payment of another store, or of the other environment (sandbox vs live), answers 404.

## Request

### Path parameters

- `payment_id` (string, required): The id of the payment.

### Example request

```bash
curl https://api.rais.app/v1/payments/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33 \
  -H "Authorization: Bearer rais_sk_test_..."
```

## Response

### 200: The payment.

Returns the [Payment object](https://rais.app/docs/api/objects/payment.md).

```json
{
  "id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
  "object": "payment",
  "status": "pending",
  "amount": 500000,
  "currency": "DZD",
  "description": "Order #1042",
  "reference": "order-1042",
  "customer": {
    "id": null,
    "name": "Amina Benali",
    "email": "amina@example.dz",
    "phone": "+213550000000"
  },
  "items": [
    {
      "name": "Running shoes",
      "description": null,
      "quantity": 2,
      "unit_amount": 250000
    }
  ],
  "metadata": {
    "cart_id": "c_8812"
  },
  "livemode": false,
  "payment_page": "rais",
  "checkout_url": "https://pay.rais.app/pay/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
  "success_url": "https://shop.example/thanks",
  "cancel_url": "https://shop.example/cart",
  "expires_at": 1793003600,
  "created": 1793000000,
  "paid_at": null,
  "amount_refunded": 0,
  "refunded": false,
  "fees": null,
  "net": null,
  "receipt_url": null,
  "failure": null,
  "payment_method": null,
  "processor": {
    "name": "satim",
    "order_id": "V721uPPfNNofVQAAABL3",
    "approval_code": null,
    "response_code": null
  }
}
```

## Errors

| Status | Code | Example message |
| --- | --- | --- |
| 401 | `invalid_api_key` | Invalid API key provided. |
| 403 | `insufficient_scope` | This API key does not have the 'payments:write' permission. |
| 403 | `account_disabled` | This store is suspended or disabled. |
| 403 | `live_mode_not_enabled` | Complete business verification to take live payments. |
| 404 | `payment_not_found` | No such payment. |
| 429 | `rate_limit_exceeded` | Too many requests. Slow down and retry after the delay in the Retry-After header. |
| 500 | `internal_error` | Something went wrong on our side. Quote the request id to support. |

See [Errors](https://rais.app/docs/errors.md) for every code and how to react.

## Related guides

- [Payments](https://rais.app/docs/payments.md)

---

# Cancel a payment

> Cancels a payment that is still pending, so its checkout page can no longer be used.

Source: https://rais.app/docs/api/cancel-payment

`POST /v1/payments/{payment_id}/cancel`

Required scope: `payments:write`.

A payment in any other state (paid, failed, expired, already cancelled...) cannot be cancelled and answers `409 payment_not_cancellable`. Emits a `payment.cancelled` event.

## Request

### Path parameters

- `payment_id` (string, required): The id of the payment.

### Example request

```bash
curl -X POST https://api.rais.app/v1/payments/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33/cancel \
  -H "Authorization: Bearer rais_sk_test_..."
```

## Response

### 200: The cancelled payment.

Returns the [Payment object](https://rais.app/docs/api/objects/payment.md).

```json
{
  "id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
  "object": "payment",
  "status": "cancelled",
  "amount": 500000,
  "currency": "DZD",
  "description": "Order #1042",
  "reference": "order-1042",
  "customer": {
    "id": null,
    "name": "Amina Benali",
    "email": "amina@example.dz",
    "phone": "+213550000000"
  },
  "items": [
    {
      "name": "Running shoes",
      "description": null,
      "quantity": 2,
      "unit_amount": 250000
    }
  ],
  "metadata": {
    "cart_id": "c_8812"
  },
  "livemode": false,
  "payment_page": "rais",
  "checkout_url": "https://pay.rais.app/pay/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
  "success_url": "https://shop.example/thanks",
  "cancel_url": "https://shop.example/cart",
  "expires_at": 1793003600,
  "created": 1793000000,
  "paid_at": null,
  "amount_refunded": 0,
  "refunded": false,
  "fees": null,
  "net": null,
  "receipt_url": null,
  "failure": null,
  "payment_method": null,
  "processor": {
    "name": "satim",
    "order_id": "V721uPPfNNofVQAAABL3",
    "approval_code": null,
    "response_code": null
  }
}
```

## Errors

| Status | Code | Example message |
| --- | --- | --- |
| 401 | `invalid_api_key` | Invalid API key provided. |
| 403 | `insufficient_scope` | This API key does not have the 'payments:write' permission. |
| 403 | `account_disabled` | This store is suspended or disabled. |
| 403 | `live_mode_not_enabled` | Complete business verification to take live payments. |
| 404 | `payment_not_found` | No such payment. |
| 409 | `payment_not_cancellable` | Only a pending payment can be cancelled; this one is paid. |
| 429 | `rate_limit_exceeded` | Too many requests. Slow down and retry after the delay in the Retry-After header. |
| 500 | `internal_error` | Something went wrong on our side. Quote the request id to support. |

See [Errors](https://rais.app/docs/errors.md) for every code and how to react.

## Related guides

- [Payments](https://rais.app/docs/payments.md)

---

# Retrieve the receipt of a payment

> Returns a signed link (valid for 15 minutes) to the PDF receipt of a paid payment of your store: the payer, the items, the card used (masked), the approval code and any refunds.

Source: https://rais.app/docs/api/retrieve-payment-receipt

`GET /v1/payments/{payment_id}/receipt`

Required scope: `payments:read`.

The receipt is in the language of the payment page; a sandbox payment's receipt is clearly marked as a test. Only payments that were paid (`paid`, `partially_refunded`, `refunded`) have a receipt: any other payment, a payment of another store or of the other environment (sandbox vs live) answers 404. The receipt is regenerated after a refund, so the link always shows the current state.

## Request

### Path parameters

- `payment_id` (string, required): The id of the payment.

### Example request

```bash
curl https://api.rais.app/v1/payments/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33/receipt \
  -H "Authorization: Bearer rais_sk_test_..."
```

## Response

### 200: A signed link to the receipt.

Returns the [Receipt object](https://rais.app/docs/api/objects/receipt.md).

```json
{
  "object": "receipt",
  "url": "https://files.example.com/storage/receipts/Rais-receipt-1042.pdf?signature=...",
  "expires_at": 1793000900
}
```

## Errors

| Status | Code | Example message |
| --- | --- | --- |
| 401 | `invalid_api_key` | Invalid API key provided. |
| 403 | `insufficient_scope` | This API key does not have the 'payments:write' permission. |
| 403 | `account_disabled` | This store is suspended or disabled. |
| 403 | `live_mode_not_enabled` | Complete business verification to take live payments. |
| 404 | `payment_not_found` | No such payment. |
| 429 | `rate_limit_exceeded` | Too many requests. Slow down and retry after the delay in the Retry-After header. |
| 500 | `internal_error` | Something went wrong on our side. Quote the request id to support. |
| 503 | `gateway_unavailable` | The payment gateway is temporarily unavailable. Please try again later. |

See [Errors](https://rais.app/docs/errors.md) for every code and how to react.

## Related guides

- [Receipts](https://rais.app/docs/receipts.md)

---

# Refund a payment

> Refunds all or part of a paid payment.

Source: https://rais.app/docs/api/create-refund

`POST /v1/payments/{payment_id}/refunds`

Required scope: `refunds:write`.

Without `amount`, everything still refundable is refunded; a payment can be refunded several times, never beyond what was paid. The refund is performed with the payment gateway before the answer is returned: `succeeded` (201), or `pending` (202) if the gateway's answer was lost, in which case the amount stays reserved and you must look at the refund (`GET /refunds/{id}`) before trying again. A refusal by the bank answers `402 refund_declined`. A key can only refund payments of its own store and environment. Send an `Idempotency-Key` so that retrying can never refund twice.

## Request

### Headers

- `Idempotency-Key` (string, optional): A unique value (at most 255 characters, a UUID is ideal) that makes the request safe to repeat: the same key with the same request returns the original answer without creating anything twice.

### Path parameters

- `payment_id` (string, required): The id of the payment.

### Body

Optional, JSON.

- `amount` (integer, optional): How much to refund, as an INTEGER in centimes (at least 100 = 1 DA). Defaults to everything still refundable.
- `reason` (string, optional): Why you are refunding. For your records. At most 255 characters.

### Example request

```bash
curl https://api.rais.app/v1/payments/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33/refunds \
  -H "Authorization: Bearer rais_sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: b7e1c1c6-6f0a-4d2f-9d8b-3a5c2f1e7a90" \
  -d '{
  "amount": 150000,
  "reason": "Customer returned one item"
}'
```

## Response

### 201: The refund succeeded.

Returns the [Refund object](https://rais.app/docs/api/objects/refund.md).

```json
{
  "id": "0c8a1d52-6e7b-4f0a-9b3d-7d2e4a8c5f10",
  "object": "refund",
  "payment_id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
  "amount": 150000,
  "currency": "DZD",
  "status": "succeeded",
  "reason": "Customer returned one item",
  "failure": null,
  "fees": {
    "satim": 800,
    "rais": 200,
    "total": 1000
  },
  "livemode": false,
  "created": 1793000900
}
```

### 202: The refund was sent but the gateway's answer was lost: `status` is `pending` and the amount is reserved.

```json
{
  "id": "0c8a1d52-6e7b-4f0a-9b3d-7d2e4a8c5f10",
  "object": "refund",
  "payment_id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
  "amount": 150000,
  "currency": "DZD",
  "status": "pending",
  "reason": "Customer returned one item",
  "failure": null,
  "fees": {
    "satim": 800,
    "rais": 200,
    "total": 1000
  },
  "livemode": false,
  "created": 1793000900
}
```

## Errors

| Status | Code | Example message |
| --- | --- | --- |
| 400 | `invalid_json` | The request body is not valid JSON. |
| 400 | `invalid_amount` | amount must be an integer number of centimes (500000 is 5,000.00 DA). |
| 400 | `amount_too_small` | The minimum amount is 50.00 DA (5000 centimes). |
| 400 | `refund_exceeds_balance` | The refund (500000 centimes) exceeds what can still be refunded (200000 centimes). |
| 400 | `insufficient_balance` | The store's balance is not sufficient to cover this refund and its fee. |
| 400 | `invalid_idempotency_key` | The Idempotency-Key header must be 1 to 255 printable ASCII characters. |
| 401 | `invalid_api_key` | Invalid API key provided. |
| 402 | `refund_declined` | The bank refused the refund. |
| 403 | `insufficient_scope` | This API key does not have the 'payments:write' permission. |
| 403 | `account_disabled` | This store is suspended or disabled. |
| 403 | `live_mode_not_enabled` | Complete business verification to take live payments. |
| 404 | `payment_not_found` | No such payment. |
| 409 | `payment_not_refundable` | Cannot refund a payment with status 'pending'. |
| 409 | `idempotency_in_progress` | A request with this Idempotency-Key is still being processed. Retry in a moment. |
| 422 | `idempotency_key_reused` | This Idempotency-Key was already used with different request parameters. |
| 429 | `rate_limit_exceeded` | Too many requests. Slow down and retry after the delay in the Retry-After header. |
| 500 | `internal_error` | Something went wrong on our side. Quote the request id to support. |
| 503 | `gateway_unavailable` | The payment gateway is temporarily unavailable. Please try again later. |

See [Errors](https://rais.app/docs/errors.md) for every code and how to react.

## Related guides

- [Refunds](https://rais.app/docs/refunds.md)
- [Idempotency and retries](https://rais.app/docs/idempotency.md)

---

# Retrieve a refund

> Returns a refund of your store.

Source: https://rais.app/docs/api/retrieve-refund

`GET /v1/refunds/{refund_id}`

Required scope: `payments:read`.

A refund of another store, or of the other environment, answers 404.

## Request

### Path parameters

- `refund_id` (string, required): The id of the refund.

### Example request

```bash
curl https://api.rais.app/v1/refunds/0c8a1d52-6e7b-4f0a-9b3d-7d2e4a8c5f10 \
  -H "Authorization: Bearer rais_sk_test_..."
```

## Response

### 200: The refund.

Returns the [Refund object](https://rais.app/docs/api/objects/refund.md).

```json
{
  "id": "0c8a1d52-6e7b-4f0a-9b3d-7d2e4a8c5f10",
  "object": "refund",
  "payment_id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
  "amount": 150000,
  "currency": "DZD",
  "status": "succeeded",
  "reason": "Customer returned one item",
  "failure": null,
  "fees": {
    "satim": 800,
    "rais": 200,
    "total": 1000
  },
  "livemode": false,
  "created": 1793000900
}
```

## Errors

| Status | Code | Example message |
| --- | --- | --- |
| 401 | `invalid_api_key` | Invalid API key provided. |
| 403 | `insufficient_scope` | This API key does not have the 'payments:write' permission. |
| 403 | `account_disabled` | This store is suspended or disabled. |
| 403 | `live_mode_not_enabled` | Complete business verification to take live payments. |
| 404 | `refund_not_found` | No such refund. |
| 429 | `rate_limit_exceeded` | Too many requests. Slow down and retry after the delay in the Retry-After header. |
| 500 | `internal_error` | Something went wrong on our side. Quote the request id to support. |

See [Errors](https://rais.app/docs/errors.md) for every code and how to react.

## Related guides

- [Refunds](https://rais.app/docs/refunds.md)

---

# List refunds

> Returns the refunds of your store in the environment of the key, newest first.

Source: https://rais.app/docs/api/list-refunds

`GET /v1/refunds`

Required scope: `payments:read`.

Pass `payment` to see only the refunds of one payment.

## Request

### Query parameters

- `payment` (string, optional): Only the refunds of this payment (its id). At most 64 characters.
- `limit` (integer, optional): How many objects to return: 1 to 100 (default 20). Between 1 and 100. Default `20`.
- `starting_after` (string, optional): The cursor of the page to return: pass the `next_cursor` of the previous page (the id of its last object). At most 100 characters.

### Example request

```bash
curl 'https://api.rais.app/v1/refunds?limit=3' \
  -H "Authorization: Bearer rais_sk_test_..."
```

## Response

### 200: A page of refunds.

- `object` (string): Always `list`. Always `list`.
- `data` (array of Refund): The refunds of this page, newest first.
- `has_more` (boolean): True when there are older refunds.
- `next_cursor` (string, nullable): The value to pass as `starting_after` for the next page; null on the last page.

```json
{
  "object": "list",
  "data": [
    {
      "id": "0c8a1d52-6e7b-4f0a-9b3d-7d2e4a8c5f10",
      "object": "refund",
      "payment_id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
      "amount": 150000,
      "currency": "DZD",
      "status": "succeeded",
      "reason": "Customer returned one item",
      "failure": null,
      "fees": {
        "satim": 800,
        "rais": 200,
        "total": 1000
      },
      "livemode": false,
      "created": 1793000900
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

## Errors

| Status | Code | Example message |
| --- | --- | --- |
| 400 | `invalid_parameter` | Invalid value. |
| 400 | `invalid_cursor` | No such payment: the starting_after cursor is unknown. |
| 401 | `invalid_api_key` | Invalid API key provided. |
| 403 | `insufficient_scope` | This API key does not have the 'payments:write' permission. |
| 403 | `account_disabled` | This store is suspended or disabled. |
| 403 | `live_mode_not_enabled` | Complete business verification to take live payments. |
| 429 | `rate_limit_exceeded` | Too many requests. Slow down and retry after the delay in the Retry-After header. |
| 500 | `internal_error` | Something went wrong on our side. Quote the request id to support. |

See [Errors](https://rais.app/docs/errors.md) for every code and how to react.

## Related guides

- [Pagination](https://rais.app/docs/pagination.md)

---

# Retrieve an event

> Returns an event of your store in the environment of the key, if it happened in the last 30 days.

Source: https://rais.app/docs/api/retrieve-event

`GET /v1/events/{event_id}`

Required scope: `events:read`.

## Request

### Path parameters

- `event_id` (string, required): The id of the event (`evt_...`). At most 100 characters.

### Example request

```bash
curl https://api.rais.app/v1/events/evt_Qm9dMhJ0k8s2Wv7Yc3XnLpAb \
  -H "Authorization: Bearer rais_sk_test_..."
```

## Response

### 200: The event.

Returns the [Event object](https://rais.app/docs/api/objects/event.md).

```json
{
  "id": "evt_Qm9dMhJ0k8s2Wv7Yc3XnLpAb",
  "object": "event",
  "api_version": "2026-10-26",
  "created": 1793000300,
  "livemode": false,
  "type": "payment.succeeded",
  "data": {
    "object": {
      "id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
      "object": "payment",
      "status": "paid",
      "amount": 500000,
      "currency": "DZD"
    }
  }
}
```

## Errors

| Status | Code | Example message |
| --- | --- | --- |
| 401 | `invalid_api_key` | Invalid API key provided. |
| 403 | `insufficient_scope` | This API key does not have the 'payments:write' permission. |
| 403 | `account_disabled` | This store is suspended or disabled. |
| 403 | `live_mode_not_enabled` | Complete business verification to take live payments. |
| 404 | `event_not_found` | No such event. |
| 429 | `rate_limit_exceeded` | Too many requests. Slow down and retry after the delay in the Retry-After header. |
| 500 | `internal_error` | Something went wrong on our side. Quote the request id to support. |

See [Errors](https://rais.app/docs/errors.md) for every code and how to react.

## Related guides

- [Webhooks](https://rais.app/docs/webhooks.md)

---

# List events

> Returns the events of your store in the environment of the key from the last 30 days, newest first.

Source: https://rais.app/docs/api/list-events

`GET /v1/events`

Required scope: `events:read`.

Filter with `type` (for instance `payment.succeeded`); page with `starting_after`.

## Request

### Query parameters

- `type` (string, optional): Only events of this type: `payment.succeeded`, `payment.failed`, `payment.cancelled`, `payment.reversed`, `refund.succeeded` or `refund.failed`. At most 64 characters.
- `limit` (integer, optional): How many objects to return: 1 to 100 (default 20). Between 1 and 100. Default `20`.
- `starting_after` (string, optional): The cursor of the page to return: pass the `next_cursor` of the previous page (the id of its last object). At most 100 characters.

### Example request

```bash
curl 'https://api.rais.app/v1/events?type=payment.succeeded&limit=3' \
  -H "Authorization: Bearer rais_sk_test_..."
```

## Response

### 200: A page of events.

- `object` (string): Always `list`. Always `list`.
- `data` (array of Event): The events of this page, newest first.
- `has_more` (boolean): True when there are older events.
- `next_cursor` (string, nullable): The value to pass as `starting_after` for the next page; null on the last page.

```json
{
  "object": "list",
  "data": [
    {
      "id": "evt_Qm9dMhJ0k8s2Wv7Yc3XnLpAb",
      "object": "event",
      "api_version": "2026-10-26",
      "created": 1793000300,
      "livemode": false,
      "type": "payment.succeeded",
      "data": {
        "object": {
          "id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
          "object": "payment",
          "status": "paid",
          "amount": 500000,
          "currency": "DZD"
        }
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

## Errors

| Status | Code | Example message |
| --- | --- | --- |
| 400 | `invalid_parameter` | Invalid value. |
| 400 | `invalid_cursor` | No such payment: the starting_after cursor is unknown. |
| 401 | `invalid_api_key` | Invalid API key provided. |
| 403 | `insufficient_scope` | This API key does not have the 'payments:write' permission. |
| 403 | `account_disabled` | This store is suspended or disabled. |
| 403 | `live_mode_not_enabled` | Complete business verification to take live payments. |
| 429 | `rate_limit_exceeded` | Too many requests. Slow down and retry after the delay in the Retry-After header. |
| 500 | `internal_error` | Something went wrong on our side. Quote the request id to support. |

See [Errors](https://rais.app/docs/errors.md) for every code and how to react.

## Related guides

- [Webhooks](https://rais.app/docs/webhooks.md)

---

# Retrieve your account

> Returns the store the API key belongs to and the environment of the key.

Source: https://rais.app/docs/api/retrieve-account

`GET /v1/account`

Any valid API key may call this endpoint, whatever its scopes.

Any valid key can call it, whatever its scopes: it is the simplest way to check that a key works.

## Request

### Example request

```bash
curl https://api.rais.app/v1/account \
  -H "Authorization: Bearer rais_sk_test_..."
```

## Response

### 200: Your store.

Returns the [Account object](https://rais.app/docs/api/objects/account.md).

```json
{
  "object": "account",
  "id": "7d0b6a3e-1c52-4f8e-9a44-2b6e8f1d0c35",
  "name": "Boutique Alger",
  "livemode": false,
  "live_enabled": false,
  "currency": "DZD",
  "payment_page": "rais"
}
```

## Errors

| Status | Code | Example message |
| --- | --- | --- |
| 401 | `invalid_api_key` | Invalid API key provided. |
| 403 | `insufficient_scope` | This API key does not have the 'payments:write' permission. |
| 403 | `account_disabled` | This store is suspended or disabled. |
| 403 | `live_mode_not_enabled` | Complete business verification to take live payments. |
| 429 | `rate_limit_exceeded` | Too many requests. Slow down and retry after the delay in the Retry-After header. |
| 500 | `internal_error` | Something went wrong on our side. Quote the request id to support. |

See [Errors](https://rais.app/docs/errors.md) for every code and how to react.

## Related guides

- [Authentication](https://rais.app/docs/authentication.md)

---

# The Payment object

> A payment is one attempt to collect an amount from a payer.

Source: https://rais.app/docs/api/objects/payment

You create it with `POST /payments`, send the payer to its `checkout_url`, and follow it until `status` is `paid`, or it fails, expires or is cancelled. Events about a payment carry this object in `data.object`.

## Attributes

- `id` (string): The unique identifier of the payment.
- `object` (string): The type of the object. Always `payment`.
- `status` (string): Where the payment stands. `pending`: waiting for the payer. `paid`: money received. `failed`: declined or errored (see `failure`). `cancelled`: you cancelled it. `expired`: nobody paid before `expires_at`. `refunded` / `partially_refunded`: money was returned. `reversed`: SATIM reversed the authorisation. One of `pending`, `paid`, `failed`, `cancelled`, `expired`, `refunded`, `partially_refunded`, `reversed`.
- `amount` (integer): The amount, in centimes.
- `currency` (string): The currency. Always `DZD`.
- `description` (string, nullable): What the payment is for.
- `reference` (string, nullable): Your own identifier of the order.
- `customer` (object, nullable): Who is paying, if known.
  - `id` (string, nullable): The id of the linked customer record, if any.
  - `name` (string, nullable): The payer's name.
  - `email` (string, nullable): The payer's e-mail address.
  - `phone` (string, nullable): The payer's phone number.
- `items` (array of object): What is being bought (empty if not given).
  - `name` (string): What was bought.
  - `description` (string, nullable): More detail.
  - `quantity` (integer): How many units.
  - `unit_amount` (integer): Price of one unit, in centimes.
- `metadata` (object): Your key/value pairs, as sent.
- `livemode` (boolean): `false` for a sandbox (test) payment, `true` for a live one.
- `payment_page` (string): The page the payer pays on. One of `rais`, `satim`.
- `checkout_url` (string): The hosted payment page. Redirect the payer here.
- `success_url` (string, nullable): Where the payer is sent after paying.
- `cancel_url` (string, nullable): Where the payer is sent if they cancel or fail.
- `expires_at` (integer, nullable): When an unpaid payment stops being payable (Unix time, seconds).
- `created` (integer): When the payment was created (Unix time, seconds).
- `paid_at` (integer, nullable): When the payment was paid (Unix time, seconds).
- `amount_refunded` (integer): How much has been refunded so far, in centimes.
- `refunded` (boolean): True once the payment is fully refunded.
- `fees` (object, nullable): What this payment cost you, in centimes, excluding VAT: SATIM's fee and Raïs's fee. Set once the payment is paid, `null` before. A test payment shows the simulated fees. They are not returned when the payment is refunded; each refund has its own fee (see the Refund object). See the pricing page.
  - `satim` (integer): SATIM's fee, in centimes, excluding VAT.
  - `rais` (integer): Raïs's fee, in centimes, excluding VAT.
  - `total` (integer): What the transaction costs: `satim` + `rais`, in centimes, excluding VAT.
- `net` (integer, nullable): What you receive for this payment: `amount` minus `fees.total`, in centimes, before any refund. `null` until it is paid.
- `receipt_url` (string, nullable): Where the receipt can be downloaded once the payment is paid.
- `failure` (object, nullable): Why the payment failed; set when `status` is `failed`.
  - `code` (string): Why it failed, machine-readable: `payment_declined`, `processing_error`, `gateway_unavailable`, `refund_declined`...
  - `message` (string): Why it failed, in words.
- `payment_method` (object, nullable): How the payer paid; set once the payment is paid.
  - `type` (string): The kind of payment method. Always `card`.
  - `brand` (string): The card scheme: `cib`, `dahabia` or `unknown`.
  - `last4` (string): The last four digits of the card.
  - `masked` (string): The card number as masked by SATIM (first six and last four digits at most).
- `processor` (object): What the processor (SATIM) knows about the payment.
  - `name` (string): The payment processor. Always `satim`.
  - `order_id` (string, nullable): SATIM's identifier of the order.
  - `approval_code` (string, nullable): The authorisation code, once the payment is approved.
  - `response_code` (string, nullable): SATIM's response code (`00` = approved).

## Example

```json
{
  "id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
  "object": "payment",
  "status": "pending",
  "amount": 500000,
  "currency": "DZD",
  "description": "Order #1042",
  "reference": "order-1042",
  "customer": {
    "id": null,
    "name": "Amina Benali",
    "email": "amina@example.dz",
    "phone": "+213550000000"
  },
  "items": [
    {
      "name": "Running shoes",
      "description": null,
      "quantity": 2,
      "unit_amount": 250000
    }
  ],
  "metadata": {
    "cart_id": "c_8812"
  },
  "livemode": false,
  "payment_page": "rais",
  "checkout_url": "https://pay.rais.app/pay/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
  "success_url": "https://shop.example/thanks",
  "cancel_url": "https://shop.example/cart",
  "expires_at": 1793003600,
  "created": 1793000000,
  "paid_at": null,
  "amount_refunded": 0,
  "refunded": false,
  "fees": null,
  "net": null,
  "receipt_url": null,
  "failure": null,
  "payment_method": null,
  "processor": {
    "name": "satim",
    "order_id": "V721uPPfNNofVQAAABL3",
    "approval_code": null,
    "response_code": null
  }
}
```

---

# The Refund object

> A refund returns all or part of a paid payment to the payer.

Source: https://rais.app/docs/api/objects/refund

A payment can be refunded several times, never beyond what was paid. Refund events carry this object in `data.object`.

## Attributes

- `id` (string): The unique identifier of the refund.
- `object` (string): The type of the object. Always `refund`.
- `payment_id` (string): The payment that was refunded.
- `amount` (integer): The amount refunded, in centimes.
- `currency` (string): The currency. Always `DZD`.
- `status` (string): `succeeded`: SATIM refunded. `failed`: SATIM refused (see `failure`). `pending`: the request was sent but SATIM's answer was lost; the amount stays reserved until the refund is checked. Do not retry with a new Idempotency-Key before looking at it. One of `succeeded`, `failed`, `pending`.
- `reason` (string, nullable): The reason you gave.
- `failure` (object, nullable): Why the refund failed; set when `status` is `failed`.
  - `code` (string): Why it failed, machine-readable: `payment_declined`, `processing_error`, `gateway_unavailable`, `refund_declined`...
  - `message` (string): Why it failed, in words.
- `fees` (object, nullable): What this refund cost you, in centimes, excluding VAT (a flat fee per refund, whatever its amount). Set once the refund `succeeded`; `null` while it is `pending` and when it `failed` (a refund that did not happen costs nothing). A test refund shows the simulated fees.
  - `satim` (integer): SATIM's fee, in centimes, excluding VAT.
  - `rais` (integer): Raïs's fee, in centimes, excluding VAT.
  - `total` (integer): What the transaction costs: `satim` + `rais`, in centimes, excluding VAT.
- `livemode` (boolean): `false` for a sandbox refund.
- `created` (integer): When the refund was requested (Unix time, seconds).

## Example

```json
{
  "id": "0c8a1d52-6e7b-4f0a-9b3d-7d2e4a8c5f10",
  "object": "refund",
  "payment_id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
  "amount": 150000,
  "currency": "DZD",
  "status": "succeeded",
  "reason": "Customer returned one item",
  "failure": null,
  "fees": {
    "satim": 800,
    "rais": 200,
    "total": 1000
  },
  "livemode": false,
  "created": 1793000900
}
```

---

# The Event object

> An event records something that happened to a payment or a refund.

Source: https://rais.app/docs/api/objects/event

The same object is sent, signed, to your webhook endpoints and can be read with the events API for 30 days.

## Attributes

- `id` (string): The unique identifier of the event.
- `object` (string): The type of the object. Always `event`.
- `api_version` (string): The API version the payload was rendered with.
- `created` (integer): When the event happened (Unix time, seconds).
- `livemode` (boolean): `false` for a sandbox event.
- `type` (string): What happened. One of `payment.succeeded`, `payment.failed`, `payment.cancelled`, `payment.reversed`, `refund.succeeded`, `refund.failed`.
- `data` (object): The object the event is about.
  - `object` (object): The Payment or Refund object as it was when the event happened.

## Example

```json
{
  "id": "evt_Qm9dMhJ0k8s2Wv7Yc3XnLpAb",
  "object": "event",
  "api_version": "2026-10-26",
  "created": 1793000300,
  "livemode": false,
  "type": "payment.succeeded",
  "data": {
    "object": {
      "id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33",
      "object": "payment",
      "status": "paid",
      "amount": 500000,
      "currency": "DZD"
    }
  }
}
```

---

# The Account object

> The store an API key belongs to, and the environment of the key.

Source: https://rais.app/docs/api/objects/account

Retrieving it is the simplest way to check that a key works.

## Attributes

- `object` (string): The type of the object. Always `account`.
- `id` (string): The unique identifier of your store.
- `name` (string): The name of your store.
- `livemode` (boolean): The environment of the key used for this request.
- `live_enabled` (boolean): Whether your store may take live payments (business verification complete).
- `currency` (string): The only supported currency. Always `DZD`.
- `payment_page` (string): The payment page your payments use by default. One of `rais`, `satim`.

## Example

```json
{
  "object": "account",
  "id": "7d0b6a3e-1c52-4f8e-9a44-2b6e8f1d0c35",
  "name": "Boutique Alger",
  "livemode": false,
  "live_enabled": false,
  "currency": "DZD",
  "payment_page": "rais"
}
```

---

# The Receipt object

> A short-lived signed link to the PDF receipt of a paid payment.

Source: https://rais.app/docs/api/objects/receipt

Ask for a new one whenever you need it again instead of storing the link.

## Attributes

- `object` (string): Always `receipt`. Always `receipt`.
- `url` (string): A signed link to the PDF receipt. It works without any key, from a browser or a server, until `expires_at`: give it to your customer right away, or fetch a new one when you need it again.
- `expires_at` (integer): When `url` stops working (Unix time, seconds): 15 minutes after the request.

## Example

```json
{
  "expires_at": 1793000900,
  "object": "receipt",
  "url": "https://files.example.com/storage/receipts/Rais-receipt-1042.pdf?signature=..."
}
```

---

# The Error object

> Every response that is not a success has exactly this envelope, whatever went wrong.

Source: https://rais.app/docs/api/objects/error

The `request_id` is also in the `Rais-Request-Id` response header: quote it when you contact support.

## Attributes

- `error` (object): The error. Every non-2xx response of the API has exactly this envelope.
  - `type` (string): The category of the error. It decides how to react (fix the request, retry, call support). One of `authentication_error`, `permission_error`, `invalid_request_error`, `not_found_error`, `idempotency_error`, `rate_limit_error`, `api_error`, `payment_error`.
  - `code` (string): A stable, machine-readable identifier of the problem (see the list of error codes).
  - `message` (string): A human-readable explanation, safe to show to a developer.
  - `param` (string, nullable): The request parameter the error is about, if any.
  - `request_id` (string): The identifier of the request (also in the Rais-Request-Id header). Quote it to support.

## Example

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "amount_too_small",
    "message": "The minimum amount is 50.00 DA (5000 centimes).",
    "param": "amount",
    "request_id": "req_8f3a1c9d2b7e4a60"
  }
}
```

---

# Changelog

> What changed in the Raïs API and in these docs, newest first.

Source: https://rais.app/docs/changelog

New entries are added at the top. A change that could break an integration will only ever ship under a new API version and is announced here first. See [Versioning](https://rais.app/docs/versioning.md).

## 2026-11-02: the payer can e-mail the receipt, and no card number is shown

**Checkout and receipts**

- A paid result page shows the payment method as **CIB/Edahabia**, never the card brand and never a card number (masked or not). The PDF receipt, its printed copy and the receipt e-mail say the same.
- **Email receipt** sits next to **Print** on the result pages. The receipt goes to the address the payment already has (yours, or your saved customer's); when there is none the payer types one. A receipt is e-mailed once per payment. Test payments can e-mail theirs too: it is marked as a test.
- The receipt e-mail now carries the rows of the result page: the Raïs order ID, the order number, the approval code, the date and the payment method.
- The security check next to the terms is a visible badge: "Checking browser…", then "Captcha OK".

## 2026-11-02: the result page stays, and the checkout speaks of Raïs

**Checkout and receipts**

- The result page no longer sends the payer to your site after a 3 second countdown. It stays on screen so the payer can read the details of the payment, and its **Return to** button leads to your `success_url` or `cancel_url` as before. If your app relied on the automatic redirect to a deep link, the payer now taps the button. Webhooks and the API are unchanged: confirm payments from them, as always.
- A paid result shows the gateway's order id as the **Raïs order ID**; a failed one shows none. The name on the card is no longer shown, on the page or on the PDF receipt, which also names the order id **Raïs order ID**.
- The sandbox checkout no longer lists SATIM's test cards or the 3-D Secure password: type a card from [Test cards and sandbox](https://rais.app/docs/testing.md). A live payment never showed them.
- The checkout names SATIM only where a payment has an outcome: the result pages and the receipt carry SATIM's name and its support number.

## 2026-10-29: fees, and the payer's pages on their own address

**API**

- Fees. A payment carries `fees` (`satim`, `rais` and `total`, in centimes, excluding VAT) and `net` (`amount` minus `fees.total`), both `null` until it is paid. A refund carries its own `fees` once it has succeeded. Events and webhooks carry the same objects. The fields are additive: the API version does not change. See [Pricing and fees](https://rais.app/docs/pricing.md).
- `insufficient_balance`: a live refund now needs your balance to cover the refund **and its fee**.
- The sandbox shows simulated fees: nothing is charged.

**Checkout and receipts**

- `checkout_url` and `receipt_url` are on `https://pay.rais.app`; the API stays on `https://api.rais.app`. Use the address the API returns, as before. See [Hosted checkout and return URLs](https://rais.app/docs/checkout.md#where-the-page-lives).

**Documentation**

- A new guide, [Pricing and fees](https://rais.app/docs/pricing.md): the price list, when a fee is charged, examples and the fee fields.

## 2026-10-26: first public version

**API**

- Payments: create, retrieve, list and cancel, with integer amounts in centimes, items, metadata, a reference and an expiry.
- Refunds: full and partial refunds of paid payments, with pending and failed outcomes.
- Events: `payment.succeeded`, `payment.failed`, `payment.cancelled`, `payment.reversed`, `refund.succeeded` and `refund.failed`, readable for 30 days.
- Account: retrieve the store behind a key.
- Idempotency keys on payment and refund creation, cursor pagination, and one error envelope with request ids.
- Scoped secret keys for the sandbox and for live, with IP allowlists, rolling and revocation. A key has no expiry date: it works until it is rolled or revoked.

**Webhooks**

- Signed deliveries with the `Rais-Signature` header (HMAC-SHA256 over the timestamp and the raw body, with a five minute tolerance).
- At-least-once delivery with up to eight attempts over about 20 hours, endpoint health with automatic disabling, secret rotation, and a test event from the dashboard.
- The legacy format stays available, unchanged, for stores that configured a webhook URL before API keys existed.

**Checkout and receipts**

- Hosted checkout in English, French and Arabic, with 3-D Secure through SATIM.
- Return URLs: `payment_id`, `status`, `reference` and `order_number` are merged into your `success_url` or `cancel_url`, and custom app schemes are kept as they are. The older `orderId` parameter is no longer sent.
- After a successful payment the result page returns the payer to your site after a 3 second countdown, which the payer can stop.
- PDF receipts: `receipt_url` on paid, partially refunded and refunded payments, and `GET /payments/{id}/receipt` for a signed link valid for 15 minutes. Receipts are regenerated after a refund.
- The sandbox checkout shows SATIM's test cards. A live payment never does.

**Documentation**

- These docs, with the API reference generated from the OpenAPI document, code samples in nine languages, `llms.txt`, `llms-full.txt`, Markdown pages and the OpenAPI file at `/openapi.json`.