{ "openapi": "3.1.0", "info": { "title": "Raïs API", "summary": "Accept CIB and Dahabia card payments in Algeria.", "description": "Accept CIB and Dahabia card payments in Algeria with a small, predictable REST API. You create a **payment**, send the\npayer to its `checkout_url`, and learn the outcome by reading the payment or through **events** / webhooks.\n\n## Authentication\n\nAuthenticate with your **secret API key** as a Bearer token:\n\n```\nAuthorization: Bearer rais_sk_test_...\n```\n\n| Key | Environment | What it does |\n|---|---|---|\n| `rais_sk_test_...` | **Sandbox** | Test payments (`livemode: false`). Always available. No money reaches your balance. |\n| `rais_sk_live_...` | **Live** | Real payments (`livemode: true`). Available once your business verification is complete. |\n\nA key belongs to **one store** and **one environment**. A sandbox key only ever sees sandbox payments and a live key only live\nones; anything else answers `404`. Keys carry **scopes** (`payments:read`, `payments:write`, `refunds:write`,\n`events:read`) and may be restricted to a list of IP addresses; a key without the scope an endpoint needs gets\n`403 insufficient_scope`.\n\n**Secret keys must never be used in a browser or a mobile app.** This API sends no CORS headers on purpose: call it from\nyour server only, and give your front end the `checkout_url` of the payment.\n\n## Amounts and currency\n\nAmounts are **integers in centimes**: `500000` is 5,000.00 DA. The only currency is `DZD`. The minimum payment is 5000\ncentimes (50 DA); the minimum refund is 100 centimes (1 DA). Floats and strings are refused.\n\n## Idempotency\n\n`POST /payments` and `POST /payments/{id}/refunds` accept an `Idempotency-Key` header (at most 255 characters, unique per\nrequest you intend to make; a UUID is a good choice). If you repeat a request with the same key after a timeout or a dropped\nconnection you get the **original answer back** (header `Idempotent-Replayed: true`), and nothing is created twice. The same\nkey with different parameters answers `422 idempotency_key_reused`; the same key while the first request is still running\nanswers `409 idempotency_in_progress` with a `Retry-After`. Only successful requests are remembered, for 24 hours; a request\nthat failed can be retried with the same key. Sandbox and live keys never share idempotency keys.\n\n## Pagination\n\nList endpoints return newest first: `{\"object\": \"list\", \"data\": [...], \"has_more\": true, \"next_cursor\": \"...\"}`. Pass\n`limit` (1 to 100, default 20) and, to get the next page, `starting_after` = the `next_cursor` of the previous page.\n\n## Errors\n\nEvery error has the same envelope, and the `Rais-Request-Id` header carries the same `request_id`:\n\n```json\n{\"error\": {\"type\": \"invalid_request_error\", \"code\": \"amount_too_small\", \"message\": \"...\", \"param\": \"amount\", \"request_id\": \"req_...\"}}\n```\n\n`type` tells you how to react: `authentication_error` (401, fix the key), `permission_error` (403), `invalid_request_error`\n(400/405/409, fix the request), `not_found_error` (404), `idempotency_error` (409/422), `rate_limit_error` (429, wait for\n`Retry-After`), `payment_error` (the payment gateway refused: 402/502) and `api_error` (500/503, retry later). `code` is stable and\nmachine-readable; `param` names the offending parameter.\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `invalid_api_key` | 401 | The key is missing, unknown, revoked, expired, not allowed from this IP address, or its store cannot use it. |\n| `insufficient_scope` | 403 | The key lacks the scope the endpoint needs. |\n| `account_disabled` | 403 | The store is suspended or disabled. |\n| `live_mode_not_enabled` | 403 | Complete business verification to take live payments. |\n| `rate_limit_exceeded` | 429 | Too many requests (60 per second, bursts of 120, per key) or too many failed authentications. |\n| `invalid_json`, `parameter_missing`, `parameter_unknown`, `invalid_parameter` | 400 | The request body or query is malformed. |\n| `invalid_amount`, `amount_too_small`, `amount_too_large`, `amount_mismatch` | 400 | The amount is not an integer, is outside 5000...999999999999 centimes, or disagrees with `items`. |\n| `currency_not_supported` | 400 | Only `DZD`. |\n| `invalid_url`, `invalid_metadata`, `invalid_email`, `customer_not_found` | 400 | A field is invalid (see `param`). |\n| `invalid_idempotency_key`, `invalid_cursor` | 400 | The header or the `starting_after` value is invalid. |\n| `refund_exceeds_balance`, `insufficient_balance` | 400 | The refund is more than what is left on the payment, or than your balance can cover (the refund plus its fee). |\n| `payment_not_found`, `refund_not_found`, `event_not_found`, `route_not_found` | 404 | Nothing there (or it belongs to another store or environment). |\n| `method_not_allowed` | 405 | Wrong HTTP method. |\n| `payment_not_cancellable`, `payment_not_refundable` | 409 | The payment is not in a state that allows it. |\n| `idempotency_in_progress` | 409 | The first request with this key is still running. |\n| `idempotency_key_reused` | 422 | The key was used with different parameters. |\n| `refund_declined` | 402 | The bank refused the refund. |\n| `gateway_rejected` | 502 | The payment gateway refused to create the payment. |\n| `gateway_unavailable` | 503 | The gateway cannot be reached; retry later. Nothing was created or refunded. |\n| `internal_error` | 500 | Our fault. Quote the `request_id`. |\n\n## Versioning\n\nThe current version is `2026-10-26`; every response carries it in the `Rais-Version` header. Events and webhooks carry it\nas `api_version`. Changes that could break an integration will only ever come with a new version.", "version": "2026-10-26" }, "servers": [ { "url": "https://api.rais.app/v1", "description": "Raïs API" } ], "paths": { "/account": { "get": { "tags": [ "Account" ], "summary": "Retrieve your account", "description": "Returns the store the API key belongs to and the environment of the key. Any valid key can call it, whatever its scopes: it is the simplest way to check that a key works.", "operationId": "retrieveAccount", "responses": { "200": { "description": "Your store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" }, "example": { "object": "account", "id": "7d0b6a3e-1c52-4f8e-9a44-2b6e8f1d0c35", "name": "Boutique Alger", "livemode": false, "live_enabled": false, "currency": "DZD", "payment_page": "rais" } } } }, "401": { "description": "The API key is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key provided.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } } } } }, "403": { "description": "The key lacks the scope, or the store cannot be used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "insufficient_scope": { "summary": "insufficient_scope", "value": { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "This API key does not have the 'payments:write' permission.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } }, "account_disabled": { "summary": "account_disabled", "value": { "error": { "type": "permission_error", "code": "account_disabled", "message": "This store is suspended or disabled.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } }, "live_mode_not_enabled": { "summary": "live_mode_not_enabled", "value": { "error": { "type": "permission_error", "code": "live_mode_not_enabled", "message": "Complete business verification to take live payments.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down and retry after the delay in the Retry-After header.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "internal_error", "value": { "error": { "type": "api_error", "code": "internal_error", "message": "Something went wrong on our side. Quote the request id to support.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } } } } } } } }, "/payments": { "post": { "tags": [ "Payments" ], "summary": "Create a payment", "description": "Creates a payment and registers it with the payment gateway. Redirect the payer to the returned `checkout_url`; when they have paid, `status` becomes `paid` (read the payment, or listen for the `payment.succeeded` event).\n\nA **sandbox** key creates a test payment (`livemode: false`); a **live** key a real one, which requires your store to have completed business verification (`live_mode_not_enabled` otherwise). Send an `Idempotency-Key` header so that retrying after a timeout can never create two payments.", "operationId": "createPayment", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A unique value (at most 255 characters, a UUID is ideal) that makes the request safe to repeat: the same key with the same request returns the original answer without creating anything twice.", "examples": [ "b7e1c1c6-6f0a-4d2f-9d8b-3a5c2f1e7a90" ], "title": "Idempotency-Key" }, "description": "A unique value (at most 255 characters, a UUID is ideal) that makes the request safe to repeat: the same key with the same request returns the original answer without creating anything twice." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentRequest" } } } }, "responses": { "201": { "description": "The payment was created. `status` is `pending` until the payer pays.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "example": { "id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33", "object": "payment", "status": "pending", "amount": 500000, "currency": "DZD", "description": "Order #1042", "reference": "order-1042", "customer": { "id": null, "name": "Amina Benali", "email": "amina@example.dz", "phone": "+213550000000" }, "items": [ { "name": "Running shoes", "description": null, "quantity": 2, "unit_amount": 250000 } ], "metadata": { "cart_id": "c_8812" }, "livemode": false, "payment_page": "rais", "checkout_url": "https://pay.rais.app/pay/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33", "success_url": "https://shop.example/thanks", "cancel_url": "https://shop.example/cart", "expires_at": 1793003600, "created": 1793000000, "paid_at": null, "amount_refunded": 0, "refunded": false, "fees": null, "net": null, "receipt_url": null, "failure": null, "payment_method": null, "processor": { "name": "satim", "order_id": "V721uPPfNNofVQAAABL3", "approval_code": null, "response_code": null } } } } }, "400": { "description": "The request is invalid; `param` names the offending field.", "content": { "application/json": { "examples": { "invalid_json": { "summary": "invalid_json", "value": { "error": { "type": "invalid_request_error", "code": "invalid_json", "message": "The request body is not valid JSON.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } }, "parameter_missing": { "summary": "parameter_missing", "value": { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "Provide `amount`, or `items` to compute it.", "param": "amount", "request_id": "req_8f3a1c9d2b7e4a60" } } }, "parameter_unknown": { "summary": "parameter_unknown", "value": { "error": { "type": "invalid_request_error", "code": "parameter_unknown", "message": "Unknown parameter.", "param": "ammount", "request_id": "req_8f3a1c9d2b7e4a60" } } }, "invalid_amount": { "summary": "invalid_amount", "value": { "error": { "type": "invalid_request_error", "code": "invalid_amount", "message": "amount must be an integer number of centimes (500000 is 5,000.00 DA).", "param": "amount", "request_id": "req_8f3a1c9d2b7e4a60" } } }, "amount_too_small": { "summary": "amount_too_small", "value": { "error": { "type": "invalid_request_error", "code": "amount_too_small", "message": "The minimum amount is 50.00 DA (5000 centimes).", "param": "amount", "request_id": "req_8f3a1c9d2b7e4a60" } } }, "amount_too_large": { "summary": "amount_too_large", "value": { "error": { "type": "invalid_request_error", "code": "amount_too_large", "message": "The maximum amount is 9,999,999,999.99 DA (999999999999 centimes).", "param": "amount", "request_id": "req_8f3a1c9d2b7e4a60" } } }, "amount_mismatch": { "summary": "amount_mismatch", "value": { "error": { "type": "invalid_request_error", "code": "amount_mismatch", "message": "amount (400000) does not equal the sum of the items (500000).", "param": "amount", "request_id": "req_8f3a1c9d2b7e4a60" } } }, "currency_not_supported": { "summary": "currency_not_supported", "value": { "error": { "type": "invalid_request_error", "code": "currency_not_supported", "message": "Only DZD is supported.", "param": "currency", "request_id": "req_8f3a1c9d2b7e4a60" } } }, "invalid_url": { "summary": "invalid_url", "value": { "error": { "type": "invalid_request_error", "code": "invalid_url", "message": "Live payments require an https:// URL.", "param": "success_url", "request_id": "req_8f3a1c9d2b7e4a60" } } }, "invalid_metadata": { "summary": "invalid_metadata", "value": { "error": { "type": "invalid_request_error", "code": "invalid_metadata", "message": "metadata can hold at most 20 keys.", "param": "metadata", "request_id": "req_8f3a1c9d2b7e4a60" } } }, "invalid_email": { "summary": "invalid_email", "value": { "error": { "type": "invalid_request_error", "code": "invalid_email", "message": "The e-mail address is not valid.", "param": "customer.email", "request_id": "req_8f3a1c9d2b7e4a60" } } }, "customer_not_found": { "summary": "customer_not_found", "value": { "error": { "type": "invalid_request_error", "code": "customer_not_found", "message": "No such customer.", "param": "customer_id", "request_id": "req_8f3a1c9d2b7e4a60" } } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": { "type": "invalid_request_error", "code": "invalid_idempotency_key", "message": "The Idempotency-Key header must be 1 to 255 printable ASCII characters.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "The API key is missing or invalid.", "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key provided.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The key lacks the scope, or the store cannot be used.", "content": { "application/json": { "examples": { "insufficient_scope": { "summary": "insufficient_scope", "value": { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "This API key does not have the 'payments:write' permission.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } }, "account_disabled": { "summary": "account_disabled", "value": { "error": { "type": "permission_error", "code": "account_disabled", "message": "This store is suspended or disabled.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } }, "live_mode_not_enabled": { "summary": "live_mode_not_enabled", "value": { "error": { "type": "permission_error", "code": "live_mode_not_enabled", "message": "Complete business verification to take live payments.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The first request with this Idempotency-Key is still running.", "content": { "application/json": { "examples": { "idempotency_in_progress": { "summary": "idempotency_in_progress", "value": { "error": { "type": "idempotency_error", "code": "idempotency_in_progress", "message": "A request with this Idempotency-Key is still being processed. Retry in a moment.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The Idempotency-Key was used with different parameters.", "content": { "application/json": { "examples": { "idempotency_key_reused": { "summary": "idempotency_key_reused", "value": { "error": { "type": "idempotency_error", "code": "idempotency_key_reused", "message": "This Idempotency-Key was already used with different request parameters.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "examples": { "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down and retry after the delay in the Retry-After header.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "examples": { "internal_error": { "summary": "internal_error", "value": { "error": { "type": "api_error", "code": "internal_error", "message": "Something went wrong on our side. Quote the request id to support.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The payment gateway refused to create the payment.", "content": { "application/json": { "examples": { "gateway_rejected": { "summary": "gateway_rejected", "value": { "error": { "type": "payment_error", "code": "gateway_rejected", "message": "The payment gateway refused to create the payment.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The payment gateway cannot be reached. Nothing was created; retry.", "content": { "application/json": { "examples": { "gateway_unavailable": { "summary": "gateway_unavailable", "value": { "error": { "type": "api_error", "code": "gateway_unavailable", "message": "The payment gateway is temporarily unavailable. Please try again later.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "tags": [ "Payments" ], "summary": "List payments", "description": "Returns the payments of your store in the environment of the key, newest first, 20 at a time by default. Filter by `status`, by your own `reference`, or by creation time (Unix seconds); page with `starting_after`.", "operationId": "listPayments", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "pending", "paid", "failed", "cancelled", "expired", "refunded", "partially_refunded", "reversed" ], "type": "string" }, { "type": "null" } ], "description": "Only payments with this status.", "examples": [ "paid" ], "title": "Status" }, "description": "Only payments with this status." }, { "name": "reference", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "description": "Only payments with exactly this `reference`.", "examples": [ "order-1042" ], "title": "Reference" }, "description": "Only payments with exactly this `reference`." }, { "name": "created_gte", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 253402300799, "minimum": 0 }, { "type": "null" } ], "description": "Only payments created at or after this Unix time (seconds).", "examples": [ 1793000000 ], "title": "Created Gte" }, "description": "Only payments created at or after this Unix time (seconds)." }, { "name": "created_lte", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer", "maximum": 253402300799, "minimum": 0 }, { "type": "null" } ], "description": "Only payments created at or before this Unix time (seconds).", "examples": [ 1793086400 ], "title": "Created Lte" }, "description": "Only payments created at or before this Unix time (seconds)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "How many objects to return: 1 to 100 (default 20).", "examples": [ 20 ], "default": 20, "title": "Limit" }, "description": "How many objects to return: 1 to 100 (default 20)." }, { "name": "starting_after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "description": "The cursor of the page to return: pass the `next_cursor` of the previous page (the id of its last object).", "title": "Starting After" }, "description": "The cursor of the page to return: pass the `next_cursor` of the previous page (the id of its last object)." } ], "responses": { "200": { "description": "A page of payments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentList" }, "example": { "object": "list", "data": [ { "id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33", "object": "payment", "status": "pending", "amount": 500000, "currency": "DZD", "description": "Order #1042", "reference": "order-1042", "customer": { "id": null, "name": "Amina Benali", "email": "amina@example.dz", "phone": "+213550000000" }, "items": [ { "name": "Running shoes", "description": null, "quantity": 2, "unit_amount": 250000 } ], "metadata": { "cart_id": "c_8812" }, "livemode": false, "payment_page": "rais", "checkout_url": "https://pay.rais.app/pay/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33", "success_url": "https://shop.example/thanks", "cancel_url": "https://shop.example/cart", "expires_at": 1793003600, "created": 1793000000, "paid_at": null, "amount_refunded": 0, "refunded": false, "fees": null, "net": null, "receipt_url": null, "failure": null, "payment_method": null, "processor": { "name": "satim", "order_id": "V721uPPfNNofVQAAABL3", "approval_code": null, "response_code": null } } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "A filter or the cursor is invalid.", "content": { "application/json": { "examples": { "invalid_parameter": { "summary": "invalid_parameter", "value": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Invalid value.", "param": "language", "request_id": "req_8f3a1c9d2b7e4a60" } } }, "invalid_cursor": { "summary": "invalid_cursor", "value": { "error": { "type": "invalid_request_error", "code": "invalid_cursor", "message": "No such payment: the starting_after cursor is unknown.", "param": "starting_after", "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "The API key is missing or invalid.", "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key provided.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The key lacks the scope, or the store cannot be used.", "content": { "application/json": { "examples": { "insufficient_scope": { "summary": "insufficient_scope", "value": { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "This API key does not have the 'payments:write' permission.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } }, "account_disabled": { "summary": "account_disabled", "value": { "error": { "type": "permission_error", "code": "account_disabled", "message": "This store is suspended or disabled.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } }, "live_mode_not_enabled": { "summary": "live_mode_not_enabled", "value": { "error": { "type": "permission_error", "code": "live_mode_not_enabled", "message": "Complete business verification to take live payments.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "examples": { "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down and retry after the delay in the Retry-After header.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "examples": { "internal_error": { "summary": "internal_error", "value": { "error": { "type": "api_error", "code": "internal_error", "message": "Something went wrong on our side. Quote the request id to support.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/payments/{payment_id}": { "get": { "tags": [ "Payments" ], "summary": "Retrieve a payment", "description": "Returns a payment of your store. If the payment is still `pending`, the gateway is asked for the outcome (at most every 15 seconds), so a payer coming back from the payment page always sees the truth even if their browser never reached us. A payment of another store, or of the other environment (sandbox vs live), answers 404.", "operationId": "retrievePayment", "parameters": [ { "name": "payment_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The id of the payment.", "examples": [ "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33" ], "title": "Payment Id" }, "description": "The id of the payment." } ], "responses": { "200": { "description": "The payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "example": { "id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33", "object": "payment", "status": "pending", "amount": 500000, "currency": "DZD", "description": "Order #1042", "reference": "order-1042", "customer": { "id": null, "name": "Amina Benali", "email": "amina@example.dz", "phone": "+213550000000" }, "items": [ { "name": "Running shoes", "description": null, "quantity": 2, "unit_amount": 250000 } ], "metadata": { "cart_id": "c_8812" }, "livemode": false, "payment_page": "rais", "checkout_url": "https://pay.rais.app/pay/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33", "success_url": "https://shop.example/thanks", "cancel_url": "https://shop.example/cart", "expires_at": 1793003600, "created": 1793000000, "paid_at": null, "amount_refunded": 0, "refunded": false, "fees": null, "net": null, "receipt_url": null, "failure": null, "payment_method": null, "processor": { "name": "satim", "order_id": "V721uPPfNNofVQAAABL3", "approval_code": null, "response_code": null } } } } }, "401": { "description": "The API key is missing or invalid.", "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key provided.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The key lacks the scope, or the store cannot be used.", "content": { "application/json": { "examples": { "insufficient_scope": { "summary": "insufficient_scope", "value": { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "This API key does not have the 'payments:write' permission.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } }, "account_disabled": { "summary": "account_disabled", "value": { "error": { "type": "permission_error", "code": "account_disabled", "message": "This store is suspended or disabled.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } }, "live_mode_not_enabled": { "summary": "live_mode_not_enabled", "value": { "error": { "type": "permission_error", "code": "live_mode_not_enabled", "message": "Complete business verification to take live payments.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No such payment.", "content": { "application/json": { "examples": { "payment_not_found": { "summary": "payment_not_found", "value": { "error": { "type": "not_found_error", "code": "payment_not_found", "message": "No such payment.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "examples": { "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down and retry after the delay in the Retry-After header.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "examples": { "internal_error": { "summary": "internal_error", "value": { "error": { "type": "api_error", "code": "internal_error", "message": "Something went wrong on our side. Quote the request id to support.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/payments/{payment_id}/cancel": { "post": { "tags": [ "Payments" ], "summary": "Cancel a payment", "description": "Cancels a payment that is still `pending`, so its checkout page can no longer be used. A payment in any other state (paid, failed, expired, already cancelled...) cannot be cancelled and answers `409 payment_not_cancellable`. Emits a `payment.cancelled` event.", "operationId": "cancelPayment", "parameters": [ { "name": "payment_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The id of the payment.", "examples": [ "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33" ], "title": "Payment Id" }, "description": "The id of the payment." } ], "responses": { "200": { "description": "The cancelled payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "example": { "id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33", "object": "payment", "status": "cancelled", "amount": 500000, "currency": "DZD", "description": "Order #1042", "reference": "order-1042", "customer": { "id": null, "name": "Amina Benali", "email": "amina@example.dz", "phone": "+213550000000" }, "items": [ { "name": "Running shoes", "description": null, "quantity": 2, "unit_amount": 250000 } ], "metadata": { "cart_id": "c_8812" }, "livemode": false, "payment_page": "rais", "checkout_url": "https://pay.rais.app/pay/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33", "success_url": "https://shop.example/thanks", "cancel_url": "https://shop.example/cart", "expires_at": 1793003600, "created": 1793000000, "paid_at": null, "amount_refunded": 0, "refunded": false, "fees": null, "net": null, "receipt_url": null, "failure": null, "payment_method": null, "processor": { "name": "satim", "order_id": "V721uPPfNNofVQAAABL3", "approval_code": null, "response_code": null } } } } }, "401": { "description": "The API key is missing or invalid.", "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key provided.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The key lacks the scope, or the store cannot be used.", "content": { "application/json": { "examples": { "insufficient_scope": { "summary": "insufficient_scope", "value": { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "This API key does not have the 'payments:write' permission.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } }, "account_disabled": { "summary": "account_disabled", "value": { "error": { "type": "permission_error", "code": "account_disabled", "message": "This store is suspended or disabled.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } }, "live_mode_not_enabled": { "summary": "live_mode_not_enabled", "value": { "error": { "type": "permission_error", "code": "live_mode_not_enabled", "message": "Complete business verification to take live payments.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No such payment.", "content": { "application/json": { "examples": { "payment_not_found": { "summary": "payment_not_found", "value": { "error": { "type": "not_found_error", "code": "payment_not_found", "message": "No such payment.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The payment is not pending.", "content": { "application/json": { "examples": { "payment_not_cancellable": { "summary": "payment_not_cancellable", "value": { "error": { "type": "invalid_request_error", "code": "payment_not_cancellable", "message": "Only a pending payment can be cancelled; this one is paid.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "examples": { "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down and retry after the delay in the Retry-After header.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "examples": { "internal_error": { "summary": "internal_error", "value": { "error": { "type": "api_error", "code": "internal_error", "message": "Something went wrong on our side. Quote the request id to support.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/payments/{payment_id}/refunds": { "post": { "tags": [ "Refunds" ], "summary": "Refund a payment", "description": "Refunds all or part of a paid payment. Without `amount`, everything still refundable is refunded; a payment can be refunded several times, never beyond what was paid. The refund is performed with the payment gateway before the answer is returned: `succeeded` (201), or `pending` (202) if the gateway's answer was lost, in which case the amount stays reserved and you must look at the refund (`GET /refunds/{id}`) before trying again. A refusal by the bank answers `402 refund_declined`. A key can only refund payments of its own store and environment. Send an `Idempotency-Key` so that retrying can never refund twice.", "operationId": "createRefund", "parameters": [ { "name": "payment_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The id of the payment.", "examples": [ "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33" ], "title": "Payment Id" }, "description": "The id of the payment." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A unique value (at most 255 characters, a UUID is ideal) that makes the request safe to repeat: the same key with the same request returns the original answer without creating anything twice.", "examples": [ "b7e1c1c6-6f0a-4d2f-9d8b-3a5c2f1e7a90" ], "title": "Idempotency-Key" }, "description": "A unique value (at most 255 characters, a UUID is ideal) that makes the request safe to repeat: the same key with the same request returns the original answer without creating anything twice." } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/CreateRefundRequest" }, { "type": "null" } ], "title": "Body" } } } }, "responses": { "201": { "description": "The refund succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" }, "example": { "id": "0c8a1d52-6e7b-4f0a-9b3d-7d2e4a8c5f10", "object": "refund", "payment_id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33", "amount": 150000, "currency": "DZD", "status": "succeeded", "reason": "Customer returned one item", "failure": null, "fees": { "satim": 800, "rais": 200, "total": 1000 }, "livemode": false, "created": 1793000900 } } } }, "202": { "description": "The refund was sent but the gateway's answer was lost: `status` is `pending` and the amount is reserved.", "content": { "application/json": { "example": { "id": "0c8a1d52-6e7b-4f0a-9b3d-7d2e4a8c5f10", "object": "refund", "payment_id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33", "amount": 150000, "currency": "DZD", "status": "pending", "reason": "Customer returned one item", "failure": null, "fees": { "satim": 800, "rais": 200, "total": 1000 }, "livemode": false, "created": 1793000900 } } } }, "400": { "description": "The request is invalid or the refund is too large.", "content": { "application/json": { "examples": { "invalid_json": { "summary": "invalid_json", "value": { "error": { "type": "invalid_request_error", "code": "invalid_json", "message": "The request body is not valid JSON.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } }, "invalid_amount": { "summary": "invalid_amount", "value": { "error": { "type": "invalid_request_error", "code": "invalid_amount", "message": "amount must be an integer number of centimes (500000 is 5,000.00 DA).", "param": "amount", "request_id": "req_8f3a1c9d2b7e4a60" } } }, "amount_too_small": { "summary": "amount_too_small", "value": { "error": { "type": "invalid_request_error", "code": "amount_too_small", "message": "The minimum amount is 50.00 DA (5000 centimes).", "param": "amount", "request_id": "req_8f3a1c9d2b7e4a60" } } }, "refund_exceeds_balance": { "summary": "refund_exceeds_balance", "value": { "error": { "type": "invalid_request_error", "code": "refund_exceeds_balance", "message": "The refund (500000 centimes) exceeds what can still be refunded (200000 centimes).", "param": "amount", "request_id": "req_8f3a1c9d2b7e4a60" } } }, "insufficient_balance": { "summary": "insufficient_balance", "value": { "error": { "type": "invalid_request_error", "code": "insufficient_balance", "message": "The store's balance is not sufficient to cover this refund and its fee.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } }, "invalid_idempotency_key": { "summary": "invalid_idempotency_key", "value": { "error": { "type": "invalid_request_error", "code": "invalid_idempotency_key", "message": "The Idempotency-Key header must be 1 to 255 printable ASCII characters.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "The API key is missing or invalid.", "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key provided.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The bank refused the refund.", "content": { "application/json": { "examples": { "refund_declined": { "summary": "refund_declined", "value": { "error": { "type": "payment_error", "code": "refund_declined", "message": "The bank refused the refund.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The key lacks the scope, or the store cannot be used.", "content": { "application/json": { "examples": { "insufficient_scope": { "summary": "insufficient_scope", "value": { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "This API key does not have the 'payments:write' permission.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } }, "account_disabled": { "summary": "account_disabled", "value": { "error": { "type": "permission_error", "code": "account_disabled", "message": "This store is suspended or disabled.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } }, "live_mode_not_enabled": { "summary": "live_mode_not_enabled", "value": { "error": { "type": "permission_error", "code": "live_mode_not_enabled", "message": "Complete business verification to take live payments.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No such payment.", "content": { "application/json": { "examples": { "payment_not_found": { "summary": "payment_not_found", "value": { "error": { "type": "not_found_error", "code": "payment_not_found", "message": "No such payment.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The payment is not paid, or the first request with this key is still running.", "content": { "application/json": { "examples": { "payment_not_refundable": { "summary": "payment_not_refundable", "value": { "error": { "type": "invalid_request_error", "code": "payment_not_refundable", "message": "Cannot refund a payment with status 'pending'.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } }, "idempotency_in_progress": { "summary": "idempotency_in_progress", "value": { "error": { "type": "idempotency_error", "code": "idempotency_in_progress", "message": "A request with this Idempotency-Key is still being processed. Retry in a moment.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The Idempotency-Key was used with different parameters.", "content": { "application/json": { "examples": { "idempotency_key_reused": { "summary": "idempotency_key_reused", "value": { "error": { "type": "idempotency_error", "code": "idempotency_key_reused", "message": "This Idempotency-Key was already used with different request parameters.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "examples": { "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down and retry after the delay in the Retry-After header.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "examples": { "internal_error": { "summary": "internal_error", "value": { "error": { "type": "api_error", "code": "internal_error", "message": "Something went wrong on our side. Quote the request id to support.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The payment gateway cannot be reached. Nothing was refunded; retry.", "content": { "application/json": { "examples": { "gateway_unavailable": { "summary": "gateway_unavailable", "value": { "error": { "type": "api_error", "code": "gateway_unavailable", "message": "The payment gateway is temporarily unavailable. Please try again later.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/refunds/{refund_id}": { "get": { "tags": [ "Refunds" ], "summary": "Retrieve a refund", "description": "Returns a refund of your store. A refund of another store, or of the other environment, answers 404.", "operationId": "retrieveRefund", "parameters": [ { "name": "refund_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The id of the refund.", "examples": [ "0c8a1d52-6e7b-4f0a-9b3d-7d2e4a8c5f10" ], "title": "Refund Id" }, "description": "The id of the refund." } ], "responses": { "200": { "description": "The refund.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" }, "example": { "id": "0c8a1d52-6e7b-4f0a-9b3d-7d2e4a8c5f10", "object": "refund", "payment_id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33", "amount": 150000, "currency": "DZD", "status": "succeeded", "reason": "Customer returned one item", "failure": null, "fees": { "satim": 800, "rais": 200, "total": 1000 }, "livemode": false, "created": 1793000900 } } } }, "401": { "description": "The API key is missing or invalid.", "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key provided.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The key lacks the scope, or the store cannot be used.", "content": { "application/json": { "examples": { "insufficient_scope": { "summary": "insufficient_scope", "value": { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "This API key does not have the 'payments:write' permission.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } }, "account_disabled": { "summary": "account_disabled", "value": { "error": { "type": "permission_error", "code": "account_disabled", "message": "This store is suspended or disabled.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } }, "live_mode_not_enabled": { "summary": "live_mode_not_enabled", "value": { "error": { "type": "permission_error", "code": "live_mode_not_enabled", "message": "Complete business verification to take live payments.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No such refund.", "content": { "application/json": { "examples": { "refund_not_found": { "summary": "refund_not_found", "value": { "error": { "type": "not_found_error", "code": "refund_not_found", "message": "No such refund.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "examples": { "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down and retry after the delay in the Retry-After header.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "examples": { "internal_error": { "summary": "internal_error", "value": { "error": { "type": "api_error", "code": "internal_error", "message": "Something went wrong on our side. Quote the request id to support.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/refunds": { "get": { "tags": [ "Refunds" ], "summary": "List refunds", "description": "Returns the refunds of your store in the environment of the key, newest first. Pass `payment` to see only the refunds of one payment.", "operationId": "listRefunds", "parameters": [ { "name": "payment", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "description": "Only the refunds of this payment (its id).", "examples": [ "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33" ], "title": "Payment" }, "description": "Only the refunds of this payment (its id)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "How many objects to return: 1 to 100 (default 20).", "examples": [ 20 ], "default": 20, "title": "Limit" }, "description": "How many objects to return: 1 to 100 (default 20)." }, { "name": "starting_after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "description": "The cursor of the page to return: pass the `next_cursor` of the previous page (the id of its last object).", "title": "Starting After" }, "description": "The cursor of the page to return: pass the `next_cursor` of the previous page (the id of its last object)." } ], "responses": { "200": { "description": "A page of refunds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundList" }, "example": { "object": "list", "data": [ { "id": "0c8a1d52-6e7b-4f0a-9b3d-7d2e4a8c5f10", "object": "refund", "payment_id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33", "amount": 150000, "currency": "DZD", "status": "succeeded", "reason": "Customer returned one item", "failure": null, "fees": { "satim": 800, "rais": 200, "total": 1000 }, "livemode": false, "created": 1793000900 } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "A filter or the cursor is invalid.", "content": { "application/json": { "examples": { "invalid_parameter": { "summary": "invalid_parameter", "value": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Invalid value.", "param": "language", "request_id": "req_8f3a1c9d2b7e4a60" } } }, "invalid_cursor": { "summary": "invalid_cursor", "value": { "error": { "type": "invalid_request_error", "code": "invalid_cursor", "message": "No such payment: the starting_after cursor is unknown.", "param": "starting_after", "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "The API key is missing or invalid.", "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key provided.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The key lacks the scope, or the store cannot be used.", "content": { "application/json": { "examples": { "insufficient_scope": { "summary": "insufficient_scope", "value": { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "This API key does not have the 'payments:write' permission.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } }, "account_disabled": { "summary": "account_disabled", "value": { "error": { "type": "permission_error", "code": "account_disabled", "message": "This store is suspended or disabled.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } }, "live_mode_not_enabled": { "summary": "live_mode_not_enabled", "value": { "error": { "type": "permission_error", "code": "live_mode_not_enabled", "message": "Complete business verification to take live payments.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "examples": { "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down and retry after the delay in the Retry-After header.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "examples": { "internal_error": { "summary": "internal_error", "value": { "error": { "type": "api_error", "code": "internal_error", "message": "Something went wrong on our side. Quote the request id to support.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/events/{event_id}": { "get": { "tags": [ "Events" ], "summary": "Retrieve an event", "description": "Returns an event of your store in the environment of the key, if it happened in the last 30 days.", "operationId": "retrieveEvent", "parameters": [ { "name": "event_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 100, "description": "The id of the event (`evt_...`).", "examples": [ "evt_Qm9dMhJ0k8s2Wv7Yc3XnLpAb" ], "title": "Event Id" }, "description": "The id of the event (`evt_...`)." } ], "responses": { "200": { "description": "The event.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_Qm9dMhJ0k8s2Wv7Yc3XnLpAb", "object": "event", "api_version": "2026-10-26", "created": 1793000300, "livemode": false, "type": "payment.succeeded", "data": { "object": { "id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33", "object": "payment", "status": "paid", "amount": 500000, "currency": "DZD" } } } } } }, "401": { "description": "The API key is missing or invalid.", "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key provided.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The key lacks the scope, or the store cannot be used.", "content": { "application/json": { "examples": { "insufficient_scope": { "summary": "insufficient_scope", "value": { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "This API key does not have the 'payments:write' permission.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } }, "account_disabled": { "summary": "account_disabled", "value": { "error": { "type": "permission_error", "code": "account_disabled", "message": "This store is suspended or disabled.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } }, "live_mode_not_enabled": { "summary": "live_mode_not_enabled", "value": { "error": { "type": "permission_error", "code": "live_mode_not_enabled", "message": "Complete business verification to take live payments.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No such event.", "content": { "application/json": { "examples": { "event_not_found": { "summary": "event_not_found", "value": { "error": { "type": "not_found_error", "code": "event_not_found", "message": "No such event.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "examples": { "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down and retry after the delay in the Retry-After header.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "examples": { "internal_error": { "summary": "internal_error", "value": { "error": { "type": "api_error", "code": "internal_error", "message": "Something went wrong on our side. Quote the request id to support.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/events": { "get": { "tags": [ "Events" ], "summary": "List events", "description": "Returns the events of your store in the environment of the key from the last 30 days, newest first. Filter with `type` (for instance `payment.succeeded`); page with `starting_after`.", "operationId": "listEvents", "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "description": "Only events of this type: `payment.succeeded`, `payment.failed`, `payment.cancelled`, `payment.reversed`, `refund.succeeded` or `refund.failed`.", "examples": [ "payment.succeeded" ], "title": "Type" }, "description": "Only events of this type: `payment.succeeded`, `payment.failed`, `payment.cancelled`, `payment.reversed`, `refund.succeeded` or `refund.failed`." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "How many objects to return: 1 to 100 (default 20).", "examples": [ 20 ], "default": 20, "title": "Limit" }, "description": "How many objects to return: 1 to 100 (default 20)." }, { "name": "starting_after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "description": "The cursor of the page to return: pass the `next_cursor` of the previous page (the id of its last object).", "title": "Starting After" }, "description": "The cursor of the page to return: pass the `next_cursor` of the previous page (the id of its last object)." } ], "responses": { "200": { "description": "A page of events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventList" }, "example": { "object": "list", "data": [ { "id": "evt_Qm9dMhJ0k8s2Wv7Yc3XnLpAb", "object": "event", "api_version": "2026-10-26", "created": 1793000300, "livemode": false, "type": "payment.succeeded", "data": { "object": { "id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33", "object": "payment", "status": "paid", "amount": 500000, "currency": "DZD" } } } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "A filter or the cursor is invalid.", "content": { "application/json": { "examples": { "invalid_parameter": { "summary": "invalid_parameter", "value": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Invalid value.", "param": "language", "request_id": "req_8f3a1c9d2b7e4a60" } } }, "invalid_cursor": { "summary": "invalid_cursor", "value": { "error": { "type": "invalid_request_error", "code": "invalid_cursor", "message": "No such payment: the starting_after cursor is unknown.", "param": "starting_after", "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "The API key is missing or invalid.", "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key provided.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The key lacks the scope, or the store cannot be used.", "content": { "application/json": { "examples": { "insufficient_scope": { "summary": "insufficient_scope", "value": { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "This API key does not have the 'payments:write' permission.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } }, "account_disabled": { "summary": "account_disabled", "value": { "error": { "type": "permission_error", "code": "account_disabled", "message": "This store is suspended or disabled.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } }, "live_mode_not_enabled": { "summary": "live_mode_not_enabled", "value": { "error": { "type": "permission_error", "code": "live_mode_not_enabled", "message": "Complete business verification to take live payments.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "examples": { "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down and retry after the delay in the Retry-After header.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "examples": { "internal_error": { "summary": "internal_error", "value": { "error": { "type": "api_error", "code": "internal_error", "message": "Something went wrong on our side. Quote the request id to support.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/payments/{payment_id}/receipt": { "get": { "tags": [ "Payments" ], "summary": "Retrieve the receipt of a payment", "description": "Returns a signed link (valid for 15 minutes) to the PDF receipt of a **paid** payment of your store: the payer, the items, the card used (masked), the approval code and any refunds. The receipt is in the language of the payment page; a sandbox payment's receipt is clearly marked as a test. Only payments that were paid (`paid`, `partially_refunded`, `refunded`) have a receipt: any other payment, a payment of another store or of the other environment (sandbox vs live) answers 404. The receipt is regenerated after a refund, so the link always shows the current state.", "operationId": "retrievePaymentReceipt", "parameters": [ { "name": "payment_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The id of the payment.", "examples": [ "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33" ], "title": "Payment Id" }, "description": "The id of the payment." } ], "responses": { "200": { "description": "A signed link to the receipt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" }, "example": { "object": "receipt", "url": "https://files.example.com/storage/receipts/Rais-receipt-1042.pdf?signature=...", "expires_at": 1793000900 } } } }, "401": { "description": "The API key is missing or invalid.", "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "invalid_api_key", "value": { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key provided.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The key lacks the scope, or the store cannot be used.", "content": { "application/json": { "examples": { "insufficient_scope": { "summary": "insufficient_scope", "value": { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "This API key does not have the 'payments:write' permission.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } }, "account_disabled": { "summary": "account_disabled", "value": { "error": { "type": "permission_error", "code": "account_disabled", "message": "This store is suspended or disabled.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } }, "live_mode_not_enabled": { "summary": "live_mode_not_enabled", "value": { "error": { "type": "permission_error", "code": "live_mode_not_enabled", "message": "Complete business verification to take live payments.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No such payment, or it has not been paid.", "content": { "application/json": { "examples": { "payment_not_found": { "summary": "payment_not_found", "value": { "error": { "type": "not_found_error", "code": "payment_not_found", "message": "No such payment.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "examples": { "rate_limit_exceeded": { "summary": "rate_limit_exceeded", "value": { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests. Slow down and retry after the delay in the Retry-After header.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "examples": { "internal_error": { "summary": "internal_error", "value": { "error": { "type": "api_error", "code": "internal_error", "message": "Something went wrong on our side. Quote the request id to support.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The receipt cannot be produced right now; retry shortly.", "content": { "application/json": { "examples": { "gateway_unavailable": { "summary": "gateway_unavailable", "value": { "error": { "type": "api_error", "code": "gateway_unavailable", "message": "The payment gateway is temporarily unavailable. Please try again later.", "param": null, "request_id": "req_8f3a1c9d2b7e4a60" } } } }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "schemas": { "Account": { "properties": { "object": { "type": "string", "const": "account", "title": "Object", "description": "The type of the object.", "examples": [ "account" ] }, "id": { "type": "string", "title": "Id", "description": "The unique identifier of your store.", "examples": [ "7d0b6a3e-1c52-4f8e-9a44-2b6e8f1d0c35" ] }, "name": { "type": "string", "title": "Name", "description": "The name of your store.", "examples": [ "Boutique Alger" ] }, "livemode": { "type": "boolean", "title": "Livemode", "description": "The environment of the key used for this request.", "examples": [ false ] }, "live_enabled": { "type": "boolean", "title": "Live Enabled", "description": "Whether your store may take live payments (business verification complete).", "examples": [ false ] }, "currency": { "type": "string", "const": "DZD", "title": "Currency", "description": "The only supported currency.", "examples": [ "DZD" ] }, "payment_page": { "type": "string", "enum": [ "rais", "satim" ], "title": "Payment Page", "description": "The payment page your payments use by default.", "examples": [ "rais" ] } }, "type": "object", "required": [ "object", "id", "name", "livemode", "live_enabled", "currency", "payment_page" ], "title": "Account", "examples": [ { "object": "account", "id": "7d0b6a3e-1c52-4f8e-9a44-2b6e8f1d0c35", "name": "Boutique Alger", "livemode": false, "live_enabled": false, "currency": "DZD", "payment_page": "rais" } ] }, "CreatePaymentRequest": { "properties": { "amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Amount", "description": "The amount to collect, as an INTEGER in centimes: 500000 is 5,000.00 DA. Between 5000 (50 DA, SATIM's minimum) and 999999999999. Floats and strings are refused. Optional when `items` is given (the amount is then the sum of quantity x unit_amount); if both are given they must agree.", "examples": [ 500000 ] }, "currency": { "anyOf": [ { "type": "string", "maxLength": 32 }, { "type": "null" } ], "title": "Currency", "description": "The currency. Only `DZD` (Algerian dinar) is supported; it is the default.", "examples": [ "DZD" ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "title": "Description", "description": "What the payment is for. Shown to the payer and sent to SATIM.", "examples": [ "Order #1042" ] }, "reference": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ], "title": "Reference", "description": "Your own identifier of the order. Returned as is, and searchable with `GET /payments?reference=`.", "examples": [ "order-1042" ] }, "customer": { "anyOf": [ { "$ref": "#/components/schemas/CustomerInput" }, { "type": "null" } ], "description": "Who is paying. Explicit values take precedence over those of `customer_id`." }, "customer_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Customer Id", "description": "The id of one of YOUR customers (of the store AND the mode the key belongs to: a sandbox key sees sandbox customers and a live key live ones; any other id answers `customer_not_found`). Fills in the payer's name and e-mail. On the Raïs payment page it also lets the payer choose to save their card for next time and pay with a card they saved earlier: they pick it and confirm with 3-D Secure (the card and its security code are stored encrypted, for your store only). Saved cards are kept per mode: a sandbox payment never offers a live card, nor a live payment a sandbox one.", "examples": [ "3f6e2d10-5a4b-4c7e-8d21-9b0c1e2f3a44" ] }, "items": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ItemInput" }, "type": "array", "maxItems": 50 }, { "type": "null" } ], "title": "Items", "description": "What is being bought, at most 50 lines. Shown on the receipt." }, "success_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Success Url", "description": "Where the payer is sent after a successful payment. `https://` (live and sandbox), `http://` (sandbox only) or your app's own scheme such as `myapp://pay/result`. At most 512 characters, no credentials, no spaces.", "examples": [ "https://shop.example/thanks" ] }, "cancel_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cancel Url", "description": "Where the payer is sent if they cancel or the payment fails. Same rules as `success_url`.", "examples": [ "https://shop.example/cart" ] }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Up to 20 key/value pairs of your own. Keys are at most 40 characters; values must be strings of at most 500 characters.", "examples": [ { "cart_id": "c_8812" } ] }, "payment_page": { "anyOf": [ { "type": "string", "enum": [ "rais", "satim" ] }, { "type": "null" } ], "title": "Payment Page", "description": "Which page the payer pays on: `rais` (Raïs' own page) or `satim` (SATIM's). Defaults to your store's setting.", "examples": [ "rais" ] }, "language": { "anyOf": [ { "type": "string", "enum": [ "en", "fr", "ar" ] }, { "type": "null" } ], "title": "Language", "description": "The language the payment page opens in. A payer who picks another language on the page (the switcher in its header) keeps their choice for every payment page. Omitted: the page follows the payer's browser (English, French or Arabic).", "examples": [ "fr" ] }, "expires_in": { "anyOf": [ { "type": "integer", "maximum": 2592000, "minimum": 300 }, { "type": "null" } ], "title": "Expires In", "description": "Seconds the payment stays payable: 300 to 2592000 (30 days). Defaults to 86400 (24 hours).", "examples": [ 3600 ] } }, "additionalProperties": false, "type": "object", "title": "CreatePaymentRequest", "examples": [ { "amount": 500000, "currency": "DZD", "description": "Order #1042", "reference": "order-1042", "customer": { "name": "Amina Benali", "email": "amina@example.dz", "phone": "+213550000000" }, "success_url": "https://shop.example/thanks", "cancel_url": "https://shop.example/cart", "metadata": { "cart_id": "c_8812" }, "expires_in": 3600 }, { "items": [ { "name": "Running shoes", "quantity": 2, "unit_amount": 250000 }, { "name": "Delivery", "quantity": 1, "unit_amount": 80000 } ], "success_url": "myapp://pay/result", "language": "fr" } ] }, "CreateRefundRequest": { "properties": { "amount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Amount", "description": "How much to refund, as an INTEGER in centimes (at least 100 = 1 DA). Defaults to everything still refundable.", "examples": [ 150000 ] }, "reason": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Reason", "description": "Why you are refunding. For your records.", "examples": [ "Customer returned one item" ] } }, "additionalProperties": false, "type": "object", "title": "CreateRefundRequest", "examples": [ { "amount": 150000, "reason": "Customer returned one item" }, {} ] }, "CustomerInput": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Name", "description": "The payer's full name.", "examples": [ "Amina Benali" ] }, "email": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ], "title": "Email", "description": "The payer's e-mail address.", "examples": [ "amina@example.dz" ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ], "title": "Phone", "description": "The payer's phone number.", "examples": [ "+213550000000" ] } }, "additionalProperties": false, "type": "object", "title": "CustomerInput" }, "ErrorBody": { "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "invalid_request_error", "not_found_error", "idempotency_error", "rate_limit_error", "api_error", "payment_error" ], "title": "Type", "description": "The category of the error. It decides how to react (fix the request, retry, call support).", "examples": [ "invalid_request_error" ] }, "code": { "type": "string", "title": "Code", "description": "A stable, machine-readable identifier of the problem (see the list of error codes).", "examples": [ "amount_too_small" ] }, "message": { "type": "string", "title": "Message", "description": "A human-readable explanation, safe to show to a developer.", "examples": [ "The minimum amount is 50.00 DA (5000 centimes)." ] }, "param": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Param", "description": "The request parameter the error is about, if any.", "examples": [ "amount" ] }, "request_id": { "type": "string", "title": "Request Id", "description": "The identifier of the request (also in the Rais-Request-Id header). Quote it to support.", "examples": [ "req_8f3a1c9d2b7e4a60" ] } }, "type": "object", "required": [ "type", "code", "message", "request_id" ], "title": "ErrorBody" }, "ErrorResponse": { "properties": { "error": { "$ref": "#/components/schemas/ErrorBody", "description": "The error. Every non-2xx response of the API has exactly this envelope." } }, "type": "object", "required": [ "error" ], "title": "ErrorResponse", "examples": [ { "error": { "type": "invalid_request_error", "code": "amount_too_small", "message": "The minimum amount is 50.00 DA (5000 centimes).", "param": "amount", "request_id": "req_8f3a1c9d2b7e4a60" } } ] }, "Event": { "properties": { "id": { "type": "string", "title": "Id", "description": "The unique identifier of the event.", "examples": [ "evt_Qm9dMhJ0k8s2Wv7Yc3XnLpAb" ] }, "object": { "type": "string", "const": "event", "title": "Object", "description": "The type of the object.", "examples": [ "event" ] }, "api_version": { "type": "string", "title": "Api Version", "description": "The API version the payload was rendered with.", "examples": [ "2026-10-26" ] }, "created": { "type": "integer", "title": "Created", "description": "When the event happened (Unix time, seconds).", "examples": [ 1793000300 ] }, "livemode": { "type": "boolean", "title": "Livemode", "description": "`false` for a sandbox event.", "examples": [ false ] }, "type": { "type": "string", "enum": [ "payment.succeeded", "payment.failed", "payment.cancelled", "payment.reversed", "refund.succeeded", "refund.failed" ], "title": "Type", "description": "What happened.", "examples": [ "payment.succeeded" ] }, "data": { "$ref": "#/components/schemas/EventData", "description": "The object the event is about." } }, "type": "object", "required": [ "id", "object", "api_version", "created", "livemode", "type", "data" ], "title": "Event", "examples": [ { "id": "evt_Qm9dMhJ0k8s2Wv7Yc3XnLpAb", "object": "event", "api_version": "2026-10-26", "created": 1793000300, "livemode": false, "type": "payment.succeeded", "data": { "object": { "id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33", "object": "payment", "status": "paid", "amount": 500000, "currency": "DZD" } } } ] }, "EventData": { "properties": { "object": { "additionalProperties": true, "type": "object", "title": "Object", "description": "The Payment or Refund object as it was when the event happened." } }, "type": "object", "required": [ "object" ], "title": "EventData" }, "EventList": { "properties": { "object": { "type": "string", "const": "list", "title": "Object", "description": "Always `list`.", "examples": [ "list" ] }, "data": { "items": { "$ref": "#/components/schemas/Event" }, "type": "array", "title": "Data", "description": "The events of this page, newest first." }, "has_more": { "type": "boolean", "title": "Has More", "description": "True when there are older events.", "examples": [ false ] }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "The value to pass as `starting_after` for the next page; null on the last page.", "examples": [ null ] } }, "type": "object", "required": [ "object", "data", "has_more", "next_cursor" ], "title": "EventList", "examples": [ { "object": "list", "data": [ { "id": "evt_Qm9dMhJ0k8s2Wv7Yc3XnLpAb", "object": "event", "api_version": "2026-10-26", "created": 1793000300, "livemode": false, "type": "payment.succeeded", "data": { "object": { "id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33", "object": "payment", "status": "paid", "amount": 500000, "currency": "DZD" } } } ], "has_more": false, "next_cursor": null } ] }, "Failure": { "properties": { "code": { "type": "string", "title": "Code", "description": "Why it failed, machine-readable: `payment_declined`, `processing_error`, `gateway_unavailable`, `refund_declined`...", "examples": [ "payment_declined" ] }, "message": { "type": "string", "title": "Message", "description": "Why it failed, in words.", "examples": [ "Insufficient funds" ] } }, "type": "object", "required": [ "code", "message" ], "title": "Failure" }, "Fees": { "properties": { "satim": { "type": "integer", "title": "Satim", "description": "SATIM's fee, in centimes, excluding VAT.", "examples": [ 3500 ] }, "rais": { "type": "integer", "title": "Rais", "description": "Raïs's fee, in centimes, excluding VAT.", "examples": [ 1500 ] }, "total": { "type": "integer", "title": "Total", "description": "What the transaction costs: `satim` + `rais`, in centimes, excluding VAT.", "examples": [ 5000 ] } }, "type": "object", "required": [ "satim", "rais", "total" ], "title": "Fees", "examples": [ { "satim": 3500, "rais": 1500, "total": 5000 } ] }, "ItemInput": { "properties": { "name": { "type": "string", "maxLength": 255, "minLength": 1, "title": "Name", "description": "What is being bought.", "examples": [ "Running shoes" ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 512 }, { "type": "null" } ], "title": "Description", "description": "More detail, shown on the receipt.", "examples": [ "Size 42, black" ] }, "quantity": { "type": "integer", "maximum": 1000000, "minimum": 1, "title": "Quantity", "description": "How many units (an integer, at least 1).", "examples": [ 2 ] }, "unit_amount": { "type": "integer", "maximum": 999999999999, "minimum": 0, "title": "Unit Amount", "description": "Price of ONE unit, in centimes (an integer).", "examples": [ 250000 ] } }, "additionalProperties": false, "type": "object", "required": [ "name", "quantity", "unit_amount" ], "title": "ItemInput" }, "Payment": { "properties": { "id": { "type": "string", "title": "Id", "description": "The unique identifier of the payment.", "examples": [ "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33" ] }, "object": { "type": "string", "const": "payment", "title": "Object", "description": "The type of the object.", "examples": [ "payment" ] }, "status": { "type": "string", "enum": [ "pending", "paid", "failed", "cancelled", "expired", "refunded", "partially_refunded", "reversed" ], "title": "Status", "description": "Where the payment stands. `pending`: waiting for the payer. `paid`: money received. `failed`: declined or errored (see `failure`). `cancelled`: you cancelled it. `expired`: nobody paid before `expires_at`. `refunded` / `partially_refunded`: money was returned. `reversed`: SATIM reversed the authorisation.", "examples": [ "pending" ] }, "amount": { "type": "integer", "title": "Amount", "description": "The amount, in centimes.", "examples": [ 500000 ] }, "currency": { "type": "string", "const": "DZD", "title": "Currency", "description": "The currency.", "examples": [ "DZD" ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "What the payment is for.", "examples": [ "Order #1042" ] }, "reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reference", "description": "Your own identifier of the order.", "examples": [ "order-1042" ] }, "customer": { "anyOf": [ { "$ref": "#/components/schemas/PaymentCustomer" }, { "type": "null" } ], "description": "Who is paying, if known." }, "items": { "items": { "$ref": "#/components/schemas/PaymentItem" }, "type": "array", "title": "Items", "description": "What is being bought (empty if not given)." }, "metadata": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Metadata", "description": "Your key/value pairs, as sent.", "examples": [ { "cart_id": "c_8812" } ] }, "livemode": { "type": "boolean", "title": "Livemode", "description": "`false` for a sandbox (test) payment, `true` for a live one.", "examples": [ false ] }, "payment_page": { "type": "string", "enum": [ "rais", "satim" ], "title": "Payment Page", "description": "The page the payer pays on.", "examples": [ "rais" ] }, "checkout_url": { "type": "string", "title": "Checkout Url", "description": "The hosted payment page. Redirect the payer here.", "examples": [ "https://pay.rais.app/pay/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33" ] }, "success_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Success Url", "description": "Where the payer is sent after paying.", "examples": [ "https://shop.example/thanks" ] }, "cancel_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cancel Url", "description": "Where the payer is sent if they cancel or fail.", "examples": [ "https://shop.example/cart" ] }, "expires_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Expires At", "description": "When an unpaid payment stops being payable (Unix time, seconds).", "examples": [ 1793003600 ] }, "created": { "type": "integer", "title": "Created", "description": "When the payment was created (Unix time, seconds).", "examples": [ 1793000000 ] }, "paid_at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Paid At", "description": "When the payment was paid (Unix time, seconds).", "examples": [ null ] }, "amount_refunded": { "type": "integer", "title": "Amount Refunded", "description": "How much has been refunded so far, in centimes.", "examples": [ 0 ] }, "refunded": { "type": "boolean", "title": "Refunded", "description": "True once the payment is fully refunded.", "examples": [ false ] }, "fees": { "anyOf": [ { "$ref": "#/components/schemas/Fees" }, { "type": "null" } ], "description": "What this payment cost you, in centimes, excluding VAT: SATIM's fee and Raïs's fee. Set once the payment is paid, `null` before. A test payment shows the simulated fees. They are not returned when the payment is refunded; each refund has its own fee (see the Refund object). See the pricing page." }, "net": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Net", "description": "What you receive for this payment: `amount` minus `fees.total`, in centimes, before any refund. `null` until it is paid.", "examples": [ null ] }, "receipt_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Receipt Url", "description": "Where the receipt can be downloaded once the payment is paid.", "examples": [ null ] }, "failure": { "anyOf": [ { "$ref": "#/components/schemas/Failure" }, { "type": "null" } ], "description": "Why the payment failed; set when `status` is `failed`." }, "payment_method": { "anyOf": [ { "$ref": "#/components/schemas/PaymentMethod" }, { "type": "null" } ], "description": "How the payer paid; set once the payment is paid." }, "processor": { "$ref": "#/components/schemas/Processor", "description": "What the processor (SATIM) knows about the payment." } }, "type": "object", "required": [ "id", "object", "status", "amount", "currency", "description", "reference", "customer", "items", "metadata", "livemode", "payment_page", "checkout_url", "success_url", "cancel_url", "expires_at", "created", "paid_at", "amount_refunded", "refunded", "fees", "net", "receipt_url", "failure", "payment_method", "processor" ], "title": "Payment", "examples": [ { "id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33", "object": "payment", "status": "pending", "amount": 500000, "currency": "DZD", "description": "Order #1042", "reference": "order-1042", "customer": { "id": null, "name": "Amina Benali", "email": "amina@example.dz", "phone": "+213550000000" }, "items": [ { "name": "Running shoes", "description": null, "quantity": 2, "unit_amount": 250000 } ], "metadata": { "cart_id": "c_8812" }, "livemode": false, "payment_page": "rais", "checkout_url": "https://pay.rais.app/pay/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33", "success_url": "https://shop.example/thanks", "cancel_url": "https://shop.example/cart", "expires_at": 1793003600, "created": 1793000000, "paid_at": null, "amount_refunded": 0, "refunded": false, "fees": null, "net": null, "receipt_url": null, "failure": null, "payment_method": null, "processor": { "name": "satim", "order_id": "V721uPPfNNofVQAAABL3", "approval_code": null, "response_code": null } } ] }, "PaymentCustomer": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "description": "The id of the linked customer record, if any.", "examples": [ "3f6e2d10-5a4b-4c7e-8d21-9b0c1e2f3a44" ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "The payer's name.", "examples": [ "Amina Benali" ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email", "description": "The payer's e-mail address.", "examples": [ "amina@example.dz" ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone", "description": "The payer's phone number.", "examples": [ "+213550000000" ] } }, "type": "object", "required": [ "id", "name", "email", "phone" ], "title": "PaymentCustomer" }, "PaymentItem": { "properties": { "name": { "type": "string", "title": "Name", "description": "What was bought.", "examples": [ "Running shoes" ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "More detail.", "examples": [ "Size 42, black" ] }, "quantity": { "type": "integer", "title": "Quantity", "description": "How many units.", "examples": [ 2 ] }, "unit_amount": { "type": "integer", "title": "Unit Amount", "description": "Price of one unit, in centimes.", "examples": [ 250000 ] } }, "type": "object", "required": [ "name", "description", "quantity", "unit_amount" ], "title": "PaymentItem" }, "PaymentList": { "properties": { "object": { "type": "string", "const": "list", "title": "Object", "description": "Always `list`.", "examples": [ "list" ] }, "data": { "items": { "$ref": "#/components/schemas/Payment" }, "type": "array", "title": "Data", "description": "The payments of this page, newest first." }, "has_more": { "type": "boolean", "title": "Has More", "description": "True when there are older payments: pass `next_cursor` as `starting_after`.", "examples": [ true ] }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "The value to pass as `starting_after` to get the next page; null on the last page.", "examples": [ "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33" ] } }, "type": "object", "required": [ "object", "data", "has_more", "next_cursor" ], "title": "PaymentList", "examples": [ { "object": "list", "data": [ { "id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33", "object": "payment", "status": "pending", "amount": 500000, "currency": "DZD", "description": "Order #1042", "reference": "order-1042", "customer": { "id": null, "name": "Amina Benali", "email": "amina@example.dz", "phone": "+213550000000" }, "items": [ { "name": "Running shoes", "description": null, "quantity": 2, "unit_amount": 250000 } ], "metadata": { "cart_id": "c_8812" }, "livemode": false, "payment_page": "rais", "checkout_url": "https://pay.rais.app/pay/5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33", "success_url": "https://shop.example/thanks", "cancel_url": "https://shop.example/cart", "expires_at": 1793003600, "created": 1793000000, "paid_at": null, "amount_refunded": 0, "refunded": false, "fees": null, "net": null, "receipt_url": null, "failure": null, "payment_method": null, "processor": { "name": "satim", "order_id": "V721uPPfNNofVQAAABL3", "approval_code": null, "response_code": null } } ], "has_more": false, "next_cursor": null } ] }, "PaymentMethod": { "properties": { "type": { "type": "string", "const": "card", "title": "Type", "description": "The kind of payment method.", "examples": [ "card" ] }, "brand": { "type": "string", "title": "Brand", "description": "The card scheme: `cib`, `dahabia` or `unknown`.", "examples": [ "cib" ] }, "last4": { "type": "string", "title": "Last4", "description": "The last four digits of the card.", "examples": [ "7215" ] }, "masked": { "type": "string", "title": "Masked", "description": "The card number as masked by SATIM (first six and last four digits at most).", "examples": [ "628058******7215" ] } }, "type": "object", "required": [ "type", "brand", "last4", "masked" ], "title": "PaymentMethod" }, "Processor": { "properties": { "name": { "type": "string", "const": "satim", "title": "Name", "description": "The payment processor.", "examples": [ "satim" ] }, "order_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Order Id", "description": "SATIM's identifier of the order.", "examples": [ "V721uPPfNNofVQAAABL3" ] }, "approval_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Approval Code", "description": "The authorisation code, once the payment is approved.", "examples": [ "913180" ] }, "response_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Response Code", "description": "SATIM's response code (`00` = approved).", "examples": [ "00" ] } }, "type": "object", "required": [ "name", "order_id", "approval_code", "response_code" ], "title": "Processor" }, "Receipt": { "properties": { "object": { "type": "string", "const": "receipt", "title": "Object", "description": "Always `receipt`.", "examples": [ "receipt" ] }, "url": { "type": "string", "title": "Url", "description": "A signed link to the PDF receipt. It works without any key, from a browser or a server, until `expires_at`: give it to your customer right away, or fetch a new one when you need it again.", "examples": [ "https://files.example.com/storage/receipts/Rais-receipt-1042.pdf?signature=..." ] }, "expires_at": { "type": "integer", "title": "Expires At", "description": "When `url` stops working (Unix time, seconds): 15 minutes after the request.", "examples": [ 1793000900 ] } }, "type": "object", "required": [ "object", "url", "expires_at" ], "title": "Receipt", "examples": [ { "expires_at": 1793000900, "object": "receipt", "url": "https://files.example.com/storage/receipts/Rais-receipt-1042.pdf?signature=..." } ] }, "Refund": { "properties": { "id": { "type": "string", "title": "Id", "description": "The unique identifier of the refund.", "examples": [ "0c8a1d52-6e7b-4f0a-9b3d-7d2e4a8c5f10" ] }, "object": { "type": "string", "const": "refund", "title": "Object", "description": "The type of the object.", "examples": [ "refund" ] }, "payment_id": { "type": "string", "title": "Payment Id", "description": "The payment that was refunded.", "examples": [ "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33" ] }, "amount": { "type": "integer", "title": "Amount", "description": "The amount refunded, in centimes.", "examples": [ 150000 ] }, "currency": { "type": "string", "const": "DZD", "title": "Currency", "description": "The currency.", "examples": [ "DZD" ] }, "status": { "type": "string", "enum": [ "succeeded", "failed", "pending" ], "title": "Status", "description": "`succeeded`: SATIM refunded. `failed`: SATIM refused (see `failure`). `pending`: the request was sent but SATIM's answer was lost; the amount stays reserved until the refund is checked. Do not retry with a new Idempotency-Key before looking at it.", "examples": [ "succeeded" ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason", "description": "The reason you gave.", "examples": [ "Customer returned one item" ] }, "failure": { "anyOf": [ { "$ref": "#/components/schemas/Failure" }, { "type": "null" } ], "description": "Why the refund failed; set when `status` is `failed`." }, "fees": { "anyOf": [ { "$ref": "#/components/schemas/Fees" }, { "type": "null" } ], "description": "What this refund cost you, in centimes, excluding VAT (a flat fee per refund, whatever its amount). Set once the refund `succeeded`; `null` while it is `pending` and when it `failed` (a refund that did not happen costs nothing). A test refund shows the simulated fees." }, "livemode": { "type": "boolean", "title": "Livemode", "description": "`false` for a sandbox refund.", "examples": [ false ] }, "created": { "type": "integer", "title": "Created", "description": "When the refund was requested (Unix time, seconds).", "examples": [ 1793000900 ] } }, "type": "object", "required": [ "id", "object", "payment_id", "amount", "currency", "status", "reason", "failure", "fees", "livemode", "created" ], "title": "Refund", "examples": [ { "id": "0c8a1d52-6e7b-4f0a-9b3d-7d2e4a8c5f10", "object": "refund", "payment_id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33", "amount": 150000, "currency": "DZD", "status": "succeeded", "reason": "Customer returned one item", "failure": null, "fees": { "satim": 800, "rais": 200, "total": 1000 }, "livemode": false, "created": 1793000900 } ] }, "RefundList": { "properties": { "object": { "type": "string", "const": "list", "title": "Object", "description": "Always `list`.", "examples": [ "list" ] }, "data": { "items": { "$ref": "#/components/schemas/Refund" }, "type": "array", "title": "Data", "description": "The refunds of this page, newest first." }, "has_more": { "type": "boolean", "title": "Has More", "description": "True when there are older refunds.", "examples": [ false ] }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor", "description": "The value to pass as `starting_after` for the next page; null on the last page.", "examples": [ null ] } }, "type": "object", "required": [ "object", "data", "has_more", "next_cursor" ], "title": "RefundList", "examples": [ { "object": "list", "data": [ { "id": "0c8a1d52-6e7b-4f0a-9b3d-7d2e4a8c5f10", "object": "refund", "payment_id": "5b1c2f4e-9d3a-4c61-8a7e-0f2d6b9e1a33", "amount": 150000, "currency": "DZD", "status": "succeeded", "reason": "Customer returned one item", "failure": null, "fees": { "satim": 800, "rais": 200, "total": 1000 }, "livemode": false, "created": 1793000900 } ], "has_more": false, "next_cursor": null } ] } }, "securitySchemes": { "SecretKey": { "type": "http", "scheme": "bearer", "bearerFormat": "rais_sk_test_... (sandbox) / rais_sk_live_... (live)", "description": "Your secret API key, sent as `Authorization: Bearer `. Keep it on your server: it must never be used from a browser or a mobile app." } } }, "tags": [ { "name": "Payments", "description": "Create a payment, send the payer to its checkout page, then follow it until it is paid." }, { "name": "Refunds", "description": "Return all or part of a paid payment to the payer." }, { "name": "Events", "description": "What happened to your payments and refunds. The same events are sent to your webhook endpoints." }, { "name": "Account", "description": "Your store, as seen by the API key in use." } ], "security": [ { "SecretKey": [] } ] }