# Checkouts

> Send customers to a hosted payment page and get them back with a result.

A checkout is a hosted payment page. You create it with the items and where to send the customer afterwards, redirect the customer to its `checkout_url`, and get the result back. Your site never handles payment details.

## Hosted or direct

|   | Hosted | Direct |
| --- | --- | --- |
| Page | The Camel payment page, with your logo and colors | The provider's own checkout page |
| Payment methods | The customer picks from all your active connections | Only the connection you choose |
| Create it with | No `provider` | `provider` and `connection_id` |

## Create a checkout

**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()
```

**201 Created**

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

The amount is the sum of `quantity × unit_amount` over the items. A hosted checkout needs at least one active connection that accepts the currency. With a production key, both return URLs must use HTTPS.

## After the payment

Camel sends the customer back to your site with the checkout id in the query string:

- `success_url?checkout_id=chk_…&payment=approved`, or `payment=pending` when the provider hasn't confirmed it yet.
- `cancel_url?checkout_id=chk_…&payment=rejected` when a direct checkout fails (also `cancelled` or `provider_error`). On the hosted page, a declined customer can try again with another method.

> **Warning**
>
> The redirect is for showing a page, not for fulfilling the order. Rely on the `checkout.completed` webhook, or retrieve the checkout from your server.

## Checkout statuses

| Status | Meaning |
| --- | --- |
| `open` | Waiting for the customer to pay. |
| `completed` | Paid: its payment is approved. |
| `expired` | Not paid in time. Hosted checkouts last 24 hours. |
| `failed` | The provider refused to create a direct checkout. |
| `unknown` | The provider's answer was lost while creating or capturing it. |

## PayPal capture

A direct PayPal checkout needs one more step: after the customer approves it, call [Capture a checkout](https://camelpayment.com/docs/api-reference/capture-checkout.md) to take the money. Other providers complete on their own.
