Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.caibo.digital/llms.txt

Use this file to discover all available pages before exploring further.

​
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

FieldTypeRequiredDescription
amountnumberYesTotal amount to charge.
unitstringYesISO 4217 currency code (e.g. EUR, USD).
referenceIdstringNoYour internal order identifier; echoed back on webhooks.
notifyUrlstringNoServer-to-server webhook URL for status updates.
successUrlstringNoURL the SDK delivers in the payment.success event payload.
failureUrlstringNoURL the SDK delivers in the payment.failure event payload.
originDomainstringNoOrigin allow-list entry that must match the page hosting the SDK iframe.
clientobjectNoOptional 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