Skip to main content

​
Setup

Adyen provides a self-service sign-up for a sandbox account. To sign up for an account visit the sign-up page and fill in the details.

​
Credentials

To set up credentials for Adyen, head to their dashboard and navigate to Developers -> API credentials in the left hand sidebar. Next, create a set of credentials. You need to create a Web Service key and give it a name. Setting the name to something that describes the use for the key is recommended, for example Orchestration API. For most Adyen connectors you need to then copy some of the following details into the dashboard.
  • A server-side API key - This key can be found on the credentials page under Server Settings -> Authentication -> API key. This is the key used to communicate with the Adyen API from the server.
  • A client-side key - This key can be found on the credentials page under Client Settings -> Authentication -> Client key. This is the key used to communicate with the Adyen API from frontend integrations. This key is mostly needed for local and alternative payment methods.
  • A merchant account - This is the public ID of your account. This value is needed for most API calls. You can find this in your dashboard under Settings -> Account settings -> Merchant overview -> Name.

​
Productions endpoints (conditional)

Most live Adyen accounts have a custom API hostname configured. In those situations the value of the prefix of your domain name is needed. For example, if your live URL is https://1797a841fbb37ca7-AdyenDemo-checkout-live.adyenpayments.com/checkout/v53/payments then the live URL prefix would be 1797a841fbb37ca7-AdyenDemo. See Live URL prefix for more details.

​
Allowed origins (conditional)

For alternative payment methods it’s essential to also enable the allowed origin for your instance. This allows connections to the Adyen API from hosted components, like Embed. For a given API credential, scroll down to the Client settings section where you find the allowed origins configuration. Add one of the following domains based on your environment.
  • https://cdn.{instance_id}.gr4vy.app
  • https://cdn.sandbox.{instance_id}.gr4vy.app
The value of {instance_id} is the name of your instance.

​
Web components environment (conditional)

It is required to set the environment to load the web components from for live Adyen transactions. This mainly applies to alternative payment methods and not card payments. The environment should be set to one of the following, depending on your region. If no value is provided, a default value of live is used.
RegionEnvironment Value
Europelive
Australialive-au
United Stateslive-us
Asia Pacific South Eastlive-apse

​
Webhook format

In the Adyen panel, “Webhook configuration” section, “Method” should be set to JSON. Adyen webhook format

​
Integration

For the alternative payment methods the default integration for Adyen is through a redirect to a hosted payments page.

​
Redirect integration

Start by creating a new transaction with the following required fields.
POST /transactions
{
  "amount": 100,
  "currency": "EUR",
  "country": "NL",
  "intent": "capture",
  "payment_method": {
    "method": "<method>",
    "redirect_url": "https://example.com/callback",
    "country": "NL",
    "currency": "EUR"
  }
}
Please use "" for the value of the <method>.
After the transaction is created, the API response includes payment_method.approval_url and the transaction will be in the buyer_approval_pending state. 
{
  "type": "transaction",
  "id": "ea1efdd0-20f9-44d9-9b0b-0a3d71e9b625",
  "payment_method": {
    "type": "payment-method",
    "approval_url": "https://cdn.sandbox.spider.gr4vy.app/connectors/adyen/apm.html?token=..."
  },
  "method": "<method>"
}
Redirect the buyer to the approval_url (open in a browser or Webview) so they can complete authentication and approve the payment. After approval the buyer is redirected to the redirect_url you provided when creating the transaction. Do not rely solely on the redirect — either poll the transaction or (recommended) rely on webhooks to detect the final status (for example capture_succeeded or failure states).

​
Direct integration

Adyen provides web, Android and iOS for a direct integration. For these flows you should indicate the platform by setting an appropriate integration_client when creating the transaction, and then build a client-side integration that uses the POST /transactions/:transaction_id/session API to initialize the Adyen SDK. To start, create a new transaction with the appropriate integration_client. 
POST /transactions

{
  "amount": 100,
  "currency": "EUR",
  "country": "NL",
  "intent": "capture",
  "integration_client": "web",
  "payment_method": {
    "method": "<method>",
    "redirect_url": "https://example.com/callback",
    "country": "NL",
    "currency": "EUR"
  }
}
Please use "" for the value of the <method>.
After the transaction is created, the API response includes a session_token which can be used to get the session data for that transaction. 
POST /transactions/:transaction_id/session?token=:session_token

{
  "session_data": {
    "sessionId": "CS04C0B8AC9849A7D8E25B20D",
    "sessionData": "Ab02b4c0!BQABAgBLgbLpvkt1r3",
    "environment": "live",
    "clientKey": "client-key",
    "returnUrl": "https://example.com/callback",
    "paymentMethod": "<method>",
    "storePaymentMethod": true // this is an optional key
  },
  "default_completion_url": "https://api.sandbox.spider.gr4vy.app/transactions/approve/some-token",
  "integration_client": "web"
}
This session data provides the sessionId and sessionData required to load the Adyen SDK. 
// Determine the URL of the script, and the method to invoke on the Adyen SDK
const adyenEnvironment = sessionData.environment;
const clientKey = sessionData.clientKey;
const sessionId = sessionData.sessionId;
const adyenSessionData = sessionData.sessionData;
const returnUrl = sessionData.returnUrl;
const paymentMethod = sessionData.paymentMethod;
const storePaymentMethod = sessionData.storePaymentMethod;
const configuration = {
    environment: adyenEnvironment,
    clientKey,
    analytics: {
      enabled: false,
    },
    session: {
      id: sessionId,
      sessionData: adyenSessionData,
    },
    paymentMethodsConfiguration: {
      cashapp: { // only cashapp requires this configuration
        storePaymentMethod: storePaymentMethod,
      },
    },
}
AdyenCheckout(configuration).then(function (checkout) {
  let component = checkout
    .create(paymentMethod)
    .mount('#component');
  });

​
Mobile redirect integration completion

On Mobile integrations you need to send a GET request to the default_completion_url provided in the session response with psp specific query parameters to finalize the transaction. On the psp page you can find the exact parameters needed. Please refer to the Adyen documentation for the web, Android and iOS for further guidance