Endpoints

Important Update

We want to inform you about upcoming changes to our API that we're releasing on the 1st April 2024. Please be aware that these changes might impact your integration and may require updates to your existing codebase. The following JSON properties in the Basket resource are being removed:

recurring
recurringPeriod
recurringNextPaymentDate

These properties will be moved within Basket Rows (i.e. the individual products/package):

recurring
recurring_period
recurring_next_payment_date

Our API documentation below has been updated to reflect this, please see Fetch a basket by its identifier for an example.

Baskets

Create a basket that can be used to pay for items

POST https://checkout.tebex.io/api/baskets

Request Body

Name Type Description

Name	Type	Description
return_url*	String	URL the customer can return to when clicking ‘return to ACCOUNTNAME'
complete_url*	String	URL the customer can return to after completing their payment
custom	Object	Free-form object allowing custom data to be passed through the request - this will be returned as is as part of webhooks post completion
first_name	String	First name of the customer to checkout
last_name	String	Last name of the customer to checkout
email	String	Email address of the customer to checkout
expires_at	Date - ISO8601	The expiry time of the basket, the customer won't be able to purchase the basket once it has expired
complete_auto_redirect	Boolean	Automatically redirect to the complete_url provided above
country	String	The ISO 3166-1 alpha-2 code of the customer's country, e.g. `US`
creator_code	String	The creator code that should automatically be applied to this basket

return_url*

String

URL the customer can return to when clicking ‘return to ACCOUNTNAME'

complete_url*

String

URL the customer can return to after completing their payment

custom

Object

Free-form object allowing custom data to be passed through the request - this will be returned as is as part of webhooks post completion

first_name

String

First name of the customer to checkout

last_name

String

Last name of the customer to checkout

String

Email address of the customer to checkout

expires_at

Date - ISO8601

The expiry time of the basket, the customer won't be able to purchase the basket once it has expired

complete_auto_redirect

Boolean

Automatically redirect to the complete_url provided above

country

String

The ISO 3166-1 alpha-2 code of the customer's country, e.g. US

creator_code

String

The creator code that should automatically be applied to this basket

{
    "ident": "1a-55fff4107740a1f40d844ff89607557f45bfafb3",
    "expire": "2022-10-25 15:15:40",
    "price": 0,
    "priceDetails": {
        "fullPrice": 0,
        "subTotal": 0,
        "discounts": [],
        "total": 0,
        "surcharges": [],
        "tax": 0,
        "balance": 0,
        "sales": [],
        "giftcards": [],
        "recurring": null,
        "roundUp": null
    },
    "type": "single",
    "complete": false,
    "tax": null,
    "username": null,
    "discounts": null,
    "coupons": [],
    "giftcards": [],
    "address": {
        "name": null,
        "first_name": null,
        "last_name": null,
        "address": null,
        "email": null,
        "state_id": null,
        "country": "XX",
        "postal_code": null
    },
    "actions": null,
    "game_currency": null,
    "tebex_account_id": null,
    "verified": null,
    "rows": [],
    "fingerprint": null,
    "creator_code": "",
    "roundup": null,
    "custom": {
        "ref": "tst-123-123"
    },
    "links": {
        "checkout": "https://checkout.tebex.io/checkout/1a-55fff4107740a1f40d844ff89607557f45bfafb3"
    }
}

{
    // Response
}

Fetch a basket by its identifier

GET https://checkout.tebex.io/api/baskets/{ident}

Path Parameters

Name	Type	Description
ident*	String	The ident for this basket (provided upon creation)

Name

Type

Description

ident*

String

The ident for this basket (provided upon creation)

NB: The links.payment property is only returned if the basket has been paid for and a payment exists with the complete/refund/chargeback status.

The links.checkout property is only returned if the basket has not been paid, and is the URL to send the customer to to make payment

{
    "ident": "1a-55fff4107740a1f40d844ff89607557f45bfafb3",
    "expire": "2022-10-25 15:15:40",
    "price": 5.77,
    "priceDetails": {
        "fullPrice": 6.2,
        "subTotal": 5.7700000000000005,
        "discounts": [],
        "total": 5.77,
        "surcharges": [],
        "tax": 0,
        "balance": 5.77,
        "sales": [
            {
                "id": 0,
                "name": "Test Sale",
                "package_id": null,
                "discountAmount": 0.43,
                "type": "sale"
            }
        ],
        "giftcards": [],
        "recurring": null,
        "roundUp": null
    },
    "type": "single",
    "complete": false,
    "tax": 0,
    "username": null,
    "discounts": null,
    "coupons": [],
    "giftcards": [],
    "address": {
        "name": "",
        "first_name": "",
        "last_name": "",
        "address": "",
        "email": "",
        "state_id": null,
        "country": "XX",
        "postal_code": null
    },
    "actions": null,
    "game_currency": null,
    "tebex_account_id": null,
    "verified": null,
    "rows": [
        {
            "id": 72,
            "basket": 46,
            "package": null,
            "override": 0,
            "quantity": 1,
            "server": null,
            "price": 5.7700000000000005,
            "gift_username_id": null,
            "options": null,
            "recurring": false,
            "recurring_period": null,
            "recurring_next_payment_date": null,
            "meta": {
                "name": "Super Cool Product 2",
                "rowprice": 5.7700000000000005,
                "initialprice": 6.2,
                "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,
                "itemType": null,
                "revenue_share": [],
                "custom": "tbx-test-1234",
                "realprice": 5.7700000000000005
            },
            "custom": "tbx-test-1234"
        }
    ],
    "fingerprint": null,
    "creator_code": "",
    "roundup": null,
    "custom": {
        "ref": "tst-123-123"
    },
    "links": {
        "checkout": "https://checkout.tebex.io/checkout/1a-55fff4107740a1f40d844ff89607557f45bfafb3",
        "payment": "https://checkout.tebex.io/api/payments/tbx-12345"
    }
}

{
    // Response
}

Add package to a basket

POST https://checkout.tebex.io/api/baskets/{ident}/packages

This endpoint requires prior approval - please contact your account manager.

Path Parameters

Name	Type	Description
ident*	String	The ident for this basket (provided upon creation)

Name

Type

Description

ident*

String

The ident for this basket (provided upon creation)

Request Body

Name Type Description

Name	Type	Description
package*	Object	Object describing the product to be added to the basket
package.name*	String	The name of the item being purchased(shown to the customer on checkout in and in their email receipt)
package.price*	Float	A float (decimal) value representingthe price of the package in your account currency
package.expiry_period	Enum	The renewal period for this item (required for subscription purchases). Allowed values: day, month, year
package.expiry_length	Integer	An integer representing the number of `expiry_period`s that make up the renewal period (required for subscription purchases)
package.metaData	Object	A sub-object to hold seller-specific properties related to the item (must be pre-agreed with Tebex)
package.metaData.custom	String	A free-text string field that is passed back to you via the webhook (for example a tracking ID)
qty	Integer	Number of package to add to basket (default: 1)
type*	Enum	The type of payment. Allowed values: single (one time payment), subscription (recurring payment)
revenue_share	Array	An array of payment destination objects describing how the purchase should be split between multiple wallets. NB: This is only available with pre-agreement from Tebex
revenue_share[].wallet_ref	String	The reference of the wallet that should be credited
revenue_share[].amount	Float	A float (decimal) value representing the amount of this payment in your account currency that should be credited
revenue_share[].gateway_fee_percent	Float	A float (decimal) value representing the percentage of the gateway fee that should be dedicated from this wallet’s revenue share. This optional value can be anywhere between 0-100

package*

Object

Object describing the product to be added to the basket

package.name*

String

The name of the item being purchased(shown to the customer on checkout in and in their email receipt)

package.price*

Float

A float (decimal) value representingthe price of the package in your account currency

package.expiry_period

Enum

The renewal period for this item (required for subscription purchases). Allowed values: day, month, year

package.expiry_length

Integer

An integer representing the number of expiry_periods that make up the renewal period (required for subscription purchases)

package.metaData

Object

A sub-object to hold seller-specific properties related to the item (must be pre-agreed with Tebex)

package.metaData.custom

String

A free-text string field that is passed back to you via the webhook (for example a tracking ID)

qty

Integer

Number of package to add to basket (default: 1)

type*

Enum

The type of payment. Allowed values: single (one time payment), subscription (recurring payment)

revenue_share

Array

An array of payment destination objects describing how the purchase should be split between multiple wallets. NB: This is only available with pre-agreement from Tebex

revenue_share[].wallet_ref

String

The reference of the wallet that should be credited

revenue_share[].amount

Float

A float (decimal) value representing the amount of this payment in your account currency that should be credited

revenue_share[].gateway_fee_percent

Float

A float (decimal) value representing the percentage of the gateway fee that should be dedicated from this wallet’s revenue share. This optional value can be anywhere between 0-100

See GET /basket/{ident} above

{
    // Response
}

Remove a row from the basket

DELETE https://checkout.tebex.io/api/baskets/{ident}/packages/{row.id}

Path Parameters

Name Type Description

Name	Type	Description
ident*	String	The ident for this basket (provided upon creation)
row.id*	Integer	The `id` of the `basket.rows` row to remove

ident*

String

The ident for this basket (provided upon creation)

row.id*

Integer

The id of the basket.rows row to remove

{
    // Response
}

Add a sale to the basket

POST https://checkout.tebex.io/api/baskets/{ident}/sales

NB: Sales cannot be applied to baskets with revenue_share set.

Path Parameters

Name	Type	Description
ident*	String	The ident for this basket (provided upon creation)

Name

Type

Description

ident*

String

The ident for this basket (provided upon creation)

Request Body

Name Type Description

Name	Type	Description
name*	String	The name of the sale (displayed to the customer)
discount_type*	Enum	The type of discount. Allowed values: `percentage` (deduct a percentage of each item) `amount` (deduct a fixed amount from each item)
amount*	Float	The amount or percentage to deduct

name*

String

The name of the sale (displayed to the customer)

discount_type*

Enum

The type of discount. Allowed values:

percentage (deduct a percentage of each item)

amount (deduct a fixed amount from each item)

amount*

Float

The amount or percentage to deduct

See GET /basket/{ident} above

Create a checkout request

POST https://checkout.tebex.io/api/checkout

This API call essentially allows all the above calls (create basket, add items, add sale) to be made in a single API call, for when the Seller is managing the basket locally. For field definitions, see above API calls.

This endpoint requires prior approval - please contact your account manager.

Request Body

Name Type Description

Name	Type	Description
basket*	Object	An object representing the `basket` portion of the request
basket.return_url*	String
basket.complete_url*	String
basket.custom	Object
items*	Array	An array of items to be added to the basket
items[].package*	Object
items[].package.name*	String
items[].package.price*	Float
items[].package.expiry_period	Enum
items[].package.expiry_length	Integer
items[].package.metaData	Object
items[].package.metaData.custom	String
items[].qty	Integer
items[].type*	Enum
items[].revenue_share	Array
items[].revenue_share[].wallet_ref	String
items[].revenue_share[].amount	Float
items[].revenue_share[].gateway_fee_percent	Float
sale	Object	An object representing the Sale portion of the request
sale.name	String
sale.discount_type	Enum
sale.amount	Float
basket.first_name	String
basket.last_name	String
basket.email	String
expires_at	Date - ISO8601

basket*

Object

An object representing the basket portion of the request

basket.return_url*

String

basket.complete_url*

String

basket.custom

Object

items*

Array

An array of items to be added to the basket

items[].package*

Object

items[].package.name*

String

items[].package.price*

Float

items[].package.expiry_period

Enum

items[].package.expiry_length

Integer

items[].package.metaData

Object

items[].package.metaData.custom

String

items[].qty

Integer

items[].type*

Enum

items[].revenue_share

Array

items[].revenue_share[].wallet_ref

String

items[].revenue_share[].amount

Float

items[].revenue_share[].gateway_fee_percent

Float

sale

Object

An object representing the Sale portion of the request

sale.name

String

sale.discount_type

Enum

sale.amount

Float

basket.first_name

String

basket.last_name

String

basket.email

String

expires_at

Date - ISO8601

See GET /basket/{ident} above

{
    // Response
}

Payments

Fetch a payment by its transaction ID

GET https://checkout.tebex.io/api/payments/{txnId}?type=txn_id

Path Parameters

Name	Type	Description
txnId*	String	The transaction ID for the payment (starts tbx-)

Name

Type

Description

txnId*

String

The transaction ID for the payment (starts tbx-)

{
    "transaction_id": "tbx-26929122a56954-0e15be",
    "status": {
        "id": 1,
        "description": "Complete"
    },
    "payment_sequence": "oneoff",
    "created_at": "2022-10-19T15:49:15.000000Z",
    "price": {
        "amount": 5.35,
        "currency": "USD"
    },
    "fees": {
        "tax": {
            "amount": 0,
            "currency": "USD"
        },
        "gateway": {
            "amount": 0.45,
            "currency": "USD"
        }
    },
    "customer": {
        "first_name": "Test",
        "last_name": "Test",
        "email": "test@test.com",
        "ip": "1.2.3.4",
        "username": null,
        "marketing_consent": false,
        "country": "TS",
        "postal_code": null
    },
    "products": [
        {
            "id": null,
            "name": "Super Cool Product",
            "quantity": 1,
            "base_price": {
                "amount": 2.45,
                "currency": "USD"
            },
            "paid_price": {
                "amount": 2.2,
                "currency": "USD"
            },
            "variables": [],
            "expires_at": null,
            "custom": "tbx-test-1234",
            "username": null
        },
        {
            "id": null,
            "name": "Super Cool Product2",
            "quantity": 1,
            "base_price": {
                "amount": 3.5,
                "currency": "USD"
            },
            "paid_price": {
                "amount": 3.15,
                "currency": "USD"
            },
            "variables": [],
            "expires_at": null,
            "custom": "tbx-test-1234",
            "username": null
        }
    ],
    "coupons": [],
    "gift_cards": [],
    "recurring_payment_reference": null,
    "custom": {
        "user": "test@test.com",
        "ref": "abc-123"
    }
}

Refund a payment by its transaction ID

POST https://checkout.tebex.io/api/payments/{txnId}/refund?type=txn_id

Path Parameters

Name	Type	Description
txnId*	String	The transaction ID for the payment (starts tbx-)

Name

Type

Description

txnId*

String

The transaction ID for the payment (starts tbx-)

See GET /payments/{txnId}?type=txn_id above.

Recurring Payments

Fetch a recurring payment (subscription) by its reference

GET https://checkout.tebex.io/api/recurring-payments/{reference}

Path Parameters

Name	Type	Description
reference*	String	The reference for the recurring payment (starts tbx-r-)

Name

Type

Description

reference*

String

The reference for the recurring payment (starts tbx-r-)

{
    "id": 5000,
    "created_at": "2022-12-16T16:43:06.000000Z",
    "updated_at": "2022-12-16T16:43:06.000000Z",
    "paused_at": null,
    "paused_until": null,
    "next_payment_date": "2022-12-30 16:43:06",
    "reference": "88",
    "account_id": 1,
    "interval": "P2W",
    "cancelled_at": null,
    "status": {
        "id": 2,
        "class": "success",
        "description": "Active",
        "active": 1
    },
    "amount": {
        "amount": 7,
        "tax": 1.4,
        "period": "P2W"
    },
    "cancel_reason": null,
    "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"
        ]
    }
}

Update a subscription with a new product / amount to pay - replacing the existing product

PUT https://checkout.tebex.io/api/recurring-payments/{reference}

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.

Path Parameters

Name	Type	Description
reference*	String	The reference for the recurring payment (starts tbx-r-)

Name

Type

Description

reference*

String

The reference for the recurring payment (starts tbx-r-)

Request Body

Name	Type	Description
items*	Array	An array containing the item to be added to the recurring payment. (Only 1 item is supported at this time)
items[].package*	Object
items[].package.name*	String
items[].package.price*	Float
items[].package.expiry_period*	Enum
items[].package.expiry_length*	Enum
items[].package.metaData	Object
items[].package.metaData.custom	String
items[].type*	String	Must be 'subscription'
items[].revenue_share	Array
items[].revenue_share[].wallet_ref	String
items[].revenue_share[].amount	Float
items[].revenue_share[].gateway_fee_percent	Float

Name

Type

Description

items*

Array

An array containing the item to be added to the recurring payment. (Only 1 item is supported at this time)

items[].package*

Object

items[].package.name*

String

items[].package.price*

Float

items[].package.expiry_period*

Enum

items[].package.expiry_length*

Enum

items[].package.metaData

Object

items[].package.metaData.custom

String

items[].type*

String

Must be 'subscription'

items[].revenue_share

Array

items[].revenue_share[].wallet_ref

String

items[].revenue_share[].amount

Float

items[].revenue_share[].gateway_fee_percent

Float

{
    "id": 3,
    "created_at": "2022-12-16T16:43:06.000000Z",
    "updated_at": "2022-12-16T16:43:53.000000Z",
    "next_payment_date": "2022-12-30 16:43:06",
    "reference": "88",
    "account_id": 1,
    "interval": "P2W",
    "cancelled_at": null,
    "status": {
        "id": 2,
        "class": "success",
        "description": "Active",
        "active": 1
    },
    "amount": {
        "amount": 21,
        "tax": 4.2,
        "period": "P2W"
    },
    "cancel_reason": null,
    "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",
            "https://checkout.tebex.io/api/payments/tbx-847abd4672be156-6b17cf?type=txn_id"
        ]
    }
}

Pause or reactivate a recurring payment

PUT /recurring-payments/{reference}/status

Path Parameters

Name	Type	Description
reference*	String	The reference for the recurring payment (starts tbx-r-)

Name

Type

Description

reference*

String

The reference for the recurring payment (starts tbx-r-)

Request Body

Name Type Description

Name	Type	Description
status*	Enum	Allowed values: `Paused` `Active`
paused_until	Date - ISO8601	If pausing a recurring payment, optionally provide the date that the recurring payment should automatically be reactivated.

status*

Enum

Allowed values:

Paused

Active

paused_until

Date - ISO8601

If pausing a recurring payment, optionally provide the date that the recurring payment should automatically be reactivated.

{
    "id": 3,
    "created_at": "2022-12-16T16:43:06.000000Z",
    "updated_at": "2022-12-16T16:43:53.000000Z",
    "paused_at": "2022-12-18T16:43:53.000000Z",
    "paused_until": "2023-01-18T16:43:53.000000Z",
    "next_payment_date": "2022-12-30 16:43:06",
    "reference": "88",
    "account_id": 1,
    "interval": "P2W",
    "cancelled_at": null,
    "status": {
        "id": 6,
        "class": "seecondary",
        "description": "Paused",
        "active": 0
    },
    "amount": {
        "amount": 21,
        "tax": 4.2,
        "period": "P2W"
    },
    "cancel_reason": null,
    "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",
            "https://checkout.tebex.io/api/payments/tbx-847abd4672be156-6b17cf?type=txn_id"
        ]
    }
}

Cancel a recurring payment

DELETE https://checkout.tebex.io/api/recurring-payments/{reference}

Path Parameters

Name	Type	Description
reference*	String	The reference for the recurring payment (starts tbx-r-)

Name

Type

Description

reference*

String

The reference for the recurring payment (starts tbx-r-)

{
    "id": 3,
    "created_at": "2022-12-16T16:43:06.000000Z",
    "updated_at": "2022-12-19T15:14:41.000000Z",
    "next_payment_date": "2022-12-30 16:43:06",
    "reference": "88",
    "account_id": 1,
    "interval": "P2W",
    "cancelled_at": "2022-12-19 15:14:41",
    "status": {
        "id": 5,
        "class": "danger",
        "description": "Cancelled",
        "active": 0
    },
    "amount": {
        "amount": 21,
        "tax": 4.2,
        "period": "P2W"
    },
    "cancel_reason": "Cancelled by Test Checkout Store on request",
    "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",
            "https://checkout.tebex.io/api/payments/tbx-847abd4672be156-6b17cf?type=txn_id"
        ]
    }
}

PreviousOverview NextRedirect To Checkout

Last updated 1 month ago