Hosted Checkout

Create a checkout session via the Online Payments API and redirect your customer to a Teya-hosted checkout page. The session supports order details, line items, and configurable redirect URLs.

How it works

1 Create checkout session (server)

2 Redirect to session URL

3 Customer completes payment

4 Redirect back + webhook

Full checkout flow with order summary

Supports line items and metadata

Automatic 3DS and error handling

Configurable success/cancel URLs

Before getting started

1. Get merchant credentials

As a partner you take payments on behalf of the merchants you serve. Each merchant's Client ID and Client Secret are delivered to your registrationWebhook when the merchant connects Teya to your platform, along with the store_id and payment_webhook_public_key.

Use client_credentials grant to obtain access tokens

Each merchant store has its own set of credentials

Store credentials securely and never expose them in client-side code

A separate Client ID and Client Secret per merchant

Unlike POSLink credentials, these aren't shared across your merchant base. Each merchant you serve gets its own Client ID and Client Secret, delivered to your registrationWebhook when they connect - keep each merchant's credentials separate and don't reuse one set across multiple merchants.

Not registered yet?

Set up your partner account and implement the merchant registration flow first. Teya sends each merchant's credentials to your registration webhook.

2. API URLs

Service	Staging	Production
Online Payments API	`https://api.teya.xyz`	`https://api.teya.com`
OAuth	`https://id.teya.xyz/oauth/v2/oauth-token`	`https://id.teya.com/oauth/v2/oauth-token`
Business Portal	`https://business.teya.xyz`	`https://business.teya.com`

3. Required scopes

Include these as a space-separated string in your OAuth token request:

scope: 'checkout/sessions/create checkout/sessions/id/get refunds/create'

Scope	Description
`checkout/sessions/create`	Create a hosted checkout session
`checkout/sessions/id/get`	Get hosted checkout session by ID
`refunds/create`	Issue a refund for a completed payment

Example responses

POST - Create a checkout session

{
  "session_id": "14411456-79c8-4d8c-8498-f01907093b83",
  "session_token": "eyJhbGciOiJSUzI1NiJ9...",
  "session_url": "https://checkout.teya.com/session/14411456-79c8-4d8c-8498-f01907093b83",
  "session_status": "ACTIVE"
}

Redirect the customer to session_url. Use session_id to retrieve the session status later.

Info

Use session_url to redirect the customer to the hosted checkout page. Use session_id to check the session status later.
Note on amount.value: Always in the smallest currency unit - for EUR, 5000 = €50.00.

GET - Retrieve a checkout session

{
  "session_id": "14411456-79c8-4d8c-8498-f01907093b83",
  "session_status": "ACTIVE",
  "amount": { "value": 5000, "currency": "EUR" },
  "type": "SALE",
  "payment_status": "NONE",
  "success_url": "https://yoursite.com/success",
  "cancel_url": "https://yoursite.com/cart"
}

Error handling

Status	Meaning	What to do
`401`	Invalid or expired token	Re-authenticate using `client_credentials`
`403`	Missing scope	Ensure `checkout/sessions/create` is in your scope list
`409`	Duplicate idempotency key	Use a unique `Idempotency-Key` header for each request
`422`	Invalid request body	Check `amount.value` is in smallest currency unit

Webhooks - Set up webhooks to receive payment notifications
Customize - Branding, checkout messages, and session options
Testing - Test cards and integration checklist
Troubleshooting - Common issues and best practices
API Reference - Full API endpoint documentation

Try it live - Create a Checkout Session

This will create a real checkout session in the Staging environment. You'll need valid Staging credentials before proceeding.

Staging endpoints shown below

Before going live, swap:
• api.teya.xyz → api.teya.com
• id.teya.xyz → id.teya.com

Node.js example — staging

// 1. Get an access token
const tokenRes = await fetch('https://id.teya.xyz/oauth/v2/oauth-token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'User-Agent': 'Teya-JS-Client/1.0',
  },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: process.env.TEYA_CLIENT_ID,
    client_secret: process.env.TEYA_CLIENT_SECRET,
    scope: 'checkout/sessions/create',
  }),
});
const { access_token } = await tokenRes.json();

// 2. Create checkout
const apiRes = await fetch('https://api.teya.xyz/v2/checkout/sessions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'User-Agent': 'Teya-JS-Client/1.0',
    Authorization: `Bearer ${access_token}`,
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
      "store_id": "YOUR_STORE_ID",
      "amount": {
        "currency": "EUR",
        "value": 5000
      },
      "type": "SALE",
      "line_items": [
        {
          "description": "Widget Pro",
          "quantity": 2,
          "unit_price": 2500
        }
      ],
      "success_url": "https://yoursite.com/success",
      "cancel_url": "https://yoursite.com/cart"
    }),
});
const data = await apiRes.json();

// Redirect customer
res.redirect(data.session_url);