API Checkout Quickstart
Create a dynamic Checkout Session from your backend and redirect the buyer to Yolfi.
API Checkout Quickstart
1. Calculate the order on your server
Load product prices from your database, apply discounts and taxes, and lock the resulting order. Do not accept the final amount from the browser.
2. Create a Checkout Session
Call Yolfi from your backend with your organization API key. Send a unique idempotency key for this logical order attempt.
curl https://app.yolfi.com/api/checkout-sessions \
-X POST \
-H "Authorization: Bearer $YOLFI_API_KEY" \
-H "Idempotency-Key: checkout_order_1042_v1" \
-H "Content-Type: application/json" \
-d '{
"amount": "24.99",
"currency": "USD",
"merchantOrderId": "order-1042",
"description": "Digital goods order",
"customerEmail": "buyer@example.com",
"successUrl": "https://merchant.example/orders/order-1042?session_id={CHECKOUT_SESSION_ID}",
"cancelUrl": "https://merchant.example/cart",
"metadata": {
"order_id": "order-1042"
}
}'Send amount as a decimal string, not a floating-point number. Product names, quantities,
discounts, and taxes remain in your own order system; Yolfi only stores the final payment amount.
3. Redirect the buyer
Yolfi returns the immutable price snapshot and hosted URL:
{
"success": true,
"data": {
"id": "ycs_0123456789abcdef0123456789abcdef",
"object": "checkout_session",
"status": "OPEN",
"amount": "24.99",
"currency": "USD",
"merchantOrderId": "order-1042",
"expiresAt": "2026-09-13T13:45:00.000Z",
"url": "https://pay.yolfi.com/ycs_0123456789abcdef0123456789abcdef"
}
}Return data.url to the browser and redirect there. Do not expose your API key.
4. Fulfill from the webhook
Once the blockchain payment is final, the signed payment.confirmed event contains:
{
"type": "payment.confirmed",
"data": {
"invoiceId": "550e8400-e29b-41d4-a716-446655440000",
"checkoutSessionId": "ycs_0123456789abcdef0123456789abcdef",
"merchantOrderId": "order-1042",
"status": "confirmed"
}
}Verify the webhook signature against the raw body, deduplicate by the event id, find the order by
merchantOrderId or checkoutSessionId, and fulfill it once. A browser redirect is not proof of
payment.