Accept Cleo at your checkout

Quickstart

The whole integration is a redirect and a confirmation. Cleo hosts the checkout, so the shopper's identity documents, bank credentials and credit data never touch your servers.

Auth & environments

Every call carries your secret key as a bearer token. Your merchant_id is derived from the key — you never send it, and you cannot act on another merchant's behalf.

Authorization: Bearer sk_live_<your-key>
Content-Type: application/json

Environments

Each environment has its own database — nothing you do in sandbox touches production. The API refuses a key from the wrong environment rather than doing something surprising with it:

{"error":"wrong_environment","detail":"This host serves test keys; that key is live. Use the production base URL."}

The only difference between sandbox and production is the base URL and the key.

The key is issued when Cleo approves your merchant application and is shown once. We store it hashed — we cannot recover it, only replace it. It is verified on every call, so a revoked key stops working on the very next request.

Create a session

Body

All URLs must be public https. URLs pointing at localhost, private ranges, link-local addresses, or containing credentials are rejected.

curl -X POST https://api-bnpl.cleo.cl/v1/sessions \
  -H "Authorization: Bearer $CLEO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "amount": 149990,
        "currency": "CLP",
        "merchant_order_id": "ORD-10432",
        "success_url": "https://shop.example.com/checkout/thanks?order=10432",
        "failure_url": "https://shop.example.com/checkout/error?order=10432",
        "callback_url": "https://shop.example.com/api/cleo/webhook"
      }'

<?php
$ch = curl_init("https://api-bnpl.cleo.cl/v1/sessions");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("CLEO_SECRET_KEY"),
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "amount"            => 149990,
    "merchant_order_id" => "ORD-10432",
    "success_url"       => "https://shop.example.com/checkout/thanks?order=10432",
    "failure_url"       => "https://shop.example.com/checkout/error?order=10432",
    "callback_url"      => "https://shop.example.com/api/cleo/webhook",
  ]),
  CURLOPT_RETURNTRANSFER => true,
]);
$session = json_decode(curl_exec($ch), true);
header("Location: " . $session["checkout_url"]);

import os, requests

r = requests.post(
    "https://api-bnpl.cleo.cl/v1/sessions",
    headers={"Authorization": f"Bearer {os.environ['CLEO_SECRET_KEY']}"},
    json={
        "amount": 149990,
        "merchant_order_id": "ORD-10432",
        "success_url": "https://shop.example.com/checkout/thanks?order=10432",
        "failure_url": "https://shop.example.com/checkout/error?order=10432",
        "callback_url": "https://shop.example.com/api/cleo/webhook",
    },
)
session = r.json()
checkout_url = session["checkout_url"]  # redirect the shopper here

const res = await fetch("https://api-bnpl.cleo.cl/v1/sessions", {
  method: "POST",
  headers: {
    authorization: `Bearer ${process.env.CLEO_SECRET_KEY}`,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    amount: 149990,
    merchant_order_id: "ORD-10432",
    success_url: "https://shop.example.com/checkout/thanks?order=10432",
    failure_url: "https://shop.example.com/checkout/error?order=10432",
    callback_url: "https://shop.example.com/api/cleo/webhook",
  }),
});
const session = await res.json();
return Response.redirect(session.checkout_url, 303);

Response · 201

{
  "session_id":   "b26d5129-146e-459b-9411-3a3800874305",
  "checkout_url": "https://api-bnpl.cleo.cl/checkout/start/b26d5129-146e-459b-9411-3a3800874305",
  "expires_at":   "2026-07-23T15:26:06.900Z",
  "amount":       149990,
  "currency":     "CLP",
  "status":       "RUT",
  "reused":       false
}

Retries and double payments

Creating a session again with the same merchant_order_id:

• returns the existing session (200, "reused": true) while it is still open — a retry never creates a second checkout;
• returns 409 order_already_paid once that order has been paid, so a stale tab or a duplicated request can't charge the shopper twice.

Merchants who genuinely need repeated references can be flagged to allow them.

Redirect the shopper

Send the browser to the checkout_url you received:

That page shows your store name, the order reference and the amount, then runs the Cleo flow: Chilean RUT verification, WhatsApp OTP, a read-only bank connection, the credit decision, the instalment plan and the direct-debit mandate. The amount is set by the merchant and the shopper cannot change it.

When they finish, the shopper gets a "Volver a {your store}" button pointing at your success_url.

Callback (result)

When the checkout finishes we POST the result to your callback_url:

{
  "createdAt": "2026-07-23T15:40:11.000Z",
  "callbackId": 8123,
  "version": "v1",
  "event": "CHECKOUT_SUCCEEDED",
  "payload": {
    "sessionId":          "b26d5129-…",
    "merchantId":         "your-login",
    "merchantSessionId":  null,
    "merchantCustomerId": null,
    "merchantOrderId":    "ORD-10432",
    "status":             "OK",
    "currency":           "CLP",
    "amount":             149990,
    "invoiceNumber":      "CLO-4821-1",
    "customer": {
      "ssn":   "12345678-9",
      "email": "…",
      "phone": "…",
      "name":    { "first": "…", "last": "…", "org": null },
      "address": { "street": "…", "region": "…", "country": "CL" }
    }
  }
}

event is CHECKOUT_SUCCEEDED (status: "OK") or CHECKOUT_FAILED (status: "ERROR", e.g. credit declined). With callback_method: "GET" the same JSON arrives base64-encoded in a SWEETPAY_DATA query parameter.

At-least-once delivery

We try twice immediately, then retry on a backoff — 1 min, 5 min, 30 min, 2 h, 6 h, i.e. 6 attempts over roughly 8.5 hours — until your endpoint answers 2xx. Any 2xx counts as delivered; a 45s timeout counts as a failure.

Because a retry re-sends the same payload byte for byte, callbackId is stable across attempts:

• Make your handler idempotent — dedupe on callbackId. If your endpoint processed the request but the 2xx never reached us, you will be called again.
• Answer fast (ack, then do the work). We treat a slow endpoint as a failure.

If all attempts fail we stop and log it; the order is still paid, and the status endpoint remains the source of truth.

Verifying the callback signature

When X-Cleo-Signature is present, it is sha256=<hex> where <hex> is HMAC-SHA256(raw request body, your webhook_signing_secret) — the same whsec_… shown to you when your key was issued (ask Cleo if you need it resent). Recompute it over the exact raw bytes you received (before any JSON re-serialization, since key order or whitespace changes the hash) and compare with a constant-time comparison:

const crypto = require("node:crypto");
function verify(rawBody, header, secret) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return header?.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

Read the status

curl https://api-bnpl.cleo.cl/v1/sessions/b26d5129-146e-459b-9411-3a3800874305 \
  -H "Authorization: Bearer $CLEO_SECRET_KEY"

const s = await (await fetch(
  `https://api-bnpl.cleo.cl/v1/sessions/${sessionId}`,
  { headers: { authorization: `Bearer ${process.env.CLEO_SECRET_KEY}` } },
)).json();
if (s.paid) await fulfil(s.merchant_order_id);

Response · 200

{
  "session_id":        "b26d5129-…",
  "status":            "CONFIRMED",
  "paid":              true,
  "expired":           false,
  "expires_at":        "2026-07-23T15:26:06.900Z",
  "amount":            149990,
  "currency":          "CLP",
  "merchant_order_id": "ORD-10432",
  "cancelled":         false,
  "callback": { "sent_at": "2026-07-23T15:40:11.000Z", "delivered": true },
  "installments": [
    { "invoice_number": "CLO-4821-1", "amount": 52497, "due_at": "…", "number": 1, "payment_status": "PENDING" }
  ]
}

paid is the field to key on. A session you didn't create returns 404 — you can only read your own.

Cancel an order

// cancel-partial
{ "amount": 15000 }

Cancels (fully or by a given amount) the order behind that session and creates a refund for anything already paid over the new total — same engine and rules as when Cleo cancels it for you: an order already cancelled returns 409 already_cancelled, one with an instalment mid-payment returns 409 invoices_in_payment_process, and a cancel-partial amount that isn't strictly less than the order's cancellable remainder returns 400 amount_too_high (or 400 bad_amount if it isn't a positive number). A session you didn't create returns 404 session_not_found — you can only cancel your own, same as reading status.

Response · 200

{ "ok": true, "cancelledInvoiceNumbers": ["CLO-4821-1"], "refundCreated": true, "amountRefunded": 31497 }

You'll also get an ORDER_CANCELLED callback (see Callback) at your callback_url — discriminate on event, since it's the same URL that receives CHECKOUT_SUCCEEDED/CHECKOUT_FAILED.

Session statuses

status tracks the shopper's journey. To decide what to do with the order, paid is enough; the intermediate statuses are for diagnostics.

A session that passes its expires_at without being confirmed comes back with "expired": true. The shopper can start over with a new session.

Errors

Testing in sandbox

Integrate against https://sandbox-api-bnpl.cleo.cl with an sk_test_… key first. These values complete a purchase end-to-end without a real WhatsApp message, bank or credit lookup:

Going live

Once your sandbox integration is ready: