Migrating from SecurePay
This page is for businesses whose website posts 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.
New credentials
Every integration below authenticates with new ecommerce credentials, created per store in the Business Portal — see Authenticate. They replace your SecurePay merchant ID, gateway ID and secret key.
Choose your integration
SecurePay was used in two ways, and each has a natural successor on the new platform:
| Hosted Checkout | Embedded Components | |
|---|---|---|
| Best for | SecurePay redirect integrations — the like-for-like path | SecurePay iframe integrations (displaymode=iframe), or anyone who wants checkout to stay on their site |
| Customer experience | Redirected to a Teya-hosted page, then back to your site — as today | Pays without leaving your site; the components render inside your checkout |
| Integration effort | Low — one server-side call and a redirect | Medium — a server-side call plus a small frontend component |
| 3D Secure, Apple Pay, DCC | Handled for you | Handled for you |
| PCI scope | SAQ A | SAQ A (components are hosted in iframes) |
| Guide | SecurePay → Hosted Checkout | SecurePay → 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.
| SecurePay | New platform | What it means for you |
|---|---|---|
Authenticationmerchantid + paymentgatewayid; secret key + HMAC checkhash on every request | store_id (one UUID) + OAuth client_id/client_secret exchanged for a short-lived bearer token | No 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,43 | amount.value as an integer in minor units, e.g. 5443 | Multiply by 100 for EUR, GBP, CZK, HUF; ISK has no decimals — 100 ISK is 100. |
currency | amount.currency | Same ISO 4217 alphabetic codes. |
orderid (12 characters), reference | merchant_reference (free-form) + metadata (key/value) | Keep writing your legacy order ID into metadata during the transition if it helps reconciliation. |
language | language (BCP 47, e.g. is-IS, cs-CZ) | Optional — auto-detected from the customer's browser. |
buyername, buyeremail | customer.name, customer.email, customer.phone_number | Prefills 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_n | line_items[].description, .quantity, .unit_price | A JSON array; unit price in minor units; shown to the customer. |
returnurlsuccess | success_url | A browser redirect after payment — a UX affordance, never payment confirmation. |
returnurlcancel | cancel_url | Rendered as a "Back" option on the checkout. |
returnurlerror | failure_url (terminal errors only) | Declined cards stay on the checkout so the customer can retry with another card. |
Payment confirmationreturnurlsuccessserver 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=1 | post_success_payment: "REDIRECT" | Go straight to your own success page instead of Teya's receipt page. |
merchantlogo, page texts | Business Portal settings (logo, checkout and receipt messages, legal URLs) | Configured once per store, not sent per payment. See Customize. |
displaymode=iframe | Embedded Components | Hosted Checkout does not support iframe embedding. |
| Verified by Visa / Mastercard SecureCode setup | Automatic 3D Secure | No code, no configuration. |
| Dynamic Currency Conversion | Automatic | Offered when the card currency differs from the transaction currency. |
| (no equivalent) | Pre-authorisation and capture: type: "PRE_AUTHORISATION", then POST /v1/transactions/{id}/capture | New capability. See Payment Actions. |
| Refunds via portal or manual process | POST /v3/refunds, or the Business Portal with no code | Partial and multiple refunds; a refund on an uncaptured payment reverses it. See Payment Actions. |
| Ticket API (pre-created payment URLs) | Payment Links | See Ticket API → Payment Links. |
| SecurePay tokenisation / recurring | Card on File | See Migrating stored cards & recurring payments. |
Finding the SecurePay code in your codebase
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
- SecurePay → Hosted Checkout - The like-for-like migration, step by step
- SecurePay → Embedded Components - Keep the checkout on your site
- Migration overview - All migration paths and guides
- Testing - Test cards and integration checklist
- API Reference - Full API endpoint documentation