Who this guide is for

• Your website sends customers to securepay.borgun.is (or test.borgun.is/SecurePay) to pay, and they come back to your site afterwards.
• The integration posts an HTML form signed with a checkhash and confirms payment from an orderhash.
• The form is not embedded in your own page (displaymode=iframe) — Hosted Checkout does not support iframes.

Why migrate, and what you gain

SecurePay runs on Teya's legacy platform, which is retiring in early 2027; onboarding to it stops soon. The new platform is an upgrade, not a like-for-like swap.

Your options

Hosted Checkout Recommended — the like-for-like path for a SecurePay redirect: lowest effort, same customer experience.

• Embedded Components — worth a look before you decide, even if you are happy with a redirect today. Teya's secure card fields sit inside your own checkout page, so the customer completes the whole journey on your site, in your branding, with Apple Pay on the page and no hand-off to another domain; checkouts like this typically convert better. It is somewhat more frontend work than Hosted Checkout, and the only path if you used displaymode=iframe. The guide opens with a side-by-side comparison to help you choose.
• Payment Links — the successor to the Ticket API.
• Stored cards & recurring — migrate last, after one-off payments are live.

What the migration involves

A small development project — days including testing, not weeks. A plain-HTML site with no backend sits at the upper end: the new platform needs one small server-side component (Step 1 below).

How it works: before and after

Today (SecurePay)

1. The customer clicks Pay; the browser posts a checkhash-signed form straight to SecurePay.
2. The customer pays on the SecurePay page.
3. SecurePay redirects to returnurlsuccess and posts an orderhash to returnurlsuccessserver.

After (Hosted Checkout)

1. The customer clicks Pay; your server gets an access token and creates a checkout session, receiving a session_id and session_url.
2. You redirect the customer to the session_url; they pay there, 3D Secure included.
3. Teya redirects to your success_url (or cancel_url) and sends a signed webhook to your server.
4. Your server verifies the webhook (or looks the session up) and fulfils the order.

The biggest change: the browser no longer talks to Teya directly — your server makes one API call first, and confirmation comes from the server side, never the redirect.

Before you start

1. Credentials

Ask your Teya contact for a development store with an ecommerce subscription. In the Staging Business Portal, select the store, go to Settings → Integrations and create an ecommerce API credential: you get a Client ID, a Client Secret (shown once) and your Store ID. Repeat at business.teya.com for production; the two sets never mix. See Authenticate.

SecurePay equivalent: merchantid + paymentgatewayid become the Store ID; the secret key becomes the OAuth client credentials.

2. Environments

Staging is api.teya.xyz, id.teya.xyz and business.teya.xyz; production is the same hosts on .com. Full table: Hosted Checkout Get Started.

3. Webhook

Teya sends a signed webhook when a payment succeeds. Register a public HTTPS endpoint with no authentication in the Business Portal (Settings → Integrations → Add webhook); the Portal issues a public key for that webhook, per webhook and per environment.

SecurePay equivalent: returnurlsuccessserver and its orderhash HMAC — same purpose, verified with an RSA signature instead. The webhook fires only for successful payments (payment.succeeded.v1); failures are covered by the session lookup in Step 5. See Webhooks.

4. Find the SecurePay code

Search your codebase for borgun.is, securepay, checkhash, orderhash, merchantid, paymentgatewayid, returnurlsuccess, returnurlsuccessserver, returnurlcancel, returnurlerror, itemdescription_, itemcount_, itemunitamount_, itemamount_, skipreceiptpage, merchantlogo, pagetype, displaymode. Each hit is a line on your to-do list. Found displaymode=iframe? Use SecurePay → Embedded Components instead.

5. Ground rules

What replaces what

Step-by-step

Requests are cURL against staging. Other languages: see Hosted Checkout Get Started.

Step 1. Add a backend (if you don't have one)

SecurePay worked from a plain HTML page because the browser posted a signed form. Hosted Checkout uses OAuth credentials that must never reach the browser, so token fetching, session creation and webhook handling run server-side. If you already have a backend, skip this step. If your site is static, a single endpoint is enough — a PHP file on your host, or a serverless function.

Step 2. Get an access token

Exchange client_id and client_secret for a Bearer token. This replaces the per-request checkhash: cache the token, derive the TTL from expires_in, refresh before expiry or on any 401.

curl -X POST https://id.teya.xyz/oauth/v2/oauth-token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$TEYA_CLIENT_ID" \
  -d "client_secret=$TEYA_CLIENT_SECRET" \
  -d "scope=checkout/sessions/create checkout/sessions/id/get refunds/create"

{ "access_token": "eyJhbGciOiJSUzI1NiJ9...", "token_type": "Bearer", "expires_in": 900 }

Things to get right: one cache per environment; don't fetch a token per payment; add captures/create if you use pre-authorisation. Full reference: Hosted Checkout Get Started.

Step 3. Create a checkout session

When the customer clicks Pay, your server creates a session. This replaces the SecurePay form: every parameter you put in the form goes in this JSON body.

curl -X POST https://api.teya.xyz/v2/checkout/sessions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "store_id": "123e4567-e89b-12d3-a456-426614174000",
    "type": "SALE",
    "amount": { "value": 5443, "currency": "EUR" },
    "merchant_reference": "ORDER-2026-00042",
    "line_items": [
      { "description": "Widget Pro", "quantity": 2, "unit_price": 2500 },
      { "description": "Delivery", "quantity": 1, "unit_price": 443 }
    ],
    "customer": { "name": "Jan Novák", "email": "jan@example.com" },
    "success_url": "https://yourstore.com/order/success",
    "cancel_url": "https://yourstore.com/cart",
    "metadata": { "legacy_orderid": "ORDER1230001" }
  }'

{
  "session_id": "14411456-79c8-4d8c-8498-f01907093b83",
  "session_url": "https://checkout.teya.com/session/14411456-79c8-4d8c-8498-f01907093b83",
  "session_status": "ACTIVE"
}

Things to get right:

• amount.value is an integer in minor units: €54.43 is 5443; 100 ISK is 100. The most common bug in SecurePay migrations.
• Idempotency-Key is required — unique per order attempt; reuse it only to retry the identical request.
• Sessions expire after 15 minutes: create one at the Pay click, not on cart load.
• Store the session_id against the order before redirecting.

Full reference: Hosted Checkout Get Started, API Reference.

Step 4. Redirect the customer

Send the browser to the session_url exactly as returned. As with SecurePay, the customer enters their card on Teya's page, not yours.

Step 5. Handle the return and look up the session

The customer lands on success_url, cancel_url, or failure_url on a terminal error. Unlike SecurePay, the redirect carries no payment data. Fulfil from the webhook (Step 6) and use the lookup to cover the gaps: a customer on your success page before the webhook arrives, or a failed payment, which produces no webhook.

curl https://api.teya.xyz/v2/checkout/sessions/$SESSION_ID \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "session_id": "14411456-79c8-4d8c-8498-f01907093b83",
  "session_status": "COMPLETED",
  "payment_status": "SUCCESS",
  "type": "SALE",
  "amount": { "value": 5443, "currency": "EUR" },
  "merchant_reference": "ORDER-2026-00042",
  "transaction_id": "tr_72302a4d-b2f9-4663-93f8-d9260e5370c8"
}

Things to get right: session_status runs ACTIVE → PROCESSING → COMPLETED or EXPIRED; trust payment_status (NONE, SUCCESS, FAILED) only once COMPLETED. Store the transaction_id for refunds and receipts. Completion logic that runs only on the success page drops orders from customers who close the browser after paying. Full reference: API Reference.

Step 6. Receive and verify the webhook

Teya POSTs a payment.succeeded.v1 event to your webhook URL when a payment succeeds — the equivalent of returnurlsuccessserver, verified by RSA signature instead of an orderhash HMAC, and delivered whether or not the customer returns.

• Verify the x-teya-signature header (SHA256withRSA, Base64) against the webhook's public key over the entire raw body, before parsing.
• Match the order on data.session_id or data.merchant_reference; store data.transaction_id.
• Be idempotent — the same event can arrive twice. Return 200 promptly; do slow work asynchronously.
• Test with the Webhook Signature Validator before go-live.

Full reference, including the payload: Webhooks.

After the payment

Refunds, captures and receipts return their outcome in the synchronous API response; there is no webhook for them. All are visible in the Business Portal.

Refunds

On SecurePay, refunds were a manual process. Now: POST /v3/refunds with the transaction_id and an amount in minor units (scope refunds/create). Partial and multiple refunds are allowed up to the original amount; 201 is processed, 202 is still processing — retry with the same Idempotency-Key. Staff can also refund in the Business Portal with no code. See Payment actions.

Payment status

Use the session lookup from Step 5 for order-level status and the Business Portal for reporting. Keep the transaction_id on every order.

Digital receipts

New: POST /v1/transactions/{transaction_id}/receipts (scope transactions/id/receipts/create) emails a Teya-generated receipt. See Payment actions.

Pre-authorisations

Create the session with "type": "PRE_AUTHORISATION"; the flow is otherwise identical, and DCC is not offered on holds. Capture with POST /v1/transactions/{transaction_id}/capture (scope captures/create) for any amount up to the authorised total, once per authorisation; the remainder is released. To release a hold early, refund the uncaptured payment — it reverses the authorisation. Pre-authorisations are currently available for certain tourism-related business activities; if your business needs them for another use case, contact your Teya account manager. Capture is API-only today. See Payment actions.

Testing and going live

Do all of this in staging with the cards on the Testing page. If your development environment isn't publicly reachable, tunnel it so staging webhooks can reach you.

Definition of done

Going live

1. Create production credentials and register your production webhook at business.teya.com; store the new public key.
2. Configure the Portal checkout settings: logo, messages, privacy and T&C URLs.
3. Swap hosts via config: id.teya.xyz → id.teya.com, api.teya.xyz → api.teya.com.
4. Process one small real transaction end to end: payment → webhook → refund.
5. Switch traffic; keep SecurePay behind a flag for a day or two so rollback is a config change. Watch logs, webhook deliveries and the Portal.
6. Remove the SecurePay form code. Teya retires the old SecurePay credentials for you once the platform is decommissioned; there is nothing to request.

Common errors

What a SecurePay developer trips on. For the general catalogue, see Troubleshooting.

Next steps

• Hosted Checkout Get Started - The canonical guide, with code in other languages
• Customize - Branding, messages and session options
• Webhooks - Payload and signature verification
• Testing - Test cards and integration checklist
• API Reference - Full API endpoint documentation