Migrating from Adyen to Adyen Checkout

Spreedly offers two integrations with Adyen:

  • Adyen: Adyen's classic Payment API (v68), authenticated with a username and password.
  • Adyen Checkout: Adyen's current Checkout API (v71), authenticated with an API key.

Both connect to Adyen, but Spreedly considers them different gateway types. This guide explains what to change on Spreedly and Adyen, and what behaves differently after you move.

Spreedly & Adyen recommend using the Adyen Checkout connection.

Using Adyen Checkout

1. Set up your Adyen account

In the Adyen Dashboard:

  1. Create an API credential and API key:
    1. Go to Developers > API credentials and select Create credential.
    2. Under Payments, select Web service user, add a description, and select Create credential.
    3. Under Server settings > Authentication > API key, select Generate API key.
    4. Copy and store the API key securely. Adyen does not display it again after you leave the page.
    5. Select Save changes.
  2. Follow the Adyen API key instructions if you need additional detail.
  3. Create a live URL prefix to perform live transactions. You can contact the Adyen team for this. This is not needed in sandbox.
  4. Ask Adyen to enable any of these that you use. They are disabled by default:
    • Immediate capture, if you use Spreedly purchase.
    • Multi-capture, if you capture one authorization more than once.
    • Multi-refund, if you refund one payment more than once.

2. Configure webhooks (required)

Follow the Adyen Checkout webhook setup guide to configure the webhook and generate its HMAC key.

This setup is required. Without a valid webhook, capture, void, and refund transactions remain in processing.

3. Add an Adyen Checkout gateway

You can use the Spreedly app or an API call.

Option 1: Create gateway from the Spreedly app

  1. Open the dashboard: https://app.spreedly.com/connect/all-connections
  2. Click Create connection > search for and select Adyen Checkout.
  3. Input your API key, HMAC key, subdomain (for live gateway), and merchant account ID, and submit the form.

Option 2: Create gateway using the Spreedly API

Call the gateway creation API:

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>adyen_checkout</gateway_type>
        <merchant_account>YourMerchantAccount</merchant_account>
        <api_key>YourCheckoutApiKey</api_key>
        <hmac_key>YourWebhookHmacKey</hmac_key>
        <subdomain>YourLiveUrlPrefix</subdomain>
      </gateway>'

subdomain is required in live mode only. Enter just the prefix from https://{subdomain}-checkout-live.adyenpayments.com.

4. Test in sandbox, then go live

Create a sandbox Adyen Checkout gateway and run through the testing checklist. Then create your live gateway, configure the live webhook with your live HMAC key, and move new traffic over.

What changes between 'Adyen' & 'Adyen Checkout'

Capture, void, and refund

This is the most important behavioral difference.

On the Adyen gateway connection, a capture, void, or refund succeeds or fails as soon as Adyen accepts the request.

On Adyen Checkout, these operations are asynchronous:

  1. Spreedly returns the transaction in the processing state.
  2. Adyen processes the request and sends a webhook.
  3. Spreedly updates the transaction to succeeded or gateway_processing_failed.

Authorize and purchase are still synchronous, except for gateway-specific 3DS transactions.

Capture behavior

Adyen gatewayAdyen Checkout
Capture follows your merchant account setting. The manual_capture field overrides it per transaction.authorize is always manual capture. purchase captures immediately once Adyen enables immediate capture.

If you previously relied on authorize being auto-captured, send purchase instead, or capture explicitly. If you used purchase with manual_capture, use authorize followed by capture.

capture_delay_hours is still supported.

3DS

  • Continue sending attempt_3dsecure: true for Adyen-handled (gateway-specific) 3DS.
  • For browser-based 3DS2, also send the new origin field, along with user_agent and accept_header.
  • Third-party 3DS2 fields are unchanged.

Not available on Adyen Checkout

FeatureWhat to do instead
General credit (unreferenced refunds)Use Spreedly's Adyen gateway integration for general credit.

Gateway-specific field changes

Most fields carry over unchanged. Update or remove these if you are using them:

Adyen fieldAdyen Checkout field
manual_captureRemoved as a GSF.
recurring_detail_referenceNot supported by Adyen Checkout.
recurring_contract_typeUse recurring_processing_model (CardOnFile, Subscription, UnscheduledCardOnFile).
fund_sourceUse fund_origin.
fund_destinationUse fund_recipient.
sub_merchant_mccPass inside sub_merchant_data, for example {"sub_merchant_data": {"subMerchantMCC": "7999"}}.
selected_brandUse brand_override.
localized_shopper_statement, update_shopper_statement, nationality, mccNot supported by Adyen Checkout.

New fields on Adyen Checkout:

FieldPurpose
originBrowser origin for web 3DS2.
shopper_emailShopper email for fraud checks and 3DS.
line_itemsBasket details for partial refunds and some payment methods.
capture_psp_referenceIdentifies which capture to refund when there are multiple captures.
merchant_refund_reasonRefund reason: FRAUD, CUSTOMER REQUEST, RETURN, DUPLICATE, OTHER.

See the Adyen Checkout gateway guide for the full field list.

Implementation checklist

  • Immediate capture, multi-capture, and multi-refund enabled by Adyen as needed.
  • Sandbox webhook configured with the sandbox HMAC key.
  • Sandbox gateway created with merchant_account, api_key, hmac_key, and subdomain.
  • Gateway-specific fields mapped.

Testing checklist

  • Purchase succeeds with existing and new payment methods.
  • Authorize, then capture. Capture moves from processing to succeeded.
  • Void and refund move from processing to succeeded.
  • Partial or multiple captures and refunds work, if you use them.
  • 3DS flow completes, if you use Adyen 3DS.
  • Purchase and authorize work with 3DS Global.
  • Recurring payment sends the expected stored-credential values.
  • Call the Store payment method API with GSF tokenize_only: true, then call Redact payment method to remove (unvault) it from the gateway side.

Go-live checklist

  • Immediate capture, multi-capture, and multi-refund enabled by Adyen as needed on production accounts.
  • Live webhook configured with the live HMAC key for production accounts.
  • Non-sandbox gateway token created with merchant_account, api_key, hmac_key, and subdomain for production accounts.
  • Implementation updated to point at production account information.
  • UAT & tests in production for final validation.

Did this page help you?