Reference
Statuses, identifiers, payment methods, redirect URLs and error codes for Hosted Checkout.
Reference for Hosted Checkout statuses, identifiers, payment methods, redirects and errors.
Statuses: session vs. transaction
The status of a session and the transaction_status of a payment attempt represent two
different things:
- Session status is the whole checkout — the order waiting to be paid. It starts as
pendingand can only end ascompletedorexpired. - Transaction status is the result of the customer's latest attempt to pay. A customer can make several attempts in one session.
For order fulfillment, base your logic on the transaction status, not only on the session
status. Before the first attempt, transaction_status is an empty string ("") on Direct API
accounts, and Pending or "" on legacy accounts.
Session status
| Status | Description |
|---|---|
| pending | The session is open. The URL is active and the customer can pay. |
| completed | The customer paid, or saved the card on an enrollment session. Final state. |
| expired | The time limit was reached (at most 24 hours). The session can no longer be paid. Final state. |
Transaction status
| Status | Description |
|---|---|
| Pending | The payment was initiated but is not yet confirmed (awaiting 3D Secure, a voucher or a transfer). |
| Success | The payment was authorized and processed. |
| Declined | The payment was declined. The customer may retry. |
| Expired | The attempt was not completed in time. |
Key identifiers
| Identifier | What it is |
|---|---|
Session id | Identifies the session, e.g. cs_97_41528_42434d…. Use it with Get a session. |
payment_id | A number that identifies the payment of a payment session. It exists from creation, never changes, and stays the same when the customer retries with another card. Use it with Get a payment, for reconciliation and with support. 0 on enrollment sessions. |
external_id | Your own order reference, e.g. ORD-001 (generated for you if you do not send one). Also send it as metadata.external_id so it comes back in webhooks. |
direct_transaction_id | Direct API accounts only: the id of the customer's latest payment attempt (a UUID). It changes when the customer retries. |
payment_flow | direct when your account is processed through the Direct API; not present otherwise. Fixed when the session is created. |
One order (external_id) maps to one session and one payment_id, which can have several
attempts.
Payment methods
Values for payment_method_types. A method is shown only when it is active for your business in
the Dashboard and listed on the session.
| Value | Method | Type |
|---|---|---|
card | Credit / debit card | Card |
saved_cards | The customer's saved cards | Card |
apple_pay | Apple Pay — on the v2 design, for Direct API accounts, on Apple devices | Wallet |
oxxopay | OXXO Pay | Cash voucher |
spei | SPEI | Bank transfer |
mercadopago | Mercado Pago | External redirect |
safetypayCash | SafetyPay Cash | Cash |
safetypayTransfer | SafetyPay Transfer | Bank transfer |
neosurf | Neosurf | Prepaid voucher |
Mercado Pago options
Sent in payment_method_config.mercadopago:
| Field | Type | Description |
|---|---|---|
payment_methods.excluded_payment_methods[].id | string | Methods to hide, e.g. master. |
payment_methods.excluded_payment_types[].id | string | Method types to hide, e.g. ticket. |
payment_methods.default_payment_method_id | string | Preselected method. |
payment_methods.installments | number | Maximum installments. |
binary_mode | boolean | Only approved or rejected, never pending. |
statement_descriptor | string | Text on the card statement. |
auto_return | string | When to return automatically: approved or all. |
Redirect URLs
| URL | The customer is sent there when… |
|---|---|
success_url | the payment succeeds. |
pending_url | the payment is pending (for example an OXXO voucher or a SPEI transfer). |
cancel_url | the customer cancels or the payment is declined at Mercado Pago. |
return_url | no specific URL above applies. The only one used by enrollment sessions. |
With redirect_on_completion: "always" (default) the checkout redirects automatically at the end.
With "never" it does not redirect; your page decides what to do from the
embedded events.
Error codes
| HTTP status | Code | Meaning |
|---|---|---|
| 400 | E004 | The request is invalid. metadata.errors has one entry per problem. |
| 400 | E0014 | You asked for the payment of an enrollment session. |
| 401 / 403 | — | Missing or invalid API key, or a key from another environment. |
| 404 | E003 | No session or payment with this id. |
| 500 | E001 | Unexpected error. Retry with the same x-idempotency-key. |
Environments
| Sandbox | Production | |
|---|---|---|
| API base URL | https://api-stage.tonder.io | https://api.tonder.io |
| Checkout page origin | https://stage-payflow.tonder.io | https://payflow.tonder.io |
| Dashboard | https://dashboard-stage.tonder.io | https://dashboard.tonder.io |
Good to know
- A session can be paid once and lasts at most 24 hours.
- The amount, currency and line items of a session cannot be changed. Create a new session instead.
- If the customer retries, the session reports only the latest attempt;
payment_idnever changes. - Test everything in Sandbox with your test API key before going live.