Migration Guide

If you're already using Adyen's ECOM APIs (Checkout) today, moving to Yeti ECOM is mostly about changing where your server-side calls go. Your frontend keeps using Adyen Drop-in or Components; under the hood, your backend talks to Yeti instead of Adyen.

This guide walks you through:

What stays the same
What changes
Endpoint-by-endpoint mapping
Migrating the Sessions flow
Migrating the Advanced flow
Updating webhooks
Testing the new setup

What stays the same

Most of your integration does not need to change:

Frontend integration
- You still use Adyen Web Drop-in or Adyen Web Components.
- You still follow Adyen's frontend docs for configuration and event handling.
Request/response shapes
- Yeti ECOM mirrors Adyen's Checkout APIs.
- Fields like amount, paymentMethod, reference, resultCode, pspReference, and action work the same way.
3D Secure and redirects
- Adyen still handles 3DS and redirects on the frontend.
- Your existing logic for RedirectShopper / ChallengeShopper maps directly to Yeti ECOM.
Webhook payloads
- Webhook bodies follow the familiar Adyen format.
- You can often reuse existing parsing and business logic.

What changes

There are a few key differences to be aware of:

Base URL
- Adyen (example): https://checkout-test.adyen.com/v71/...
- Yeti ECOM (test): https://test.yeti.host/v1/ecom/...
- Yeti ECOM (production): https://api.yeti.host/v1/ecom/...
Authentication
- Before: Adyen API key in the X-API-Key header to Adyen.
- Now: Yeti API key in the Authorization: Bearer YOUR_API_KEY header to Yeti.
- See Authentication for details.
Path structure and routing
- Yeti ECOM adds a **siteId** path parameter to most endpoints.
- Yeti also has an extra GET /config endpoint to get the clientToken for the frontend.
- Example:
  - Adyen: POST /payments
  - Yeti: POST /v1/ecom/{siteId}/payments
Merchant configuration
- With Yeti, merchant, site, and split configuration live in within Yeti, you dont need to handle any of that.
- Your code doesn't need to handle this directly, but you might see new validation/configuration errors if something isn’t set up yet. See Error Handling.
Webhooks source and signatures
- Webhooks now come from Yeti, not directly from Adyen.
- You configure subscriptions and HMAC secrets in Basecamp, and verify them as described in Webhooks.

Endpoint mapping

Here’s how the Adyen ECOM endpoints map to Yeti ECOM:

Core endpoints

What you do	Adyen endpoint	Yeti ECOM endpoint
Get frontend config/client token	n/a (Adyen clientKey is static from CA)	`GET /v1/ecom/config`
Create a session	`POST /sessions`	`POST /v1/ecom/{siteId}/sessions`
Get payment methods	`POST /paymentMethods`	`POST /v1/ecom/{siteId}/payment-methods`
Start a payment	`POST /payments`	`POST /v1/ecom/{siteId}/payments`
Submit additional payment details	`POST /payments/details`	`POST /v1/ecom/{siteId}/payments/details`
Capture a payment	`POST /payments/{pspReference}/captures`	`POST /v1/ecom/{siteId}/payments/{pspReference}/captures`
Cancel or refund a payment	`POST /payments/{pspReference}/reversals`	`POST /v1/ecom/{siteId}/payments/{pspReference}/reversals`
Update authorised amount	`POST /payments/{pspReference}/amountUpdates`	`POST /v1/ecom/{siteId}/payments/{pspReference}/amount-updates`

The bodies and responses follow the same Adyen formats; the main differences are:

The base URL
The presence of siteId in the path
The use of Yeti API keys and headers

For detailed Yeti request/response docs, see:

High-level migration checklist

At a high level, migrating looks like this:

Get set up on Yeti ECOM

Make sure your merchant and ECOM site(s) exist in Basecamp.
Confirm you have a Yeti ECOM API key.

Introduce siteId

Decide which siteId to use for each ecommerce site you serve.
Make sure it's available wherever you build your Yeti API URLs.

Switch your server-side calls

Replace calls to Adyen Checkout with calls to Yeti ECOM.
Update base URLs, paths, and headers as shown above.

Update webhooks

Point webhook subscriptions to Yeti via Basecamp.
Update your verification logic to use Yeti’s HMAC headers and secret.

Test in the Yeti test environment

Use https://test.yeti.host/v1/ecom.
Run through the checklist in Testing.

Switch production traffic

When you’re happy in test, update URLs, keys, and Drop-in/Components environment to use production.

Monitor and fine-tune

Watch logs and webhooks as you cut traffic over.
Handle any new Yeti-specific error codes using Error Handling.

Migrating the Sessions flow

If you're currently using Adyen /sessions plus Drop-in, the flow becomes:

Before (Adyen)

Backend:
- POST https://checkout-*.adyen.com/v71/sessions
Frontend:
- Configure Drop-in with:
  - environment: 'test' | 'live'
  - clientKey from Adyen Customer Area
  - session from the backend

After (Yeti ECOM)

Get the client token Replace your static Adyen clientKey with a dynamic client token from Yeti: See Sessions – Get config.
Create a session via Yeti Instead of calling Adyen’s /sessions, call Yeti: The request/response shape mirrors Adyen’s /sessions API. See Sessions – Create session.
Update your frontend initialisation On the frontend, you still use Adyen Drop-in, but:

clientKey now comes from GET /config.
The session object comes from Yeti instead of Adyen directly.

Webhooks

Make sure your webhook endpoint is set up with Yeti as described in Webhooks.
Your existing logic for interpreting eventCode, pspReference, and merchantReference can usually stay the same.

Migrating the Advanced flow

If you use Adyen Components and make your own calls to /paymentMethods, /payments, and /payments/details, you’ll update each call to point at Yeti.

Before (Adyen)

Typical server-side endpoints:

POST https://checkout-*.adyen.com/v71/paymentMethods
POST https://checkout-*.adyen.com/v71/payments
POST https://checkout-*.adyen.com/v71/payments/details

After (Yeti ECOM)

Update them to:

POST https://test.yeti.host/v1/ecom/{siteId}/payment-methods
POST https://test.yeti.host/v1/ecom/{siteId}/payments
POST https://test.yeti.host/v1/ecom/{siteId}/payments/details

With headers:

Authorization: Bearer YOUR_YETI_API_KEY
Content-Type: application/json
Idempotency-Key: OPTIONAL-BUT-RECOMMENDED

The request/response bodies remain aligned with Adyen’s:

paymentMethods: send amount, optional filters; receive paymentMethods and storedPaymentMethods.
payments: send amount, paymentMethod, returnUrl, reference; receive resultCode, pspReference, possibly an action.
payments/details: send details (and optionally paymentData); receive an updated PaymentResponse.

See:

Webhooks

If you’re already consuming Adyen-style webhooks, migration is largely about pointing them at Yeti and changing how you verify authenticity.

Before (Adyen)

Webhooks configured in Adyen Customer Area.
HMAC secrets and signatures managed by Adyen.
Payloads in Adyen’s notification format.

After (Yeti ECOM)

Webhooks configured via Basecamp.
HMAC secret configured per subscription in Basecamp.
Yeti sends webhooks to your configured HTTPS endpoint.

Headers include:

X-Webhook-Id
X-Webhook-Timestamp
X-Webhook-HMAC-Signature
X-Webhook-Delivery-Attempt
X-Webhook-Payload-Version

Payloads look like:

{
  "live": true,
  "notificationItems": [
    {
      "NotificationRequestItem": {
        "eventCode": "AUTHORISATION",
        "success": "true",
        "pspReference": "8835612345678901",
        "merchantReference": "order-12345",
        "amount": {
          "value": 2500,
          "currency": "GBP"
        },
        "paymentMethod": "visa",
        "additionalData": {
          "paymentSource": "Ecom"
        }
      }
    }
  ]
}

You should:

Keep your existing business logic for handling events like AUTHORISATION, CANCELLATION, REFUND, etc.
Update signature verification to use Yeti’s HMAC scheme as described in Webhooks – Checking that a webhook is genuine.
Treat webhooks as the source of truth, just as before.

Environments and testing

When migrating, use Yeti’s test environment:

Test base URL: https://test.yeti.host/v1/ecom
Production base URL: https://api.yeti.host/v1/ecom
Frontend environment:
- Test: environment: 'test'
- Live: environment: 'live'

Follow the checklist in Testing to:

Verify auth with GET /config
Confirm Sessions or Advanced flows end-to-end
Check 3DS, refusals, webhooks, captures, reversals, and error handling

Common gotchas

A few things to watch out for during migration:

Missing or wrong siteId
- Yeti ECOM endpoints require a valid ecommerce siteId.
- If you see yp_3003 or yp_3004, double-check the site configuration and type.
Merchant not configured for ECOM
- Error codes like yp_5003 indicate your merchant isn’t fully set up for ECOM yet.
- Get in touch with your account manager or support.
Mixed environments
- Make sure your frontend Adyen environment and backend Yeti base URL match (both test, or both live).
- Don’t send production keys to test endpoints, or vice versa.
Idempotency
- If you use retries or have flaky networks, always send Idempotency-Key on POSTs.
- See Best Practices – Idempotency.

Once you’ve worked through this guide, your integration should behave just like your existing Adyen ECOM setup — with Yeti handling the merchant routing, splits, and configuration behind the scenes for you.

What stays the same​

What changes​

Endpoint mapping​

Core endpoints​

High-level migration checklist​

Migrating the Sessions flow​

Before (Adyen)​

After (Yeti ECOM)​

Migrating the Advanced flow​

Before (Adyen)​

After (Yeti ECOM)​

Webhooks​

Before (Adyen)​

After (Yeti ECOM)​

Environments and testing​

Common gotchas​

What stays the same

What changes

Endpoint mapping

Core endpoints

High-level migration checklist

Migrating the Sessions flow

Before (Adyen)

After (Yeti ECOM)

Migrating the Advanced flow

Before (Adyen)

After (Yeti ECOM)

Webhooks

Before (Adyen)

After (Yeti ECOM)

Environments and testing

Common gotchas