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

# Create a Payment Request

> Create a payment request before initializing the embedded checkout SDK and obtain the requestId required by CaiboCheckout.init().

# 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](/ipg/iframe-checkout/checkout-session-token)).

<Info>
  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.
</Info>

## Endpoint

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

## Sample Request Body

```json theme={null}
{
  "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:

```text theme={null}
https://pay.caibo.digital/main?requestId=REQUEST_ID&token=CHECKOUT_TOKEN
```

<Warning>
  Do **not** put your `apiKey` in this URL. Use a short-lived checkout session token instead — see [Mint a Checkout Session Token](/ipg/iframe-checkout/checkout-session-token). The `apiKey` belongs only on your server.
</Warning>

<Tip>
  Replace `REQUEST_ID` with the `id` from the response above, and `CHECKOUT_TOKEN` with the `token` returned by the [mint endpoint](/ipg/iframe-checkout/checkout-session-token).
</Tip>

## Next Steps

* [Mint a Checkout Session Token](/ipg/iframe-checkout/checkout-session-token) — required server-side step before opening the iframe.
* [Quick Start — Inline & Modal](/ipg/iframe-checkout/quick-start)
* [SDK API Reference](/ipg/iframe-checkout/sdk-api-reference)