Docs
Search the docs
Find a page in the docs

API reference

Create a checkout

Create a hosted payment page and get its URL.

POST /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 -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"
    }
  }'

Response

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

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