Overview

Before initializing the checkout SDK, you must create a payment request via the API and obtain its id. The requestId is a required parameter in the paymentUrl passed to CaiboCheckout.init(). The accompanying token is obtained in the next step (Mint a Checkout Session Token).

This call is made from your backend so your X-API-Key is never exposed to the browser. The returned payment request id is the value you’ll use as requestId in the SDK.

Endpoint

POST {api_base}/payment-requests?send=null
Header: X-API-KEY: <your-merchant-api-key>
Content-Type: application/json

Sample Request Body

{
  "amount": 49.99,
  "unit": "EUR",
  "referenceId": "ORDER-12345",
  "notifyUrl": "https://merchant.example.com/ipg/webhook",
  "successUrl": "https://merchant.example.com/thank-you",
  "failureUrl": "https://merchant.example.com/payment-failed",
  "originDomain": "shop.example.com",
  "client": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "address": "123 Main St",
    "phone": "+15551234567",
    "memberId": "CUST-001"
  }
}

Field Reference

Field	Type	Required	Description
`amount`	number	Yes	Total amount to charge.
`unit`	string	Yes	ISO 4217 currency code (e.g. `EUR`, `USD`).
`referenceId`	string	No	Your internal order identifier; echoed back on webhooks.
`notifyUrl`	string	No	Server-to-server webhook URL for status updates.
`successUrl`	string	No	URL the SDK delivers in the `payment.success` event payload.
`failureUrl`	string	No	URL the SDK delivers in the `payment.failure` event payload.
`originDomain`	string	No	Origin allow-list entry that must match the page hosting the SDK iframe.
`client`	object	No	Optional customer details prefilled into the checkout UI.

Use the Response

The response includes the payment request id. Pass that value as requestId when constructing the paymentUrl for CaiboCheckout.init(). Pair it with a freshly minted checkout session token:

https://pay.caibo.digital/main?requestId=REQUEST_ID&token=CHECKOUT_TOKEN

Do not put your apiKey in this URL. Use a short-lived checkout session token instead — see Mint a Checkout Session Token. The apiKey belongs only on your server.

Replace REQUEST_ID with the id from the response above, and CHECKOUT_TOKEN with the token returned by the mint endpoint.

Next Steps

Mint a Checkout Session Token — required server-side step before opening the iframe.
Quick Start — Inline & Modal
SDK API Reference

Embedded Checkout (SDK)

Create a Payment Request

Overview

Endpoint

Sample Request Body

Field Reference

Use the Response

Next Steps

​Overview

​Endpoint

​Sample Request Body

​Field Reference

​Use the Response

​Next Steps

Overview

Endpoint

Sample Request Body

Field Reference

Use the Response

Next Steps