Create checkout button embed session

POST

/api/v1/merchants/checkout-buttons/{button_id}/embed-session

Call this from your server to get a one-time buy link for a checkout button, with metadata
your server signs. Send the customer to buy_url. Create the button in the merchant portal first.

The link works once and expires after 15 minutes (expires_in_seconds). Create a new session for each customer visit.

metadata is attached to the resulting checkout and returned on checkout responses and webhooks under
meta_data.embed.signed. Trust only signed; meta_data.embed.client comes from the browser.

Errors from this endpoint return {"detail"} without error_code.

Request

Authorization

API Key

Add parameter in header

x-api-key

Example:

x-api-key: ********************

Path Params

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢200

application/json

Embed session created.

Bodyapplication/json

🟠400

🟠404

🟠401Unauthorized

🟠403Forbidden

🟠422RequestValidationError

Request Example

Shell

JavaScript

Java

Swift

curl --location '/api/v1/merchants/checkout-buttons/5b2c7e1a-3d4f-4a6b-9c8d-0e1f2a3b4c5d/embed-session' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
    "metadata": {
        "order_id": "ORD-7842",
        "plan": "pro",
        "seats": 5
    }
}'

Response Example

200 - Success

{
    "data": {
        "buy_url": "https://app.kutanaafrica.com/public/buy/5b2c7e1a-3d4f-4a6b-9c8d-0e1f2a3b4c5d?embed=Xq3v9TzL0bN2kR7sW4yH8mJ1cF6dA5eG0pU3iO2nV9w",
        "embed_token": "Xq3v9TzL0bN2kR7sW4yH8mJ1cF6dA5eG0pU3iO2nV9w",
        "expires_in_seconds": 900
    },
    "message": "Embed session created",
    "status": "success"
}

Modified at 2026-10-13 22:36:35

Cancel checkout

Checkout created