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