Adyen Integration Guide

The partnership between Braintree and Adyen enables merchants in any country that Adyen supports to use their existing Braintree integration to process transactions through the PayPal Orchestration platform.

ImportantUse the Braintree platform for all transaction operations. Performing operations directly with Adyen could cause synchronization issues and data inconsistencies.

Features

The following topics summarize the capabilities that this integration supports.

Core transaction lifecycle

The following table describes support for the core transaction lifecycle operations with this integration.

Legend: ✅ Supported | ❌ Not supported | ⚠️ Conditional or varies by merchant configuration

Capability	Support	Notes
Charge (single-step or orchestrated)	❌	Use Authorization and Capture instead.
Standalone authorization	✅	Must be captured before expiration (the processor-defined expiry window).
Capture (full)	✅	Captures a previously authorized transaction. Asynchronously transitions from `SETTLING` to `SETTLED` or `SETTLEMENT_DECLINED` on the Adyen webhook.
Partial capture	✅
Capture more than the authorized amount	❌
Adjust the authorization API (incremental authorization or partial reversal)	❌	If you need this, contact your TAM.

Voids and refunds

The following table describes support for voids and refusals with this integration.

Legend: ✅ Supported | ❌ Not supported | ⚠️ Conditional or varies by merchant configuration

Capability	Support	Notes
Full void (authorization reversal)	✅	A full void cancels an authorized transaction prior to settlement.
Partial void	❌
Void a settled transaction	❌	Use a refund instead.
Issue a full refund	✅	Asynchronously transitions from `SETTLING` to `SETTLED` or `SETTLEMENT_DECLINED` on the Adyen webhook.
Partial refund	✅	Refunds cannot exceed the settled amount.
Multiple refunds	✅
Blind credits (refunds for transactions that were processed elsewhere)	❌	A refund must reference the original transaction.

Payment instruments and methods

The following table describes support for payment instruments and methods with this integration.

Legend: ✅ Supported | ❌ Not supported | ⚠️ Conditional or varies by merchant configuration

Capability	Support	Notes
Credit cards	✅	This integration includes support for all cards that Adyen supports.
Debit cards	✅	This integration includes support for all debit cards that Adyen supports.
Prepaid cards	✅	Supported where Adyen supports prepaid cards.
Apple Pay	❌	Not currently supported through Custom Actions
Google Pay	❌	Not currently supported through Custom Actions
Venmo or PayPal	❌

Data, descriptors, and fraud signals

The following table describes support for data, descriptors, and fraud signals with this integration.

Legend: ✅ Supported | ❌ Not supported | ⚠️ Conditional or varies by merchant configuration

Capability	Support	Notes
Address Verification System (AVS) or Card Verification Value (CVV) response handling	⚠️	Authorization returns a CVV response code. Not returned for Card Verification.
Dynamic descriptors	⚠️	Supported for Authorization. Not sent on Card Verification.
Network tokens	✅	Braintree-managed and Bring Your Own Network Token (BYONT) are both available. For more information, see Network token support.
Level 2 or Level 3 (L2/L3) data	⚠️	Supported on Authorization and Capture. Both `purchaseOrderNumber` and `taxAmount` must be present to include L2/L3 data on Capture.
3D Secure (3DS)	⚠️	Supported, but not required.

Verifications

The following table describes support for verifications with this integration.

Legend: ✅ Supported | ❌ Not supported | ⚠️ Conditional or varies by merchant configuration

Capability	Support	Notes
$0 (zero) verification	✅	Adyen receives `amount: 0` with the verification amount as `additionalAmount`.
Non-zero verification	✅	Verifications are synchronous and return `VERIFIED` or `PROCESSOR_DECLINED`.
Wallet verification	❌	Not supported through Custom Actions in this integration

Before you begin

To set up an Adyen integration, you configure both Braintree and Adyen:

On Braintree: Processing card transactions through Adyen requires currency-specific Braintree merchant accounts. Your Braintree account manager (AM) or technical account manager (TAM) can help.
On Adyen: Each merchant must have an Adyen account. When your Adyen account is set up, work with your AM or TAM to configure your processor connection to Adyen.

ImportantYou must contact Adyen directly and request that your API user has the API PCI Payments role. For more information, see the Adyen PCI DSS Compliance Guide. Your Braintree AM or TAM can provide the Attestation of Compliance (AOC) from PayPal.

NoteIf you do not have a dedicated AM or TAM for Braintree, contact [email protected] for support.

Also review the following Adyen-specific requirements to ensure that you are in compliance before processing transactions through Adyen:

CVV requirements: Recurring transactions (for example, subscriptions) or transactions that use a vaulted card might not include a CVV. This can affect approval rates with some card issuers. To adjust CVV handling, contact your TAM.
Billing address format: Braintree passes the billing address to Adyen with the house number separate from the street name. It sends leading digits in the street address as houseNumberOrName and the remainder as street. If your street addresses do not begin with a house number (for example, "Flat 3, 10 Baker Street"), you might see validation errors for billing address fields (Adyen error codes 131–133). If you encounter this type of error, contact your TAM.

Webhooks: Braintree subscribes to the following Adyen webhook event codes to drive transaction status updates: CAPTURE, CAPTURE_FAILED, REFUND, REFUND_FAILED, and CANCELLATION. Merchants are not required to implement their own webhooks, though they can do so for additional notifications.

L2/L3 data: For information about L2/L3 data, see L2/L3 enhanced data support.
Decimal places: Only currencies with 0 or 2 decimal places are supported (for example, USD, EUR, JPY). Currencies with 3 decimal places (for example, KWD, BHD) are not currently supported and will return an error.

Transactions

The following topics describe the requirements for this integration.

ImportantUse the Braintree platform for all transaction operations. Performing operations directly with Adyen could cause synchronization issues and data inconsistencies.

For general information about Braintree transactions, see:

Transaction creation

When you create a transaction, include the required fields and any optional fields that are appropriate for your use case.

The following table lists the fields that Adyen transactions typically require.

Field	Location	How to provide	Notes
`amount`	Transaction	Include in transaction	Transaction amount in the smallest currency unit.
`currencyIsoCode`	Transaction	Include in transaction	Must be a valid ISO currency code for a 0- or 2-decimal currency that Adyen supports.

NoteCustomer creation is optional with Adyen. For more information, see Customer creation.

Fields that Braintree passes to Adyen

The following tables list the fields that Braintree passes to Adyen for each operation.

Authorize

The following table lists the Braintree fields that Braintree passes to Adyen on authorization.

Braintree field	Adyen field	Required	Notes
`amount`	`amount.value`	✅	Converted to smallest currency unit (cents for 2-decimal currencies)
`currencyIsoCode`	`amount.currency`	✅	Three-letter ISO currency code, uppercase
`creditCard.number`	`paymentMethod.number`	✅	Test cards are remapped in sandbox.
`creditCard.expirationMonth`	`paymentMethod.expiryMonth`	✅	Format: MM
`creditCard.expirationYear`	`paymentMethod.expiryYear`	✅	Format: YYYY
`creditCard.cardholderName`	`paymentMethod.holderName`
`creditCard.cvv`	`paymentMethod.cvc`		Omitted for recurring or merchant-initiated transactions (MIT)
`billing.streetAddress`	`billingAddress.street` + `billingAddress.houseNumberOrName`		Braintree sends the leading digits as `houseNumberOrName` and the remainder as `street`.
`billing.locality`	`billingAddress.city`
`billing.region`	`billingAddress.stateOrProvince`
`billing.postalCode`	`billingAddress.postalCode`
`billing.countryCodeAlpha2`	`billingAddress.country`
`customer.email`	`shopperEmail`
`customer.firstName`	`shopperName.firstName`
`customer.lastName`	`shopperName.lastName`
`customer.phone`	`telephoneNumber`
`riskData.customerIp`	`shopperIP`
`descriptor.name`	`shopperStatement`		Descriptor that appears on the cardholder statement
`threeDSecureData.cavv`	`mpiData.cavv`		3DS CAVV value
`threeDSecureData.dsTransactionId`	`mpiData.dsTransID`		3DS Directory Server Transaction ID
`threeDSecureData.eciFlag`	`mpiData.eci`		3DS Electronic Commerce Indicator
`threeDSecureData.version`	`mpiData.threeDSVersion`		For example, "2.1.0"
`threeDSecureData.xId`	`mpiData.xid`		3DS XID value
`networkTransactionIdentifier`	`networkTxReference`		Included for merchant-initiated transactions

Capture

The following table lists the Braintree fields that pass to Adyen on capture.

Braintree field	Adyen field	Required	Notes
`amount`	`amount.value`	✅	Capture amount in smallest currency unit. Partial capture is supported.
`currencyIsoCode`	`amount.currency`	✅
`purchaseOrderNumber` + `taxAmount`	`additionalData` (L2/L3 fields)		Both `purchaseOrderNumber` and `taxAmount` must be present to include L2/L3 data on capture. For more information, see L2/L3 enhanced data support.

Card verification

Card verification uses the same request structure as authorization, except for the following differences:

amount.value is always 0.
additionalAmount.value and additionalAmount.currency carry the actual verification amount that the merchant passed. Adyen handles the hold internally.

Customer creation

Creating a customer is optional for the Adyen integration. To create a customer, you can use either the Braintree SDKs or the GraphQL API. For more information, see the customer creation guide (SDK) or the customer creation guide (GraphQL).

Tokenization

Tokenization returns a single-use token (nonce) that represents the payment method. When you use the SDK, use a client-generated payment nonce for the transaction. For details, see receiving a payment method nonce from your client. See also the tokenization documentation for the SDK or GraphQL.

Vaulted payment methods

Vaulting a tokenized payment method creates an entity that can be authorized or charged multiple times. A tokenized payment method also can be vaulted during authorization. For more information, see the vault guide (SDK) or the vault guide (GraphQL).

Transaction object support

The following topics describe support for transaction operations and CVV handling with this integration.

Supported transaction operations

The following table lists the transaction operations that the Adyen integration supports.

Legend: ✅ Supported | ❌ Not supported |

Operation	Supported
Sale	✅
Find	✅
Void	✅
Refund	✅
Submit for Settlement	✅
Clone	✅
Search	✅
Adjust Authorization	❌
Hold in Escrow	❌
Release from Escrow	❌
Submit for Partial Settlement	❌
Cancel Release	❌

NoteUsing the ReverseTransactionmutation in GraphQL voids a transaction that is not in the SETTLED state. It refunds a transaction that is in the SETTLED state.

NoteVoiding a card verification is a no-op. Adyen automatically cancels non-zero verification holds. Braintree returns VOIDED immediately for these transactions without contacting Adyen.

CVV handling

For recurring transactions or when using a vaulted card, the CVV might not be present, which can affect approval rates.

L2/L3 enhanced data support

The Adyen integration supports L2/L3 data, enabling merchants to include detailed transaction attributes (such as line items, tax amounts, and shipping information) within payment requests. Providing this enhanced data helps merchants qualify for lower interchange rates on eligible commercial and corporate card transactions.

ImportantWhen L2/L3 enhanced data fields are present, Braintree automatically sends that data. To include L2/L3 data on capture, both purchaseOrderNumber and taxAmount must be non-empty for Braintree. If only one is present, the capture proceeds through the standard path with no L2/L3 data, and no error is raised. L2/L3 data is not sent on refund, void, or card verification.

For more information about processing L2/L3 data fields, see the core documentation for processing L2/L3 data fields.

Transaction statuses

The following table maps Adyen responses to Braintree transaction statuses. For general information about Braintree result objects, see result objects.

Operation	Adyen response	Braintree transaction status	Additional information
Authorize	Authorised or Success	`AUTHORIZED`	Synchronous
Authorize	PSP refusal (any non-Authorised result code)	`PROCESSOR_DECLINED`	Hard decline from Adyen
Authorize	Authorised but PSP reference missing	`FAILED`	Adyen returned success with no reference. For more information, see FAILED status.
Authorize	Adyen API error (HTTP 4xx/5xx)	`FAILED`	Network or configuration issue For more information, see FAILED status.
Capture	Capture call succeeds	`SETTLING`	Async (awaiting Adyen `CAPTURE` webhook)
Capture	`CAPTURE` webhook received (success)	`SETTLED`
Capture	`CAPTURE` webhook (failure) or `CAPTURE_FAILED` event	`SETTLEMENT_DECLINED`	Triggers Sentry alert and Datadog metric
Capture	Adyen API error on Capture call	`SETTLEMENT_DECLINED`	Immediate (no webhook needed)
Refund	Refund call succeeds (Received status)	`SETTLING`	Async (awaiting Adyen `REFUND` webhook) For more information, see SETTLING status.
Refund	`REFUND` webhook received (success)	`SETTLED`
Refund	`REFUND` webhook (failure) or `REFUND_FAILED` event	`SETTLEMENT_DECLINED`	Triggers Sentry alerts and Datadog metrics
VerifyCard	Authorised	`VERIFIED`	Synchronous
VerifyCard	PSP refusal	`PROCESSOR_DECLINED`
VerifyCard	Adyen API error	`FAILED`
Void	Cancellation accepted	`VOIDED`

SETTLING status

When you capture or refund a transaction through Adyen, the initial status is SETTLING. Adyen processes these operations asynchronously and notifies Braintree of the outcome through a webhook.

Do not ship goods or provide services until the transaction status transitions to SETTLED. While a transition from SETTLING to SETTLEMENT_DECLINED is rare, it can occur. Braintree does not control when Adyen sends the webhook. For more information, see Adyen's webhook delay documentation.

FAILED status

A FAILED status occurs for system-level errors on authorization, void, and card verification when network issues or API errors prevent Braintree from receiving a valid response from Adyen.

Retries

Do not build a duplicate capture or refund retry loop when you see success: true with the SETTLING status. The transaction is pending while it waits for an asynchronous webhook from Adyen.

Always rely on transaction status to determine when to ship goods. If your request times out or you are unsure whether a transaction was created, query the transaction using Find or Search with your internal transaction reference (transactionId) before attempting a second create.

Network token support

Adyen supports network tokens. With this integration, you can choose either of these options:

Braintree-managed network tokens: Braintree provisions and manages network tokens on your behalf.
Bring Your Own Network Token (BYONT): Use network tokens that you provision through another provider.

To enable Braintree-managed network tokens for your account, contact your AM or an integration engineer. For more information, see the Getting started with network tokens guide.

Response codes

Braintree can only display a limited number of response codes, because Adyen controls transaction results. When Braintree cannot map Adyen decline codes to equivalent Braintree decline codes, Braintree returns code 2000 with the message Do Not Honor.

To query for the Adyen response message, use:

SDK:additional_processor_response. For more information, see additional processor response.
GraphQL:PaymentStatusEvent.processorResponse.additionalInformation. For more information, see the documentation for the PaymentStatusEvent interface.

Processor response pass-through and debugging

Because Adyen controls approval and decline outcomes, Braintree surfaces a standardized set of result codes. To find processor response details, use:

SDK:additional_processor_response
GraphQL:TransactionSettlementProcessorResponse or TransactionAuthorizationProcessorResponse (includes AVS and CVV response mapping)

CVV codes

Adyen CVV codes are the same as the CVV response codes that Braintree uses. Only authorization responses include the CVV response code. Card verification responses do not incude a CVV response code.

The following table describes the CVV codes.

CVV code	Description
M	Match
N	No match
U	Unable to process
I	Issuer unable to process
S	Service not available
A	Not applicable
B	Not provided

Error response code mapping

Error response codes from Adyen are validation errors that return before the transaction is submitted to the payment network. The following table maps Adyen API error codes to their Braintree equivalents.

Braintree error code	Braintree error message	Adyen API error code	Adyen message
2000	Do Not Honor	010	Not allowed
2048	Invalid Amount	100	Required object 'amount' is not provided
2005	Invalid Credit Card Number	101	Invalid card number
2010	Card Issuer Declined CVV	103	CVC is not the right length
2059	Address Verification Failed	104	Billing address problem
2000	Do Not Honor	105	Invalid paRes from issuer
2000	Do Not Honor	106	This session was already used previously
2000	Do Not Honor	107	Recurring is not enabled
2059	Address Verification Failed	117	Invalid billing address
2060	Address Verification and Card Security Code Failed	118	Invalid delivery address
2000	Do Not Honor	119	Invalid shopper name
2000	Do Not Honor	120	Required field 'shopperEmail' is not provided
2000	Do Not Honor	122	Required field 'telephoneNumber' is not provided
2000	Do Not Honor	124	Invalid PhoneNumber
2000	Do Not Honor	128	Required field 'card.holderName' is not provided
2006	Invalid Expiration Date	129	Expiry Date Invalid
2000	Do Not Honor	130	Reference Missing
2059	Address Verification Failed	131	Required field 'billingAddress.city' is not provided
2059	Address Verification Failed	132	Required field 'billingAddress.street' is not provided
2059	Address Verification Failed	133	Required field 'billingAddress.houseNumberOrName' is not provided
2059	Address Verification Failed	134	Billing address problem (Country)
2059	Address Verification Failed	135	Required field 'billingAddress.stateOrProvince' is not provided
2048	Invalid Amount	137	Field 'amount' is not valid
2064	Invalid Currency Code	138	Field 'currency' is not valid
2000	Do Not Honor	139	Recurring requires 'shopperEmail' and 'shopperReference'
2006	Invalid Expiration Date	140	Invalid expiryMonth[1..12] / expiryYear[>2000], or before now
2006	Invalid Expiration Date	141	Invalid expiryMonth[1..12] / expiryYear[>2000]
2006	Invalid Expiration Date	144	Invalid startMonth[1..12] / startYear[>2000], or in the future
2000	Do Not Honor	145	Invalid issuer countryCode
2000	Do Not Honor	146	Invalid social security number
2059	Address Verification Failed	147	Required field 'deliveryAddress.city' is not provided
2059	Address Verification Failed	148	Required field 'deliveryAddress.street' is not provided
2059	Address Verification Failed	149	Required field 'deliveryAddress.houseNumberOrName' is not provided
2059	Address Verification Failed	150	Delivery address problem (Country)
2000	Do Not Honor	151	Required field 'deliveryAddress.stateOrProvince' is not provided
2010	Card Issuer Declined CVV	153	Invalid CVC

Refusal response code mapping

Refusal response codes from Adyen are declines from the payment network after the transaction was processed. The following table maps Adyen API refusal codes to their Braintree equivalents.

Braintree error code	Braintree error message	Adyen refusal reason code	Adyen message
2000	Do Not Honor	2	Refused
2025	Set Up Error – Merchant	3	Referral
3001	Error	4	Acquirer Error
2057	Issuer or Cardholder has put a restriction on the card	5	Blocked Card
2004	Expired Card	6	Expired Card
2048	Invalid Amount	7	Invalid Amount
2005	Invalid Credit Card Number	8	Invalid Card Number
2104	Offline Issuer Declined	9	Issuer Unavailable
2000	Do Not Honor	10	Not supported
2000	Do Not Honor	11	3D Not Authenticated
2001	Insufficient Funds	12	Not enough balance
2014	Processor Declined – Fraud Suspected	14	Acquirer Fraud
2000	Do Not Honor	15	Cancelled
2000	Do Not Honor	16	Shopper Cancelled
2102	Incorrect PIN	17	Invalid Pin
2103	PIN try exceeded	18	Pin tries exceeded
2102	Incorrect PIN	19	Pin validation not possible
2014	Processor Declined – Fraud Suspected	20	Fraud
3000	Processor Network Unavailable – Try Again	21	Not Submitted
2014	Processor Declined – Fraud Suspected	22	Fraud-Cancelled
2000	Do Not Honor	23	Transaction Not Permitted
2010	Card Issuer Declined CVV	24	CVC Declined
2000	Do Not Honor	25	Restricted Card
2067	Authorization Expired	26	Revocation Of Auth
2000	Do Not Honor	27	Declined Non Generic
4006	Capture Amount Exceeded Allowable Limit	28	Withdrawal amount exceeded
4006	Capture Amount Exceeded Allowable Limit	29	Withdrawal count exceeded
2014	Processor Declined – Fraud Suspected	31	Issuer Suspected Fraud
2000	Do Not Honor	32	AVS Declined
2000	Do Not Honor	33	Card requires online pin
2000	Do Not Honor	34	No checking account available on card
2000	Do Not Honor	35	No savings account available on card
2000	Do Not Honor	36	Mobile pin required
2000	Do Not Honor	37	Contactless fallback
2099	Cardholder Authentication Required	38	Authentication required
2000	Do Not Honor	39	RReq not received from DS
2000	Do Not Honor	40	Current AID is in Penalty Box
2000	Do Not Honor	41	CVM Required Restart Payment
2000	Do Not Honor	42	3DS Authentication Error
2000	Do Not Honor	46	Transaction blocked by Adyen to prevent excessive retry fees

Test cards

Braintree provides a set of test card numbers for sandbox testing. The Adyen integration automatially maps some Braintree test card numbers to Adyen test card numbers.

NoteThe sandbox environment remaps credit cards to facilitate end-to-end testing. This can cause discrepancies in sandbox reporting.

Test cards: Success

The following test cards trigger successful transactions in the sandbox environment.

Card type	Braintree test number	Adyen test number	Automatically mapped?	CVV
Mastercard	`5555555555554444`	`5555341244441115`	✅	737
Visa	`4012888888881881`	`4000620000000007`	✅	737
American Express	`370000000000002`	`370000000000002`	Passthrough	7373
Maestro	`6304958000000009`	`6759649826438453`	✅	737
Discover	`6011601160116611`	`6011601160116611`	Passthrough	737

Test cards: Failure

Use the following card and CVV combinations to simulate failure scenarios in the sandbox environment.

Expired card refusal: Use a date in the past (for example, 01/2020).
General refusal: Use CVVs other than 737.

For additional failure scenarios, see the Adyen test documentation.

Supported countries

This integration supports all countries that Adyen supports.

NoteOnly currencies with 0 or 2 decimal places are supported (for example, USD, EUR, JPY). Currencies with 3 decimal places (for example, KWD, BHD) are not currently supported and will return an error.

Next steps

For information about testing this integration, see the Braintree testing guide.

The following resources provide additional information about the Adyen integration and Braintree platform: