Create Payment Links via API

Create payment links programmatically via the Teya Online Payments API. Ideal for automated billing, e-commerce platforms, and any workflow where you need to generate links at scale.

How it works

Here's the end-to-end flow from creating a link to receiving confirmation:

1 Create payment link via API

2 Share URL with customer

3 Customer pays on hosted page

4 Receive webhook confirmation

No frontend code needed

Works with any platform

Shareable via email, SMS, QR code

Automatic receipt and confirmation

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: 'payment-links/create payment-links/id/get payment-links/id/update'

Scope	Description
`payment-links/create`	Create a payment link
`payment-links/id/get`	Get payment link by ID
`payment-links/id/update`	Update a payment link

Example responses

POST - Create a payment link

{
  "payment_link_id": "20eb276c-5b6b-4474-a5a1-49bcd6193148",
  "payment_link": "https://checkout.teya.com/pbl/20eb276c-5b6b-4474-a5a1-49bcd6193148"
}

Use payment_link to share with your customer. Use payment_link_id to retrieve or update the link later.

Info

Use payment_url to redirect or send to your customer. Use id to look up or update the link later.
Note on amount.value: Always in the smallest currency unit - for GBP, 2500 = £25.00.

GET - Retrieve a payment link

{
  "payment_link_id": "20eb276c-5b6b-4474-a5a1-49bcd6193148",
  "status": "VALID",
  "amount": { "value": 2500, "currency": "GBP" },
  "merchant_reference": "order-12345",
  "expires_at": "2026-12-31T23:59:59.000Z",
  "line_items": [
    { "description": "Product 1", "quantity": 1, "unit_price": 2500 }
  ],
  "required_customer_fields": ["EMAIL", "PHONE"],
  "metadata": { "order_id": "12345" },
  "customer": {
    "email": "john.doe@example.com",
    "name": "John Doe",
    "phone_number": "+447911123456"
  },
  "billing_address": {
    "city": "London",
    "country": "GB",
    "street_address_line1": "Main Street",
    "zipcode": "SW1A1AA"
  },
  "customer_success_email": "john.doe@example.com",
  "merchant_success_email": "merchant@example.com",
  "post_success_payment": "REDIRECT",
  "success_url": "https://mywebsite.com/checkout/success",
  "cancel_url": "https://mywebsite.com/checkout/cart",
  "supported_card_brands": ["VISA", "MASTERCARD"],
  "supported_payment_methods": ["CARD", "APPLE_PAY"]
}

PATCH - Update expiry

The only updatable field is expires_at. Set it to a future date to extend the link, or a past date to effectively cancel it.

{
  "payment_link_id": "20eb276c-5b6b-4474-a5a1-49bcd6193148",
  "status": "VALID",
  "amount": { "value": 2500, "currency": "GBP" },
  "merchant_reference": "order-12345",
  "expires_at": "2026-07-03T13:37:58.709Z",
  "line_items": [
    { "description": "Product 1", "quantity": 1, "unit_price": 2500 }
  ],
  "required_customer_fields": ["EMAIL", "PHONE"],
  "metadata": { "order_id": "12345" },
  "customer": {
    "email": "john.doe@example.com",
    "name": "John Doe",
    "phone_number": "+447911123456"
  },
  "billing_address": {
    "city": "London",
    "country": "GB",
    "street_address_line1": "Main Street",
    "zipcode": "SW1A1AA"
  },
  "customer_success_email": "john.doe@example.com",
  "merchant_success_email": "merchant@example.com",
  "post_success_payment": "REDIRECT",
  "success_url": "https://mywebsite.com/checkout/success",
  "cancel_url": "https://mywebsite.com/checkout/cart",
  "supported_card_brands": ["VISA", "MASTERCARD"],
  "supported_payment_methods": ["CARD", "APPLE_PAY"]
}

Error handling

Status	Meaning	What to do
`401`	Invalid or expired token	Re-authenticate using `client_credentials`
`403`	Missing scope	Ensure `payment-links/create` is in your scope list
`422`	Invalid request body	Check `amount.value` is in smallest currency unit (2500 = £25.00)

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

Try it live - Create a Payment Link

This will create a real payment link 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: 'payment-links/create payment-links/id/get payment-links/id/update',
  }),
});
const { access_token } = await tokenRes.json();

// 2. Create link
const apiRes = await fetch('https://api.teya.xyz/v2/payment-links', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'User-Agent': 'Teya-JS-Client/1.0',
    Authorization: `Bearer ${access_token}`,
  },
  body: JSON.stringify({
      "store_id": "YOUR_STORE_ID",
      "amount": {
        "currency": "GBP",
        "value": 2500
      }
    }), // Smallest currency unit - 2500 = £25.00
});
const data = await apiRes.json();