Create a Payment Session

curl --request POST \
  --url https://stage.tonder.io/api/v1/checkout/v1/sessions \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]"
  },
  "amount_total": 35000,
  "currency": "MXN",
  "line_items": [
    {
      "name": "Product 1",
      "quantity": 1,
      "unit_price": 15000,
      "product_id": "prod-001"
    },
    {
      "name": "Product 2",
      "quantity": 2,
      "unit_price": 10000,
      "product_id": "prod-002"
    }
  ],
  "return_url": "https://my-store.com/checkout/complete",
  "external_id": "ORD-12345"
}
'

{
  "id": "cs_97_41521_d11ba771527b4056c7f85786cfbb980bc105efaf42af113d",
  "url": "https://stage-payflow.tonder.io/checkout/cs_97_41521_d11ba771527b4056c7f85786cfbb980bc105efaf42af113d",
  "status": "pending",
  "payment_id": 41521,
  "amount_total": 35000,
  "currency": "MXN",
  "expires_at": 1751564943,
  "external_id": "ORD-12345",
  "session_type": "payment",
  "checkout_type": "hosted",
  "return_url": "https://my-store.com/checkout/complete",
  "metadata": {},
  "payment_method_types": [
    "card"
  ],
  "ui_config": {},
  "ui_config_version": "V1",
  "created_at": 1751478543567,
  "modified_at": 1751478543567,
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]"
  },
  "line_items": [
    {
      "name": "Product 1",
      "quantity": 1,
      "unit_price": 15000,
      "product_id": "prod-001"
    }
  ],
  "transaction_status": "Pending",
  "provider": "tonder"
}

POST

checkout

sessions

Create a Payment Session

curl --request POST \
  --url https://stage.tonder.io/api/v1/checkout/v1/sessions \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]"
  },
  "amount_total": 35000,
  "currency": "MXN",
  "line_items": [
    {
      "name": "Product 1",
      "quantity": 1,
      "unit_price": 15000,
      "product_id": "prod-001"
    },
    {
      "name": "Product 2",
      "quantity": 2,
      "unit_price": 10000,
      "product_id": "prod-002"
    }
  ],
  "return_url": "https://my-store.com/checkout/complete",
  "external_id": "ORD-12345"
}
'

{
  "id": "cs_97_41521_d11ba771527b4056c7f85786cfbb980bc105efaf42af113d",
  "url": "https://stage-payflow.tonder.io/checkout/cs_97_41521_d11ba771527b4056c7f85786cfbb980bc105efaf42af113d",
  "status": "pending",
  "payment_id": 41521,
  "amount_total": 35000,
  "currency": "MXN",
  "expires_at": 1751564943,
  "external_id": "ORD-12345",
  "session_type": "payment",
  "checkout_type": "hosted",
  "return_url": "https://my-store.com/checkout/complete",
  "metadata": {},
  "payment_method_types": [
    "card"
  ],
  "ui_config": {},
  "ui_config_version": "V1",
  "created_at": 1751478543567,
  "modified_at": 1751478543567,
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]"
  },
  "line_items": [
    {
      "name": "Product 1",
      "quantity": 1,
      "unit_price": 15000,
      "product_id": "prod-001"
    }
  ],
  "transaction_status": "Pending",
  "provider": "tonder"
}

This is the main endpoint for initiating a Hosted Checkout payment. It creates a new payment session and returns a secure URL where your customer can complete their payment.

How It Works

Your server calls this endpoint with payment details (amount, items, customer info).
Tonder creates a secure session and returns a checkout URL.
You redirect your customer to this URL.
Customer completes the payment on Tonder’s hosted page.
Customer is redirected back to your success_url or cancel_url.

Session Lifecycle

The session starts in pending status and transitions to completed, expired, or cancelled based on customer actions. See the Status Reference for all possible status values.

Quickstart Guide: Complete walk-through of creating your first session.
How to Create a Payment Session: Detailed integration guide.
Status Reference: Understanding all session and transaction status values.

Authorizations

Authorization

string

header

required

Body

application/json

customer

object

required

Show child attributes

amount_total

number

required

Total charge amount

Example:

35000

currency

enum<string>

required

Currency code

Available options:

MXN

Example:

"MXN"

line_items

object[]

required

List of order items

Show child attributes

external_id

string

Unique order reference from the merchant. Used to visually identify/filter the order in dashboard

Example:

"ORD-12345"

expires_at

integer

Unix timestamp (seconds). Must be 30 min to 24h in future. Default 24h

Example:

1751063448

metadata

object

Additional metadata

success_url

string<uri>

Redirect after successful payment

Example:

"https://my-store.com/order/success"

return_url

string<uri>

Required if success_url is not set. If specified, used as fallback for all redirects

Example:

"https://my-store.com/checkout/complete"

pending_url

string<uri>

Redirect if payment is under review. Only applicable for future APM support

payment_method_types

enum<string>[]

Defaults to ["card"]. Currently only card is supported

Available options:

card

Example:

["card"]

checkout_type

enum<string>

Defaults to "hosted"

Available options:

hosted

Example:

"hosted"

session_type

enum<string>

Defaults to "payment"

Available options:

payment

Example:

"payment"

ui_config_version

string

Version of the UI config. Defaults to "V1"

Example:

"V1"

ui_config

object

UI configuration for Hosted Checkout customization

Show child attributes

Response

201 - application/json

Session created successfully

string

Unique session identifier

Example:

"cs_97_41521_d11ba771527b4056c7f85786cfbb980bc105efaf42af113d"

url

string<uri>

Redirect your customer to this URL to begin the payment

Example:

"https://stage-payflow.tonder.io/checkout/cs_97_41521_d11ba771527b4056c7f85786cfbb980bc105efaf42af113d"

status

enum<string>

Session status

Available options:

pending,

completed,

expired

Example:

"pending"

payment_id

number

Associated payment ID

Example:

41521

amount_total

number

Total amount to be charged

Example:

35000

currency

string

Currency used

Example:

"MXN"

expires_at

integer

Expiration time (Unix timestamp in seconds)

Example:

1751564943

external_id

string

Order reference from the merchant

Example:

"ORD-12345"

session_type

string

Type of session

Example:

"payment"

checkout_type

string

Checkout method

Example:

"hosted"

success_url

string<uri> | null

Success redirect URL

return_url

string<uri>

Return/fallback redirect URL

pending_url

string<uri> | null

Pending redirect URL

metadata

object

Custom data sent by the merchant

payment_method_types

string[]

Allowed payment methods

Example:

["card"]

ui_config

object

UI configuration applied

ui_config_version

string

Version of UI config

Example:

"V1"

created_at

integer

Creation timestamp in milliseconds

Example:

1751478543567

modified_at

integer

Last modification timestamp in milliseconds

Example:

1751478543567

paid_at

integer | null

Payment completion timestamp in milliseconds

customer

object

Show child attributes

line_items

object[]

Show child attributes

transaction_status

enum<string>

Result of transaction

Available options:

Pending,

Success,

Declined,

Expired

Example:

"Pending"

provider

string

Gateway used

Example:

"tonder"

Set Business Configuration Get a Session

⌘I

Hosted Checkout API

​How It Works

​Session Lifecycle

​Related Resources

Authorizations

Body

Response

How It Works

Session Lifecycle

Related Resources