Skip to content
Raïs

API reference

API reference

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

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

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:

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

See Authentication 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.
  • POST requests that create something accept an Idempotency-Key. See Idempotency and retries.
  • 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.

Errors

Every error uses one envelope with a type, a stable code, a message, the offending param and a request_id. See Errors.

Endpoints

MethodPathDescription
GET/v1/accountRetrieve your account
POST/v1/paymentsCreate a payment
GET/v1/paymentsList payments
GET/v1/payments/{payment_id}Retrieve a payment
POST/v1/payments/{payment_id}/cancelCancel a payment
POST/v1/payments/{payment_id}/refundsRefund a payment
GET/v1/refunds/{refund_id}Retrieve a refund
GET/v1/refundsList refunds
GET/v1/events/{event_id}Retrieve an event
GET/v1/eventsList events
GET/v1/payments/{payment_id}/receiptRetrieve the receipt of a payment

Objects

Paymentone attempt to collect an amount from a payer.Refundmoney returned for a paid payment.Eventwhat happened to a payment or a refund.Accountthe store behind your key.Receipta signed link to a payer's PDF receipt.Errorthe 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. This reference is generated from it, so the two cannot disagree. Use it to generate clients, tests and mocks.