Sessions

Sessions are the simplest way to take a payment. You create one on your server, hand it to the Adyen Drop-in on your frontend, and the Drop-in handles everything else -- the payment form, 3D Secure, redirects, the lot.

How it works

1. Call GET /v1/ecom/config to get your clientToken.
2. Call POST /v1/ecom/{siteId}/sessions to create a session.
3. On your frontend, pass both to the Adyen Drop-in and let it do its thing.
4. You'll get a webhook when the payment is done.

---

Get config

This gives you the client token you need to set up Adyen Drop-in or Components on your frontend. It's the only value from this API that's safe to use in browser-side code.

Request

GET /v1/ecom/config

Headers:

Header	Needed?	What to send
Authorization	Yes	Bearer YOUR_API_KEY

No body needed.

Response

{
  "clientToken": "live_XXXXXXXXXXXXXXXXXXXXXXXX"
}

Field	Type	What it is
clientToken	string	The client key for setting up Adyen Drop-in/Components. You'll pass this as clientKey when you create the checkout.

Example

curl -X GET https://api.yeti.host/v1/ecom/config \
  -H "Authorization: Bearer YOUR_API_KEY"

What could go wrong

Status	Code	What it means
403	yp_1002	Your API key isn't allowed to call this endpoint
422	yp_5003	Your merchant account isn't set up for ECOM yet

---

Create session

Creates a checkout session that the Adyen Drop-in needs to show a payment form and process the payment. This mirrors Adyen's /sessions endpoint, so the fields will look familiar if you've used Adyen before.

Request

POST /v1/ecom/{siteId}/sessions

Path:

Parameter	Type	What it is
siteId	string	Your ecommerce site ID

Headers:

Header	Needed?	What to send
Authorization	Yes	Bearer YOUR_API_KEY
Content-Type	Yes	application/json
Idempotency-Key	No	A unique key to stop duplicate sessions being created. See Best Practices.

Body:

Field	Type	Needed?	What it is
amount	object	Yes	How much to charge.
amount.value	integer	Yes	The amount in minor units. So 10.00 GBP would be 1000.
amount.currency	string	Yes	Three-letter currency code, like GBP or EUR.
returnUrl	string (URI)	Yes	Where to send the customer after they pay (or after 3DS).
reference	string	No	Your own reference for this payment. Handy for matching things up later.
shopperEmail	string	No	The customer's email.
telephoneNumber	string	No	The customer's phone number.
shopperName	object	No	The customer's name.
shopperName.firstName	string	No	First name.
shopperName.lastName	string	No	Last name.
mode	string	No	Session mode. Defaults to embedded.
blockedPaymentMethods	string[]	No	Any extra payment methods you want to hide. Some are already blocked by default (see below).
shopperLocale	string	No	Language for the payment page, like en-GB.
countryCode	string	No	Two-letter country code. Defaults to your merchant's country if you leave it out.
lineItems	object[]	No	Line items for the order, if you want detailed invoicing.

Line items:

Field	Type	Needed?	What it is
quantity	integer	Yes	How many (at least 1)
description	string	No	What it is (up to 127 characters)
id	string	No	Your item ID (up to 50 characters)
amountExcludingTax	integer	No	Price before tax, in minor units
amountIncludingTax	integer	No	Price with tax, in minor units
taxAmount	integer	No	Tax amount, in minor units
taxPercentage	integer	No	Tax rate
productUrl	string (URI)	No	Link to the product page
imageUrl	string (URI)	No	Link to a product image

Things we handle for you

You don't need to think about these -- we sort them out automatically:

• Blocked payment methods: We always block sepadirectdebit, bacs, and directdebit_GB. If you add your own to blockedPaymentMethods, we'll add them to the list too.
• Country code: If you don't send one, we use your merchant's registered country.
• Payment splits: These are set up behind the scenes. You don't need to do anything.
• Shopper interaction: Automatically set to Ecommerce.

Response

You'll get back an Adyen CreateCheckoutSessionResponse. The main things you need are:

Field	Type	What it is
id	string	The session ID. Pass this to the Adyen Drop-in.
sessionData	string	Encrypted session data. Also pass this to the Drop-in.

The full response follows Adyen's session response format.

Example

Making the request:

curl -X POST https://api.yeti.host/v1/ecom/YOUR_SITE_ID/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": {
      "value": 2500,
      "currency": "GBP"
    },
    "returnUrl": "https://your-shop.com/checkout/result",
    "reference": "order-12345",
    "shopperEmail": "shopper@example.com",
    "countryCode": "GB",
    "lineItems": [
      {
        "quantity": 1,
        "description": "Blue T-Shirt",
        "id": "sku-001",
        "amountIncludingTax": 2500
      }
    ]
  }'

Using it on the frontend:

// Your server gets the clientToken and creates a session.
// Then you pass both to the frontend.

const checkout = await AdyenCheckout({
  environment: "live",
  clientKey: clientToken,           // from GET /config
  session: {
    id: session.id,                 // from POST /sessions
    sessionData: session.sessionData,
  },
  onPaymentCompleted: (result) => {
    // The payment's done -- show a confirmation
  },
  onError: (error) => {
    // Something went wrong
  },
});

checkout.create("dropin").mount("#dropin-container");

For the full frontend setup, have a look at the Adyen Web Drop-in guide.

What could go wrong

Status	Code	What it means
400	yp_2002	Something's wrong with the request -- check the message for details
403	yp_1002	Your API key isn't allowed to call this endpoint
404	yp_3004	We can't find that site, or it's not an ecommerce site
404	yp_3005	We can't find the merchant
409	yp_3004	This site type can't be used for this
422	yp_5003	Your merchant account isn't set up for ECOM yet
500	yp_4008	Something went wrong on our end creating the session