Introduction

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

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.

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 and Going live.

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.

Refunds

You can refund all or part of a paid payment, as many times as you like, never beyond what was paid. See Refunds.

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.

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.

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.

Conventions

Where to go next