Plaid logo
Docs
ALL DOCS

API

  • Overview
  • Libraries
  • API versioning
  • Postman Collection
  • Webhooks
Payments and Funding
  • Auth
  • Balance
  • Identity
  • Signal
  • Transfer
  • Investments Move
  • Payment Initiation
  • Virtual Accounts
Financial Insights
  • Transactions
  • Investments
  • Liabilities
  • Enrich
KYC/AML and anti-fraud
  • Look up Dashboard users
  • Identity Verification
  • Monitor
  • Beacon (beta)
Instant Onboarding
  • Layer
Credit and Underwriting
  • Consumer Report (by Plaid Check)
  • Assets
  • Statements
  • Income
Fundamentals
  • Items
  • Accounts
  • Institutions
  • Sandbox
  • Link
  • Users
  • Consent
  • Network
  • OAuth
Partnerships
  • Processor tokens
  • Processor partners
  • Reseller partners
Plaid logo
Docs
Close search modal
Ask Bill!
Ask Bill!
Hi! I'm Bill! You can ask me all about the Plaid API. Try asking questions like:
    Note: Bill isn't perfect. He's just a robot platypus that reads our docs for fun. You should treat his answers with the same healthy skepticism you might treat any other answer on the internet. This chat may be logged for quality and training purposes. Please don't send Bill any PII -- he's scared of intimacy. All chats with Bill are subject to Plaid's Privacy Policy.
    Plaid.com
    Log in
    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.

    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 /link/token/create for more information on how to obtain a payments link_token.

    See also
    /sandbox/payment/simulateSimulate a payment in Sandbox
    /wallet/createCreate a virtual account
    /wallet/getFetch a virtual account
    /wallet/listList all virtual accounts
    /wallet/transaction/executeExecute a transaction
    /wallet/transaction/getFetch a transaction
    /wallet/transaction/listList all transactions
    WALLET_TRANSACTION_STATUS_UPDATEThe status of a transaction has changed
    Webhooks
    PAYMENT_STATUS_UPDATEThe status of a payment has changed
    CONSENT_STATUS_UPDATEThe status of a consent 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

    client_id
    stringstring
    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
    stringstring
    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
    requiredstringrequired, string
    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
    stringstring
    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
    objectobject
    An object containing a BACS account number and sort code. If an IBAN is not provided or if this recipient needs to accept domestic GBP-denominated payments, BACS data is required.
    account
    stringstring
    The account number of the account. Maximum of 10 characters.

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

    Min length: 6
    Max length: 6
    address
    objectobject
    The optional address of the payment recipient's bank account. Required by most institutions outside of the UK.
    street
    required[string]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
    requiredstringrequired, string
    The city where the recipient is located. Maximum of 35 characters.

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

    Min length: 1
    Max length: 16
    country
    requiredstringrequired, string
    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
    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
    stringstring
    A unique ID identifying the recipient
    request_id
    stringstring
    A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
    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

    client_id
    stringstring
    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
    stringstring
    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
    requiredstringrequired, string
    The ID of the recipient
    Select group for content switcher
    Select Language
    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
    stringstring
    The ID of the recipient.
    name
    stringstring
    The name of the recipient.
    address
    nullableobjectnullable, object
    The optional address of the payment recipient's bank account. Required by most institutions outside of the UK.
    street
    [string][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
    stringstring
    The city where the recipient is located. Maximum of 35 characters.

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

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

    Min length: 2
    Max length: 2
    iban
    nullablestringnullable, string
    The International Bank Account Number (IBAN) for the recipient.
    bacs
    nullableobjectnullable, object
    An object containing a BACS account number and sort code. If an IBAN is not provided or if this recipient needs to accept domestic GBP-denominated payments, BACS data is required.
    account
    stringstring
    The account number of the account. Maximum of 10 characters.

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

    Min length: 6
    Max length: 6
    request_id
    stringstring
    A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
    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

    client_id
    stringstring
    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
    stringstring
    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
    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][object]
    An array of payment recipients created for Payment Initiation
    recipient_id
    stringstring
    The ID of the recipient.
    name
    stringstring
    The name of the recipient.
    address
    nullableobjectnullable, object
    The optional address of the payment recipient's bank account. Required by most institutions outside of the UK.
    street
    [string][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
    stringstring
    The city where the recipient is located. Maximum of 35 characters.

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

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

    Min length: 2
    Max length: 2
    iban
    nullablestringnullable, string
    The International Bank Account Number (IBAN) for the recipient.
    bacs
    nullableobjectnullable, object
    An object containing a BACS account number and sort code. If an IBAN is not provided or if this recipient needs to accept domestic GBP-denominated payments, BACS data is required.
    account
    stringstring
    The account number of the account. Maximum of 10 characters.

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

    Min length: 6
    Max length: 6
    request_id
    stringstring
    A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
    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 Limited Production, payments must be below 5 GBP or other chosen currency, and standing orders, variable recurring payments, and Virtual Accounts are not supported.

    payment_initiation/payment/create

    Request fields

    client_id
    stringstring
    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
    stringstring
    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
    requiredstringrequired, string
    The ID of the recipient the payment is for.
    reference
    requiredstringrequired, string
    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. Some institutions may limit the reference to less than 18 characters. If necessary, Plaid will adjust the reference by truncating it to fit the institution's requirements. 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
    requiredobjectrequired, object
    The amount and currency of a payment
    currency
    requiredstringrequired, string
    The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported.

    Possible values: GBP, EUR, PLN, SEK, DKK, NOK
    Min length: 3
    Max length: 3
    value
    requirednumberrequired, 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
    schedule
    objectobject
    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
    requiredstringrequired, string
    The frequency interval of the payment.

    Possible values: WEEKLY, MONTHLY
    Min length: 1
    interval_execution_day
    requiredintegerrequired, 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
    requiredstringrequired, 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
    stringstring
    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
    stringstring
    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
    objectobject
    Additional payment options
    request_refund_details
    booleanboolean
    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
    stringstring
    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
    objectobject
    An optional object used to restrict the accounts used for payments. If provided, the end user will be able to send payments only from the specified bank account.
    account
    stringstring
    The account number of the account. Maximum of 10 characters.

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

    Min length: 6
    Max length: 6
    scheme
    stringstring
    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.
    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
    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
    stringstring
    A unique ID identifying the payment
    status
    stringstring
    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
    stringstring
    A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
    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

    client_id
    stringstring
    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
    stringstring
    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
    requiredstringrequired, string
    The payment_id returned from /payment_initiation/payment/create.
    Select group for content switcher
    Select Language
    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
    stringstring
    The ID of the payment. Like all Plaid identifiers, the payment_id is case sensitive.
    amount
    objectobject
    The amount and currency of a payment
    currency
    stringstring
    The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported.

    Possible values: GBP, EUR, PLN, SEK, DKK, NOK
    Min length: 3
    Max length: 3
    value
    numbernumber
    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
    stringstring
    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. For successful payments, this is a potential terminal status. Further status transitions can be to REJECTED and, when supported by the institution, to 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 may be caused by transient system outages and is retryable once the root cause is resolved.
    PAYMENT_STATUS_BLOCKED: The payment has been blocked by Plaid. This can occur, for example, due to Plaid flagging the payment as potentially risky. 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 (typically by the end user) during authorisation.
    PAYMENT_STATUS_EXECUTED: The funds have successfully left the payer account and payment is considered complete. Not all institutions support this status: support is more common in the UK, and less common in the EU. For institutions where this status is not supported, the terminal status for a successful payment will be PAYMENT_STATUS_INITIATED.
    PAYMENT_STATUS_SETTLED: The payment has settled and funds are available for use. A payment will typically settle within seconds to several days, depending on which payment rail is used. This status is only available to customers using Plaid Virtual Accounts.
    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
    stringstring
    The ID of the recipient
    reference
    stringstring
    A reference for the payment.
    adjusted_reference
    nullablestringnullable, string
    The value of the reference sent to the bank after adjustment to pass bank validation rules.
    last_status_update
    stringstring
    The date and time of the last time the status was updated, in IS0 8601 format

    Format: date-time
    schedule
    nullableobjectnullable, 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
    stringstring
    The frequency interval of the payment.

    Possible values: WEEKLY, MONTHLY
    Min length: 1
    interval_execution_day
    integerinteger
    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
    stringstring
    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
    nullablestringnullable, 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
    nullablestringnullable, 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
    refund_details
    nullableobjectnullable, object
    Details about external payment refund
    name
    stringstring
    The name of the account holder.
    iban
    nullablestringnullable, string
    The International Bank Account Number (IBAN) for the account.
    bacs
    nullableobjectnullable, object
    An object containing a BACS account number and sort code. If an IBAN is not provided or if this recipient needs to accept domestic GBP-denominated payments, BACS data is required.
    account
    stringstring
    The account number of the account. Maximum of 10 characters.

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

    Min length: 6
    Max length: 6
    bacs
    nullableobjectnullable, object
    An object containing a BACS account number and sort code. If an IBAN is not provided or if this recipient needs to accept domestic GBP-denominated payments, BACS data is required.
    account
    stringstring
    The account number of the account. Maximum of 10 characters.

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

    Min length: 6
    Max length: 6
    iban
    nullablestringnullable, string
    The International Bank Account Number (IBAN) for the sender, if specified in the /payment_initiation/payment/create call.
    refund_ids
    nullable[string]nullable, [string]
    Refund IDs associated with the payment.
    amount_refunded
    nullableobjectnullable, object
    The amount and currency of a payment
    currency
    stringstring
    The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported.

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

    Format: double
    Minimum: 0.01
    wallet_id
    nullablestringnullable, string
    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
    nullablestringnullable, 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.
    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
    nullablestringnullable, 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.
    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
    nullablestringnullable, string
    The payment consent ID that this payment was initiated with. Is present only when payment was initiated using the payment consent.
    transaction_id
    nullablestringnullable, string
    The transaction ID that this payment is associated with, if any. This is present only when a payment was initiated using virtual accounts.
    end_to_end_id
    nullablestringnullable, string
    A unique identifier assigned by Plaid to each payment for tracking and reconciliation purposes.
    Note: Not all banks handle end_to_end_id consistently. To ensure accurate matching, clients should convert both the incoming end_to_end_id and the one provided by Plaid to the same case (either lower or upper) before comparison. For virtual account payments, Plaid manages this field automatically.
    request_id
    stringstring
    A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
    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 "recipient_id": "recipient-id-sandbox-9b6b4679-914b-445b-9450-efbdb80296f6",
    12 "bacs": {
    13 "account": "31926819",
    14 "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
    15 "sort_code": "601613"
    16 },
    17 "iban": null,
    18 "request_id": "aEAQmewMzlVa1k6"
    19}
    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

    client_id
    stringstring
    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
    stringstring
    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
    integerinteger
    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
    stringstring
    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
    stringstring
    The consent ID. If specified, only payments, executed using this consent, will be returned.
    Select group for content switcher
    Select Language
    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][object]
    An array of payments that have been created, associated with the given client_id.
    payment_id
    stringstring
    The ID of the payment. Like all Plaid identifiers, the payment_id is case sensitive.
    amount
    objectobject
    The amount and currency of a payment
    currency
    stringstring
    The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported.

    Possible values: GBP, EUR, PLN, SEK, DKK, NOK
    Min length: 3
    Max length: 3
    value
    numbernumber
    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
    stringstring
    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. For successful payments, this is a potential terminal status. Further status transitions can be to REJECTED and, when supported by the institution, to 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 may be caused by transient system outages and is retryable once the root cause is resolved.
    PAYMENT_STATUS_BLOCKED: The payment has been blocked by Plaid. This can occur, for example, due to Plaid flagging the payment as potentially risky. 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 (typically by the end user) during authorisation.
    PAYMENT_STATUS_EXECUTED: The funds have successfully left the payer account and payment is considered complete. Not all institutions support this status: support is more common in the UK, and less common in the EU. For institutions where this status is not supported, the terminal status for a successful payment will be PAYMENT_STATUS_INITIATED.
    PAYMENT_STATUS_SETTLED: The payment has settled and funds are available for use. A payment will typically settle within seconds to several days, depending on which payment rail is used. This status is only available to customers using Plaid Virtual Accounts.
    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
    stringstring
    The ID of the recipient
    reference
    stringstring
    A reference for the payment.
    adjusted_reference
    nullablestringnullable, string
    The value of the reference sent to the bank after adjustment to pass bank validation rules.
    last_status_update
    stringstring
    The date and time of the last time the status was updated, in IS0 8601 format

    Format: date-time
    schedule
    nullableobjectnullable, 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
    stringstring
    The frequency interval of the payment.

    Possible values: WEEKLY, MONTHLY
    Min length: 1
    interval_execution_day
    integerinteger
    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
    stringstring
    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
    nullablestringnullable, 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
    nullablestringnullable, 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
    refund_details
    nullableobjectnullable, object
    Details about external payment refund
    name
    stringstring
    The name of the account holder.
    iban
    nullablestringnullable, string
    The International Bank Account Number (IBAN) for the account.
    bacs
    nullableobjectnullable, object
    An object containing a BACS account number and sort code. If an IBAN is not provided or if this recipient needs to accept domestic GBP-denominated payments, BACS data is required.
    account
    stringstring
    The account number of the account. Maximum of 10 characters.

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

    Min length: 6
    Max length: 6
    bacs
    nullableobjectnullable, object
    An object containing a BACS account number and sort code. If an IBAN is not provided or if this recipient needs to accept domestic GBP-denominated payments, BACS data is required.
    account
    stringstring
    The account number of the account. Maximum of 10 characters.

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

    Min length: 6
    Max length: 6
    iban
    nullablestringnullable, string
    The International Bank Account Number (IBAN) for the sender, if specified in the /payment_initiation/payment/create call.
    refund_ids
    nullable[string]nullable, [string]
    Refund IDs associated with the payment.
    amount_refunded
    nullableobjectnullable, object
    The amount and currency of a payment
    currency
    stringstring
    The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported.

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

    Format: double
    Minimum: 0.01
    wallet_id
    nullablestringnullable, string
    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
    nullablestringnullable, 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.
    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
    nullablestringnullable, 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.
    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
    nullablestringnullable, string
    The payment consent ID that this payment was initiated with. Is present only when payment was initiated using the payment consent.
    transaction_id
    nullablestringnullable, string
    The transaction ID that this payment is associated with, if any. This is present only when a payment was initiated using virtual accounts.
    end_to_end_id
    nullablestringnullable, string
    A unique identifier assigned by Plaid to each payment for tracking and reconciliation purposes.
    Note: Not all banks handle end_to_end_id consistently. To ensure accurate matching, clients should convert both the incoming end_to_end_id and the one provided by Plaid to the same case (either lower or upper) before comparison. For virtual account payments, Plaid manages this field automatically.
    next_cursor
    nullablestringnullable, string
    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
    stringstring
    A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
    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.
    Providing counterparty information such as date of birth and address increases the likelihood of refund being successful without human intervention.

    payment_initiation/payment/reverse

    Request fields

    client_id
    stringstring
    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
    stringstring
    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
    requiredstringrequired, string
    The ID of the payment to reverse
    idempotency_key
    requiredstringrequired, string
    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
    requiredstringrequired, string
    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
    objectobject
    The amount and currency of a payment
    currency
    requiredstringrequired, string
    The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported.

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

    Format: double
    Minimum: 0.01
    counterparty_date_of_birth
    stringstring
    The counterparty's birthdate, in ISO 8601 (YYYY-MM-DD) format.

    Format: date
    counterparty_address
    objectobject
    The optional address of the payment recipient's bank account. Required by most institutions outside of the UK.
    street
    required[string]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
    requiredstringrequired, string
    The city where the recipient is located. Maximum of 35 characters.

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

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

    Min length: 2
    Max length: 2
    Select Language
    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
    stringstring
    A unique ID identifying the refund
    status
    stringstring
    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
    stringstring
    A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
    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

    client_id
    stringstring
    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
    stringstring
    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
    requiredstringrequired, string
    The ID of the recipient the payment consent is for. The created consent can be used to transfer funds to this recipient only.
    reference
    requiredstringrequired, string
    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
    deprecated[string]deprecated, [string]
    An array of payment consent scopes.

    Min items: 1
    Possible values: ME_TO_ME, EXTERNAL
    type
    stringstring
    Payment consent type. Defines possible use case for payments made with the given consent.
    SWEEPING: Allows moving money between accounts owned by the same user.
    COMMERCIAL: Allows initiating payments from the user's account to third parties.


    Possible values: SWEEPING, COMMERCIAL
    constraints
    requiredobjectrequired, object
    Limitations that will be applied to payments initiated using the payment consent.
    valid_date_time
    objectobject
    Life span for the payment consent. After the to date the payment consent expires and can no longer be used for payment initiation.
    from
    stringstring
    The date and time from which the consent should be active, in ISO 8601 format.

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

    Format: date-time
    max_payment_amount
    requiredobjectrequired, object
    Maximum amount of a single payment initiated using the payment consent.
    currency
    requiredstringrequired, string
    The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported.

    Possible values: GBP, EUR, PLN, SEK, DKK, NOK
    Min length: 3
    Max length: 3
    value
    requirednumberrequired, 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
    required[object]required, [object]
    A list of amount limitations per period of time.

    Min items: 1
    amount
    requiredobjectrequired, object
    Maximum cumulative amount for all payments in the specified interval.
    currency
    requiredstringrequired, string
    The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported.

    Possible values: GBP, EUR, PLN, SEK, DKK, NOK
    Min length: 3
    Max length: 3
    value
    requirednumberrequired, 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
    requiredstringrequired, string
    Payment consent periodic interval.

    Possible values: DAY, WEEK, MONTH, YEAR
    alignment
    requiredstringrequired, string
    Where the payment consent period should start.
    If the institution is Monzo, only CONSENT alignments are supported.
    CALENDAR: line up with a calendar.
    CONSENT: on the date of consent creation.


    Possible values: CALENDAR, CONSENT
    options
    deprecatedobjectdeprecated, object
    (Deprecated) Additional payment consent options. Please use payer_details to specify the account.
    request_refund_details
    booleanboolean
    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
    stringstring
    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
    objectobject
    An optional object used to restrict the accounts used for payments. If provided, the end user will be able to send payments only from the specified bank account.
    account
    stringstring
    The account number of the account. Maximum of 10 characters.

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

    Min length: 6
    Max length: 6
    payer_details
    objectobject
    An object representing the payment consent payer details. Payer name and account numbers are required to lock the account to which the consent can be created.
    name
    requiredstringrequired, string
    The name of the payer as it appears in their bank account

    Min length: 1
    numbers
    requiredobjectrequired, object
    The counterparty's bank account numbers. Exactly one of IBAN or BACS data is required.
    bacs
    objectobject
    An optional object used to restrict the accounts used for payments. If provided, the end user will be able to send payments only from the specified bank account.
    account
    stringstring
    The account number of the account. Maximum of 10 characters.

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

    Min length: 6
    Max length: 6
    iban
    stringstring
    International Bank Account Number (IBAN).

    Min length: 15
    Max length: 34
    address
    objectobject
    The optional address of the payment recipient's bank account. Required by most institutions outside of the UK.
    street
    required[string]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
    requiredstringrequired, string
    The city where the recipient is located. Maximum of 35 characters.

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

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

    Min length: 2
    Max length: 2
    date_of_birth
    stringstring
    The payer's birthdate, in ISO 8601 (YYYY-MM-DD) format.

    Format: date
    phone_numbers
    [string][string]
    The payer's phone numbers in E.164 format: +{countrycode}{number}
    emails
    [string][string]
    The payer's emails
    Select Language
    1const request: PaymentInitiationConsentCreateRequest = {
    2 recipient_id: recipientID,
    3 reference: 'TestPaymentConsent',
    4 type: PaymentInitiationConsentType.Commercial,
    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
    stringstring
    A unique ID identifying the payment consent.
    status
    stringstring
    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
    stringstring
    A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
    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

    client_id
    stringstring
    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
    stringstring
    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
    requiredstringrequired, string
    The consent_id returned from /payment_initiation/consent/create.
    Select Language
    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
    stringstring
    The consent ID.

    Min length: 1
    status
    stringstring
    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
    stringstring
    Consent creation timestamp, in ISO 8601 format.

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

    Min length: 1
    reference
    stringstring
    A reference for the payment consent.
    constraints
    objectobject
    Limitations that will be applied to payments initiated using the payment consent.
    valid_date_time
    nullableobjectnullable, 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
    nullablestringnullable, string
    The date and time from which the consent should be active, in ISO 8601 format.

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

    Format: date-time
    max_payment_amount
    objectobject
    Maximum amount of a single payment initiated using the payment consent.
    currency
    stringstring
    The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported.

    Possible values: GBP, EUR, PLN, SEK, DKK, NOK
    Min length: 3
    Max length: 3
    value
    numbernumber
    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][object]
    A list of amount limitations per period of time.

    Min items: 1
    amount
    objectobject
    Maximum cumulative amount for all payments in the specified interval.
    currency
    stringstring
    The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported.

    Possible values: GBP, EUR, PLN, SEK, DKK, NOK
    Min length: 3
    Max length: 3
    value
    numbernumber
    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
    stringstring
    Payment consent periodic interval.

    Possible values: DAY, WEEK, MONTH, YEAR
    alignment
    stringstring
    Where the payment consent period should start.
    If the institution is Monzo, only CONSENT alignments are supported.
    CALENDAR: line up with a calendar.
    CONSENT: on the date of consent creation.


    Possible values: CALENDAR, CONSENT
    scopes
    deprecated[string]deprecated, [string]
    Deprecated, use the 'type' field instead.

    Possible values: ME_TO_ME, EXTERNAL
    type
    stringstring
    Payment consent type. Defines possible use case for payments made with the given consent.
    SWEEPING: Allows moving money between accounts owned by the same user.
    COMMERCIAL: Allows initiating payments from the user's account to third parties.


    Possible values: SWEEPING, COMMERCIAL
    payer_details
    nullableobjectnullable, object
    Details about external payment refund
    name
    stringstring
    The name of the account holder.
    iban
    nullablestringnullable, string
    The International Bank Account Number (IBAN) for the account.
    bacs
    nullableobjectnullable, object
    An object containing a BACS account number and sort code. If an IBAN is not provided or if this recipient needs to accept domestic GBP-denominated payments, BACS data is required.
    account
    stringstring
    The account number of the account. Maximum of 10 characters.

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

    Min length: 6
    Max length: 6
    request_id
    stringstring
    A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
    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 "type": "SWEEPING"
    29}
    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

    client_id
    stringstring
    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
    stringstring
    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
    requiredstringrequired, string
    The consent ID.
    Select Language
    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
    stringstring
    A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
    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

    client_id
    stringstring
    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
    stringstring
    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
    requiredstringrequired, string
    The consent ID.
    amount
    requiredobjectrequired, object
    The amount and currency of a payment
    currency
    requiredstringrequired, string
    The ISO-4217 currency code of the payment. For standing orders and payment consents, "GBP" must be used. For Poland, Denmark, Sweden and Norway, only the local currency is currently supported.

    Possible values: GBP, EUR, PLN, SEK, DKK, NOK
    Min length: 3
    Max length: 3
    value
    requirednumberrequired, 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
    idempotency_key
    requiredstringrequired, string
    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 48 hours of the first request, from being processed.


    Max length: 128
    Min length: 1
    reference
    stringstring
    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). If not provided, Plaid will automatically fall back to the reference from consent. 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. Some institutions may limit the reference to less than 18 characters. If necessary, Plaid will adjust the reference by truncating it to fit the institution's requirements. 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
    scope
    deprecatedstringdeprecated, string
    Deprecated, payments will be executed within the type of the consent.
    A scope of the payment. Must be one of the scopes mentioned in the consent. Optional if the appropriate consent has only one scope defined, required otherwise.


    Possible values: ME_TO_ME, EXTERNAL
    processing_mode
    stringstring
    Decides the mode under which the payment processing should be performed, using IMMEDIATE as default.
    IMMEDIATE: Will immediately execute the payment, waiting for a response from the ASPSP before returning the result of the payment initiation. This is ideal for user-present flows.
    ASYNC: Will accept a payment execution request and schedule it for processing, immediately returning the new payment_id. Listen for webhooks or use the /payment_initiation/payment/get endpoint to obtain updates on the payment status. This is ideal for non user-present flows.


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

    Response fields and example

    payment_id
    stringstring
    A unique ID identifying the payment
    status
    stringstring
    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. For successful payments, this is a potential terminal status. Further status transitions can be to REJECTED and, when supported by the institution, to 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 may be caused by transient system outages and is retryable once the root cause is resolved.
    PAYMENT_STATUS_BLOCKED: The payment has been blocked by Plaid. This can occur, for example, due to Plaid flagging the payment as potentially risky. 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 (typically by the end user) during authorisation.
    PAYMENT_STATUS_EXECUTED: The funds have successfully left the payer account and payment is considered complete. Not all institutions support this status: support is more common in the UK, and less common in the EU. For institutions where this status is not supported, the terminal status for a successful payment will be PAYMENT_STATUS_INITIATED.
    PAYMENT_STATUS_SETTLED: The payment has settled and funds are available for use. A payment will typically settle within seconds to several days, depending on which payment rail is used. This status is only available to customers using Plaid Virtual Accounts.
    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
    stringstring
    A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
    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
    stringstring
    PAYMENT_INITIATION
    webhook_code
    stringstring
    PAYMENT_STATUS_UPDATE
    payment_id
    stringstring
    The payment_id for the payment being updated
    transaction_id
    stringstring
    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
    stringstring
    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. For successful payments, this is a potential terminal status. Further status transitions can be to REJECTED and, when supported by the institution, to 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 may be caused by transient system outages and is retryable once the root cause is resolved.
    PAYMENT_STATUS_BLOCKED: The payment has been blocked by Plaid. This can occur, for example, due to Plaid flagging the payment as potentially risky. 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 (typically by the end user) during authorisation.
    PAYMENT_STATUS_EXECUTED: The funds have successfully left the payer account and payment is considered complete. Not all institutions support this status: support is more common in the UK, and less common in the EU. For institutions where this status is not supported, the terminal status for a successful payment will be PAYMENT_STATUS_INITIATED.
    PAYMENT_STATUS_SETTLED: The payment has settled and funds are available for use. A payment will typically settle within seconds to several days, depending on which payment rail is used. This status is only available to customers using Plaid Virtual Accounts.
    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
    stringstring
    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. For successful payments, this is a potential terminal status. Further status transitions can be to REJECTED and, when supported by the institution, to 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 may be caused by transient system outages and is retryable once the root cause is resolved.
    PAYMENT_STATUS_BLOCKED: The payment has been blocked by Plaid. This can occur, for example, due to Plaid flagging the payment as potentially risky. 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 (typically by the end user) during authorisation.
    PAYMENT_STATUS_EXECUTED: The funds have successfully left the payer account and payment is considered complete. Not all institutions support this status: support is more common in the UK, and less common in the EU. For institutions where this status is not supported, the terminal status for a successful payment will be PAYMENT_STATUS_INITIATED.
    PAYMENT_STATUS_SETTLED: The payment has settled and funds are available for use. A payment will typically settle within seconds to several days, depending on which payment rail is used. This status is only available to customers using Plaid Virtual Accounts.
    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
    stringstring
    The original value of the reference when creating the payment.
    adjusted_reference
    stringstring
    The value of the reference sent to the bank after adjustment to pass bank validation rules.
    original_start_date
    stringstring
    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
    stringstring
    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
    stringstring
    The timestamp of the update, in ISO 8601 format, e.g. "2017-09-14T14:42:19.350Z"

    Format: date-time
    error
    objectobject
    Errors are identified by error_code and categorized by error_type. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. 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
    stringstring
    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, SANDBOX_ERROR, PARTNER_ERROR, TRANSACTIONS_ERROR, TRANSACTION_ERROR, TRANSFER_ERROR, CHECK_REPORT_ERROR, CONSUMER_REPORT_ERROR
    error_code
    stringstring
    The particular error code. Safe for programmatic use.
    error_code_reason
    stringstring
    The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; null will be returned otherwise. Safe for programmatic use.
    Possible values: OAUTH_INVALID_TOKEN: The user’s OAuth connection to this institution has been invalidated.
    OAUTH_CONSENT_EXPIRED: The user's access consent for this OAuth connection to this institution has expired.
    OAUTH_USER_REVOKED: The user’s OAuth connection to this institution is invalid because the user revoked their connection.
    error_message
    stringstring
    A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
    display_message
    stringstring
    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
    stringstring
    A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
    causes
    arrayarray
    In this 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 be provided for the error_type ASSET_REPORT_ERROR or CHECK_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
    status
    integerinteger
    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
    stringstring
    The URL of a Plaid documentation page with more information about the error
    suggested_action
    stringstring
    Suggested steps for resolving the error
    environment
    stringstring
    The Plaid environment the webhook was sent from

    Possible values: sandbox, production
    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?

    CONSENT_STATUS_UPDATE

    Fired when the status of a payment consent has changed.

    webhook_type
    stringstring
    PAYMENT_INITIATION
    webhook_code
    stringstring
    CONSENT_STATUS_UPDATE
    consent_id
    stringstring
    The id for the consent being updated
    old_status
    stringstring
    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
    new_status
    stringstring
    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
    timestamp
    stringstring
    The timestamp of the update, in ISO 8601 format, e.g. "2017-09-14T14:42:19.350Z"

    Format: date-time
    error
    objectobject
    Errors are identified by error_code and categorized by error_type. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. 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
    stringstring
    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, SANDBOX_ERROR, PARTNER_ERROR, TRANSACTIONS_ERROR, TRANSACTION_ERROR, TRANSFER_ERROR, CHECK_REPORT_ERROR, CONSUMER_REPORT_ERROR
    error_code
    stringstring
    The particular error code. Safe for programmatic use.
    error_code_reason
    stringstring
    The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; null will be returned otherwise. Safe for programmatic use.
    Possible values: OAUTH_INVALID_TOKEN: The user’s OAuth connection to this institution has been invalidated.
    OAUTH_CONSENT_EXPIRED: The user's access consent for this OAuth connection to this institution has expired.
    OAUTH_USER_REVOKED: The user’s OAuth connection to this institution is invalid because the user revoked their connection.
    error_message
    stringstring
    A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
    display_message
    stringstring
    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
    stringstring
    A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
    causes
    arrayarray
    In this 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 be provided for the error_type ASSET_REPORT_ERROR or CHECK_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
    status
    integerinteger
    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
    stringstring
    The URL of a Plaid documentation page with more information about the error
    suggested_action
    stringstring
    Suggested steps for resolving the error
    environment
    stringstring
    The Plaid environment the webhook was sent from

    Possible values: sandbox, production
    1{
    2 "webhook_type": "PAYMENT_INITIATION",
    3 "webhook_code": "CONSENT_STATUS_UPDATE",
    4 "consent_id": "payment-consent-id-production-e7258765-69f9-46b1-9c67-d2800448e5ff",
    5 "old_status": "UNAUTHORISED",
    6 "new_status": "AUTHORISED",
    7 "timestamp": "2017-09-14T14:42:19.350Z",
    8 "environment": "production"
    9}
    Was this helpful?
    Developer community
    GitHub
    GitHub
    Stack Overflow
    Stack Overflow
    YouTube
    YouTube
    Discord
    Discord