Payment Initiation (UK and Europe)

Create a payment recipient for payment initiation. The recipient must be in Europe, within a country that is a member of the Single Euro Payment Area (SEPA) or a non-Eurozone country supported by Plaid. For a standing order (recurring) payment, the recipient must be in the UK.
It is recommended to use bacs in the UK and iban in EU.
The endpoint is idempotent: if a developer has already made a request with the same payment details, Plaid will return the same recipient_id.

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

Get details about a payment recipient you have previously created.

1const request: PaymentInitiationRecipientGetRequest = {
2  recipient_id: recipientID,
3};
4try {
5  const response = await plaidClient.paymentInitiationRecipientGet(request);
6  const recipientID = response.data.recipient_id;
7  const name = response.data.name;
8  const iban = response.data.iban;
9  const address = response.data.address;
10} catch (error) {
11  // handle error
12}

The /payment_initiation/recipient/list endpoint list the payment recipients that you have previously created.

1try {
2  const response = await plaidClient.paymentInitiationRecipientList({});
3  const recipients = response.data.recipients;
4} catch (error) {
5  // handle error
6}

After creating a payment recipient, you can use the /payment_initiation/payment/create endpoint to create a payment to that recipient. Payments can be one-time or standing order (recurring) and can be denominated in either EUR, GBP or other chosen currency. If making domestic GBP-denominated payments, your recipient must have been created with BACS numbers. In general, EUR-denominated payments will be sent via SEPA Credit Transfer, GBP-denominated payments will be sent via the Faster Payments network and for non-Eurozone markets typically via the local payment scheme, but the payment network used will be determined by the institution. Payments sent via Faster Payments will typically arrive immediately, while payments sent via SEPA Credit Transfer or other local payment schemes will typically arrive in one business day.
Standing orders (recurring payments) must be denominated in GBP and can only be sent to recipients in the UK. Once created, standing order payments cannot be modified or canceled via the API. An end user can cancel or modify a standing order directly on their banking application or website, or by contacting the bank. Standing orders will follow the payment rules of the underlying rails (Faster Payments in UK). Payments can be sent Monday to Friday, excluding bank holidays. If the pre-arranged date falls on a weekend or bank holiday, the payment is made on the next working day. It is not possible to guarantee the exact time the payment will reach the recipient’s account, although at least 90% of standing order payments are sent by 6am.
In the Development environment, payments must be below 5 GBP or other chosen currency. For details on any payment limits in Production, contact your Plaid Account Manager.

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

The /payment_initiation/payment/get endpoint can be used to check the status of a payment, as well as to receive basic information such as recipient and payment amount. In the case of standing orders, the /payment_initiation/payment/get endpoint will provide information about the status of the overall standing order itself; the API cannot be used to retrieve payment status for individual payments within a standing order.

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

The /payment_initiation/payment/list endpoint can be used to retrieve all created payments. By default, the 10 most recent payments are returned. You can request more payments and paginate through the results using the optional count and cursor parameters.

1const request: PaymentInitiationPaymentListRequest = {
2  count: 10,
3  cursor: '2019-12-06T22:35:49Z',
4};
5try {
6  const response = await plaidClient.paymentInitiationPaymentList(request);
7  const payments = response.data.payments;
8  const nextCursor = response.data.next_cursor;
9} catch (error) {
10  // handle error
11}

Reverse a settled payment from a Plaid virtual account.
The original payment must be in a settled state to be refunded. To refund partially, specify the amount as part of the request. If the amount is not specified, the refund amount will be equal to all of the remaining payment amount that has not been refunded yet.
The refund will go back to the source account that initiated the payment. The original payment must have been initiated to a Plaid virtual account so that this account can be used to initiate the refund.

1const request: PaymentInitiationPaymentReverseRequest = {
2  payment_id: paymentID,
3  reference: 'Refund for purchase ABC123',
4  idempotency_key: 'ae009325-df8d-4f52-b1e0-53ff26c23912',
5};
6try {
7  const response = await plaidClient.paymentInitiationPaymentReverse(request);
8  const refundID = response.data.refund_id;
9  const status = response.data.status;
10} catch (error) {
11  // handle error
12}

The /payment_initiation/consent/create endpoint is used to create a payment consent, which can be used to initiate payments on behalf of the user. Payment consents are created with UNAUTHORISED status by default and must be authorised by the user before payments can be initiated.
Consents can be limited in time and scope, and have constraints that describe limitations for payments.

1const request: PaymentInitiationConsentCreateRequest = {
2  recipient_id: recipientID,
3  reference: 'TestPaymentConsent',
4  scopes: new Set([PaymentInitiationConsentScope.MeToMe]),
5  constraints: {
6    valid_date_time: {
7      to: '2024-12-31T23:59:59Z',
8    },
9    max_payment_amount: {
10      currency: PaymentAmountCurrency.Gbp,
11      value: 15,
12    },
13    periodic_amounts: [
14      {
15        amount: {
16          currency: PaymentAmountCurrency.Gbp,
17          value: 40,
18        },
19        alignment: PaymentConsentPeriodicAlignment.Calendar,
20        interval: PaymentConsentPeriodicInterval.Month,
21      },
22    ],
23  },
24};
25
26try {
27  const response = await plaidClient.paymentInitiationConsentCreate(request);
28  const consentID = response.data.consent_id;
29  const status = response.data.status;
30} catch (error) {
31  // handle error
32}

The /payment_initiation/consent/get endpoint can be used to check the status of a payment consent, as well as to receive basic information such as recipient and constraints.

1const request: PaymentInitiationConsentGetRequest = {
2  consent_id: consentID,
3};
4
5try {
6  const response = await plaidClient.paymentInitiationConsentGet(request);
7  const consentID = response.data.consent_id;
8  const status = response.data.status;
9} catch (error) {
10  // handle error
11}

The /payment_initiation/consent/revoke endpoint can be used to revoke the payment consent. Once the consent is revoked, it is not possible to initiate payments using it.

1const request: PaymentInitiationConsentRevokeRequest = {
2  consent_id: consentID,
3};
4try {
5  const response = await plaidClient.paymentInitiationConsentRevoke(request);
6} catch (error) {
7  // handle error
8}