Migrating from SecurePay

This page is for partners and merchants who post payments to SecurePay, Teya's legacy hosted payment page, and are moving to the new online payments platform. It walks through the integration options and maps every SecurePay parameter to its replacement.

```admonition icon: fas fa-key title: Taking payments on behalf of merchants? content: Every integration below authenticates with new ecommerce credentials, issued per store. Register each merchant through the registration flow; for larger merchant bases, agree a batch approach with your Teya partner contact. See the migration overview. ```

Choose your integration

SecurePay was used in two ways, and each has a natural successor on the new platform:

Hosted CheckoutEmbedded Components
Best forSecurePay redirect integrations — the like-for-like pathSecurePay iframe integrations (displaymode=iframe), or anyone who wants checkout to stay on their site
Customer experienceRedirected to a Teya-hosted page, then back to your site — as todayPays without leaving your site; the components render inside your checkout
Integration effortLow — one server-side call and a redirectMedium — a server-side call plus a small frontend component
3D Secure, Apple Pay, DCCHandled for youHandled for you
PCI scopeSAQ ASAQ A (components are hosted in iframes)
GuideSecurePay → Hosted CheckoutSecurePay → Embedded Components

Two related legacy services have their own successors: pre-created payment URLs (the Ticket API) become Payment Links, and stored cards or recurring payments follow the stored cards & recurring guide.

What replaces what

The biggest change: SecurePay let your site talk to Teya straight from the customer's browser with a signed form. On the new platform your server makes one API call first — creating a checkout session — and everything you used to put in the form goes in that call's JSON body. The table covers the SecurePay form parameters and where each one lives now.

SecurePayNew platformWhat it means for you
Authentication
merchantid + paymentgatewayid; secret key + HMAC checkhash on every request		store_id (one UUID) + OAuth client_id/client_secret exchanged for a short-lived bearer tokenNo per-request signing. Mint a token, cache it for its expires_in, refresh on expiry. See Authenticate.
Starting a payment
HTML form posted from the browser to the SecurePay URL		POST /v2/checkout/sessions from your server, then redirect to session_url (Hosted Checkout) or mount a component with session_token (Embedded Components)Requires a backend. See Hosted Checkout or Embedded checkout.
amount as a decimal string, e.g. 54,43amount.value as an integer in minor units, e.g. 5443Multiply by 100 for EUR, GBP, CZK, HUF; ISK has no decimals — 100 ISK is 100.
currencyamount.currencySame ISO 4217 alphabetic codes.
orderid (12 characters), referencemerchant_reference (free-form) + metadata (key/value)Keep writing your legacy order ID into metadata during the transition if it helps reconciliation.
languagelanguage (BCP 47, e.g. is-IS, cs-CZ)Optional — auto-detected from the customer's browser.
buyername, buyeremailcustomer.name, customer.email, customer.phone_numberPrefills the checkout form.
pagetype=1 (collect address/phone/email)required_customer_fields, e.g. ["SHIPPING_ADDRESS", "PHONE", "EMAIL"]Explicit per field; returned in the session lookup.
itemdescription_n, itemcount_n, itemunitamount_nline_items[].description, .quantity, .unit_priceA JSON array; unit price in minor units; shown to the customer.
returnurlsuccesssuccess_urlA browser redirect after payment — a UX affordance, never payment confirmation.
returnurlcancelcancel_urlRendered as a "Back" option on the checkout.
returnurlerrorfailure_url (terminal errors only)Declined cards stay on the checkout so the customer can retry with another card.
Payment confirmation
returnurlsuccessserver POST with orderhash		Webhook payment.succeeded.v1, RSA-signed, or GET /v2/checkout/sessions/{session_id}Same purpose, verified with a public key instead of a shared-secret hash. Never trust the browser redirect to confirm success.
skipreceiptpage=1post_success_payment: "REDIRECT"Go straight to your own success page instead of Teya's receipt page.
merchantlogo, page textsBusiness Portal settings (logo, checkout and receipt messages, legal URLs)Configured once per store, not sent per payment. See Customize.
displaymode=iframeEmbedded ComponentsHosted Checkout does not support iframe embedding.
Verified by Visa / Mastercard SecureCode setupAutomatic 3D SecureNo code, no configuration.
Dynamic Currency ConversionAutomaticOffered when the card currency differs from the transaction currency.
(no equivalent)Pre-authorisation and capture: type: "PRE_AUTHORISATION", then POST /v1/transactions/{id}/captureNew capability. See Payment Actions.
Refunds via portal or manual processPOST /v3/refunds, or the Business Portal with no codePartial and multiple refunds; a refund on an uncaptured payment reverses it. See Payment Actions.
Ticket API (pre-created payment URLs)Payment LinksSee Ticket API → Payment Links.
SecurePay tokenisation / recurringCard on FileSee Migrating stored cards & recurring payments.
```admonition icon: fas fa-search title: Finding the SecurePay code in your codebase content: Search for borgun.is, securepay, checkhash, orderhash, merchantid, paymentgatewayid, returnurlsuccess, returnurlsuccessserver, itemdescription_, skipreceiptpage, displaymode. Each hit is a line on your migration to-do list — and displaymode=iframe tells you which guide to follow. ```

Next steps