Are you looking for test card numbers?

Would you like to contact support?

Payment-method icon

Account validation with Plaid

Use Plaid for account validation of ACH Direct Debit payments.

When accepting ACH Direct Debit payments, NACHA requires you to validate that the shopper's bank account details are correct, if it is a consumer account. To make this validation easier for you, we have partnered with Plaid. Plaid collects the shopper's permission to connect their account to Plaid, and verifies the account details directly with the shopper's bank.

Benefits:

  • Smooth shopper experience. Shoppers link their account using Plaid Link. Shoppers don't need to search for their account number and routing number.
  • You send us the shopper's Plaid processor token instead of having to deal with sensitive account details.
  • Plaid collects the shopper's permission to store their details and check their account balance.
  • Real-time balance check. This reduces the chance that transactions are reversed due to insufficient funds. It can also save shoppers having to pay overdraft fees or non-sufficient funds fees.

If you don't want to validate the account with Plaid, you need to collect the shopper's bank account number, bank routing number, and account holder name, and pass these details in the payment request. We then try to verify the account in another way.

Current limitations

  • Account validation with Plaid is supported for the following online payments integrations:

    • API-only integration.
    • Web Drop-in or Web Components integration using the /payments endpoint.

    You can't use validation with Plaid if your integration uses the /sessions endpoint.

  • Plaid processor tokens expire after a number of months depending on the consumer bank. This means you may need to repeat getting the shopper's Plaid processor token from time to time.

How it works

  1. The shopper selects ACH Direct Debit on your payment form.
  2. You check if the shopper has already connected their account with Plaid.
  3. If the shopper's account isn't connected to Plaid yet:
    • You direct the shopper to Plaid Link.
    • You make a series of API requests to Plaid to get the shopper's Plaid processor token.
  4. You make a payment with the shopper's Plaid processor token and optionally include parameters to check the customer's account balance. We use the shopper's Plaid processor token to validate their account details with Plaid.

The following diagram illustrates this flow.

Before you begin

Before starting your ACH Direct Debit with Plaid integration:

  1. Reach out to your Adyen contact to configure your Adyen account for collaboration with Plaid.
  2. Make sure that you have set up your back end implementation.
  3. Add ACH Direct Debit in your test Customer Area.
  4. Create an account with Plaid, and complete an application profile and a company profile.
    Plaid will give you a client_id and a secret to make API calls to Plaid.

Check the shopper's processor token

It is possible that with a previous payment to you, the shopper connected their account to Plaid and you saved their Plaid processor token. If you don't have the shopper's Plaid processor token, you need to direct the shopper to the Plaid Link app and get their token.

Proceed as follows:

  1. In your POST /paymentMethods request, make sure to use:

    • currency: set to USD.
    • countryCode: set to US.
  2. When the shopper selects ACH Direct Debit, on your payment form collect:

    • The account owner's name.
    • The shopper's billing address (optional).
    • Any other details you need to be able to look up this shopper in your database.
  3. Based on the provided details, look up the shopper in your database and check if you have their Plaid processor token.

  4. If you have the shopper's Plaid processor token, proceed to make a payment.

  5. If you don't have the shopper's Plaid processor token, get it from Plaid:

    1. Make a series of requests to Plaid from your backend:

      In the near future, Plaid will publish a page with instructions specifically for Adyen integrations.

    2. Save the shopper's processor token, and proceed to make a payment.

Make a payment

The ACH Direct Debit payment request must include the shopper's Plaid processor token. Optionally you can add parameters to check if the account balance meets specific conditions before trying an authorisation.

You can also tokenize the transaction for future recurring payments.

Proceed as follows:

  1. From your server, make a POST /payments request.

    Specify the following parameters:

    Parameter Required Description
    paymentMethod.type -white_check_mark- Set to ach.
    bankAccount.countryCode -white_check_mark- Set to US.
    bankAccount.ownerName -white_check_mark- The account holder name that you collected on your payment form when the shopper selected ACH Direct Debit.
    billingAddress The account owner's address information.
    additionalData The shopper's Plaid processor token and any balance check parameters you want to use.

    These are the Plaid parameters you can use in additionalData:

    Parameter Description
    plaid.processorToken The shopper's Plaid processor token that you received from Plaid and stored in your database.
    Required for validation with Plaid.
    plaid.balanceCheck A string value set to true if you want us to check the account balance.
    plaid.minimumAmount A string value indicating the minimum amount available on the account, in minor units. Use only with plaid.balanceCheck set to true.

    For example, if the balance must be 10 USD or more, specify 1000. You can also use this in combination with plaid.balanceMultiplier.
    plaid.balanceMultiplier A string value indicating the condition that the account balance must at least be X times the payment amount.

    If plaid.minimumAmount is specified, indicates the condition that the account balance must at least be X times the specified minimum amount. For example, if the balance must be at least 2.5 times 10 USD, set plaid.balanceMultiplier to 2.5 and set plaid.minimumAmount to 1000.
    ACH Direct Debit payment with Plaid validation
    curl https://checkout-test.adyen.com/v70/payments \
    -H "x-API-key: YOUR_X-API-KEY" \
    -H "content-type: application/json" \
    -X POST \
    -d '{
       "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
       "amount":{
          "currency":"USD",
          "value":"12000"
       },
       "paymentMethod":{
          "type":"ach"
       },
       "bankAccount":{
          "countryCode": "US",
          "ownerName": "ACCOUNT_HOLDER_NAME"
       },
       "reference":"YOUR_ORDER_NUMBER",
       "additionalData":{
          "plaid.processorToken":"processor-sandbox-ef6a7fe3-5984-4437-994b-41e565197426",
          "plaid.balanceCheck":"true",
          "plaid.balanceMinimumAmount":"10000",
          "plaid.balanceMultiplier":"2.5"
       },
       "billingAddress":{
          "houseNumberOrName":"50",
          "street":"Test Street",
          "city":"Amsterdam",
          "stateOrProvince":"NY",
          "postalCode":"12010",
          "country":"US"
       }
    }'
  2. Check the /payments response.

    The additionalData object contains the validation result:

    Parameter Description
    achdirectdebit.dateOfSignature The date that the shopper gave permission to collect direct debit payments from their account.
    achdirectdebit.mandateId The identification of the shopper's permission to collect direct debit payments from their account. This ID is the same as the PSP reference of the payment.
    achdirectdebit.sequenceType Indicates if the direct debit payments are recurring. Possible values: OneOff, First.
    availableBalanceValue The account balance. Only included if the request has plaid.balanceCheck true. Note that the balance is not in minor units.
    bankSummary The last four digits of the shopper's bank account.
    bankVerificationResult The result of the account validation and balance checks: Passed. If the validation fails, you receive an error message.
    bankVerificationResultRaw The details of the account validation result. For example:
    Passed: Available Balance greater than threshold if you asked for a balance check with conditions.
    Passed: Routing number and Account number successfully retrieved if you didn't ask for a balance check.
    plaidProcessorToken The shopper's Plaid processor token passed in the request.

    Other parameters in the response include:

    Parameter Description
    pspReference Our unique reference for the payment.
    resultCode Authorised. This means that the payment has been successfully received by Adyen. However, it may take up to 5 business days to know whether the payment was authorized by the bank.
    Response with Plaid validation details
    {
        "additionalData": {
            "achdirectdebit.dateOfSignature": "2023-02-22",
            "achdirectdebit.mandateId": "P27P5Q9LM7MKDM92",
            "achdirectdebit.sequenceType": "OneOff",
            "availableBalanceValue": "300.0",
            "bankSummary": "0000",
            "bankVerificationResult": "Passed",
            "bankVerificationResultRaw": "Passed: Available Balance greater than threshold",
            "plaidProcessorToken": "processor-sandbox-ef6a7fe3-5984-4437-994b-41e565197426",
        },
        "pspReference": "P27P5Q9LM7MKDM92",
        "resultCode": "Authorised",
        "amount": {
            "currency": "USD",
            "value": 12000
        },
        "merchantReference": "b3d74f31-67a2-4aa6-9b1c-d6980499985f",
        "paymentMethod": {
            "type": "ach"
        }
    }

    If you don't get an Authorised response, refer to Handle Plaid validation errors.

The payment is sent to the bank. If the payment is successful, it will appear in the Settlement details report. If it fails, you will receive a CHARGEBACK notification.

Handle Plaid validation errors

If the Plaid validation failed, you get an error response like the following example.

Example Plaid validation error
{
    "status": 422,
    "errorCode": "32_003",
    "message": "Please have customer reauthenticate with Plaid",
    "errorType": "validation",
    "pspReference": "QTSXQ59LM7MKDM92"
}

Make sure your integration can handle the following validation error responses:

Error Description
000 - Insufficient available balance The balance on the shopper's account doesn't match the conditions in your payment request. Ask the shopper to try another account or bank.
32_001 - Plaid service is currently unavailable Try again later.
32_002 - Unknown error for Plaid Try again later.
32_003 - Let the customer re-authenticate with Plaid The shopper's Plaid processor token has expired. Direct the shopper to the Plaid Link app to get a new processor token.
32_004 - No valid checking or savings accounts for which account and routing numbers could be retrieved Ask the shopper to try another account or bank.
32_005 - Plaid internal error Plaid was unable to process the request. Possible causes:
  • An issue in the response from the bank.
  • An issue with the shopper's consent to sharing data with Plaid. Some banks require the shopper to confirm they gave their consent to Plaid. Ask the shopper to try again later.
32_006 - Plaid rate limit exceeded. Please try again later Too many requests were made in a short period of time. Possible causes:
  • You used Plaid Sandbox credentials in the Plaid Developer or Production environment.
  • The shopper entered their credentials incorrectly too many times. Ask the shopper to try again in one or two days.

Present the payment result

Use the resultCode that you received in the /payments response to present the payment result to your shopper.

The resultCode values you can receive for ACH Direct Debit are:

resultCode Description Action to take
Authorised The payment has been successfully received by Adyen.
It may take up to 5 business days to know whether the payment was authorized by the bank. If the payment is successful, it will appear in the Settlement Detail Report. If it fails, you will receive a CHARGEBACK notification.
Inform the shopper that the payment was successful.
Refused The payment was refused. Ask the shopper to try the payment again using a different payment method.

Chargebacks

ACH Direct Debit payments can fail when:

  • There was a problem with settlement, for example because the account had insufficient funds, had been closed, or the account number was invalid.

  • The shopper asked their bank for a refund. This is referred to as a chargeback. Shoppers can reverse an ACH payment up to 60 days after settlement for one of the following reasons:

    • They did not formally agree to the charge, or revoked such an agreement.
    • The charge is processed earlier than the agreed date.
    • The charge is different than the agreed amount.

    This is different from credit card transactions, where a customer can initiate a chargeback by claiming that a product or service was not what they expected.

    You cannot defend ACH Direct Debit chargebacks. These will always result in the payment being reversed.

    For more information on the chargeback process, refer to Dispute management.

If an ACH Direct Debit payment fails, you will receive a CHARGEBACK notification, and your Settlement details report will show a credit and a corresponding debit.

CHARGEBACK notification
{
  "live": "false",
  "notificationItems": [
    {
      "NotificationRequestItem": {
        "additionalData": {
          "modificationMerchantReferences": ""
        },
        "amount": {
          "currency": "",
          "value": 1000
        },
        "eventCode": "CHARGEBACK",
        "eventDate": "2019-03-20T15:40:27+01:00",
        "merchantAccountCode": "YOUR_MERCHANT_ACCOUNT",
        "merchantReference": "YOUR_PAYMENT_REFERENCE",
        "originalReference": "161552590902659C",
        "paymentMethod": "ach",
        "pspReference": "181552594831625C",
        "reason": "Chargeback",
        "success": "true"
      }
    }
  ]
}

Test and go live

To test the connection with Plaid, use the Plaid sandbox. Optionally use the Plaid GitHub repo to test specific scenarios.

Before you go live, create a Plaid developer account and run tests in the Plaid Developer environment.

See also