Create checkout session
curl --request POST \
--url https://mapi.boomfi.xyz/v1/checkout/sessions \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--data '
{
"allowed_origin": "https://shop.example",
"amount": "248.00",
"cancel_url": "https://shop.example/cart",
"config": {},
"currency": "EUR",
"customer_reference": "user_4815",
"expires_in": 86400,
"locale": "en-GB",
"merchant_request_id": "dep_92817",
"mode": "Payment",
"payment_link_id": "2ZxK1qLm9vQnR7sT4uY6wB8cD0e",
"redirect_on_completion": "if_required",
"return_url": "https://shop.example/deposit/result",
"success_url": "https://shop.example/deposit/done",
"ui_mode": "Embedded"
}
'import requests
url = "https://mapi.boomfi.xyz/v1/checkout/sessions"
payload = {
"allowed_origin": "https://shop.example",
"amount": "248.00",
"cancel_url": "https://shop.example/cart",
"config": {},
"currency": "EUR",
"customer_reference": "user_4815",
"expires_in": 86400,
"locale": "en-GB",
"merchant_request_id": "dep_92817",
"mode": "Payment",
"payment_link_id": "2ZxK1qLm9vQnR7sT4uY6wB8cD0e",
"redirect_on_completion": "if_required",
"return_url": "https://shop.example/deposit/result",
"success_url": "https://shop.example/deposit/done",
"ui_mode": "Embedded"
}
headers = {
"X-API-KEY": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
allowed_origin: 'https://shop.example',
amount: '248.00',
cancel_url: 'https://shop.example/cart',
config: {},
currency: 'EUR',
customer_reference: 'user_4815',
expires_in: 86400,
locale: 'en-GB',
merchant_request_id: 'dep_92817',
mode: 'Payment',
payment_link_id: '2ZxK1qLm9vQnR7sT4uY6wB8cD0e',
redirect_on_completion: 'if_required',
return_url: 'https://shop.example/deposit/result',
success_url: 'https://shop.example/deposit/done',
ui_mode: 'Embedded'
})
};
fetch('https://mapi.boomfi.xyz/v1/checkout/sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://mapi.boomfi.xyz/v1/checkout/sessions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'allowed_origin' => 'https://shop.example',
'amount' => '248.00',
'cancel_url' => 'https://shop.example/cart',
'config' => [
],
'currency' => 'EUR',
'customer_reference' => 'user_4815',
'expires_in' => 86400,
'locale' => 'en-GB',
'merchant_request_id' => 'dep_92817',
'mode' => 'Payment',
'payment_link_id' => '2ZxK1qLm9vQnR7sT4uY6wB8cD0e',
'redirect_on_completion' => 'if_required',
'return_url' => 'https://shop.example/deposit/result',
'success_url' => 'https://shop.example/deposit/done',
'ui_mode' => 'Embedded'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-KEY: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://mapi.boomfi.xyz/v1/checkout/sessions"
payload := strings.NewReader("{\n \"allowed_origin\": \"https://shop.example\",\n \"amount\": \"248.00\",\n \"cancel_url\": \"https://shop.example/cart\",\n \"config\": {},\n \"currency\": \"EUR\",\n \"customer_reference\": \"user_4815\",\n \"expires_in\": 86400,\n \"locale\": \"en-GB\",\n \"merchant_request_id\": \"dep_92817\",\n \"mode\": \"Payment\",\n \"payment_link_id\": \"2ZxK1qLm9vQnR7sT4uY6wB8cD0e\",\n \"redirect_on_completion\": \"if_required\",\n \"return_url\": \"https://shop.example/deposit/result\",\n \"success_url\": \"https://shop.example/deposit/done\",\n \"ui_mode\": \"Embedded\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-KEY", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://mapi.boomfi.xyz/v1/checkout/sessions")
.header("X-API-KEY", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"allowed_origin\": \"https://shop.example\",\n \"amount\": \"248.00\",\n \"cancel_url\": \"https://shop.example/cart\",\n \"config\": {},\n \"currency\": \"EUR\",\n \"customer_reference\": \"user_4815\",\n \"expires_in\": 86400,\n \"locale\": \"en-GB\",\n \"merchant_request_id\": \"dep_92817\",\n \"mode\": \"Payment\",\n \"payment_link_id\": \"2ZxK1qLm9vQnR7sT4uY6wB8cD0e\",\n \"redirect_on_completion\": \"if_required\",\n \"return_url\": \"https://shop.example/deposit/result\",\n \"success_url\": \"https://shop.example/deposit/done\",\n \"ui_mode\": \"Embedded\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://mapi.boomfi.xyz/v1/checkout/sessions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"allowed_origin\": \"https://shop.example\",\n \"amount\": \"248.00\",\n \"cancel_url\": \"https://shop.example/cart\",\n \"config\": {},\n \"currency\": \"EUR\",\n \"customer_reference\": \"user_4815\",\n \"expires_in\": 86400,\n \"locale\": \"en-GB\",\n \"merchant_request_id\": \"dep_92817\",\n \"mode\": \"Payment\",\n \"payment_link_id\": \"2ZxK1qLm9vQnR7sT4uY6wB8cD0e\",\n \"redirect_on_completion\": \"if_required\",\n \"return_url\": \"https://shop.example/deposit/result\",\n \"success_url\": \"https://shop.example/deposit/done\",\n \"ui_mode\": \"Embedded\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"activated_at": "<string>",
"allowed_origin": "<string>",
"amount": "<string>",
"cancel_url": "<string>",
"client_secret": "<string>",
"completed_at": "<string>",
"config": {},
"created_at": "<string>",
"currency": "<string>",
"customer_reference": "<string>",
"expired_at": "<string>",
"expires_at": "<string>",
"id": "<string>",
"locale": "<string>",
"merchant_request_id": "<string>",
"mode": "Payment",
"payment_id": "<string>",
"payment_link_id": "<string>",
"payment_status": "<string>",
"return_url": "<string>",
"revoked_reason": "<string>",
"status": "Open",
"success_url": "<string>",
"ui_mode": "Hosted"
},
"error": true,
"message": "<string>"
}{
"data": {
"activated_at": "<string>",
"allowed_origin": "<string>",
"amount": "<string>",
"cancel_url": "<string>",
"client_secret": "<string>",
"completed_at": "<string>",
"config": {},
"created_at": "<string>",
"currency": "<string>",
"customer_reference": "<string>",
"expired_at": "<string>",
"expires_at": "<string>",
"id": "<string>",
"locale": "<string>",
"merchant_request_id": "<string>",
"mode": "Payment",
"payment_id": "<string>",
"payment_link_id": "<string>",
"payment_status": "<string>",
"return_url": "<string>",
"revoked_reason": "<string>",
"status": "Open",
"success_url": "<string>",
"ui_mode": "Hosted"
},
"error": true,
"message": "<string>"
}{
"error": {
"code": 400,
"errors": [
{
"domain": "orders",
"reason": "InsufficientQuantity"
}
],
"message": "Insufficient quantity"
}
}{
"error": {
"code": 400,
"errors": [
{
"domain": "orders",
"reason": "InsufficientQuantity"
}
],
"message": "Insufficient quantity"
}
}{
"error": {
"code": 400,
"errors": [
{
"domain": "orders",
"reason": "InsufficientQuantity"
}
],
"message": "Insufficient quantity"
}
}{
"error": {
"code": 400,
"errors": [
{
"domain": "orders",
"reason": "InsufficientQuantity"
}
],
"message": "Insufficient quantity"
}
}{
"error": {
"code": 400,
"errors": [
{
"domain": "orders",
"reason": "InsufficientQuantity"
}
],
"message": "Insufficient quantity"
}
}Checkout Sessions
Create checkout session
Open a checkout session and return the client secret the merchant’s page passes to @boomfi-sdk/connect-web. The secret is returned once, by this call only; repeating merchant_request_id with the same parameters returns the existing session with client_secret absent.
POST
/
checkout
/
sessions
Create checkout session
curl --request POST \
--url https://mapi.boomfi.xyz/v1/checkout/sessions \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--data '
{
"allowed_origin": "https://shop.example",
"amount": "248.00",
"cancel_url": "https://shop.example/cart",
"config": {},
"currency": "EUR",
"customer_reference": "user_4815",
"expires_in": 86400,
"locale": "en-GB",
"merchant_request_id": "dep_92817",
"mode": "Payment",
"payment_link_id": "2ZxK1qLm9vQnR7sT4uY6wB8cD0e",
"redirect_on_completion": "if_required",
"return_url": "https://shop.example/deposit/result",
"success_url": "https://shop.example/deposit/done",
"ui_mode": "Embedded"
}
'import requests
url = "https://mapi.boomfi.xyz/v1/checkout/sessions"
payload = {
"allowed_origin": "https://shop.example",
"amount": "248.00",
"cancel_url": "https://shop.example/cart",
"config": {},
"currency": "EUR",
"customer_reference": "user_4815",
"expires_in": 86400,
"locale": "en-GB",
"merchant_request_id": "dep_92817",
"mode": "Payment",
"payment_link_id": "2ZxK1qLm9vQnR7sT4uY6wB8cD0e",
"redirect_on_completion": "if_required",
"return_url": "https://shop.example/deposit/result",
"success_url": "https://shop.example/deposit/done",
"ui_mode": "Embedded"
}
headers = {
"X-API-KEY": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
allowed_origin: 'https://shop.example',
amount: '248.00',
cancel_url: 'https://shop.example/cart',
config: {},
currency: 'EUR',
customer_reference: 'user_4815',
expires_in: 86400,
locale: 'en-GB',
merchant_request_id: 'dep_92817',
mode: 'Payment',
payment_link_id: '2ZxK1qLm9vQnR7sT4uY6wB8cD0e',
redirect_on_completion: 'if_required',
return_url: 'https://shop.example/deposit/result',
success_url: 'https://shop.example/deposit/done',
ui_mode: 'Embedded'
})
};
fetch('https://mapi.boomfi.xyz/v1/checkout/sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://mapi.boomfi.xyz/v1/checkout/sessions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'allowed_origin' => 'https://shop.example',
'amount' => '248.00',
'cancel_url' => 'https://shop.example/cart',
'config' => [
],
'currency' => 'EUR',
'customer_reference' => 'user_4815',
'expires_in' => 86400,
'locale' => 'en-GB',
'merchant_request_id' => 'dep_92817',
'mode' => 'Payment',
'payment_link_id' => '2ZxK1qLm9vQnR7sT4uY6wB8cD0e',
'redirect_on_completion' => 'if_required',
'return_url' => 'https://shop.example/deposit/result',
'success_url' => 'https://shop.example/deposit/done',
'ui_mode' => 'Embedded'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-KEY: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://mapi.boomfi.xyz/v1/checkout/sessions"
payload := strings.NewReader("{\n \"allowed_origin\": \"https://shop.example\",\n \"amount\": \"248.00\",\n \"cancel_url\": \"https://shop.example/cart\",\n \"config\": {},\n \"currency\": \"EUR\",\n \"customer_reference\": \"user_4815\",\n \"expires_in\": 86400,\n \"locale\": \"en-GB\",\n \"merchant_request_id\": \"dep_92817\",\n \"mode\": \"Payment\",\n \"payment_link_id\": \"2ZxK1qLm9vQnR7sT4uY6wB8cD0e\",\n \"redirect_on_completion\": \"if_required\",\n \"return_url\": \"https://shop.example/deposit/result\",\n \"success_url\": \"https://shop.example/deposit/done\",\n \"ui_mode\": \"Embedded\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-KEY", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://mapi.boomfi.xyz/v1/checkout/sessions")
.header("X-API-KEY", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"allowed_origin\": \"https://shop.example\",\n \"amount\": \"248.00\",\n \"cancel_url\": \"https://shop.example/cart\",\n \"config\": {},\n \"currency\": \"EUR\",\n \"customer_reference\": \"user_4815\",\n \"expires_in\": 86400,\n \"locale\": \"en-GB\",\n \"merchant_request_id\": \"dep_92817\",\n \"mode\": \"Payment\",\n \"payment_link_id\": \"2ZxK1qLm9vQnR7sT4uY6wB8cD0e\",\n \"redirect_on_completion\": \"if_required\",\n \"return_url\": \"https://shop.example/deposit/result\",\n \"success_url\": \"https://shop.example/deposit/done\",\n \"ui_mode\": \"Embedded\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://mapi.boomfi.xyz/v1/checkout/sessions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"allowed_origin\": \"https://shop.example\",\n \"amount\": \"248.00\",\n \"cancel_url\": \"https://shop.example/cart\",\n \"config\": {},\n \"currency\": \"EUR\",\n \"customer_reference\": \"user_4815\",\n \"expires_in\": 86400,\n \"locale\": \"en-GB\",\n \"merchant_request_id\": \"dep_92817\",\n \"mode\": \"Payment\",\n \"payment_link_id\": \"2ZxK1qLm9vQnR7sT4uY6wB8cD0e\",\n \"redirect_on_completion\": \"if_required\",\n \"return_url\": \"https://shop.example/deposit/result\",\n \"success_url\": \"https://shop.example/deposit/done\",\n \"ui_mode\": \"Embedded\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"activated_at": "<string>",
"allowed_origin": "<string>",
"amount": "<string>",
"cancel_url": "<string>",
"client_secret": "<string>",
"completed_at": "<string>",
"config": {},
"created_at": "<string>",
"currency": "<string>",
"customer_reference": "<string>",
"expired_at": "<string>",
"expires_at": "<string>",
"id": "<string>",
"locale": "<string>",
"merchant_request_id": "<string>",
"mode": "Payment",
"payment_id": "<string>",
"payment_link_id": "<string>",
"payment_status": "<string>",
"return_url": "<string>",
"revoked_reason": "<string>",
"status": "Open",
"success_url": "<string>",
"ui_mode": "Hosted"
},
"error": true,
"message": "<string>"
}{
"data": {
"activated_at": "<string>",
"allowed_origin": "<string>",
"amount": "<string>",
"cancel_url": "<string>",
"client_secret": "<string>",
"completed_at": "<string>",
"config": {},
"created_at": "<string>",
"currency": "<string>",
"customer_reference": "<string>",
"expired_at": "<string>",
"expires_at": "<string>",
"id": "<string>",
"locale": "<string>",
"merchant_request_id": "<string>",
"mode": "Payment",
"payment_id": "<string>",
"payment_link_id": "<string>",
"payment_status": "<string>",
"return_url": "<string>",
"revoked_reason": "<string>",
"status": "Open",
"success_url": "<string>",
"ui_mode": "Hosted"
},
"error": true,
"message": "<string>"
}{
"error": {
"code": 400,
"errors": [
{
"domain": "orders",
"reason": "InsufficientQuantity"
}
],
"message": "Insufficient quantity"
}
}{
"error": {
"code": 400,
"errors": [
{
"domain": "orders",
"reason": "InsufficientQuantity"
}
],
"message": "Insufficient quantity"
}
}{
"error": {
"code": 400,
"errors": [
{
"domain": "orders",
"reason": "InsufficientQuantity"
}
],
"message": "Insufficient quantity"
}
}{
"error": {
"code": 400,
"errors": [
{
"domain": "orders",
"reason": "InsufficientQuantity"
}
],
"message": "Insufficient quantity"
}
}{
"error": {
"code": 400,
"errors": [
{
"domain": "orders",
"reason": "InsufficientQuantity"
}
],
"message": "Insufficient quantity"
}
}Authorizations
Body
application/json
Checkout session parameters
The registered origin permitted to frame this session. Embedded only — a hosted or lite checkout is not framed. May be omitted when the organisation has registered exactly one.
Example:
"https://shop.example"
Amount to charge. Must currently match the payment link's own price.
Example:
"248.00"
Where a hosted or lite checkout sends a payer who abandons it. Same rules as success_url, but optional.
Maximum string length:
2048Example:
"https://shop.example/cart"
Passed through to the checkout. No credentials and nothing about the payer — it is served to whoever holds the public embed handle.
Currency to charge in. Must currently match the payment link's own.
Example:
"EUR"
Your own identifier for the payer. Not shown to them.
Maximum string length:
255Example:
"user_4815"
Seconds until the session stops accepting new bindings. Defaults to 86400, bounded 1800-86400, as Stripe's.
Required range:
1800 <= x <= 86400Example:
86400
Preferred display locale.
Maximum string length:
35Example:
"en-GB"
Your idempotency key. Repeating one with the same parameters returns the session it already created; repeating it with different parameters is a conflict.
Maximum string length:
255Example:
"dep_92817"
What the session collects. Only Payment is supported so far.
Available options:
Payment, Subscription, Rfq Example:
"Payment"
Payment link the session opens. Omit for a session with no paylink behind it.
Example:
"2ZxK1qLm9vQnR7sT4uY6wB8cD0e"
Whether an embedded checkout redirects to return_url on completion. Embedded only; never is refused if a redirect-based payment method (e.g. Binance Pay) is available.
Available options:
always, if_required, never Example:
"if_required"
Where an embedded checkout returns the payer. Embedded only; must be on allowed_origin. Required unless redirect_on_completion is never.
Maximum string length:
2048Example:
"https://shop.example/deposit/result"
Where a hosted or lite checkout sends the payer once it completes. Required for those modes, rejected for Embedded, and must be on one of your registered origins.
Maximum string length:
2048Example:
"https://shop.example/deposit/done"
How the checkout is presented.
Available options:
Hosted, Embedded, Lite Example:
"Embedded"