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).

{
  "webhook_type": "PAYMENT_INITIATION",
  "webhook_code": "PAYMENT_STATUS_UPDATE",
  "payment_id": "payment-id-production-2ba30780-d549-4335-b1fe-c2a938aa39d2",
  "new_payment_status": "PAYMENT_STATUS_AUTHORISING",
  "old_payment_status": "PAYMENT_STATUS_INPUT_NEEDED",
  "original_reference": "Account Funding 99744",
  "adjusted_reference": "Account Funding 99",
  "original_start_date": "2017-09-14",
  "adjusted_start_date": "2017-09-15",
  "timestamp": "2017-09-14T14:42:19.350Z",
  "environment": "production"
}

While you could 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 treat PAYMENT_STATUS_INITIATED as your primary success signal and trigger downstream workflows at that point. PAYMENT_STATUS_EXECUTED, if and when it arrives, is a supplementary confirmation. 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.

PAYMENT_STATUS_INITIATED is the terminal success status for most EU banks and a significant number of UK banks. PAYMENT_STATUS_EXECUTED is reached for many other UK banks, but is not universally supported—it may arrive hours after INITIATED or not arrive at all. Do not block downstream workflows waiting for EXECUTED.

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

• PAYMENT_STATUS_INITIATED: Real-time confirmation that the payment has been authorised and accepted into the payment flow. For most EU banks and many UK banks, this is the terminal success status. Treat it as a high-confidence signal that the payment will complete and use it to trigger downstream workflows.

• PAYMENT_STATUS_EXECUTED: Indicates that funds have left the payer's account. It is a useful additional confirmation when received, but is not guaranteed across all banks, is not always delivered promptly, and does not confirm that funds have arrived at the destination. Plaid has no visibility into fund movement on the payment rails after this point.

• PAYMENT_STATUS_SETTLED: Only available via the Virtual Accounts product. Sent once funds are confirmed as received at the destination account. This is the only Plaid status that provides direct receipt confirmation. For integrations that require end-to-end receipt confirmation, Virtual Accounts is the solution. For standard PIS customers without Virtual Accounts, confirming receipt requires checking the destination account directly.

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.

INPUT_NEEDED 
    |
    +--> AUTHORISING 
    |        |
    |        +--> INITIATED [terminal state for most EU banks and many UK banks]
    |        |        |
    |        |        +--> EXECUTED [supplementary; not guaranteed across all banks]
    |        |        |
    |        |        +--> BLOCKED 
    |        |        +--> REJECTED
    |        |        +--> CANCELLED
    |        |        +--> INSUFFICIENT_FUNDS
    |        |        +--> FAILED
    |        |
    |        +--> BLOCKED
    |
    +--> BLOCKED