Add Payment Initiation to your app

In this guide, we'll start from scratch and walk through how to use Payment Initiation to make a payment. The steps are a bit different from setting up to use most Plaid products. For a high level overview of the process before diving in to the code, see Intro to Payment Initiation.

If you don't already have one, you'll need to create a Plaid developer account. After creating your account, you can find your API keys under the Team Settings menu on the Plaid Dashboard.

You will also need to complete your application profile and company profile on the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the Plaid Portal, and must be completed before connecting to certain institutions.

You'll need to request access to Payment Initiation before using it in any Plaid development environment, including Sandbox. To get access to Payment Initiation, submit a product access request Support ticket.

You can use our official server-side client libraries to connect to the Plaid API from your application:

1// Install via npm
2npm install --save plaid

After you've installed Plaid's client libraries, you can initialize them by passing in your client_id, secret, and the environment you wish to connect to (Sandbox, Development, or Production). This will make sure the client libraries pass along your client_id and secret with each request, and you won't need to explicitly include them in any other calls.

In the code samples below, you will need to replace PLAID_CLIENT_ID and PLAID_SECRET with your own keys, which you can obtain from the Dashboard. These code samples also demonstrate starting up a server commonly used in each framework (such as Express or Flask).

1// Using Express
2const express = require('express');
3const app = express();
4app.use(express.json());
5
6const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');
7
8const configuration = new Configuration({
9  basePath: PlaidEnvironments.sandbox,
10  baseOptions: {
11    headers: {
12      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
13      'PLAID-SECRET': process.env.PLAID_SECRET,
14    },
15  },
16}); 
17
18const client = new PlaidApi(configuration);

Before beginning the payment initiation process, you will need to know how much money is being sent and the name and account information of the recipient. With this information in hand, you can then call /payment_initiation/recipient/create to create a payment recipient and receive a recipient_id.

1const { PaymentInitiationRecipientCreateRequest } = require('plaid');
2
3// Using BACS, without IBAN or address
4const request: PaymentInitiationRecipientCreateRequest = {
5  name: 'John Doe',
6  bacs: {
7    account: '26207729',
8    sort_code: '560029',
9  },
10};
11try {
12  const response = await plaidClient.paymentInitiationRecipientCreate(request);
13  const recipientID = response.data.recipient_id;
14} catch (error) {
15  // handle error
16}

Now that you have the recipient_id, you can provide it and the payment amount to /payment_initiation/payment/create, which will return a payment_id.

1const { PaymentInitiationPaymentCreateRequest } = require('plaid');
2
3const request: PaymentInitiationPaymentCreateRequest = {
4  recipient_id: recipientID,
5  reference: 'TestPayment',
6  amount: {
7    currency: 'GBP',
8    value: 100.0,
9  },
10};
11try {
12  const response = await plaidClient.paymentInitiationPaymentCreate(request);
13  const paymentID = response.data.payment_id;
14  const status = response.data.status;
15} catch (error) {
16  // handle error
17}

Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the Link documentation. If you want to customize Link's look and feel, you can do so from the Dashboard.

Before initializing Link, you will need to create a new link_token on the server side of your application. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. You can create one using the /link/token/create endpoint. Then, on the client side of your application, you'll need to initialize Link with the link_token that you just created. This will bring up the Payment Initiation flow in Link that will allow your end user to confirm the payment.

When calling /link/token/create for use with Payment Initiation, you will provide the payment_id in order to create a token that will initialize Link for the Payment Initiation flow, and you will specify payment_initiation as the product. While it is normally possible to initialize Link with multiple products, payment_initiation cannot be specified along with any other products and must be the only product in Link's product array if it is being used.

In the code samples below, you will need to replace PLAID_CLIENT_ID and PLAID_SECRET with your own keys, which you can obtain from the Dashboard.

1// Using Express
2app.post('/api/create_link_token', async function (request, response) {
3  const configs = {
4    user: {
5      // This should correspond to a unique id for the current user.
6      client_user_id: 'user-id',
7    },
8    client_name: 'Plaid Test App',
9    products: [Products.PaymentInitiation],
10    language: 'en',
11    webhook: 'https://webhook.sample.com',
12    country_codes: [CountryCode.Gb],
13    payment_initiation: {
14      payment_id: paymentID,
15    },
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(configs);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});

1<head>
2  <title>Connect a bank</title>
3  <script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
4</head>

1const linkHandler = Plaid.create({
2  token: (await $.post('/create_link_token')).link_token,
3  onSuccess: (public_token, metadata) => {
4    // Send the public_token to your app server.
5    $.post('/exchange_public_token', {
6      public_token: public_token,
7    });
8  },
9  onExit: (err, metadata) => {
10    // Optionally capture when your user exited the Link flow.
11    // Storing this information can be helpful for support.
12  },
13  onEvent: (eventName, metadata) => {
14    // Optionally capture Link flow events, streamed through
15    // this callback as your users connect an Item to Plaid.
16  },
17});
18
19linkHandler.open();

Because Link has access to all of the details of the payment at the time of initialization, it will display a screen with the payment details already populated. All your end user has to do is log in to their financial institution through a Link-initiated OAuth flow, select a funding account, and confirm the payment details.

Once the payment is confirmed, you can track its status with the /payment_initiation/payment/get endpoint. A status of PAYMENT_STATUS_INITIATED means that the payment was successfully completed. Plaid will also fire the PAYMENT_STATUS_UPDATE webhook to alert you when there are any changes to the status of an initiated payment. Payments will generally complete immediately if the recipient account is in the UK, or in one business day if it is elsewhere in Europe.

1const { PaymentInitiationPaymentGetRequest } = require('plaid');
2
3const request: PaymentInitiationPaymentGetRequest = {
4  payment_id: paymentID,
5};
6try {
7  const response = await plaidClient.paymentInitiationPaymentGet(request);
8  const paymentID = response.data.payment_id;
9  const paymentToken = response.data.payment_token;
10  const reference = response.data.reference;
11  const amount = response.data.amount;
12  const status = response.data.status;
13  const lastStatusUpdate = response.data.last_status_update;
14  const paymentTokenExpirationTime =
15    response.data.payment_token_expiration_time;
16  const recipientID = response.data.recipient_id;
17} catch (error) {
18  // handle error
19}

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