Skip to main content
This guide explains how to create a new payment session by calling the Create a Payment Session endpoint. This is the first and most critical step in the Hosted Checkout integration.

​
Creating a Payment Session

Follow these steps to construct your request, call the API, and handle the response.

​
Step 1: Construct the Request Body

Create a JSON object with the payment details. At a minimum, you must include customer, amount_total, currency, and line_items. The table below describes all the required fields for creating a payment session:
FieldTypeRequiredDescription
customerobjectYesObject containing customer details (first_name, last_name, email).
amount_totalnumberYesTotal charge amount.
currencystringYesCurrency code (e.g., “MXN”).
line_itemsarrayYesArray of objects detailing the items in the cart (name, quantity, unit_price, product_id).
return_urlstringConditionalRequired if success_url is not set. Fallback redirect URL.
success_urlstringNoRedirect URL after successful payment.
external_idstringNoYour unique identifier for the order (e.g., order ID).
expires_atintegerNoUnix timestamp (seconds). Must be 30 min to 24h in future. Default 24h.
payment_method_typesarrayNoPayment methods to enable for this session. Accepted values: card, mercadopago, oxxopay, spei, safetypayCash, safetypayTransfer. Defaults to card if not specified.
metadataobjectNoOptional key-value object for storing additional data with the session. All fields are optional.
ui_configobjectNoOptional. An object to override the default UI settings for this session.
See the API Reference for a full list of all available fields.

​
Step 2: Call the API Endpoint

Send a POST request to the Create a Payment Session endpoint for your environment, including your API key as a Token in the Authorization header. This example demonstrates how to create a payment session using cURL or Node.js: 
curl -X POST 'https://api-stage.tonder.io/checkout/v1/sessions' \
  -H 'Authorization: Token YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer": {
      "first_name": "Vicente",
      "last_name": "Quintero",
      "email": "vquintero@testuser.com"
    },
    "amount_total": 300,
    "currency": "MXN",
    "line_items": [
      {
        "name": "Deposit",
        "quantity": 1,
        "unit_price": 10,
        "product_id": "your_internal_product_id"
      }
    ],
    "payment_method_types": ["spei"],
    "return_url": "https://tonder.io",
    "external_id": "ORD-12345-1",
    "metadata": {}
  }'

​
Payment Method Types

The payment_method_types field defines which payment methods are available in the checkout. You should only include the method(s) you want to enable — there is no need to send all of them. Available options:
ValueDescription
cardCredit / Debit card
mercadopagoMercadoPago
oxxopayOXXO Pay
speiSPEI (bank transfer)
safetypayCashSafetyPay Cash
safetypayTransferSafetyPay Transfer
In this example, only spei is included in payment_method_types. Include only the methods relevant to your integration.

​
Step 3: Handle the Response

If successful, Tonder returns a 201 status and the session object. The two most important fields are id (the session ID) and url (the redirect URL). Here’s an example of a successful response: 
{
  "id": "cs_97_41521_d11ba771527b4056c7f85786cfbb980bc105efaf42af113d",
  "url": "https://stage-payflow.tonder.io/checkout/cs_97_41521_d11ba771527b4056c7f85786cfbb980bc105efaf42af113d",
  "status": "pending",
  "payment_id": 41521,
  "amount_total": 25000,
  "currency": "MXN",
  "external_id": "ORD-2025-A9B8",
  "session_type": "payment",
  "checkout_type": "hosted",
  "return_url": "https://your-store.com/checkout/complete",
  "metadata": {},
  "payment_method_types": ["card"],
  "ui_config": {
    "branding": {
      "brand_color": "#0066FF"
    }
  },
  "ui_config_version": "V1",
  "created_at": 1751478543567,
  "modified_at": 1751478543567,
  "customer": {
    "first_name": "Juan",
    "last_name": "Perez",
    "email": "juan.perez@example.com"
  },
  "line_items": [
    {
      "name": "Blue T-Shirt",
      "quantity": 1,
      "unit_price": 25000
    }
  ],
  "transaction_status": "Pending",
  "provider": "tonder"
}

​
What’s Next

Now that you have created a payment session, here are the next steps: