Payment Status

Once the payment has been authorised by the end user and the Link flow is completed, the onSuccess callback is invoked, signaling that the payment status is now PAYMENT_STATUS_AUTHORISING.

From this point on, you can track the payment status using the PAYMENT_STATUS_UPDATE webhook, which Plaid sends to the configured webhook URL in real time to indicate that the status of an initiated payment has changed. (For more information on how to implement your webhook listener, see the webhook documentation).

While you can repeatedly call /payment_initiation/payment/get to check a payment's status instead of listening for webhooks, this approach may trigger API rate limit errors and is strongly discouraged. Only consider polling as a fallback when webhooks are unavailable or significantly delayed.

Once you receive the PAYMENT_STATUS_UPDATE webhook, use the payment_id field to retrieve the payment's metadata from your database.

From the status update object, use the new_payment_status field to decide what action needs to be taken for this payment. For example, you may decide to fund the account once the payment status is PAYMENT_STATUS_EXECUTED, or display a user-facing error if the status is PAYMENT_STATUS_REJECTED.

Note: In order to protect against webhook forgery attacks, before funding an account in response to a webhook, it's recommended to ensure the status is legitimate. One way is to implement webhook verification. An easier alternative is to verify the new status by calling /payment_initiation/payment/get a single time after receiving the webhook.

For many payments, including most payments in the UK, the terminal status (if not using Virtual Accounts) is PAYMENT_STATUS_EXECUTED, which indicates that funds have left the payer's account. PAYMENT_STATUS_INITIATED is the terminal state for payments at some non-UK banks, as well as smaller UK banks.

Funds typically settle (i.e., arrive in the payee's account) within a few seconds of the payment execution, although settlement of an executed payment is not guaranteed.

If using Virtual Accounts, the successful terminal status will always be PAYMENT_STATUS_SETTLED, regardless of bank.

The most common payment schemes and their settlement times are:

• Faster Payments Service (FPS): An instant payment scheme used in the UK. The money is usually available in the receiving customer's account almost immediately, although it can sometimes take up to two hours.
• SEPA Instant Credit Transfer: A pan-European instant payment scheme. Funds will be made available in less than ten seconds.
• SEPA Credit Transfer: A pan-European payment scheme where payments are processed and settled within one business day.

Below is the status transitions for Payment Initiation. If using Virtual Accounts, see Payment Confirmation, which adds the SETTLED status.

1INPUT_NEEDED 
2    |
3    +--> AUTHORISING 
4    |        |
5    |        +--> INITIATED [terminal state for successful payments at some banks]
6    |        |        |
7    |        |        +--> EXECUTED [For some banks only, mostly in UK]
8    |        |        |
9    |        |        +--> BLOCKED 
10    |        |        +--> REJECTED
11    |        |        +--> CANCELLED
12    |        |        +--> INSUFFICIENT_FUNDS
13    |        |        +--> FAILED
14    |        |
15    |        +--> BLOCKED
16    |
17    +--> BLOCKED