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