Overview
Develop advanced custom checkout experiences.
The Checkout API is designed to allow creators to use Tebex's Merchant of Record platform without the need to use a Tebex-powered webstore.
If you haven't already done so, we recommend having a read of our quick start guide before beginning integration.
This means creators can create baskets with custom products (as opposed to pre-created products on our webstore platform), and send customers directly to the checkout flow to proceed with payment.
The Checkout API can be used with Tebex.js for a fully embedded checkout experience without the user ever leaving your own website.
Using the Checkout API requires prior approval from our compliance teams. Please note that the Checkout API is not available to some UGC creators, such as those on FiveM or RedM.
Terminology
Basket
To start a transaction, a basket must be created. The basket, similar to a standard eCommerce basket will contain the items that the customer is purchasing
Ident
A string identifier representing the basket
Checkout API Flow
Below is the expected flow your application should follow when implementing the Checkout API. This should be considered a general guideline. For a full list of endpoints available, see the Endpoints page.
You have two options for implementing Checkout API. We include a Checkout request where all data about the customer and their desired packages can be provided in one request.
Option 1. Using the Checkout Request
If your app has existing basket functionality, we recommend using a Checkout request. You can send the details of your customer, basket, and sale information all in one request:
This API call allows the complete checkout flow (create basket, add items, add sale) to be made in a single API call, for when the Seller is managing the basket locally. This endpoint requires prior approval - please contact your account manager.
POST /api/checkout HTTP/1.1
Host: checkout.tebex.io
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 330
{
"basket": {
"first_name": "Neil",
"last_name": "McNeil",
"email": "[email protected]",
"return_url": "https://tebex.io",
"complete_url": "https://tebex.io",
"custom": {
"foo": "bar",
"trackingId": 127,
"list": [
"1",
"2",
"3"
]
}
},
"items": [
{
"package": {
"price": 1.27,
"name": "1000 Gold"
}
}
],
"sale": {
"name": "Test Sale",
"discount_type": "amount",
"amount": 4.99
}
}
{
"ident": "1a-55fff4107740a1f40d844ff89607557f45bfafb3",
"expire": "2022-10-25 15:15:40",
"price": 1.27,
"priceDetails": {
"fullPrice": 1.4,
"subTotal": 1.27,
"discounts": [],
"total": 1.4,
"surcharges": [],
"tax": 0.13,
"balance": 0,
"sales": [],
"giftcards": [],
"roundUp": null
},
"isPaymentMethodUpdate": false,
"returnUrl": null,
"complete": false,
"tax": 1,
"username": null,
"discounts": [
{}
],
"coupons": [
{}
],
"giftcards": [
{}
],
"address": {
"name": "Ted Tebex",
"first_name": "Ted",
"last_name": "Tebex",
"address": "37 Broadhurst Gardens, London, United Kingdom, NW6 3QT",
"email": "[email protected]",
"state_id": null,
"country": "UK",
"postal_code": "NW6 3QT"
},
"rows": [
{
"id": 173125385,
"basket": 725572301,
"package": null,
"override": 0,
"quantity": 2,
"server": null,
"price": 1.27,
"gift_username_id": null,
"options": null,
"recurring": false,
"recurring_period": null,
"recurring_next_payment_date": null,
"meta": {
"name": "1000 Gold",
"rowprice": 2.54,
"initialprice": 1.27,
"isCumulative": false,
"requiredPackages": [],
"requiresAny": false,
"category": false,
"producesGiftCard": false,
"allowsGiftCards": true,
"servers": [],
"limits": {
"user": {
"enabled": false,
"timestamp": 0,
"limit": false
},
"global": {
"enabled": false,
"timestamp": 0,
"limit": false
},
"packageExpiryTime": 0
},
"hasDeliverables": false,
"deliverableTypes": [],
"downloadLink": "",
"hasSellerProtection": true,
"itemType": null,
"revenue_share": [],
"image": null,
"realprice": 1.27
},
"custom": null,
"image_url": null,
"recurring_price": null
}
],
"fingerprint": "",
"creator_code": "text",
"roundup": false,
"cancel_url": "https://tebex.io",
"complete_url": null,
"complete_auto_redirect": false,
"custom": {
"foo": "bar",
"ref": 1234
},
"links": {
"payment": "https://checkout.tebex.io/api/payments/tbx-12345",
"checkout": "https://checkout.tebex.io/checkout/1a-55fff4107740a1f40d844ff89607557f45bfafb3"
}
}
Option 2. Using the Tebex Basket
If you do not have existing basket functionality in your app, you can use the Checkout API to fully manage the customer's basket on Tebex:
Create a basket for the customer.
Your app should save the
ident
value for reference later, as this is the identifier for this customer's basket.
This will create and return a Basket
that can be paid for by redirecting the user to links.checkout
The URL a customer can return to without completing checkout
https://example.tebex.io/
URL the customer can return to after completing payment
https://example.tebex.io/complete
Any custom data to be passed through the request. This will be returned in a post-completion webhook.
{"foo":"bar"}
The first name of the customer
Neil
The last name of the customer
McNeil
An ISO8601 formatted date. After this date the basket cannot be used to checkout.
2025-01-27T18:09:51Z
Automatically redirect to the complete_url provided
true
An ISO 3166-1 alpha-2 character code representing the customer's country.
US
The creator code is used to share a percentage of the payment with another party. See more about creator codes at https://docs.tebex.io/creators/tebex-control-panel/engagement/creator-codes
The IP address of the customer using this basket. Provide the IP if creating a basket on your server backend.
1.2.3.4
POST /api/baskets HTTP/1.1
Host: checkout.tebex.io
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 300
{
"return_url": "https://example.tebex.io/",
"complete_url": "https://example.tebex.io/complete",
"custom": {
"foo": "bar"
},
"first_name": "Neil",
"last_name": "McNeil",
"email": "[email protected]",
"expires_at": "2025-01-27T18:09:51Z",
"complete_auto_redirect": true,
"country": "US",
"creator_code": null,
"ip": "1.2.3.4"
}
Basket created successfully
{
"ident": "1a-55fff4107740a1f40d844ff89607557f45bfafb3",
"expire": "2022-10-25 15:15:40",
"price": 1.27,
"priceDetails": {
"fullPrice": 1.4,
"subTotal": 1.27,
"discounts": [],
"total": 1.4,
"surcharges": [],
"tax": 0.13,
"balance": 0,
"sales": [],
"giftcards": [],
"roundUp": null
},
"isPaymentMethodUpdate": false,
"returnUrl": null,
"complete": false,
"tax": 1,
"username": null,
"discounts": [
{}
],
"coupons": [
{}
],
"giftcards": [
{}
],
"address": {
"name": "Ted Tebex",
"first_name": "Ted",
"last_name": "Tebex",
"address": "37 Broadhurst Gardens, London, United Kingdom, NW6 3QT",
"email": "[email protected]",
"state_id": null,
"country": "UK",
"postal_code": "NW6 3QT"
},
"rows": [
{
"id": 173125385,
"basket": 725572301,
"package": null,
"override": 0,
"quantity": 2,
"server": null,
"price": 1.27,
"gift_username_id": null,
"options": null,
"recurring": false,
"recurring_period": null,
"recurring_next_payment_date": null,
"meta": {
"name": "1000 Gold",
"rowprice": 2.54,
"initialprice": 1.27,
"isCumulative": false,
"requiredPackages": [],
"requiresAny": false,
"category": false,
"producesGiftCard": false,
"allowsGiftCards": true,
"servers": [],
"limits": {
"user": {
"enabled": false,
"timestamp": 0,
"limit": false
},
"global": {
"enabled": false,
"timestamp": 0,
"limit": false
},
"packageExpiryTime": 0
},
"hasDeliverables": false,
"deliverableTypes": [],
"downloadLink": "",
"hasSellerProtection": true,
"itemType": null,
"revenue_share": [],
"image": null,
"realprice": 1.27
},
"custom": null,
"image_url": null,
"recurring_price": null
}
],
"fingerprint": "",
"creator_code": "text",
"roundup": false,
"cancel_url": "https://tebex.io",
"complete_url": null,
"complete_auto_redirect": false,
"custom": {
"foo": "bar",
"ref": 1234
},
"links": {
"payment": "https://checkout.tebex.io/api/payments/tbx-12345",
"checkout": "https://checkout.tebex.io/checkout/1a-55fff4107740a1f40d844ff89607557f45bfafb3"
}
}
Add or remove packages from the customer's basket as desired.
This adds a package (an object describing the product) to the basket {ident}
. For subscriptions, only one subscription item may be in a basket at a time, and it cannot be included with one-time payment items. This endpoint requires prior approval. Please contact your account manager.
The basket identifier.
1a-55fff4107740a1f40d844ff89607557f45bfafb3
The quantity of package
in this basket. This is not the total quantity of overall items in the basket.
2
The type of payment, either single
for one-time payments or subscription
.
single
Possible values: POST /api/baskets/{ident}/packages HTTP/1.1
Host: checkout.tebex.io
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 260
{
"package": {
"name": "1000 Gold",
"price": 1.27,
"type": "subscription",
"qty": 1,
"expiry_period": "month",
"expiry_length": 3,
"custom": {
"foo": "bar"
}
},
"qty": 2,
"type": "single",
"revenue_share": [
{
"wallet_ref": "centralised_404244_127",
"amount": 0.5,
"gateway_fee_percent": 50
}
]
}
{
"ident": "1a-55fff4107740a1f40d844ff89607557f45bfafb3",
"expire": "2022-10-25 15:15:40",
"price": 1.27,
"priceDetails": {
"fullPrice": 1.4,
"subTotal": 1.27,
"discounts": [],
"total": 1.4,
"surcharges": [],
"tax": 0.13,
"balance": 0,
"sales": [],
"giftcards": [],
"roundUp": null
},
"isPaymentMethodUpdate": false,
"returnUrl": null,
"complete": false,
"tax": 1,
"username": null,
"discounts": [
{}
],
"coupons": [
{}
],
"giftcards": [
{}
],
"address": {
"name": "Ted Tebex",
"first_name": "Ted",
"last_name": "Tebex",
"address": "37 Broadhurst Gardens, London, United Kingdom, NW6 3QT",
"email": "[email protected]",
"state_id": null,
"country": "UK",
"postal_code": "NW6 3QT"
},
"rows": [
{
"id": 173125385,
"basket": 725572301,
"package": null,
"override": 0,
"quantity": 2,
"server": null,
"price": 1.27,
"gift_username_id": null,
"options": null,
"recurring": false,
"recurring_period": null,
"recurring_next_payment_date": null,
"meta": {
"name": "1000 Gold",
"rowprice": 2.54,
"initialprice": 1.27,
"isCumulative": false,
"requiredPackages": [],
"requiresAny": false,
"category": false,
"producesGiftCard": false,
"allowsGiftCards": true,
"servers": [],
"limits": {
"user": {
"enabled": false,
"timestamp": 0,
"limit": false
},
"global": {
"enabled": false,
"timestamp": 0,
"limit": false
},
"packageExpiryTime": 0
},
"hasDeliverables": false,
"deliverableTypes": [],
"downloadLink": "",
"hasSellerProtection": true,
"itemType": null,
"revenue_share": [],
"image": null,
"realprice": 1.27
},
"custom": null,
"image_url": null,
"recurring_price": null
}
],
"fingerprint": "",
"creator_code": "text",
"roundup": false,
"cancel_url": "https://tebex.io",
"complete_url": null,
"complete_auto_redirect": false,
"custom": {
"foo": "bar",
"ref": 1234
},
"links": {
"payment": "https://checkout.tebex.io/api/payments/tbx-12345",
"checkout": "https://checkout.tebex.io/checkout/1a-55fff4107740a1f40d844ff89607557f45bfafb3"
}
}
This will remove the given {rows.id}
from the basket {ident}
. The basket must be re-fetched after running to receive updated totals.
The basket identifier.
1a-55fff4107740a1f40d844ff89607557f45bfafb3
The id
of the basket.rows
row to remove.
1
DELETE /api/baskets/{ident}/packages/{rows.id} HTTP/1.1
Host: checkout.tebex.io
Authorization: Basic username:password
Accept: */*
No content
Add any desired sales / discounts to the basket
Adds a Sale
to the basket with {ident}
. Sales cannot be applied to baskets with revenue_share
set.
The basket identifier.
1a-55fff4107740a1f40d844ff89607557f45bfafb3
The name of the sale (displayed to the customer)
Test Sale
The type of discount, either percentage
for deducting a percentage of each item, or amount
to deduct a fixed amount from each item.
amount
Possible values: The amount or percentage to deduct
4.99
POST /api/baskets/{ident}/sales HTTP/1.1
Host: checkout.tebex.io
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 59
{
"name": "Test Sale",
"discount_type": "amount",
"amount": 4.99
}
{
"ident": "1a-55fff4107740a1f40d844ff89607557f45bfafb3",
"expire": "2022-10-25 15:15:40",
"price": 1.27,
"priceDetails": {
"fullPrice": 1.4,
"subTotal": 1.27,
"discounts": [],
"total": 1.4,
"surcharges": [],
"tax": 0.13,
"balance": 0,
"sales": [],
"giftcards": [],
"roundUp": null
},
"isPaymentMethodUpdate": false,
"returnUrl": null,
"complete": false,
"tax": 1,
"username": null,
"discounts": [
{}
],
"coupons": [
{}
],
"giftcards": [
{}
],
"address": {
"name": "Ted Tebex",
"first_name": "Ted",
"last_name": "Tebex",
"address": "37 Broadhurst Gardens, London, United Kingdom, NW6 3QT",
"email": "[email protected]",
"state_id": null,
"country": "UK",
"postal_code": "NW6 3QT"
},
"rows": [
{
"id": 173125385,
"basket": 725572301,
"package": null,
"override": 0,
"quantity": 2,
"server": null,
"price": 1.27,
"gift_username_id": null,
"options": null,
"recurring": false,
"recurring_period": null,
"recurring_next_payment_date": null,
"meta": {
"name": "1000 Gold",
"rowprice": 2.54,
"initialprice": 1.27,
"isCumulative": false,
"requiredPackages": [],
"requiresAny": false,
"category": false,
"producesGiftCard": false,
"allowsGiftCards": true,
"servers": [],
"limits": {
"user": {
"enabled": false,
"timestamp": 0,
"limit": false
},
"global": {
"enabled": false,
"timestamp": 0,
"limit": false
},
"packageExpiryTime": 0
},
"hasDeliverables": false,
"deliverableTypes": [],
"downloadLink": "",
"hasSellerProtection": true,
"itemType": null,
"revenue_share": [],
"image": null,
"realprice": 1.27
},
"custom": null,
"image_url": null,
"recurring_price": null
}
],
"fingerprint": "",
"creator_code": "text",
"roundup": false,
"cancel_url": "https://tebex.io",
"complete_url": null,
"complete_auto_redirect": false,
"custom": {
"foo": "bar",
"ref": 1234
},
"links": {
"payment": "https://checkout.tebex.io/api/payments/tbx-12345",
"checkout": "https://checkout.tebex.io/checkout/1a-55fff4107740a1f40d844ff89607557f45bfafb3"
}
}
Direct the user to the basket's
links.checkout
URL in order to complete payment.
Gets the basket associated with the provided identifier.
The basket identifier.
1a-55fff4107740a1f40d844ff89607557f45bfafb3
GET /api/baskets/{ident} HTTP/1.1
Host: checkout.tebex.io
Authorization: Basic username:password
Accept: */*
{
"ident": "1a-55fff4107740a1f40d844ff89607557f45bfafb3",
"expire": "2022-10-25 15:15:40",
"price": 1.27,
"priceDetails": {
"fullPrice": 1.4,
"subTotal": 1.27,
"discounts": [],
"total": 1.4,
"surcharges": [],
"tax": 0.13,
"balance": 0,
"sales": [],
"giftcards": [],
"roundUp": null
},
"isPaymentMethodUpdate": false,
"returnUrl": null,
"complete": false,
"tax": 1,
"username": null,
"discounts": [
{}
],
"coupons": [
{}
],
"giftcards": [
{}
],
"address": {
"name": "Ted Tebex",
"first_name": "Ted",
"last_name": "Tebex",
"address": "37 Broadhurst Gardens, London, United Kingdom, NW6 3QT",
"email": "[email protected]",
"state_id": null,
"country": "UK",
"postal_code": "NW6 3QT"
},
"rows": [
{
"id": 173125385,
"basket": 725572301,
"package": null,
"override": 0,
"quantity": 2,
"server": null,
"price": 1.27,
"gift_username_id": null,
"options": null,
"recurring": false,
"recurring_period": null,
"recurring_next_payment_date": null,
"meta": {
"name": "1000 Gold",
"rowprice": 2.54,
"initialprice": 1.27,
"isCumulative": false,
"requiredPackages": [],
"requiresAny": false,
"category": false,
"producesGiftCard": false,
"allowsGiftCards": true,
"servers": [],
"limits": {
"user": {
"enabled": false,
"timestamp": 0,
"limit": false
},
"global": {
"enabled": false,
"timestamp": 0,
"limit": false
},
"packageExpiryTime": 0
},
"hasDeliverables": false,
"deliverableTypes": [],
"downloadLink": "",
"hasSellerProtection": true,
"itemType": null,
"revenue_share": [],
"image": null,
"realprice": 1.27
},
"custom": null,
"image_url": null,
"recurring_price": null
}
],
"fingerprint": "",
"creator_code": "text",
"roundup": false,
"cancel_url": "https://tebex.io",
"complete_url": null,
"complete_auto_redirect": false,
"custom": {
"foo": "bar",
"ref": 1234
},
"links": {
"payment": "https://checkout.tebex.io/api/payments/tbx-12345",
"checkout": "https://checkout.tebex.io/checkout/1a-55fff4107740a1f40d844ff89607557f45bfafb3"
}
}
After payment is complete, you may verify payment if you wish by checking the
links.payment
URL associated with the customer's basket.
Recurring Payments
Tebex Checkout supports recurring payments in addition to single, one-time payments. Below are the endpoints you can use for managing a customer's recurring payments.
The recurring payment reference to fetch.
tbx-r-55fff4107740a1f40d844ff89607557f45bfafb3
GET /api/recurring-payments/{reference} HTTP/1.1
Host: checkout.tebex.io
Authorization: Basic username:password
Accept: */*
{
"id": 5000,
"created_at": "2022-12-16T16:43:06.000000Z",
"updated_at": "2022-12-16T16:43:06.000000Z",
"paused_at": "2025-07-01T15:29:24.245Z",
"paused_until": "2025-07-01T15:29:24.245Z",
"next_payment_date": "2022-12-30T16:43:06",
"reference": "88",
"account_id": 1,
"interval": "P2W",
"cancelled_at": "2025-07-01T15:29:24.245Z",
"cancellation_requested_at": "2024-07-25 14:01:03",
"status": {
"id": 2,
"class": "success",
"description": "Active",
"active": 1
},
"amount": {
"amount": 7,
"tax": 1.4,
"period": "P2W"
},
"cancel_reason": "text",
"links": {
"initial_payment": "https://checkout.tebex.io/api/payments/tbx-123123aabccd123-bf71ad?type=txn_id",
"payment_history": [
"https://checkout.tebex.io/api/payments/tbx-123123aabccd123-bf71ad?type=txn_id"
]
}
}
If the new subscription amount is higher than the existing amount, a pro-rata charge will be made to cover the cost of the new price up until the next billing date.
This endpoint requires prior approval - please contact your account manager.
The recurring payment reference to fetch.
tbx-r-55fff4107740a1f40d844ff89607557f45bfafb3
PUT /api/recurring-payments/{reference} HTTP/1.1
Host: checkout.tebex.io
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 201
{
"items": [
{
"type": "subscription",
"qty": 1,
"revenue_share": [],
"package": {
"name": "1000 Gold",
"price": 1.27,
"type": "subscription",
"qty": 1,
"expiry_period": "month",
"expiry_length": 3,
"custom": {
"foo": "bar"
}
}
}
]
}
{
"id": 5000,
"created_at": "2022-12-16T16:43:06.000000Z",
"updated_at": "2022-12-16T16:43:06.000000Z",
"paused_at": "2025-07-01T15:29:24.245Z",
"paused_until": "2025-07-01T15:29:24.245Z",
"next_payment_date": "2022-12-30T16:43:06",
"reference": "88",
"account_id": 1,
"interval": "P2W",
"cancelled_at": "2025-07-01T15:29:24.245Z",
"cancellation_requested_at": "2024-07-25 14:01:03",
"status": {
"id": 2,
"class": "success",
"description": "Active",
"active": 1
},
"amount": {
"amount": 7,
"tax": 1.4,
"period": "P2W"
},
"cancel_reason": "text",
"links": {
"initial_payment": "https://checkout.tebex.io/api/payments/tbx-123123aabccd123-bf71ad?type=txn_id",
"payment_history": [
"https://checkout.tebex.io/api/payments/tbx-123123aabccd123-bf71ad?type=txn_id"
]
}
}
This cancels the recurring payment for the reference provided. Recurring payment references start with tbx-r-
The recurring payment reference to cancel.
tbx-r-55fff4107740a1f40d844ff89607557f45bfafb3
DELETE /api/recurring-payments/{reference} HTTP/1.1
Host: checkout.tebex.io
Authorization: Basic username:password
Accept: */*
{
"id": 5000,
"created_at": "2022-12-16T16:43:06.000000Z",
"updated_at": "2022-12-16T16:43:06.000000Z",
"paused_at": "2025-07-01T15:29:24.245Z",
"paused_until": "2025-07-01T15:29:24.245Z",
"next_payment_date": "2022-12-30T16:43:06",
"reference": "88",
"account_id": 1,
"interval": "P2W",
"cancelled_at": "2025-07-01T15:29:24.245Z",
"cancellation_requested_at": "2024-07-25 14:01:03",
"status": {
"id": 2,
"class": "success",
"description": "Active",
"active": 1
},
"amount": {
"amount": 7,
"tax": 1.4,
"period": "P2W"
},
"cancel_reason": "text",
"links": {
"initial_payment": "https://checkout.tebex.io/api/payments/tbx-123123aabccd123-bf71ad?type=txn_id",
"payment_history": [
"https://checkout.tebex.io/api/payments/tbx-123123aabccd123-bf71ad?type=txn_id"
]
}
}
The recurring payment reference to update.
tbx-r-55fff4107740a1f40d844ff89607557f45bfafb3
Your desired state of the recurring payment. Provide Paused
with paused_until
to pause a recurring payment. Otherwise, provide Active
to resume a recurring payment.
Paused
Possible values: To pause a payment, provide a ISO8601 formatted date on which the payment should be reactivated.
2025-01-27T16:43:53.000000Z
PUT /api/recurring-payments/{reference}/status HTTP/1.1
Host: checkout.tebex.io
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 64
{
"status": "Paused",
"paused_until": "2025-01-27T16:43:53.000000Z"
}
{
"id": 5000,
"created_at": "2022-12-16T16:43:06.000000Z",
"updated_at": "2022-12-16T16:43:06.000000Z",
"paused_at": "2025-07-01T15:29:24.245Z",
"paused_until": "2025-07-01T15:29:24.245Z",
"next_payment_date": "2022-12-30T16:43:06",
"reference": "88",
"account_id": 1,
"interval": "P2W",
"cancelled_at": "2025-07-01T15:29:24.245Z",
"cancellation_requested_at": "2024-07-25 14:01:03",
"status": {
"id": 2,
"class": "success",
"description": "Active",
"active": 1
},
"amount": {
"amount": 7,
"tax": 1.4,
"period": "P2W"
},
"cancel_reason": "text",
"links": {
"initial_payment": "https://checkout.tebex.io/api/payments/tbx-123123aabccd123-bf71ad?type=txn_id",
"payment_history": [
"https://checkout.tebex.io/api/payments/tbx-123123aabccd123-bf71ad?type=txn_id"
]
}
}
OpenAPI Schema and SDKs
Tebex Checkout is documented with OpenAPI. To view the schema and available SDKs, see our releases on GitHub.
Postman Schema
An importable Postman collection can always be downloaded from Tebex Checkout's repository on GitHub.
Examples
The following websites are integrated using the Checkout API.
Last updated
Was this helpful?