Pay by Bank (US) Redirect Component for iOS

This page explains how to add Pay by Bank (US) to your existing iOS Components integration.

Requirements

Select the server-side flow that your integration uses:

API reference

Select the endpoint you are using to make payments:

/sessions/payments/sessions/payments

This is the default with Components v5.0.0 or later.

Parameter name	Required	Description
countryCode		The shopper's country/region. This determines the banks that our partner shows to the shopper. Format: the two-letter ISO-3166-1 alpha-2 country code. Currently, only US is supported. This is also the default if you do not include this parameter.

Component setup

Create an instance of the Pay by Bank (US) Component:

let paymentMethods = session.sessionContext.paymentMethods
// Check that the payment method is supported before showing the Component.
guard let paymentMethod = paymentMethods.paymentMethod(ofType: PayByBankUSPaymentMethod.self) else { return }
let component = PayByBankUSComponent(
                paymentMethod: paymentMethod,
                context: context)
self.currentComponent = component
// Set the session as the delegate.
component.delegate = session
present(component.viewController, animated: true)

// Check that the payment method is supported before showing the Component.
guard let paymentMethod = paymentMethods.stored.compactMap { $0 as? StoredPayByBankUSPaymentMethod }.first else { return }
let component = StoredPaymentMethodComponent(
                paymentMethod: paymentMethod,
                context: context)
self.currentComponent = component
// Set the session as the delegate.
component.delegate = session
present(component.viewController, animated: true)

Redirect handling

Your Components integration handles the redirect, so you do not need to do anything additional for Pay by Bank (US).

Payment outcome

Your Components integration gets the payment outcome, so you do not need to do anything additional for Pay by Bank (US).

Capture

We strongly recommend capturing Pay by Bank (US) payments immediately, to reduce the risk of insufficient funds at the time of capture.

Through our partner Plaid, Adyen completes the checks on the shopper's bank account, including a balance check and risk checks, at the time of authorization. However, the issuing bank does not hold the authorized funds and thus it is possible that the account balance is no longer sufficient by the time you capture the payment. For that reason, you should capture Pay by Bank (US) payments as soon as possible.

However, even with immediate capture there is still a risk of insufficient funds at the time of capture, because capturing is an asynchronous process on the ACH Direct Debit network.

Recurring payments

Pay by Bank (US) supports tokenization of the shopper's payment details for recurring transactions.

To make recurring payments, refer to Tokenization to:

• Create a token through the initial payment.
• Use the token in subsequent payments.
• Manage tokens.

Test and go live

You can test the payment flow as well as the chargeback flow.

To go live, you need to await registration with our partner Plaid.

Test the payment flow

In the test environment, the redirect flow mimics the live flow, but not all refusal reasons can be simulated.

1. Make a test Pay by Bank (US) payment using an amount from the following table for the payment scenario you want to test. Note that other amounts lead to random results.

   Scenario	Amount
   Approved	USD 3.53
   Approved with the paybybank_plaid.customerInitiatedReturnRisk and paybybank_plaid.bankInitiatedReturnRisk risk scores both at 60 (out of a maximum of 99).	USD 12.17
   Refused with refusal reason Not enough balance	USD 27.53

   You are redirected to First Platypus Bank.

2. You do not need to enter any bank credentials, but if you want to try different bank accounts, enter one of the following usernames:

   • custom_chase
   • custom_boa
   • custom_citi
   • custom_wellsfargo

   Tests without one of these usernames all use the same bank account from CITIZENS BANK.

3. Leave the password blank and select Continue.

4. Check the status of test payments in your test Customer Area > Transactions > Payments.

Test the chargeback flow

The chargeback mechanism for Pay by Bank (US) chargebacks relies on the ACH Direct Debit network. You can simulate a Pay by Bank (US) chargeback by providing a username that indicates the chargeback scenario you want to test. In the test environment, the flow goes directly to the Chargeback stage.

1. Send a test Pay by Bank (US) payment request.

2. When redirected to First Platypus Bank, specify the following username:

   • custom_chargeback_rXX where XX is the dispute reason code without the leading R.
     You can use any of the ACH Direct Debit reason codes.

     Example: the username custom_chargeback_r01 triggers a chargeback with reason code R01 for Insufficient Funds.

3. Leave the password blank and select Continue.

4. Note that the request succeeds with resultCode: Authorised.
   The chargeback flow starts after the test payment is captured and settled.

5. Wait for the CHARGEBACK webhook and check your test Customer Area > Revenue & risk > Disputes.
   The webhook and your Customer Area show a chargeback with the return reason code that you specified in the test payment request.

Go live

To go live, you need to add Pay by Bank (US) in your live Customer Area. Our partner Plaid then registers your merchant account with participating banks, including some of the largest banks in the US. The registration takes up to one business week from the moment Plaid has started the process. During this time, your shoppers cannot connect their bank account to Plaid. For this reason, you cannot accept live Pay by Bank (US) payments until the registration process is completed.

We send you a paymentMethod.created webhook when you can start accepting live Pay by Bank (US) payments.

See also