# 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](/online-payments/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](/online-payments/saved-payments/charge) and [Saving an Apple Pay card](/online-payments/embedded-components/checkout/customize).

---

## 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](/online-payments/migration/stored-cards).

---

## 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](/partners/online-payments/migration/rpg-credentials).

---

## 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:

```text
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](/partners/online-payments/migration/rpg-credentials) and [Migrating from RPG](/partners/online-payments/migration/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](/online-payments/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](/online-payments/saved-payments/overview) and [Charge a Saved Payment Method](/online-payments/saved-payments/charge).

---

## 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`.

### Documentation Fix: `transaction_type` on Payment Links API

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**

### New Fields on Payment Links API

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**

### Cardholder Data Fields for Sessions, Pay by Link & Transactions APIs

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**

### New `transaction_type` Field for Payment Links API

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

```admonition
icon: fas fa-exclamation-triangle
content: The <code>v2/refunds</code> endpoint is now deprecated and will be removed on <strong>March 2, 2026</strong>.
```

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.

```admonition
icon: fas fa-exclamation-triangle
content: The <code>v2/refunds</code> endpoint will be fully removed on <strong>March 2, 2026</strong>. 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.