# Create a payment

> Creates a payment and registers it with the payment gateway.

Source: https://rais.app/docs/api/create-payment

`POST /v1/payments`

Required scope: `payments:write`.

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.

## Request

### Headers

- `Idempotency-Key` (string, optional): 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.

- `amount` (integer, optional): 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.
- `currency` (string, optional): The currency. Only `DZD` (Algerian dinar) is supported; it is the default. At most 32 characters.
- `description` (string, optional): What the payment is for. Shown to the payer and sent to SATIM. At most 512 characters.
- `reference` (string, optional): Your own identifier of the order. Returned as is, and searchable with `GET /payments?reference=`. At most 64 characters.
- `customer` (object, optional): Who is paying. Explicit values take precedence over those of `customer_id`.
  - `name` (string, optional): The payer's full name. At most 255 characters.
  - `email` (string, optional): The payer's e-mail address. At most 255 characters.
  - `phone` (string, optional): The payer's phone number. At most 50 characters.
- `customer_id` (string (uuid), optional): 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.
- `items` (array of object, optional): What is being bought, at most 50 lines. Shown on the receipt. At most 50 items.
  - `name` (string, required): What is being bought. At most 255 characters.
  - `description` (string, optional): More detail, shown on the receipt. At most 512 characters.
  - `quantity` (integer, required): How many units (an integer, at least 1). Between 1 and 1000000.
  - `unit_amount` (integer, required): Price of ONE unit, in centimes (an integer). Between 0 and 999999999999.
- `success_url` (string, optional): 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_url` (string, optional): Where the payer is sent if they cancel or the payment fails. Same rules as `success_url`.
- `metadata` (object, optional): 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_page` (string, optional): 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`.
- `language` (string, optional): 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_in` (integer, optional): Seconds the payment stays payable: 300 to 2592000 (30 days). Defaults to 86400 (24 hours). Between 300 and 2592000.

### Example request

```bash
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
}'
```

## Response

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

Returns the [Payment object](https://rais.app/docs/api/objects/payment.md).

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

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

See [Errors](https://rais.app/docs/errors.md) for every code and how to react.

## Related guides

- [Payments](https://rais.app/docs/payments.md)
- [Hosted checkout and return URLs](https://rais.app/docs/checkout.md)
- [Idempotency and retries](https://rais.app/docs/idempotency.md)