# Register a new hosted checkout session

This endpoint creates a new hosted checkout session for processing online payments.\
The merchant submits order details, payer information, and callback URLs. The API returns a unique `checkoutId` and a `checkoutUrl` that can be used to redirect the customer to the hosted payment page.

### Request

**HTTP Method**: `POST`\
**Endpoint**:

```
/v2/checkouts
```

**Headers**:

```http
Authorization: {tokenType} {access_token}
Content-Type: application/json
```

***

**Request Body Parameters**

| Name        | Type   | Required | Description                                                       |
| ----------- | ------ | -------- | ----------------------------------------------------------------- |
| amount      | number | Yes      | Total amount to be charged, in major currency units.              |
| currency    | string | Yes      | ISO 4217 currency code (e.g. MDL).                                |
| orderInfo   | object | Yes      | Order details including ID, description, date, amounts and items. |
| payerInfo   | object | Optional | Information about the payer (name, contact, IP, user agent).      |
| language    | string | Optional | Preferred language for the checkout interface (ro, ru, en).       |
| callbackUrl | string | Yes      | URL to which payment status will be sent after processing.        |
| successUrl  | string | Optional | Redirect URL after successful payment.                            |
| failUrl     | string | Optional | Redirect URL after failed or cancelled payment.                   |

***

#### OrderInfo object

| Field            | Type               | Required | Description                          |
| ---------------- | ------------------ | -------- | ------------------------------------ |
| id               | string             | Yes      | Merchant’s order identifier.         |
| description      | string             | Yes      | Description or purpose of the order. |
| date             | string (date-time) | Yes      | Order creation timestamp (ISO 8601). |
| orderAmount      | number             | Optional | Order subtotal (without delivery).   |
| orderCurrency    | string             | Optional | Currency for the order amount.       |
| deliveryAmount   | number             | Optional | Delivery amount.                     |
| deliveryCurrency | string             | Optional | Currency for the delivery amount.    |
| items\[]         | array              | Yes      | List of order items.                 |

***

#### OrderInfo.items\[]

| Field        | Type    | Required | Description                          |
| ------------ | ------- | -------- | ------------------------------------ |
| externalId   | string  | Yes      | External product identifier (SKU).   |
| title        | string  | Yes      | Product name or title.               |
| amount       | number  | Yes      | Item price, in major currency units. |
| currency     | string  | Yes      | ISO 4217 code of the item currency.  |
| quantity     | integer | Yes      | Number of items ordered.             |
| displayOrder | integer | Optional | Optional display order index.        |

***

#### PayerInfo object

| Field     | Type   | Required | Description                              |
| --------- | ------ | -------- | ---------------------------------------- |
| name      | string | Yes      | Payer full name.                         |
| email     | string | Yes      | Payer email address.                     |
| phone     | string | Yes      | Payer phone number (E.164 format).       |
| ip        | string | Yes      | IP address of the payer.                 |
| userAgent | string | Yes      | User agent string of the payer’s device. |

***

**Example request**

```json
{
  "amount": 50.61,
  "currency": "MDL",
  "orderInfo": {
    "id": "EK123123BV",
    "description": "Order description",
    "date": "2025-11-03T09:28:40.814748+00:00",
    "orderAmount": null,
    "orderCurrency": null,
    "deliveryAmount": null,
    "deliveryCurrency": null,
    "items": [
      {
        "externalId": "243345345",
        "title": "Product1",
        "amount": 50.61,
        "currency": "MDL",
        "quantity": 3,
        "displayOrder": null
      },
      {
        "externalId": "54353453",
        "title": "Product2",
        "amount": 50.61,
        "currency": "MDL",
        "quantity": 2,
        "displayOrder": null
      }
    ]
  },
  "payerInfo": {
    "name": "John D.",
    "email": "test@gmail.com",
    "phone": "+37377382716",
    "ip": "192.168.172.22",
    "userAgent": "Mozilla/5.0"
  },
  "language": "ro",
  "callbackUrl": "https://example.com/path",
  "successUrl": "https://example.com/path",
  "failUrl": "https://example.com/path"
}


```

***

### Response

#### Response Parameters

| Name                 | Type          | Description                                                                                                |
| -------------------- | ------------- | ---------------------------------------------------------------------------------------------------------- |
| `result.checkoutId`  | string (UUID) | Unique identifier of the created checkout session.                                                         |
| `result.checkoutUrl` | string        | URL to redirect the payer to the hosted checkout page. (The bank URL to which the user must be redirected) |
| `ok`                 | boolean       | Indicates successful request execution.                                                                    |
| `errors`             | array         | List of validation or processing errors, if any.                                                           |

***

#### Example Successful Response

```json
{
  "result": {
    "checkoutId": "f6d0812a-50ee-47ec-bb3f-d3b3a4dda40d",
    "checkoutUrl": "https://example.com/path"
  },
  "ok": true,
  "errors": null
}

```

***

### Notes

* The checkout is created in **Pending** status.
