# Create a checkout

> Create a hosted payment page and get its URL.

`POST https://api.camelpayment.com/v1/checkouts`

Leave out provider for a hosted checkout: the Camel payment page, where the customer picks a method from your active connections. It expires after 24 hours. Set provider and connection_id for a direct checkout on the provider’s own page.

With a production key, success_url and cancel_url must use HTTPS.

## Headers

- `Idempotency-Key` (string, required): A unique key for this operation, up to 255 characters. Retrying with the same key and body returns the original response. See Idempotency.

## Body parameters

- `items` (array, required): 1 to 100 items, each with name (up to 255 characters), quantity (1–999), and unit_amount (minor units, greater than 0). The checkout amount is their sum.
- `currency` (string, required): Three-letter ISO code.
- `success_url` (string, required): Where the customer returns after paying.
- `cancel_url` (string, required): Where the customer returns if they leave or the payment fails.
- `provider` (string): mercadopago, stripe, paypal, or uala. Set it for a direct checkout.
- `connection_id` (string): The connection for a direct checkout. Requires provider.
- `external_reference` (string): Your own id, up to 128 characters.
- `metadata` (object): Up to 50 keys of your own data.

## Request

**cURL**

```bash
curl -X POST https://api.camelpayment.com/v1/checkouts \
  -H "Authorization: Bearer $CAMEL_API_KEY" \
  -H "Idempotency-Key: order-1524" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "name": "Desk lamp",
        "quantity": 2,
        "unit_amount": 425000
      }
    ],
    "currency": "ARS",
    "success_url": "https://shop.example.com/orders/1524/return",
    "cancel_url": "https://shop.example.com/orders/1524",
    "external_reference": "ORDER-1524",
    "metadata": {
      "order_id": "1524"
    }
  }'
```

**Node.js**

```javascript
const response = await fetch('https://api.camelpayment.com/v1/checkouts', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CAMEL_API_KEY}`,
    'Idempotency-Key': 'order-1524',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "items": [
      {
        "name": "Desk lamp",
        "quantity": 2,
        "unit_amount": 425000
      }
    ],
    "currency": "ARS",
    "success_url": "https://shop.example.com/orders/1524/return",
    "cancel_url": "https://shop.example.com/orders/1524",
    "external_reference": "ORDER-1524",
    "metadata": {
      "order_id": "1524"
    }
  })
});
const data = await response.json();
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://api.camelpayment.com/v1/checkouts",
    headers={
        "Authorization": f"Bearer {os.environ['CAMEL_API_KEY']}",
        "Idempotency-Key": "order-1524",
    },
    json={
        "items": [
            {
                "name": "Desk lamp",
                "quantity": 2,
                "unit_amount": 425000
            }
        ],
        "currency": "ARS",
        "success_url": "https://shop.example.com/orders/1524/return",
        "cancel_url": "https://shop.example.com/orders/1524",
        "external_reference": "ORDER-1524",
        "metadata": {
            "order_id": "1524"
        }
    },
)
data = response.json()
```

## Response

**201**

```json
{
  "id": "chk_01JBX9C3D4E5F6G7H8J9KMNPQR",
  "object": "checkout",
  "mode": "hosted",
  "provider": null,
  "connection_id": null,
  "provider_checkout_id": null,
  "amount": 850000,
  "currency": "ARS",
  "charge": null,
  "items": [
    {
      "name": "Desk lamp",
      "quantity": 2,
      "unit_amount": 425000
    }
  ],
  "status": "open",
  "provider_status": null,
  "checkout_url": "https://camelpayment.com/pay/chk_01JBX9C3D4E5F6G7H8J9KMNPQR",
  "success_url": "https://shop.example.com/orders/1524/return",
  "cancel_url": "https://shop.example.com/orders/1524",
  "external_reference": "ORDER-1524",
  "metadata": {
    "order_id": "1524"
  },
  "expires_at": "2026-11-13T15:04:05Z",
  "created_at": "2026-11-12T15:04:05Z",
  "updated_at": "2026-11-12T15:04:05Z"
}
```

## Errors

| Status | When |
| --- | --- |
| `202` | Direct checkouts only: the provider did not give a definitive answer. |
| `401` | The API key is missing, malformed, or revoked. |
| `402` | Production only: the account has a past-due Camel invoice. |
| `404` | The connection does not exist in this environment. |
| `409` | The Idempotency-Key was used with a different body, or the first request is still running. |
| `422` | The body is invalid, no active connection accepts the currency, or a production return URL is not HTTPS. |
| `429` | Too many requests. Wait for Retry-After seconds. |
| `502` | Direct checkouts only: the provider returned an error. |
| `503` | A currency conversion was needed and exchange rates are unavailable. |
