Migrate with an AI assistant

Working with Claude, ChatGPT, Copilot or another coding assistant? These prompts and the migration pack give it the context it needs to identify your legacy integration, pick the right path and build the migration from the exact endpoints and fields in this documentation — without inventing any.

Give it the whole migration section in one file

The migration pack is every page of this section — overview, guides, what-replaces-what tables and FAQ — as a single Markdown file, plus a short "facts and rules" header written for models. Download it and attach it to your assistant's conversation before using the prompts below. For a single page, use the Copy as Markdown button at the top of any page. The OpenAPI specs are on the Downloads page.

How to work with an assistant on this migration

Let it read your code first. Point it at your repository (or paste the payment-related files) and use the diagnosis prompt. The legacy platform leaves clear fingerprints — borgun.is, checkhash, /api/payment, tm_ tokens — and the assistant should find them before proposing anything.

Make it follow one guide. Once the path is clear, give it that guide (or the pack) and the canonical pages the guide links to. Ask it to work through the guide's steps in order and stop at "Testing".

Keep secrets out of the conversation. Never paste a Client Secret, private key or webhook key. Use environment variables in the generated code and fill them in yourself.

Test in staging with the definition-of-done checklist. The assistant can write the tests; you run them against api.teya.xyz with the official test cards and check the Business Portal yourself.

Let it write to Teya when it is stuck. Anything the documentation doesn't answer should become one complete email to your Teya contact — Prompt 4 makes the assistant gather every detail Teya needs before it asks.

Stored cards need a human in the loop. The assistant can implement the routing rule and the first-use conversion, but the phase dates and the import are agreed with your Teya contact — don't let it "simplify" the order of phases.

Prompt 1 — Identify my legacy integration and choose the path

Use this first, with access to your codebase. It produces an inventory and a recommendation, not code.

You are helping me migrate an online payments integration from Teya's legacy platform
(SecurePay hosted payment page, the RPG / Borgun Payment API, the Ticket API, and legacy
multi-use card tokens) to Teya's new online payments platform. The legacy platform is
retiring in early 2027.

Step 1 - Inventory. Search my codebase and configuration for every place that touches the
legacy platform. Look for: URLs containing borgun.is, securepay, rpgapi, /api/payment,
/api/mpi, /api/token, /api/events; the parameters merchantid, paymentgatewayid, checkhash,
orderhash, returnurlsuccess, returnurlsuccessserver, displaymode, skipreceiptpage,
itemdescription_; scripts named BAPIjs or borgun-payment.js; a "Private Access Token";
stored values starting with tm_ or 16-digit numbers starting with 991001.
List each finding with file path, what it does, and which legacy product it belongs to.

Step 2 - Classify. Using the routing table at
https://docs.teya.com/online-payments/migration/overview, tell me which migration path(s) apply and why:
- SecurePay redirect -> Hosted Checkout
- SecurePay iframe (displaymode=iframe) -> Embedded Components
- RPG direct API -> Embedded Components (direct API only where components have no equivalent)
- Ticket API -> Payment Links
- Stored cards / recurring -> the stored cards & recurring guide, AFTER one-off payments
If more than one applies, list them separately. If you are not sure, say what you would
need to see rather than guessing.

Step 3 - Plan. For each path, summarise from the corresponding guide: what replaces what
in MY code (map my findings to the new API fields), whether I need a backend I don't
have, and the order of work. Do not write code yet.

Documentation to use (read before answering; do not invent endpoints or fields):
- https://docs.teya.com/online-payments/migration/overview
- https://docs.teya.com/online-payments/migration/securepay   (SecurePay -> new platform mapping)
- https://docs.teya.com/online-payments/migration/rpg         (RPG -> new platform mapping)
- The migration pack: https://docs.teya.com/online-payments/migration/migration-pack.txt

Prompt 2 — Build the migration for one path

Run this once per path from Prompt 1. Replace the bracketed values.

Migrate my [SecurePay redirect | SecurePay iframe | RPG direct API | Ticket API]
integration to Teya's new online payments platform following this guide exactly:
https://docs.teya.com/online-payments/migration/[securepay-hosted-checkout | securepay-embedded-components |
rpg-embedded-components | ticket-api-payment-links]

My stack: [backend language/framework, frontend framework, hosting]
My findings from the inventory: [paste the Step 1 list]

Rules:
- Work through the guide's "Step-by-step" section in order. For each step, show the code
  change, referencing the guide's request and response. Use the exact endpoints, headers
  and field names from the guide and the canonical pages it links to; do not invent fields.
- Credentials (client_id, client_secret, store_id, webhook public key) come from
  environment variables. Never hard-code or ask me to paste them.
- amount.value is an integer in the smallest currency unit; ISK has no subunit (100 ISK = 100).
- Cache the OAuth token for its expires_in (currently 15 minutes in production, 24 hours in staging)
  and refresh on 401. Send a unique Idempotency-Key on every session, refund and capture.
- Payment confirmation comes from the payment.succeeded.v1 webhook (verify the
  x-teya-signature RSA signature over the raw body) or from GET /v2/checkout/sessions/{id}.
  Never mark an order paid from the browser redirect.
- Keep the legacy code path behind a feature flag so I can roll back by configuration.
- Target staging (api.teya.xyz, id.teya.xyz) first; make the production hosts a config switch.
- Finish by writing a test plan that covers every item in the guide's "Definition of done".

Documentation to follow:
- The guide above
- https://docs.teya.com/online-payments/hosted-checkout/get-started  (or the Embedded Components /
  Pay By Link Get Started page for the path in question)
- https://docs.teya.com/online-payments/webhooks
- https://docs.teya.com/online-payments/payment-actions
- https://docs.teya.com/online-payments/testing
- Full endpoint schemas: https://docs.teya.com/apis/online-payments/apis
If something in my code has no equivalent in the documentation, stop and tell me instead
of improvising.

Prompt 3 — Stored cards and recurring payments

Only after the one-off payments path is live. The assistant implements the routing; the phases are agreed with your Teya contact.

My systems store legacy Teya tokens (values starting tm_ or 16 digits starting 991001) and
charge them for [subscriptions | instalments | saved cards]. Implement the migration
described at https://docs.teya.com/online-payments/migration/stored-cards, which has four phases whose ORDER is
mandatory: (1) new cards are saved on the new platform, (2) both platforms run side by
side with a routing rule keyed on which token type each customer has, (3) Teya imports the
stored cards - nothing for me to code, (4) legacy tokens are charged on the new platform as
payment_method.type LEGACY_TOKEN and their first charge returns a permanent token_id that
I must store and use as payment_method.type TOKEN from then on.

Deliver: (a) the new-card path using store_payment_method on POST /v3/transactions/online,
(b) the routing rule in my billing job, (c) the Phase 4 change behind a feature flag,
(d) handling for the legacy-token error codes in the guide (never retry "not migrated" in a
loop), (e) a query that reports how many customers still hold only a legacy value.
Do not change the order of phases or merge them. Use the exact fields from:
- https://docs.teya.com/online-payments/migration/stored-cards
- https://docs.teya.com/online-payments/saved-payments/charge
- https://docs.teya.com/online-payments/saved-payments/overview

Prompt 4 — Raise a question or an issue with Teya

When the assistant hits something the documentation doesn't answer — an unexpected error, a field with no equivalent, a business question — the fastest route to an answer is a complete message to your Teya contact. Give the assistant this prompt so it drafts one with everything Teya needs in a single pass, instead of a back-and-forth.

Something in this migration needs Teya's input. Draft an email to my Teya contact that I can
send as-is. Include, in this order:

Subject: "Legacy migration - [merchant or partner name] - [one-line topic]"

1. Who we are: business name; Teya merchant ID (MID) [fill in]; contact person and email.
2. Where we are in the migration:
   - legacy integration(s): [SecurePay redirect | SecurePay iframe | RPG direct API |
     Ticket API | stored cards], with the legacy merchant/gateway ID if known
   - chosen migration path and guide: [name + URL]
   - new-platform details if we already have them: environment (staging / production),
     store_id, and the date of our last successful test payment
   - what is already working, and what is not
3. The question or issue, precisely: what we did, what we expected, what happened.
   Include the request and response that show it (method, endpoint, timestamp, the
   Idempotency-Key, session_id or transaction_id, HTTP status, error code and description),
   with every secret removed: no client_secret, no access token, no private key, no full
   card numbers, no webhook key.
4. What we have already tried, and what we found in the documentation (with URLs), so the
   answer can start from there.
5. What we need from Teya, as one clear ask, and by when if there is a deadline.

Keep it factual and short; use bullet points; one question per email where possible.
If any of the details above are missing, ask me for them before drafting.

Send the result to your Teya account manager, or use the address in the email that pointed you to this section. For integration questions, see Support.

What an assistant can and can't do here

Can do well from these pages	Needs you or Teya
Find every legacy touchpoint in your code and classify it	Confirm the path when your setup is unusual (two integrations, custom MPI, agency-built code)
Map SecurePay/RPG fields to the new request bodies	Create credentials in the Business Portal / run the registration flow; keep secrets out of the chat
Write the token, session, redirect/component, webhook and refund code, and tests	Run the staging tests with real test cards and check the Business Portal
Implement the stored-card routing rule and first-use conversion	Agree phase dates and the import with your Teya contact
Draft the go-live and rollback plan	Choose the switch-over moment and watch the first live transactions

Next steps

Migration overview - Find your path
Download the migration pack - The whole section as one Markdown file
Downloads - OpenAPI specifications
Testing - Test cards and integration checklist