Payments

Create a payment

Creates a payment and registers it with the payment gateway.

POST/v1/payments

Requires the payments:write scope.

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

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

curl https://api.rais.app/v1/payments \
  -H "Authorization: Bearer rais_sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: b7e1c1c6-6f0a-4d2f-9d8b-3a5c2f1e7a90" \
  -d '{
  "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
}'

Response201

{
  "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
  }
}

Request

Headers

Idempotency-Keystring

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.

Body

Required, JSON.

amountinteger

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.

currencystring

The currency. Only DZD (Algerian dinar) is supported; it is the default.

At most 32 characters.

descriptionstring

What the payment is for. Shown to the payer and sent to SATIM.

At most 512 characters.

referencestring

Your own identifier of the order. Returned as is, and searchable with GET /payments?reference=.

At most 64 characters.

customerobject

Who is paying. Explicit values take precedence over those of customer_id.

namestring

The payer's full name.

At most 255 characters.

emailstring

The payer's e-mail address.

At most 255 characters.

phonestring

The payer's phone number.

At most 50 characters.

customer_idstring (uuid)

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.

itemsarray of object

What is being bought, at most 50 lines. Shown on the receipt.

At most 50 items.

namestringrequired

What is being bought.

At most 255 characters.

descriptionstring

More detail, shown on the receipt.

At most 512 characters.

quantityintegerrequired

How many units (an integer, at least 1).

Between 1 and 1000000.

unit_amountintegerrequired

Price of ONE unit, in centimes (an integer).

Between 0 and 999999999999.

success_urlstring

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.

cancel_urlstring

Where the payer is sent if they cancel or the payment fails. Same rules as success_url.

metadataobject

Up to 20 key/value pairs of your own. Keys are at most 40 characters; values must be strings of at most 500 characters.

payment_pagestring

Which page the payer pays on: rais (Raïs' own page) or satim (SATIM's). Defaults to your store's setting.

One of rais, satim.

languagestring

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

One of en, fr, ar.

expires_ininteger

Seconds the payment stays payable: 300 to 2592000 (30 days). Defaults to 86400 (24 hours).

Between 300 and 2592000.

Response

201The payment was created. status is pending until the payer pays.

Returns the Payment object.

Errors

Status	Code	Example message
400	`invalid_json`	The request body is not valid JSON.
400	`parameter_missing`	Provide `amount`, or `items` to compute it.
400	`parameter_unknown`	Unknown parameter.
400	`invalid_amount`	amount must be an integer number of centimes (500000 is 5,000.00 DA).
400	`amount_too_small`	The minimum amount is 50.00 DA (5000 centimes).
400	`amount_too_large`	The maximum amount is 9,999,999,999.99 DA (999999999999 centimes).
400	`amount_mismatch`	amount (400000) does not equal the sum of the items (500000).
400	`currency_not_supported`	Only DZD is supported.
400	`invalid_url`	Live payments require an https:// URL.
400	`invalid_metadata`	metadata can hold at most 20 keys.
400	`invalid_email`	The e-mail address is not valid.
400	`customer_not_found`	No such customer.
400	`invalid_idempotency_key`	The Idempotency-Key header must be 1 to 255 printable ASCII characters.
401	`invalid_api_key`	Invalid API key provided.
403	`insufficient_scope`	This API key does not have the 'payments:write' permission.
403	`account_disabled`	This store is suspended or disabled.
403	`live_mode_not_enabled`	Complete business verification to take live payments.
409	`idempotency_in_progress`	A request with this Idempotency-Key is still being processed. Retry in a moment.
422	`idempotency_key_reused`	This Idempotency-Key was already used with different request parameters.
429	`rate_limit_exceeded`	Too many requests. Slow down and retry after the delay in the Retry-After header.
500	`internal_error`	Something went wrong on our side. Quote the request id to support.
502	`gateway_rejected`	The payment gateway refused to create the payment.
503	`gateway_unavailable`	The payment gateway is temporarily unavailable. Please try again later.

Every error has the same envelope. See Errors.

Request

Headers

Body

Response

Errors

Related guides