# 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`.