Docs
Search the docs
Find a page in the docs

Guides

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

HostedDirect
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 -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"
    }
  }'
201 Created
{
  "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.

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

StatusMeaning
openWaiting for the customer to pay.
completedPaid: its payment is approved.
expiredNot paid in time. Hosted checkouts last 24 hours.
failedThe 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 to take the money. Other providers complete on their own.