Plaid logo
Docs
ALL DOCS

Payment Initiation (UK and Europe)

  • Introduction to Payment Initiation
  • Add Payment Initiation to your app
  • User onboarding and account funding
Plaid logo
Docs
Plaid.com
Get API keys
Open nav

User onboarding and account funding

Use Plaid to simplify your onboarding and funding flow

In this guide, we first walk through setting up an account linking flow that uses Plaid to connect your user's bank account. We'll then demonstrate how to verify the identity of your users which may help comply with KYC and AML regulations.

Finally, we’ll show how how to initiate payments while requiring that bank accounts involved in money movements are verified.

Before you get started

The Auth, Identity, and Payment Initiation products covered in this guide can immediately be tried out in the Sandbox environment, which uses test data and does not interact with financial institutions.

To gain access to these products in the Development and Production environments, submit a product access Support ticket.

User onboarding

The Plaid flow begins when the user registers with your app. The flow will connect your app to your user's financial institution.
Step  diagram
1Your backend creates a link_token by using the/link/token/create endpoint and passes the temporary token to your Client app.
Step 1 diagram
2Your Client app uses the link_token to initiate a Link flow for your user. The onSuccess callback signals that the user has granted your app access to their financial institution.
Step 2 diagram
3The onSuccess payload contains a public_token which, after sending it to your backend, needs to be exchanged for a long-lived access token using the /item/public_token/exchange endpoint.
Step 3 diagram
4Using this access token your backend can now retrieve the user’s bank account numbers via /auth/get or their identity information (such as their full name) via /identity/get.
Step 4 diagram

Adding the Auth and Identity products to your app

The steps listed above are broken down into more detail in the guides linked below. The first guide covers adding the Auth product (e.g. for obtaining the user’s bank account numbers). The second covers the Identity product (e.g. for obtaining the user’s legal name). Both guides describe almost identical steps, so you can follow either one.

The next section will highlight the single difference between the two and will show how you can use both products at the same time.

Auth

Add Auth to your app

Detailed steps

Identity

Add Identity to your app

Detailed steps

Creating a Link token

Link token creation is the only step requires changes when requesting both Auth and Identity-related information. To do so, pass both products as part of the /link/token/create request.

1{
2 "client_id": "CLIENT_ID",
3 "secret": "SECRET",
4 "client_name": "Plaid Test App",
5 "user": { "client_user_id": "UNIQUE_USER_ID" },
6 "products": ["auth", "identity"], // using both products
7 "country_codes": ["GB", "NL", "DE"],
8 "language": "en"
9 "webhook": "https://webhook.sample.com",
10}

End user experience

During the Link flow, your user grants permission to all the data products that you request. The images below demonstrate examples of the panes Link will present when requesting access to one or multiple products.

Account funding and withdrawal best practices

This section describes how to use the access_token that was obtained earlier to improve your user's account funding and withdrawal experiences.

Payment Initiation is offered only in Europe. For the US, see Transfer.

Payments in Europe are powered by the Payment Initiation product. See the Add Payment Initiation to your app guide to learn more about setting it up.

The following sections expand on this guide by providing compliance and conversion best practices.

Preselecting a financial institution

By default, Plaid will ask the user to manually select their financial institution. However, there might be cases where you already know which institution your user wants to use. For example, when your user has previously completed a sign up flow, you can increase conversion by skipping this part of the payment flow. This requires two steps:

  1. Call /item/get with the access_token as an input parameter. This endpoint will return the institution_id as part of the response.
  2. Provide the institution_id as part of the payment /link/token/create request.
1{
2 "client_id": "CLIENT_ID",
3 "secret": "SECRET",
4 "client_name": "Plaid Test App",
5 "user": { "client_user_id": "UNIQUE_USER_ID" },
6 "products": ["payment_initiation"],
7 "country_codes": ["GB", "NL", "DE"],
8 "language": "en"
9 "webhook": "https://webhook.sample.com",
10 "payment_initiation": { "payment_id": "PAYMENT_ID" },
11 "institution_id": "INSTITUTION_ID" // preselect institution_id
12}

Compliant account funding

To help comply with KYC & AML regulations you may choose to restrict payments to your app from bank accounts whose owner was previously verified.

Payment Initiation can support this flow by requiring that a payment is to be made from a specific account. The process has three steps:

  1. Call /auth/get with the access_token as an input parameter. This endpoint will return the user’s account numbers as part of the response (Use bacs for the UK and international for the rest of Europe).
  2. Provide one of the account numbers under options as part of the /payment_initiation/payment/create request. See the snippet below as an example.
  3. Provide the institution_id as part of the /link/token/create request, as described in the previous section.

Not all financial institutions support this feature. In the UK there is full support. In the rest of Europe, support may be limited. Plaid will let the user choose any account when their financial institution does not support this feature. It is recommended to also verify the origin of payments as part of your payment reconciliation process.

1{
2 "client_id": "CLIENT_ID",
3 "secret": "SECRET",
4 "recipient_id": "RECIPIENT_ID",
5 "reference": "Sample reference",
6 "amount": {
7 "currency": "GBP",
8 "amount": 1.99
9 },
10 "options": { // additional payee account restriction
11 "bacs": {
12 "account": "26207729",
13 "sort_code": "560029"
14 }
15 }
16}

Compliant withdrawals

To comply with KYC & AML regulations, you may want to restrict outbound money movements to accounts whose owner is verified. You can do this in the following ways:

Using Virtual Accounts

Make sure your virtual account is set up before following these steps. For more information on setting up an account, see Managing virtual accounts.

  1. Follow the Payment Confirmation flow to confirm that funds have settled in your virtual account.
  2. Fetch the payment object by calling /payment_initiation/payment/get with the payment_id of the payment you initiated. The payment object will contain a transaction_id, which corresponds to the payment's underlying virtual account transaction.
  3. Fetch the virtual account transaction by calling /wallet/transaction/get with the transaction_id.
  4. The virtual account transaction will contain account details in the counterparty field.
  5. Execute a Payout using the counterparty details.
Using Auth data
  1. Call /auth/get with the access_token as an input parameter. This endpoint will return the user’s verified account numbers as part of the response (Use bacs for the UK and international for the rest of Europe).
  2. Select accounts that can receive funds by filtering for account.subtype = "checking".
  3. Initiate the withdrawal to any of the filtered accounts. You may want to let the user choose a preferred account in case there are multiple.
Using the request_refund_details flag

This approach is not recommended since it is an optional flag with limited incomplete coverage dependent on the financial institution a payment was initiated to.

  1. Go through the Payment Initiation flow and initiate a payment with the request_refund_details flag enabled.
  2. Fetch the payment object by calling /payment_initiation/payment/get and parse the refund_details field.
  3. Initiate the withdrawal to account specified in the refund_details field.

Next steps

If you're ready to launch to Production, see the Launch checklist.

Launch checklist

Recommended steps to take before launching in Production

Launch
Was this helpful?
Developer community
GitHub
GitHub
Stack Overflow
Stack Overflow
YouTube
YouTube
Twitter
Twitter
Discord
Discord