Online Payments API Changelog

All notable changes, deprecations, and releases for the Online Payments API will be tracked here.

Nov 3, 2026 - New Feature

Diners Club & Discover Card Acceptance

Online payments now accept Diners Club and Discover cards across hosted checkout, embedded components, plugins, and Pay by Link. 3DS authentication is supported for both schemes, including frictionless and challenge flows.

Action Required: None. Payments with these schemes work automatically - no integration changes are needed. Test cards for both schemes are available on the Testing page.

Nov 3, 2026 - Enhancement

token_type on Saved Payment Tokens

token_response now documents token_type: CARD_TOKEN for a token created from card details, WALLET_TOKEN for one created from Apple Pay. payment_method.token on POST /v3/transactions/online accepts the same field; it defaults to CARD_TOKEN when omitted.

Action Required: If you save cards through Apple Pay, store token_type with the token_id and send it back on every charge, with initiator: MERCHANT. A wallet token charged without it fails with 404 Network token not found.

See Charge a Saved Payment Method and Saving an Apple Pay card.

Oct 28, 2026 - Enhancement

Documented TokenCreationResponse Fields

The API reference now documents the possible token_response.failure_reason values when token_status is FAILED, and documents the optional brand and last4 fields returned with token details.

Action Required: None. The API behaviour is unchanged. If your integration reads failure_reason, treat any value you don't recognise as UNKNOWN.

Sep 30, 2026 - New Feature

LEGACY_TOKEN Payment Method for Migrating Stored Cards

POST /v3/transactions/online now accepts payment_method.type: "LEGACY_TOKEN" with a legacy_token object carrying the token exactly as stored on the legacy platform — an RPG multi-use token (tm_ prefix) or a virtual card PAN (16 digits starting with 991001) — plus a recurring_payment_type.

Key Features:

  • The first charge converts the legacy token to a Teya token, returned in token_response.token_id; send it as payment method TOKEN from then on
  • Charging the same legacy token again returns the same Teya token
  • Enabled per store by Teya once the stored cards import is complete

Action Required: None. This payment method only affects merchants migrating stored cards from RPG or SecurePay.

See Migrating stored cards & recurring payments.

Sep 1, 2026 - Enhancement

plugin_metadata on the RPG Credentials Migration Endpoint

POST /v1/ecommerce/legacy/credentials now accepts an optional plugin_metadata object identifying the plugin the merchant integrates through. When supplied, plugin_type is required and decides the application name recorded for the new credentials; plugin_version is optional.

Action Required: None. Existing integrations are unaffected — the field is optional.

See RPG Credentials Migration.

Aug 26, 2026 - Enhancement

New Domain for the RPG Credentials Migration Endpoint

The RPG credentials migration endpoint is now served from a new generic domain:

https://ecom-gateway.teya.com/v1/ecommerce/legacy/credentials

The previous domain, callback-ecom.teya.com, remains live and continues to serve the endpoint, but ecom-gateway.teya.com is the URL we publish going forward.

Action Required: None — existing integrations keep working. We recommend switching to ecom-gateway.teya.com for new integrations.

Aug 26, 2026 - New Feature

RPG Credentials Migration for Partners

Partners processing payments on merchants' behalf via RPG (Borgun Payment API) can now exchange each merchant's RPG private key for new ecommerce credentials via POST https://ecom-gateway.teya.com/v1/ecommerce/legacy/credentials. No merchant onboarding is required.

Key Features:

  • Authenticate with the merchant's existing RPG private key (HTTP Basic)
  • Receive the mapped store_id plus a new client_id and client_secret per store
  • Optionally register a payments webhook in the same call via webhook_url

Action Required: None. This endpoint only affects partners migrating from RPG.

See RPG Credentials Migration and Migrating from RPG.

Aug 24, 2026 - Enhancement

Send a User-Agent Header on API Requests

We recommend that every request to the Online Payments API includes a User-Agent header identifying your integration, for example YourCompany-Integration/1.0.

Not all HTTP clients set one by default. PHP's curl sends no User-Agent unless you set CURLOPT_USERAGENT, and the same applies to Node's http/https modules and .NET's HttpClient. Higher-level libraries such as Guzzle, axios and Python's requests set one for you.

Our PHP and JavaScript code samples now set one explicitly. Samples in other languages rely on the header their HTTP client sends by default.

Action Required: None. Adding the header is recommended for all integrations.

See Troubleshooting.

Aug 5, 2026 - New Feature

Save a Card from a Checkout Session

POST /v2/checkout/sessions now supports saving a customer's payment method for future payments.

What's new:

  • save_payment_method (boolean) — when true, the card entered during the session is tokenized. The resulting token_id is delivered in the payment.succeeded.v1 webhook and on the transaction, and can be charged later via POST /v3/transactions/online with payment_method.type: TOKEN.
  • ACCOUNT_VERIFICATION added to the type field — verifies a card without charging it. Requires amount.value of 0. Combine it with save_payment_method to save a card outside a purchase, such as in account settings or at the start of a free trial.

Both fields are required to mint a token: ACCOUNT_VERIFICATION on its own verifies the card but saves nothing.

Action Required: None. Existing integrations are unaffected — save_payment_method defaults to false.

See Card on File and Charge a Saved Payment Method.

Aug 5, 2026 - Enhancement

token_response Now Live in Payment Webhook Payload

The data.token_response field is now included in the payment webhook payload. It contains details of the token created for the card (token_id and token_status).

The field is optional and will be null when no token was created for the payment.

No action required. Existing integrations continue to work without changes.

Jul 22, 2026 - Enhancement

PRE_AUTHORISATION Now Supported on Sessions API

The type field on POST /v2/checkout/sessions supports PRE_AUTHORISATION in addition to SALE. Use it to reserve funds for later capture via POST /v1/transactions/{id}/capture.

Removed PRE_AUTHORISATION from the documented values of the transaction_type field on POST /v2/payment-links. It is not supported at the moment for payment links, so leaving it there can be misleading. Accepted values are SALE (default) and ACCOUNT_VERIFICATION.

Jul 2, 2026 - Enhancement

store_id Added to Registration Webhook Payload

The plugin registration webhook payload now includes a store_id field. It identifies the store the merchant selected during registration, so you can link the delivered credentials (client_id, client_secret, payment_webhook_public_key) to the correct store.

No action required. Existing integrations continue to work without changes.

Mar 27, 2026 - Enhancement

ACCOUNT_VERIFICATION Transaction Type for Transactions API

Added ACCOUNT_VERIFICATION as a new value for the type field on POST /v3/transactions/online. Use this type to verify a card and optionally tokenize it without charging the customer.

recurring_payment_type Now Required on Token

The recurring_payment_type field is now required when providing a token in a transaction request. Accepted values: CARD_ON_FILE, RECURRING, INSTALLMENT.

Mar 26, 2026 - Enhancement

The POST /v2/payment-links and GET /v1/payment-links/{payment_link_id} endpoints now support additional fields:

Create request (POST /v2/payment-links):

  • billing_address - Pre-fill customer billing address (ignored for MULTI_USE links)
  • customer - Pre-fill customer name, email, and phone number (ignored for MULTI_USE links)
  • customer_success_email - Send payment receipt to customer email
  • merchant_success_email - Send payment receipt to merchant email
  • metadata - Attach key-value pairs (max 10 keys, keys ≤40 chars, values ≤500 chars)
  • post_success_payment - Control post-payment behavior (SHOW_SUCCESS_PAGE or REDIRECT)
  • success_url / cancel_url - Redirect URLs for payment outcome (HTTPS required)
  • supported_card_brands - Restrict accepted card brands (VISA, MASTERCARD, AMEX)
  • supported_payment_methods - Restrict payment methods (CARD, TOKEN, APPLE_PAY)

Get response (GET /v1/payment-links/{payment_link_id}):
All of the above fields are now returned in the response (where applicable).

Mar 5, 2026 - New Feature

Checkout Customisation Fields on Sessions API

The GET /v2/checkout/sessions/{session_id} endpoint now returns checkout customisation fields configured in the Teya Business Portal:

  • logo_url - Public URL of the merchant's logo displayed on the checkout page
  • checkout_custom_note - Custom note shown on the checkout page (max 1000 characters)
  • privacy_policy_url - Link to the merchant's privacy policy
  • terms_url - Link to the merchant's terms and conditions

These fields allow integrators to preview and validate checkout customisation settings programmatically before directing customers to the hosted checkout page.

Feb 27, 2026 - New Feature

New Capture Endpoint for Pre-Authorised Transactions

Added POST /v1/transactions/{id}/capture endpoint to capture a previously pre-authorised transaction.

Key Features:

  • Capture the full or partial amount of a pre-authorisation
  • Idempotency support via Idempotency-Key header
  • Synchronous (201) and asynchronous (202) processing support
  • Requires captures/create scope

Feb 3, 2026 - New Feature

Added new optional fields across multiple APIs to support cardholder data collection, including addresses and customer contact information.

Transactions API (POST /v3/transactions/online):

  • shipping_address - Optional shipping address for the order
  • customer_contact - Optional customer contact details (phone_number, email)
  • name field added to existing billing_address object

Sessions API (POST /v2/checkout/sessions):

  • required_customer_fields - Specify which customer fields must be collected during checkout. Allowed values: SHIPPING_ADDRESS, PHONE, EMAIL

Sessions API (GET /v2/checkout/sessions/{session_id}):

  • required_customer_fields - Returns the required customer fields configured for the session
  • payment_link_type - Returns the type of payment link used to create the session (SINGLE_USE)
  • transaction_id - Returns the payment gateway transaction ID

Pay by Link API (POST /v2/payment-links):

  • required_customer_fields - Specify which customer fields must be collected during checkout
  • type - Payment link type (SINGLE_USE). Defaults to SINGLE_USE

Pay by Link API (GET /v1/payment-links/{payment_link_id}):

  • required_customer_fields - Returns the required customer fields configured for the payment link

Jan 27, 2026 - Enhancement

Added optional transaction_type field to POST /v2/payment-links. Defaults to SALE if not provided. Only SALE is supported at the moment.

Jan 9, 2026 - Deprecation

Deprecation of v2/refunds API in Favor of v3/refunds

The v2/refunds endpoint is now deprecated and will be removed on March 2, 2026.

The v2/refunds API has been deprecated in favor of the new v3/refunds endpoint. The new version includes improved functionality and better aligns with our API standards.

Action Required

Please update your integration to:

  1. Stop using the v2/refunds endpoint.
  2. Migrate to the v3/refunds endpoint.
The v2/refunds endpoint will be fully removed on March 2, 2026. Failure to migrate before this date may result in failed refund requests.

v0.1.0 - Initial draft

  • Initial public draft of Online Payments endpoints and example payloads.