Plaid logo
Docs
ALL DOCS

API

  • Overview
  • Libraries
  • API versioning
  • Postman Collection
  • Webhooks
Product API reference
  • Transactions
  • Auth
  • Balance
  • Identity
  • Assets
  • Investments
  • Liabilities
  • Payment Initiation
  • Virtual Accounts
  • Transfer (beta)
  • Income
  • Identity Verification
  • Monitor
  • Signal
  • Enrich
Other API reference
  • Item endpoints and webhooks
  • Account endpoints and schemas
  • Institution endpoints
  • Token flow and endpoints
  • Processor endpoints
  • Sandbox endpoints
  • Reseller partner endpoints
Plaid logo
Docs
Plaid.com
Get API keys
Open nav

Payment Initiation (UK and Europe)

API reference for Payment Initiation endpoints and webhooks

Make payment transfers from your app. Plaid supports both domestic payments denominated in local currencies and international payments, generally denominated in Euro. Domestic payments can be made in pound sterling (typically via the Faster Payments network), Euro (via SEPA Credit Transfer or SEPA Instant) and other local currencies (Polish Zloty, Danish Krone, Swedish Krona, Norwegian Krone), typically via local payment schemes.

For payments in the US, see Transfer (beta).

Looking for guidance on how to integrate using these endpoints? Check out the Payment Initiation documentation.

Endpoints
/payment_initiation/recipient/createCreate a recipient
/payment_initiation/recipient/getFetch recipient data
/payment_initiation/recipient/listList all recipients
/payment_initiation/payment/createCreate a payment
/payment_initiation/payment/getFetch a payment
/payment_initiation/payment/listList all payments
/payment_initiation/payment/reverseRefund a payment from a virtual account
/payment_initiation/consent/createCreate a payment consent
/payment_initiation/consent/getFetch a payment consent
/payment_initiation/consent/revokeRevoke a payment consent
/payment_initiation/consent/payment/executeExecute a payment using payment consent

Users will be prompted to authorise the payment once you initialise Link. See the documentation for link/token/create for more information on how to obtain a payments link_token.

Webhooks
PAYMENT_STATUS_UPDATEThe status of a payment has changed

Endpoints

/payment_initiation/recipient/create

Create payment recipient

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.

payment_initiation/recipient/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
name
requiredstring
The name of the recipient. We recommend using strings of length 18 or less and avoid special characters to ensure compatibility with all institutions.

Min length: 1
iban
string
The International Bank Account Number (IBAN) for the recipient. If BACS data is not provided, an IBAN is required.

Min length: 15
Max length: 34
bacs
object
The account number and sort code of the recipient's account.
account
string
The account number of the account. Maximum of 10 characters.

Min length: 1
Max length: 10
sort_code
string
The 6-character sort code of the account.

Min length: 6
Max length: 6
address
object
The optional address of the payment recipient. Required by most institutions outside of the UK.
street
required[string]
An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters.

Min items: 1
Min length: 1
city
requiredstring
The city where the recipient is located. Maximum of 35 characters.

Min length: 1
Max length: 35
postal_code
requiredstring
The postal code where the recipient is located. Maximum of 16 characters.

Min length: 1
Max length: 16
country
requiredstring
The ISO 3166-1 alpha-2 country code where the recipient is located.

Min length: 2
Max length: 2
Select group for content switcher
Select Language
Copy
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}
payment_initiation/recipient/create

Response fields and example

recipient_id
string
A unique ID identifying the recipient
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
Copy
1{
2 "recipient_id": "recipient-id-sandbox-9b6b4679-914b-445b-9450-efbdb80296f6",
3 "request_id": "4zlKapIkTm8p5KM"
4}
Was this helpful?

/payment_initiation/recipient/get

Get payment recipient

Get details about a payment recipient you have previously created.

payment_initiation/recipient/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
recipient_id
requiredstring
The ID of the recipient
Select group for content switcher
Select Language
Copy
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}
payment_initiation/recipient/get

Response fields and example

recipient_id
string
The ID of the recipient.
name
string
The name of the recipient.
address
nullableobject
The optional address of the payment recipient. Required by most institutions outside of the UK.
street
[string]
An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters.

Min items: 1
Min length: 1
city
string
The city where the recipient is located. Maximum of 35 characters.

Min length: 1
Max length: 35
postal_code
string
The postal code where the recipient is located. Maximum of 16 characters.

Min length: 1
Max length: 16
country
string
The ISO 3166-1 alpha-2 country code where the recipient is located.

Min length: 2
Max length: 2
iban
nullablestring
The International Bank Account Number (IBAN) for the recipient.
bacs
nullableobject
The account number and sort code of the recipient's account.
account
string
The account number of the account. Maximum of 10 characters.

Min length: 1
Max length: 10
sort_code
string
The 6-character sort code of the account.

Min length: 6
Max length: 6
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
Copy
1{
2 "recipient_id": "recipient-id-sandbox-9b6b4679-914b-445b-9450-efbdb80296f6",
3 "name": "Wonder Wallet",
4 "iban": "GB29NWBK60161331926819",
5 "address": {
6 "street": [
7 "96 Guild Street",
8 "9th Floor"
9 ],
10 "city": "London",
11 "postal_code": "SE14 8JW",
12 "country": "GB"
13 },
14 "request_id": "4zlKapIkTm8p5KM"
15}
Was this helpful?

/payment_initiation/recipient/list

List payment recipients

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

payment_initiation/recipient/list

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
Select group for content switcher
Select Language
Copy
1try {
2 const response = await plaidClient.paymentInitiationRecipientList({});
3 const recipients = response.data.recipients;
4} catch (error) {
5 // handle error
6}
payment_initiation/recipient/list

Response fields and example

recipients
[object]
An array of payment recipients created for Payment Initiation
recipient_id
string
The ID of the recipient.
name
string
The name of the recipient.
address
nullableobject
The optional address of the payment recipient. Required by most institutions outside of the UK.
street
[string]
An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters.

Min items: 1
Min length: 1
city
string
The city where the recipient is located. Maximum of 35 characters.

Min length: 1
Max length: 35
postal_code
string
The postal code where the recipient is located. Maximum of 16 characters.

Min length: 1
Max length: 16
country
string
The ISO 3166-1 alpha-2 country code where the recipient is located.

Min length: 2
Max length: 2
iban
nullablestring
The International Bank Account Number (IBAN) for the recipient.
bacs
nullableobject
The account number and sort code of the recipient's account.
account
string
The account number of the account. Maximum of 10 characters.

Min length: 1
Max length: 10
sort_code
string
The 6-character sort code of the account.

Min length: 6
Max length: 6
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
Copy
1{
2 "recipients": [
3 {
4 "recipient_id": "recipient-id-sandbox-9b6b4679-914b-445b-9450-efbdb80296f6",
5 "name": "Wonder Wallet",
6 "iban": "GB29NWBK60161331926819",
7 "address": {
8 "street": [
9 "96 Guild Street",
10 "9th Floor"
11 ],
12 "city": "London",
13 "postal_code": "SE14 8JW",
14 "country": "GB"
15 }
16 }
17 ],
18 "request_id": "4zlKapIkTm8p5KM"
19}
Was this helpful?

/payment_initiation/payment/create

Create a payment

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.

payment_initiation/payment/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
recipient_id
requiredstring
The ID of the recipient the payment is for.
reference
requiredstring
A reference for the payment. This must be an alphanumeric string with at most 18 characters and must not contain any special characters (since not all institutions support them). In order to track settlement via Payment Confirmation, each payment must have a unique reference. If the reference provided through the API is not unique, Plaid will adjust it. Both the originally provided and automatically adjusted references (if any) can be found in the reference and adjusted_reference fields, respectively.

Min length: 1
Max length: 18
amount
requiredobject
The amount and currency of a payment
currency
requiredstring
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used.

Possible values: GBP, EUR, PLN, SEK, DKK, NOK
Min length: 3
Max length: 3
value
requirednumber
The amount of the payment. Must contain at most two digits of precision e.g. 1.23. Minimum accepted value is 1.

Format: double
schedule
object
The schedule that the payment will be executed on. If a schedule is provided, the payment is automatically set up as a standing order. If no schedule is specified, the payment will be executed only once.
interval
requiredstring
The frequency interval of the payment.

Possible values: WEEKLY, MONTHLY
Min length: 1
interval_execution_day
requiredinteger
The day of the interval on which to schedule the payment.
If the payment interval is weekly, interval_execution_day should be an integer from 1 (Monday) to 7 (Sunday).
If the payment interval is monthly, interval_execution_day should be an integer indicating which day of the month to make the payment on. Integers from 1 to 28 can be used to make a payment on that day of the month. Negative integers from -1 to -5 can be used to make a payment relative to the end of the month. To make a payment on the last day of the month, use -1; to make the payment on the second-to-last day, use -2, and so on.
start_date
requiredstring
A date in ISO 8601 format (YYYY-MM-DD). Standing order payments will begin on the first interval_execution_day on or after the start_date.
If the first interval_execution_day on or after the start date is also the same day that /payment_initiation/payment/create was called, the bank may make the first payment on that day, but it is not guaranteed to do so.


Format: date
end_date
string
A date in ISO 8601 format (YYYY-MM-DD). Standing order payments will end on the last interval_execution_day on or before the end_date. If the only interval_execution_day between the start date and the end date (inclusive) is also the same day that /payment_initiation/payment/create was called, the bank may make a payment on that day, but it is not guaranteed to do so.

Format: date
adjusted_start_date
string
The start date sent to the bank after adjusting for holidays or weekends. Will be provided in ISO 8601 format (YYYY-MM-DD). If the start date did not require adjustment, this field will be null.

Format: date
options
object
Additional payment options
request_refund_details
boolean
When true, Plaid will attempt to request refund details from the payee's financial institution. Support varies between financial institutions and will not always be available. If refund details could be retrieved, they will be available in the /payment_initiation/payment/get response.
iban
string
The International Bank Account Number (IBAN) for the payer's account. Where possible, the end user will be able to send payments only from the specified bank account if provided.

Min length: 15
Max length: 34
bacs
object
An object containing a BACS account number and sort code. If an IBAN is not provided or if you need to accept domestic GBP-denominated payments, BACS data is required.
account
string
The account number of the account. Maximum of 10 characters.

Min length: 1
Max length: 10
sort_code
string
The 6-character sort code of the account.

Min length: 6
Max length: 6
scheme
string
Payment scheme. If not specified - the default in the region will be used (e.g. SEPA_CREDIT_TRANSFER for EU). Using unsupported values will result in a failed payment.
LOCAL_DEFAULT: The default payment scheme for the selected market and currency will be used.
LOCAL_INSTANT: The instant payment scheme for the selected market and currency will be used (if applicable). Fees may be applied by the institution. If the market does not support an Instant Scheme (e.g. Denmark), the default in the region will be used.
SEPA_CREDIT_TRANSFER: The standard payment to a beneficiary within the SEPA area.
SEPA_CREDIT_TRANSFER_INSTANT: Instant payment within the SEPA area. May involve additional fees and may not be available at some banks.


Possible values: null, LOCAL_DEFAULT, LOCAL_INSTANT, SEPA_CREDIT_TRANSFER, SEPA_CREDIT_TRANSFER_INSTANT
Select group for content switcher
Select Language
Copy
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}
payment_initiation/payment/create

Response fields and example

payment_id
string
A unique ID identifying the payment
status
string
For a payment returned by this endpoint, there is only one possible value:
PAYMENT_STATUS_INPUT_NEEDED: The initial phase of the payment


Possible values: PAYMENT_STATUS_INPUT_NEEDED
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
Copy
1{
2 "payment_id": "payment-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3",
3 "status": "PAYMENT_STATUS_INPUT_NEEDED",
4 "request_id": "4ciYVmesrySiUAB"
5}
Was this helpful?

/payment_initiation/payment/get

Get payment details

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.

payment_initiation/payment/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
payment_id
requiredstring
The payment_id returned from /payment_initiation/payment/create.
Select group for content switcher
Select Language
Copy
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}
payment_initiation/payment/get

Response fields and example

payment_id
string
The ID of the payment. Like all Plaid identifiers, the payment_id is case sensitive.
amount
object
The amount and currency of a payment
currency
string
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used.

Possible values: GBP, EUR, PLN, SEK, DKK, NOK
Min length: 3
Max length: 3
value
number
The amount of the payment. Must contain at most two digits of precision e.g. 1.23. Minimum accepted value is 1.

Format: double
status
string
The status of the payment.
PAYMENT_STATUS_INPUT_NEEDED: This is the initial state of all payments. It indicates that the payment is waiting on user input to continue processing. A payment may re-enter this state later on if further input is needed.
PAYMENT_STATUS_INITIATED: The payment has been successfully authorised and accepted by the financial institution but has not been executed.
PAYMENT_STATUS_INSUFFICIENT_FUNDS: The payment has failed due to insufficient funds.
PAYMENT_STATUS_FAILED: The payment has failed to be initiated. This error is retryable once the root cause is resolved.
PAYMENT_STATUS_BLOCKED: The payment has been blocked. This is a retryable error.
PAYMENT_STATUS_AUTHORISING: The payment is currently being processed. The payment will automatically exit this state when the financial institution has authorised the transaction.
PAYMENT_STATUS_CANCELLED: The payment was cancelled during authorisation.
PAYMENT_STATUS_EXECUTED: The payment has been successfully executed and is considered complete.
PAYMENT_STATUS_SETTLED: The payment has settled and funds are available for use. Payment settlement can only be guaranteed by using Plaid virtual accounts. A payment will typically settle within seconds to several days, depending on which payment rail is used.
PAYMENT_STATUS_ESTABLISHED: Indicates that the standing order has been successfully established. This state is only used for standing orders.
PAYMENT_STATUS_REJECTED: The payment was rejected by the financial institution.
Deprecated: These statuses will be removed in a future release.
PAYMENT_STATUS_UNKNOWN: The payment status is unknown.
PAYMENT_STATUS_PROCESSING: The payment is currently being processed. The payment will automatically exit this state when processing is complete.
PAYMENT_STATUS_COMPLETED: Indicates that the standing order has been successfully established. This state is only used for standing orders.


Possible values: PAYMENT_STATUS_INPUT_NEEDED, PAYMENT_STATUS_PROCESSING, PAYMENT_STATUS_INITIATED, PAYMENT_STATUS_COMPLETED, PAYMENT_STATUS_INSUFFICIENT_FUNDS, PAYMENT_STATUS_FAILED, PAYMENT_STATUS_BLOCKED, PAYMENT_STATUS_UNKNOWN, PAYMENT_STATUS_EXECUTED, PAYMENT_STATUS_SETTLED, PAYMENT_STATUS_AUTHORISING, PAYMENT_STATUS_CANCELLED, PAYMENT_STATUS_ESTABLISHED, PAYMENT_STATUS_REJECTED
recipient_id
string
The ID of the recipient
reference
string
A reference for the payment.
adjusted_reference
nullablestring
The value of the reference sent to the bank after adjustment to pass bank validation rules.
last_status_update
string
The date and time of the last time the status was updated, in IS0 8601 format

Format: date-time
schedule
nullableobject
The schedule that the payment will be executed on. If a schedule is provided, the payment is automatically set up as a standing order. If no schedule is specified, the payment will be executed only once.
interval
string
The frequency interval of the payment.

Possible values: WEEKLY, MONTHLY
Min length: 1
interval_execution_day
integer
The day of the interval on which to schedule the payment.
If the payment interval is weekly, interval_execution_day should be an integer from 1 (Monday) to 7 (Sunday).
If the payment interval is monthly, interval_execution_day should be an integer indicating which day of the month to make the payment on. Integers from 1 to 28 can be used to make a payment on that day of the month. Negative integers from -1 to -5 can be used to make a payment relative to the end of the month. To make a payment on the last day of the month, use -1; to make the payment on the second-to-last day, use -2, and so on.
start_date
string
A date in ISO 8601 format (YYYY-MM-DD). Standing order payments will begin on the first interval_execution_day on or after the start_date.
If the first interval_execution_day on or after the start date is also the same day that /payment_initiation/payment/create was called, the bank may make the first payment on that day, but it is not guaranteed to do so.


Format: date
end_date
nullablestring
A date in ISO 8601 format (YYYY-MM-DD). Standing order payments will end on the last interval_execution_day on or before the end_date. If the only interval_execution_day between the start date and the end date (inclusive) is also the same day that /payment_initiation/payment/create was called, the bank may make a payment on that day, but it is not guaranteed to do so.

Format: date
adjusted_start_date
nullablestring
The start date sent to the bank after adjusting for holidays or weekends. Will be provided in ISO 8601 format (YYYY-MM-DD). If the start date did not require adjustment, this field will be null.

Format: date
refund_details
nullableobject
Details about external payment refund
name
string
The name of the account holder.
iban
nullablestring
The International Bank Account Number (IBAN) for the account.
bacs
nullableobject
The account number and sort code of the recipient's account.
account
string
The account number of the account. Maximum of 10 characters.

Min length: 1
Max length: 10
sort_code
string
The 6-character sort code of the account.

Min length: 6
Max length: 6
bacs
nullableobject
The account number and sort code of the sender's account, if specified in the /payment_initiation/payment/create call.
account
string
The account number of the account. Maximum of 10 characters.

Min length: 1
Max length: 10
sort_code
string
The 6-character sort code of the account.

Min length: 6
Max length: 6
iban
nullablestring
The International Bank Account Number (IBAN) for the sender, if specified in the /payment_initiation/payment/create call.
refund_ids
nullable[string]
Refund IDs associated with the payment.
amount_refunded
nullableobject
The amount that has been refunded already. Subtract this from the payment amount to calculate the amount still available to refund.
currency
string
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used.

Possible values: GBP, EUR, PLN, SEK, DKK, NOK
Min length: 3
Max length: 3
value
number
The amount of the payment. Must contain at most two digits of precision e.g. 1.23.

Format: double
Minimum: 0.01
wallet_id
nullablestring
The EMI (E-Money Institution) wallet that this payment is associated with, if any. This wallet is used as an intermediary account to enable Plaid to reconcile the settlement of funds for Payment Initiation requests.
scheme
nullablestring
Payment scheme. If not specified - the default in the region will be used (e.g. SEPA_CREDIT_TRANSFER for EU). Using unsupported values will result in a failed payment.
LOCAL_DEFAULT: The default payment scheme for the selected market and currency will be used.
LOCAL_INSTANT: The instant payment scheme for the selected market and currency will be used (if applicable). Fees may be applied by the institution. If the market does not support an Instant Scheme (e.g. Denmark), the default in the region will be used.
SEPA_CREDIT_TRANSFER: The standard payment to a beneficiary within the SEPA area.
SEPA_CREDIT_TRANSFER_INSTANT: Instant payment within the SEPA area. May involve additional fees and may not be available at some banks.


Possible values: null, LOCAL_DEFAULT, LOCAL_INSTANT, SEPA_CREDIT_TRANSFER, SEPA_CREDIT_TRANSFER_INSTANT
adjusted_scheme
nullablestring
Payment scheme. If not specified - the default in the region will be used (e.g. SEPA_CREDIT_TRANSFER for EU). Using unsupported values will result in a failed payment.
LOCAL_DEFAULT: The default payment scheme for the selected market and currency will be used.
LOCAL_INSTANT: The instant payment scheme for the selected market and currency will be used (if applicable). Fees may be applied by the institution. If the market does not support an Instant Scheme (e.g. Denmark), the default in the region will be used.
SEPA_CREDIT_TRANSFER: The standard payment to a beneficiary within the SEPA area.
SEPA_CREDIT_TRANSFER_INSTANT: Instant payment within the SEPA area. May involve additional fees and may not be available at some banks.


Possible values: null, LOCAL_DEFAULT, LOCAL_INSTANT, SEPA_CREDIT_TRANSFER, SEPA_CREDIT_TRANSFER_INSTANT
consent_id
nullablestring
The payment consent ID that this payment was initiated with. Is present only when payment was initiated using the payment consent.
transaction_id
nullablestring
The transaction ID that this payment is associated with, if any. This is present only when a payment was initiated using virtual accounts.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
Copy
1{
2 "payment_id": "payment-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3",
3 "payment_token": "payment-token-sandbox-c6a26505-42b4-46fe-8ecf-bf9edcafbebb",
4 "reference": "Account Funding 99744",
5 "amount": {
6 "currency": "GBP",
7 "value": 100
8 },
9 "status": "PAYMENT_STATUS_INPUT_NEEDED",
10 "last_status_update": "2019-11-06T21:10:52Z",
11 "payment_expiration_time": "2019-11-06T21:25:52Z",
12 "recipient_id": "recipient-id-sandbox-9b6b4679-914b-445b-9450-efbdb80296f6",
13 "bacs": {
14 "account": "31926819",
15 "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
16 "sort_code": "601613"
17 },
18 "iban": null,
19 "request_id": "aEAQmewMzlVa1k6"
20}
Was this helpful?

/payment_initiation/payment/list

List payments

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.

payment_initiation/payment/list

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
count
integer
The maximum number of payments to return. If count is not specified, a maximum of 10 payments will be returned, beginning with the most recent payment before the cursor (if specified).

Minimum: 1
Maximum: 200
Default: 10
cursor
string
A string in RFC 3339 format (i.e. "2019-12-06T22:35:49Z"). Only payments created before the cursor will be returned.

Format: date-time
consent_id
string
The consent ID. If specified, only payments, executed using this consent, will be returned.
Select group for content switcher
Select Language
Copy
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}
payment_initiation/payment/list

Response fields and example

payments
[object]
An array of payments that have been created, associated with the given client_id.
payment_id
string
The ID of the payment. Like all Plaid identifiers, the payment_id is case sensitive.
amount
object
The amount and currency of a payment
currency
string
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used.

Possible values: GBP, EUR, PLN, SEK, DKK, NOK
Min length: 3
Max length: 3
value
number
The amount of the payment. Must contain at most two digits of precision e.g. 1.23. Minimum accepted value is 1.

Format: double
status
string
The status of the payment.
PAYMENT_STATUS_INPUT_NEEDED: This is the initial state of all payments. It indicates that the payment is waiting on user input to continue processing. A payment may re-enter this state later on if further input is needed.
PAYMENT_STATUS_INITIATED: The payment has been successfully authorised and accepted by the financial institution but has not been executed.
PAYMENT_STATUS_INSUFFICIENT_FUNDS: The payment has failed due to insufficient funds.
PAYMENT_STATUS_FAILED: The payment has failed to be initiated. This error is retryable once the root cause is resolved.
PAYMENT_STATUS_BLOCKED: The payment has been blocked. This is a retryable error.
PAYMENT_STATUS_AUTHORISING: The payment is currently being processed. The payment will automatically exit this state when the financial institution has authorised the transaction.
PAYMENT_STATUS_CANCELLED: The payment was cancelled during authorisation.
PAYMENT_STATUS_EXECUTED: The payment has been successfully executed and is considered complete.
PAYMENT_STATUS_SETTLED: The payment has settled and funds are available for use. Payment settlement can only be guaranteed by using Plaid virtual accounts. A payment will typically settle within seconds to several days, depending on which payment rail is used.
PAYMENT_STATUS_ESTABLISHED: Indicates that the standing order has been successfully established. This state is only used for standing orders.
PAYMENT_STATUS_REJECTED: The payment was rejected by the financial institution.
Deprecated: These statuses will be removed in a future release.
PAYMENT_STATUS_UNKNOWN: The payment status is unknown.
PAYMENT_STATUS_PROCESSING: The payment is currently being processed. The payment will automatically exit this state when processing is complete.
PAYMENT_STATUS_COMPLETED: Indicates that the standing order has been successfully established. This state is only used for standing orders.


Possible values: PAYMENT_STATUS_INPUT_NEEDED, PAYMENT_STATUS_PROCESSING, PAYMENT_STATUS_INITIATED, PAYMENT_STATUS_COMPLETED, PAYMENT_STATUS_INSUFFICIENT_FUNDS, PAYMENT_STATUS_FAILED, PAYMENT_STATUS_BLOCKED, PAYMENT_STATUS_UNKNOWN, PAYMENT_STATUS_EXECUTED, PAYMENT_STATUS_SETTLED, PAYMENT_STATUS_AUTHORISING, PAYMENT_STATUS_CANCELLED, PAYMENT_STATUS_ESTABLISHED, PAYMENT_STATUS_REJECTED
recipient_id
string
The ID of the recipient
reference
string
A reference for the payment.
adjusted_reference
nullablestring
The value of the reference sent to the bank after adjustment to pass bank validation rules.
last_status_update
string
The date and time of the last time the status was updated, in IS0 8601 format

Format: date-time
schedule
nullableobject
The schedule that the payment will be executed on. If a schedule is provided, the payment is automatically set up as a standing order. If no schedule is specified, the payment will be executed only once.
interval
string
The frequency interval of the payment.

Possible values: WEEKLY, MONTHLY
Min length: 1
interval_execution_day
integer
The day of the interval on which to schedule the payment.
If the payment interval is weekly, interval_execution_day should be an integer from 1 (Monday) to 7 (Sunday).
If the payment interval is monthly, interval_execution_day should be an integer indicating which day of the month to make the payment on. Integers from 1 to 28 can be used to make a payment on that day of the month. Negative integers from -1 to -5 can be used to make a payment relative to the end of the month. To make a payment on the last day of the month, use -1; to make the payment on the second-to-last day, use -2, and so on.
start_date
string
A date in ISO 8601 format (YYYY-MM-DD). Standing order payments will begin on the first interval_execution_day on or after the start_date.
If the first interval_execution_day on or after the start date is also the same day that /payment_initiation/payment/create was called, the bank may make the first payment on that day, but it is not guaranteed to do so.


Format: date
end_date
nullablestring
A date in ISO 8601 format (YYYY-MM-DD). Standing order payments will end on the last interval_execution_day on or before the end_date. If the only interval_execution_day between the start date and the end date (inclusive) is also the same day that /payment_initiation/payment/create was called, the bank may make a payment on that day, but it is not guaranteed to do so.

Format: date
adjusted_start_date
nullablestring
The start date sent to the bank after adjusting for holidays or weekends. Will be provided in ISO 8601 format (YYYY-MM-DD). If the start date did not require adjustment, this field will be null.

Format: date
refund_details
nullableobject
Details about external payment refund
name
string
The name of the account holder.
iban
nullablestring
The International Bank Account Number (IBAN) for the account.
bacs
nullableobject
The account number and sort code of the recipient's account.
account
string
The account number of the account. Maximum of 10 characters.

Min length: 1
Max length: 10
sort_code
string
The 6-character sort code of the account.

Min length: 6
Max length: 6
bacs
nullableobject
The account number and sort code of the sender's account, if specified in the /payment_initiation/payment/create call.
account
string
The account number of the account. Maximum of 10 characters.

Min length: 1
Max length: 10
sort_code
string
The 6-character sort code of the account.

Min length: 6
Max length: 6
iban
nullablestring
The International Bank Account Number (IBAN) for the sender, if specified in the /payment_initiation/payment/create call.
refund_ids
nullable[string]
Refund IDs associated with the payment.
amount_refunded
nullableobject
The amount that has been refunded already. Subtract this from the payment amount to calculate the amount still available to refund.
currency
string
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used.

Possible values: GBP, EUR, PLN, SEK, DKK, NOK
Min length: 3
Max length: 3
value
number
The amount of the payment. Must contain at most two digits of precision e.g. 1.23.

Format: double
Minimum: 0.01
wallet_id
nullablestring
The EMI (E-Money Institution) wallet that this payment is associated with, if any. This wallet is used as an intermediary account to enable Plaid to reconcile the settlement of funds for Payment Initiation requests.
scheme
nullablestring
Payment scheme. If not specified - the default in the region will be used (e.g. SEPA_CREDIT_TRANSFER for EU). Using unsupported values will result in a failed payment.
LOCAL_DEFAULT: The default payment scheme for the selected market and currency will be used.
LOCAL_INSTANT: The instant payment scheme for the selected market and currency will be used (if applicable). Fees may be applied by the institution. If the market does not support an Instant Scheme (e.g. Denmark), the default in the region will be used.
SEPA_CREDIT_TRANSFER: The standard payment to a beneficiary within the SEPA area.
SEPA_CREDIT_TRANSFER_INSTANT: Instant payment within the SEPA area. May involve additional fees and may not be available at some banks.


Possible values: null, LOCAL_DEFAULT, LOCAL_INSTANT, SEPA_CREDIT_TRANSFER, SEPA_CREDIT_TRANSFER_INSTANT
adjusted_scheme
nullablestring
Payment scheme. If not specified - the default in the region will be used (e.g. SEPA_CREDIT_TRANSFER for EU). Using unsupported values will result in a failed payment.
LOCAL_DEFAULT: The default payment scheme for the selected market and currency will be used.
LOCAL_INSTANT: The instant payment scheme for the selected market and currency will be used (if applicable). Fees may be applied by the institution. If the market does not support an Instant Scheme (e.g. Denmark), the default in the region will be used.
SEPA_CREDIT_TRANSFER: The standard payment to a beneficiary within the SEPA area.
SEPA_CREDIT_TRANSFER_INSTANT: Instant payment within the SEPA area. May involve additional fees and may not be available at some banks.


Possible values: null, LOCAL_DEFAULT, LOCAL_INSTANT, SEPA_CREDIT_TRANSFER, SEPA_CREDIT_TRANSFER_INSTANT
consent_id
nullablestring
The payment consent ID that this payment was initiated with. Is present only when payment was initiated using the payment consent.
transaction_id
nullablestring
The transaction ID that this payment is associated with, if any. This is present only when a payment was initiated using virtual accounts.
next_cursor
nullablestring
The value that, when used as the optional cursor parameter to /payment_initiation/payment/list, will return the next unreturned payment as its first payment.

Format: date-time
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
Copy
1{
2 "payments": [
3 {
4 "payment_id": "payment-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3",
5 "reference": "Account Funding 99744",
6 "amount": {
7 "currency": "GBP",
8 "value": 100
9 },
10 "status": "PAYMENT_STATUS_INPUT_NEEDED",
11 "last_status_update": "2019-11-06T21:10:52Z",
12 "recipient_id": "recipient-id-sandbox-9b6b4679-914b-445b-9450-efbdb80296f6",
13 "bacs": {
14 "account": "31926819",
15 "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
16 "sort_code": "601613"
17 },
18 "iban": null
19 }
20 ],
21 "next_cursor": "2020-01-01T00:00:00Z",
22 "request_id": "aEAQmewMzlVa1k6"
23}
Was this helpful?

/payment_initiation/payment/reverse

Reverse an existing payment

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.

payment_initiation/payment/reverse

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
payment_id
requiredstring
The ID of the payment to reverse
idempotency_key
requiredstring
A random key provided by the client, per unique wallet transaction. Maximum of 128 characters.
The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. If a request to execute a wallet transaction fails due to a network connection error, then after a minimum delay of one minute, you can retry the request with the same idempotency key to guarantee that only a single wallet transaction is created. If the request was successfully processed, it will prevent any transaction that uses the same idempotency key, and was received within 24 hours of the first request, from being processed.


Max length: 128
Min length: 1
reference
requiredstring
A reference for the refund. This must be an alphanumeric string with 6 to 18 characters and must not contain any special characters or spaces.

Max length: 18
Min length: 6
amount
object
An amount to refund the payment partially. If this amount is not specified, the payment is refunded fully for the remaining amount.
currency
requiredstring
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used.

Possible values: GBP, EUR, PLN, SEK, DKK, NOK
Min length: 3
Max length: 3
value
requirednumber
The amount of the payment. Must contain at most two digits of precision e.g. 1.23.

Format: double
Minimum: 0.01
Select Language
Copy
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}
payment_initiation/payment/reverse

Response fields and example

refund_id
string
A unique ID identifying the refund
status
string
The status of the transaction.
AUTHORISING: The transaction is being processed for validation and compliance.
INITIATED: The transaction has been initiated and is currently being processed.
EXECUTED: The transaction has been successfully executed and is considered complete. This is only applicable for debit transactions.
SETTLED: The transaction has settled and funds are available for use. This is only applicable for credit transactions. A transaction will typically settle within seconds to several days, depending on which payment rail is used.
FAILED: The transaction failed to process successfully. This is a terminal status.
BLOCKED: The transaction has been blocked for violating compliance rules. This is a terminal status.


Possible values: AUTHORISING, INITIATED, EXECUTED, SETTLED, BLOCKED, FAILED
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
Copy
1{
2 "refund_id": "wallet-transaction-id-production-c5f8cd31-6cae-4cad-9b0d-f7c10be9cc4b",
3 "request_id": "HtlKzBX0fMeF7mU",
4 "status": "INITIATED"
5}
Was this helpful?

/payment_initiation/consent/create

Create payment consent

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.

payment_initiation/consent/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
recipient_id
requiredstring
The ID of the recipient the payment consent is for. The created consent can be used to transfer funds to this recipient only.
reference
requiredstring
A reference for the payment consent. This must be an alphanumeric string with at most 18 characters and must not contain any special characters.

Min length: 1
Max length: 18
scopes
required[string]
An array of payment consent scopes.

Min items: 1
Possible values: ME_TO_ME, EXTERNAL
constraints
requiredobject
Limitations that will be applied to payments initiated using the payment consent.
valid_date_time
object
Life span for the payment consent. After the to date the payment consent expires and can no longer be used for payment initiation.
from
string
The date and time from which the consent should be active, in ISO 8601 format.

Format: date-time
to
string
The date and time at which the consent expires, in ISO 8601 format.

Format: date-time
max_payment_amount
requiredobject
The amount and currency of a payment
currency
requiredstring
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used.

Possible values: GBP, EUR, PLN, SEK, DKK, NOK
Min length: 3
Max length: 3
value
requirednumber
The amount of the payment. Must contain at most two digits of precision e.g. 1.23. Minimum accepted value is 1.

Format: double
periodic_amounts
required[object]
A list of amount limitations per period of time.

Min items: 1
amount
requiredobject
The amount and currency of a payment
currency
requiredstring
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used.

Possible values: GBP, EUR, PLN, SEK, DKK, NOK
Min length: 3
Max length: 3
value
requirednumber
The amount of the payment. Must contain at most two digits of precision e.g. 1.23. Minimum accepted value is 1.

Format: double
interval
requiredstring
Payment consent periodic interval.

Possible values: DAY, WEEK, MONTH, YEAR
alignment
requiredstring
Where the payment consent period should start.
CALENDAR: line up with a calendar.
CONSENT: on the date of consent creation.


Possible values: CALENDAR, CONSENT
options
object
Additional payment consent options
request_refund_details
boolean
When true, Plaid will attempt to request refund details from the payee's financial institution. Support varies between financial institutions and will not always be available. If refund details could be retrieved, they will be available in the /payment_initiation/payment/get response.
iban
string
The International Bank Account Number (IBAN) for the payer's account. Where possible, the end user will be able to set up payment consent using only the specified bank account if provided.

Min length: 15
Max length: 34
bacs
object
An object containing a BACS account number and sort code. If an IBAN is not provided or if you need to accept domestic GBP-denominated payments, BACS data is required.
account
string
The account number of the account. Maximum of 10 characters.

Min length: 1
Max length: 10
sort_code
string
The 6-character sort code of the account.

Min length: 6
Max length: 6
Select Language
Copy
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}
payment_initiation/consent/create

Response fields and example

consent_id
string
A unique ID identifying the payment consent.
status
string
The status of the payment consent.
UNAUTHORISED: Consent created, but requires user authorisation.
REJECTED: Consent authorisation was rejected by the user and/or the bank.
AUTHORISED: Consent is active and ready to be used.
REVOKED: Consent has been revoked and can no longer be used.
EXPIRED: Consent is no longer valid.


Possible values: UNAUTHORISED, AUTHORISED, REVOKED, REJECTED, EXPIRED
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
Copy
1{
2 "consent_id": "consent-id-production-feca8a7a-5491-4444-9999-f3062bb735d3",
3 "status": "UNAUTHORISED",
4 "request_id": "4ciYmmesdqSiUAB"
5}
Was this helpful?

/payment_initiation/consent/get

Get payment consent

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.

payment_initiation/consent/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
consent_id
requiredstring
The consent_id returned from /payment_initiation/consent/create.
Select Language
Copy
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}
payment_initiation/consent/get

Response fields and example

consent_id
string
The consent ID.

Min length: 1
status
string
The status of the payment consent.
UNAUTHORISED: Consent created, but requires user authorisation.
REJECTED: Consent authorisation was rejected by the user and/or the bank.
AUTHORISED: Consent is active and ready to be used.
REVOKED: Consent has been revoked and can no longer be used.
EXPIRED: Consent is no longer valid.


Possible values: UNAUTHORISED, AUTHORISED, REVOKED, REJECTED, EXPIRED
created_at
string
Consent creation timestamp, in ISO 8601 format.

Format: date-time
recipient_id
string
The ID of the recipient the payment consent is for.

Min length: 1
reference
string
A reference for the payment consent.
constraints
object
Limitations that will be applied to payments initiated using the payment consent.
valid_date_time
nullableobject
Life span for the payment consent. After the to date the payment consent expires and can no longer be used for payment initiation.
from
nullablestring
The date and time from which the consent should be active, in ISO 8601 format.

Format: date-time
to
nullablestring
The date and time at which the consent expires, in ISO 8601 format.

Format: date-time
max_payment_amount
object
The amount and currency of a payment
currency
string
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used.

Possible values: GBP, EUR, PLN, SEK, DKK, NOK
Min length: 3
Max length: 3
value
number
The amount of the payment. Must contain at most two digits of precision e.g. 1.23. Minimum accepted value is 1.

Format: double
periodic_amounts
[object]
A list of amount limitations per period of time.

Min items: 1
amount
object
The amount and currency of a payment
currency
string
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used.

Possible values: GBP, EUR, PLN, SEK, DKK, NOK
Min length: 3
Max length: 3
value
number
The amount of the payment. Must contain at most two digits of precision e.g. 1.23. Minimum accepted value is 1.

Format: double
interval
string
Payment consent periodic interval.

Possible values: DAY, WEEK, MONTH, YEAR
alignment
string
Where the payment consent period should start.
CALENDAR: line up with a calendar.
CONSENT: on the date of consent creation.


Possible values: CALENDAR, CONSENT
scopes
[string]
An array of payment consent scopes.

Possible values: ME_TO_ME, EXTERNAL
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
Copy
1{
2 "request_id": "4ciYuuesdqSiUAB",
3 "consent_id": "consent-id-production-feca8a7a-5491-4aef-9298-f3062bb735d3",
4 "status": "AUTHORISED",
5 "created_at": "2021-10-30T15:26:48Z",
6 "recipient_id": "recipient-id-production-9b6b4679-914b-445b-9450-efbdb80296f6",
7 "reference": "ref-00001",
8 "constraints": {
9 "valid_date_time": {
10 "from": "2021-12-25T11:12:13Z",
11 "to": "2022-12-31T15:26:48Z"
12 },
13 "max_payment_amount": {
14 "currency": "GBP",
15 "value": 100
16 },
17 "periodic_amounts": [
18 {
19 "amount": {
20 "currency": "GBP",
21 "value": 300
22 },
23 "interval": "WEEK",
24 "alignment": "CALENDAR"
25 }
26 ]
27 },
28 "scopes": [
29 "ME_TO_ME"
30 ]
31}
Was this helpful?

/payment_initiation/consent/revoke

Revoke payment consent

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.

payment_initiation/consent/revoke

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
consent_id
requiredstring
The consent ID.
Select Language
Copy
1const request: PaymentInitiationConsentRevokeRequest = {
2 consent_id: consentID,
3};
4try {
5 const response = await plaidClient.paymentInitiationConsentRevoke(request);
6} catch (error) {
7 // handle error
8}
payment_initiation/consent/revoke

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
Copy
1{
2 "request_id": "4ciYaaesdqSiUAB"
3}
Was this helpful?

/payment_initiation/consent/payment/execute

Execute a single payment using consent

The /payment_initiation/consent/payment/execute endpoint can be used to execute payments using payment consent.

payment_initiation/consent/payment/execute

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
consent_id
requiredstring
The consent ID.
amount
requiredobject
The amount and currency of a payment
currency
requiredstring
The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used.

Possible values: GBP, EUR, PLN, SEK, DKK, NOK
Min length: 3
Max length: 3
value
requirednumber
The amount of the payment. Must contain at most two digits of precision e.g. 1.23. Minimum accepted value is 1.

Format: double
idempotency_key
requiredstring
A random key provided by the client, per unique consent payment. Maximum of 128 characters.
The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. If a request to execute a consent payment fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single payment is created. If the request was successfully processed, it will prevent any payment that uses the same idempotency key, and was received within 24 hours of the first request, from being processed.


Max length: 128
Min length: 1
Select Language
Copy
1const request: PaymentInitiationConsentPaymentExecuteRequest = {
2 consent_id: consentID,
3 amount: {
4 currency: PaymentAmountCurrency.Gbp,
5 value: 7.99,
6 },
7 idempotency_key: idempotencyKey,
8};
9try {
10 const response = await plaidClient.paymentInitiationConsentPaymentExecute(
11 request,
12 );
13 const paymentID = response.data.payment_id;
14 const status = response.data.status;
15} catch (error) {
16 // handle error
17}
payment_initiation/consent/payment/execute

Response fields and example

payment_id
string
A unique ID identifying the payment
status
string
The status of the payment.
PAYMENT_STATUS_INPUT_NEEDED: This is the initial state of all payments. It indicates that the payment is waiting on user input to continue processing. A payment may re-enter this state later on if further input is needed.
PAYMENT_STATUS_INITIATED: The payment has been successfully authorised and accepted by the financial institution but has not been executed.
PAYMENT_STATUS_INSUFFICIENT_FUNDS: The payment has failed due to insufficient funds.
PAYMENT_STATUS_FAILED: The payment has failed to be initiated. This error is retryable once the root cause is resolved.
PAYMENT_STATUS_BLOCKED: The payment has been blocked. This is a retryable error.
PAYMENT_STATUS_AUTHORISING: The payment is currently being processed. The payment will automatically exit this state when the financial institution has authorised the transaction.
PAYMENT_STATUS_CANCELLED: The payment was cancelled during authorisation.
PAYMENT_STATUS_EXECUTED: The payment has been successfully executed and is considered complete.
PAYMENT_STATUS_SETTLED: The payment has settled and funds are available for use. Payment settlement can only be guaranteed by using Plaid virtual accounts. A payment will typically settle within seconds to several days, depending on which payment rail is used.
PAYMENT_STATUS_ESTABLISHED: Indicates that the standing order has been successfully established. This state is only used for standing orders.
PAYMENT_STATUS_REJECTED: The payment was rejected by the financial institution.
Deprecated: These statuses will be removed in a future release.
PAYMENT_STATUS_UNKNOWN: The payment status is unknown.
PAYMENT_STATUS_PROCESSING: The payment is currently being processed. The payment will automatically exit this state when processing is complete.
PAYMENT_STATUS_COMPLETED: Indicates that the standing order has been successfully established. This state is only used for standing orders.


Possible values: PAYMENT_STATUS_INPUT_NEEDED, PAYMENT_STATUS_PROCESSING, PAYMENT_STATUS_INITIATED, PAYMENT_STATUS_COMPLETED, PAYMENT_STATUS_INSUFFICIENT_FUNDS, PAYMENT_STATUS_FAILED, PAYMENT_STATUS_BLOCKED, PAYMENT_STATUS_UNKNOWN, PAYMENT_STATUS_EXECUTED, PAYMENT_STATUS_SETTLED, PAYMENT_STATUS_AUTHORISING, PAYMENT_STATUS_CANCELLED, PAYMENT_STATUS_ESTABLISHED, PAYMENT_STATUS_REJECTED
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
Copy
1{
2 "payment_id": "payment-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3",
3 "request_id": "4ciYccesdqSiUAB",
4 "status": "PAYMENT_STATUS_INITIATED"
5}
Was this helpful?

Webhooks

Updates are sent to indicate that the status of an initiated payment has changed. All Payment Initiation webhooks have a webhook_type of PAYMENT_INITIATION.

PAYMENT_STATUS_UPDATE

Fired when the status of a payment has changed.

webhook_type
string
PAYMENT_INITIATION
webhook_code
string
PAYMENT_STATUS_UPDATE
payment_id
string
The payment_id for the payment being updated
transaction_id
string
The transaction ID that this payment is associated with, if any. This is present only when a payment was initiated using virtual accounts.
new_payment_status
string
The status of the payment.
PAYMENT_STATUS_INPUT_NEEDED: This is the initial state of all payments. It indicates that the payment is waiting on user input to continue processing. A payment may re-enter this state later on if further input is needed.
PAYMENT_STATUS_INITIATED: The payment has been successfully authorised and accepted by the financial institution but has not been executed.
PAYMENT_STATUS_INSUFFICIENT_FUNDS: The payment has failed due to insufficient funds.
PAYMENT_STATUS_FAILED: The payment has failed to be initiated. This error is retryable once the root cause is resolved.
PAYMENT_STATUS_BLOCKED: The payment has been blocked. This is a retryable error.
PAYMENT_STATUS_AUTHORISING: The payment is currently being processed. The payment will automatically exit this state when the financial institution has authorised the transaction.
PAYMENT_STATUS_CANCELLED: The payment was cancelled during authorisation.
PAYMENT_STATUS_EXECUTED: The payment has been successfully executed and is considered complete.
PAYMENT_STATUS_SETTLED: The payment has settled and funds are available for use. Payment settlement can only be guaranteed by using Plaid virtual accounts. A payment will typically settle within seconds to several days, depending on which payment rail is used.
PAYMENT_STATUS_ESTABLISHED: Indicates that the standing order has been successfully established. This state is only used for standing orders.
PAYMENT_STATUS_REJECTED: The payment was rejected by the financial institution.
Deprecated: These statuses will be removed in a future release.
PAYMENT_STATUS_UNKNOWN: The payment status is unknown.
PAYMENT_STATUS_PROCESSING: The payment is currently being processed. The payment will automatically exit this state when processing is complete.
PAYMENT_STATUS_COMPLETED: Indicates that the standing order has been successfully established. This state is only used for standing orders.


Possible values: PAYMENT_STATUS_INPUT_NEEDED, PAYMENT_STATUS_PROCESSING, PAYMENT_STATUS_INITIATED, PAYMENT_STATUS_COMPLETED, PAYMENT_STATUS_INSUFFICIENT_FUNDS, PAYMENT_STATUS_FAILED, PAYMENT_STATUS_BLOCKED, PAYMENT_STATUS_UNKNOWN, PAYMENT_STATUS_EXECUTED, PAYMENT_STATUS_SETTLED, PAYMENT_STATUS_AUTHORISING, PAYMENT_STATUS_CANCELLED, PAYMENT_STATUS_ESTABLISHED, PAYMENT_STATUS_REJECTED
old_payment_status
string
The status of the payment.
PAYMENT_STATUS_INPUT_NEEDED: This is the initial state of all payments. It indicates that the payment is waiting on user input to continue processing. A payment may re-enter this state later on if further input is needed.
PAYMENT_STATUS_INITIATED: The payment has been successfully authorised and accepted by the financial institution but has not been executed.
PAYMENT_STATUS_INSUFFICIENT_FUNDS: The payment has failed due to insufficient funds.
PAYMENT_STATUS_FAILED: The payment has failed to be initiated. This error is retryable once the root cause is resolved.
PAYMENT_STATUS_BLOCKED: The payment has been blocked. This is a retryable error.
PAYMENT_STATUS_AUTHORISING: The payment is currently being processed. The payment will automatically exit this state when the financial institution has authorised the transaction.
PAYMENT_STATUS_CANCELLED: The payment was cancelled during authorisation.
PAYMENT_STATUS_EXECUTED: The payment has been successfully executed and is considered complete.
PAYMENT_STATUS_SETTLED: The payment has settled and funds are available for use. Payment settlement can only be guaranteed by using Plaid virtual accounts. A payment will typically settle within seconds to several days, depending on which payment rail is used.
PAYMENT_STATUS_ESTABLISHED: Indicates that the standing order has been successfully established. This state is only used for standing orders.
PAYMENT_STATUS_REJECTED: The payment was rejected by the financial institution.
Deprecated: These statuses will be removed in a future release.
PAYMENT_STATUS_UNKNOWN: The payment status is unknown.
PAYMENT_STATUS_PROCESSING: The payment is currently being processed. The payment will automatically exit this state when processing is complete.
PAYMENT_STATUS_COMPLETED: Indicates that the standing order has been successfully established. This state is only used for standing orders.


Possible values: PAYMENT_STATUS_INPUT_NEEDED, PAYMENT_STATUS_PROCESSING, PAYMENT_STATUS_INITIATED, PAYMENT_STATUS_COMPLETED, PAYMENT_STATUS_INSUFFICIENT_FUNDS, PAYMENT_STATUS_FAILED, PAYMENT_STATUS_BLOCKED, PAYMENT_STATUS_UNKNOWN, PAYMENT_STATUS_EXECUTED, PAYMENT_STATUS_SETTLED, PAYMENT_STATUS_AUTHORISING, PAYMENT_STATUS_CANCELLED, PAYMENT_STATUS_ESTABLISHED, PAYMENT_STATUS_REJECTED
original_reference
string
The original value of the reference when creating the payment.
adjusted_reference
string
The value of the reference sent to the bank after adjustment to pass bank validation rules.
original_start_date
string
The original value of the start_date provided during the creation of a standing order. If the payment is not a standing order, this field will be null.

Format: date
adjusted_start_date
string
The start date sent to the bank after adjusting for holidays or weekends. Will be provided in ISO 8601 format (YYYY-MM-DD). If the start date did not require adjustment, or if the payment is not a standing order, this field will be null.

Format: date
timestamp
string
The timestamp of the update, in ISO 8601 format, e.g. "2017-09-14T14:42:19.350Z"

Format: date-time
error
object
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
string
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
number
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
string
Suggested steps for resolving the error
environment
string
The Plaid environment the webhook was sent from

Possible values: development, sandbox, production
Copy
1{
2 "webhook_type": "PAYMENT_INITIATION",
3 "webhook_code": "PAYMENT_STATUS_UPDATE",
4 "payment_id": "payment-id-production-2ba30780-d549-4335-b1fe-c2a938aa39d2",
5 "new_payment_status": "PAYMENT_STATUS_INITIATED",
6 "old_payment_status": "PAYMENT_STATUS_PROCESSING",
7 "original_reference": "Account Funding 99744",
8 "adjusted_reference": "Account Funding 99",
9 "original_start_date": "2017-09-14",
10 "adjusted_start_date": "2017-09-15",
11 "timestamp": "2017-09-14T14:42:19.350Z",
12 "environment": "production"
13}
Was this helpful?
Developer community
GitHub
GitHub
Stack Overflow
Stack Overflow
YouTube
YouTube
Twitter
Twitter
Discord
Discord