Create a Session

Creates a Hosted Checkout session for one payment or one card enrollment. Tonder returns the checkout URL and, for payment sessions, the `payment_id`.

Authorization

Authorization

Authorization<token>

Your public API key, with the word Token and a space in front of it. Example: Token 6534bc0a7e1f4d2b9c8e3a5f7b1d2c4e6f8a9b0c — that whole value is the header. Sending the key alone returns 401 'Authentication credentials were not provided'. In this playground you may paste just the key; the prefix is added for you.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

session_type?string

payment (default) charges the customer. enrollment saves the customer's card without charging; payment fields are then not allowed.

customer*

The customer who pays. Saved cards belong to this customer.

amount_total?number

Total to charge, greater than 0. Required for payment sessions; not allowed on enrollment. Not checked against the sum of line_items — the customer is always charged amount_total.

currency?string

Your business currency. Required for payment sessions; not allowed on enrollment.

line_items?array<>

What the customer is paying for (display only). Required for payment sessions; not allowed on enrollment. The checkout shows the full breakdown only when the items add up to amount_total.

payment_method_types?array<>

Methods to offer. Defaults to ["card"]. A method is shown only when it is active for your business and listed here. apple_pay needs the v2 design, a Direct API account and an Apple device. Not allowed on enrollment.

payment_method_config?

Per-method options for the hosted page. Only applies to methods listed in payment_method_types.

checkout_ui_version?string

Checkout design: v2 is the current design, v1 the first-generation one. If omitted, your business default applies, then Tonder's default (v2 for payment sessions). Enrollment always uses v1.

submit_type?string

Wording of the amount and the pay button. Defaults to your business default, then pay. A custom button text in ui_config takes precedence. Not allowed on enrollment.

locale?string

Language the checkout opens in. Defaults to your business default, then es. The customer can still change it on the page.

ui_config?

Appearance of the checkout. Accepted when saving the business configuration and when creating a session; session values are applied on top of the business appearance, field by field.

ui_config_version?string

Which saved business appearance to use. Defaults to V1. Unrelated to checkout_ui_version.

success_url?string

Where the customer goes when the payment succeeds. Not allowed on enrollment.

pending_url?string

Where the customer goes when the payment is pending (an OXXO voucher or a SPEI transfer, for example). Not allowed on enrollment.

cancel_url?string

Where the customer goes when they cancel or the payment is declined at Mercado Pago. Not allowed on enrollment.

return_url?string

Fallback redirect, used when no specific URL applies. Required for payment sessions without success_url. The only redirect URL allowed on enrollment.

expires_at?integer

Unix time in seconds, between 30 minutes and 24 hours from now. Default 24 hours.

external_id?string

Your order reference. Generated for you if you do not send one.

metadata?

Any data you want back in responses and webhooks.

checkout_type?string

Defaults to hosted. Use embedded to load the checkout in an iframe.

post_message_enabled?boolean

Send events to your page. Requires checkout_type set to embedded.

redirect_on_completion?string

Defaults to always. never keeps the customer on the checkout so your page handles navigation.

Response Body

`application/json`

curl -X POST "https://example.com/checkout/v1/sessions" \  -H "Content-Type: application/json" \  -d '{    "customer": {      "first_name": "Maria",      "last_name": "Garcia",      "email": "maria@example.com"    },    "amount_total": 150,    "currency": "MXN",    "external_id": "ORD-001",    "line_items": [      {        "name": "Premium Plan",        "quantity": 1,        "unit_price": 150,        "product_id": "plan-premium-01"      }    ],    "payment_method_types": [      "card",      "saved_cards",      "oxxopay"    ],    "submit_type": "pay",    "locale": "en",    "return_url": "https://your-store.com/checkout/complete",    "metadata": {      "external_id": "ORD-001"    }  }'

{
  "id": "cs_97_41528_42434df6c3644b9610df7b64a1fa9925e3b9562b05972097",
  "url": "https://stage-payflow.tonder.io/checkout/cs_97_41528_42434df6c3644b9610df7b64a1fa9925e3b9562b05972097",
  "status": "pending",
  "session_type": "payment",
  "checkout_type": "hosted",
  "payment_id": 41528,
  "checkout_ui_version": "v2",
  "submit_type": "pay",
  "locale": "en",
  "amount_total": 150,
  "currency": "MXN",
  "external_id": "ORD-001",
  "return_url": "https://your-store.com/checkout/complete",
  "payment_method_types": [
    "card",
    "saved_cards",
    "oxxopay"
  ],
  "ui_config": {},
  "ui_config_version": "V1",
  "created_at": 1751483563558,
  "modified_at": 1751483563558,
  "expires_at": 1751569963
}

{
  "code": "E004",
  "message": "The request was invalid. Please check your input and try again.",
  "metadata": {
    "errors": [
      {
        "keyword": "required",
        "params": {
          "missingProperty": "currency"
        },
        "message": "must have required property 'currency'",
        "field": "currency"
      }
    ]
  },
  "name": "TNDR004",
  "statusCode": 400
}

{
  "code": "E004",
  "message": "The request was invalid. Please check your input and try again.",
  "metadata": {},
  "name": "TNDR004",
  "statusCode": 400
}

Create a Session

Authorization

Request Body

Response Body

200application/json

400application/json

500application/json

`application/json`

`application/json`

`application/json`