Get payment details

POST /payment_initiation/payment/get

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.

Polling for status updates in Production is highly discouraged. Repeatedly calling /payment_initiation/payment/get to check a payment's status is unreliable and may trigger API rate limits. Only the payment_status_update webhook should be used to receive real-time status updates in Production.

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.

Request Body

Required

PaymentInitiationPaymentGetRequest defines the request schema for /payment_initiation/payment/get

Parameters

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
payment_id
required, string
The payment_id returned from /payment_initiation/payment/create.

Response

PaymentInitiationPaymentGetResponse defines the response schema for /payment_initation/payment/get

Response Properties

payment_id
required, string
The ID of the payment. Like all Plaid identifiers, the payment_id is case sensitive.
amount
required, object
The amount and currency of a payment
currency
required, 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.
value
required, number
The amount of the payment. Must contain at most two digits of precision e.g. 1.23. Minimum accepted value is 1.
status
required, string
The status of the payment. Core lifecycle statuses: PAYMENT_STATUS_INPUT_NEEDED: Transitional. The payment is awaiting user input to continue processing. It may re-enter this state if additional input is required. PAYMENT_STATUS_AUTHORISING: Transitional. The payment is being authorised by the financial institution. It will automatically move on once authorisation completes. PAYMENT_STATUS_INITIATED: Transitional. The payment has been authorised and accepted by the financial institution and is now in transit. A payment should be considered complete once it reaches the PAYMENT_STATUS_EXECUTED state or the funds settle in the recipient account. PAYMENT_STATUS_EXECUTED: Terminal. The funds have left the payer’s account and the payment is en route to settlement. Support is more common in the UK than in the EU; where unsupported, a successful payment remains in PAYMENT_STATUS_INITIATED before settling. When using Plaid Virtual Accounts, PAYMENT_STATUS_EXECUTED is not terminal—the payment will continue to PAYMENT_STATUS_SETTLED once funds are available. PAYMENT_STATUS_SETTLED: Terminal. The funds are available in the recipient’s account. Only available to customers using Plaid Virtual Accounts. Failure statuses: PAYMENT_STATUS_INSUFFICIENT_FUNDS: Terminal. The payment failed due to insufficient funds. No further retries will succeed until the payer’s balance is replenished. PAYMENT_STATUS_FAILED: Terminal (retryable). The payment could not be initiated due to a system error or outage. Retry once the root cause is resolved. PAYMENT_STATUS_BLOCKED: Terminal (retryable). The payment was blocked by Plaid (e.g., flagged as risky). Resolve any compliance or risk issues and retry. PAYMENT_STATUS_REJECTED: Terminal. The payment was rejected by the financial institution. No automatic retry is possible. PAYMENT_STATUS_CANCELLED: Terminal. The end user cancelled the payment during authorisation. Standing-order statuses: PAYMENT_STATUS_ESTABLISHED: Terminal. A recurring/standing order has been successfully created. Deprecated (to be removed in a future release): PAYMENT_STATUS_UNKNOWN: The payment status is unknown. PAYMENT_STATUS_PROCESSING: The payment is currently being processed. PAYMENT_STATUS_COMPLETED: Indicates that the standing order has been successfully established.
recipient_id
required, string
The ID of the recipient
reference
required, string
A reference for the payment.
adjusted_reference
string
The value of the reference sent to the bank after adjustment to pass bank validation rules.
last_status_update
required, string
The date and time of the last time the status was updated, in IS0 8601 format
schedule
object
The schedule that the payment will be executed on. If a schedule is provided, the payment is automatically set up as a standing order. If no schedule is specified, the payment will be executed only once.
refund_details
object
Details about external payment refund
name
required, string
The name of the account holder.
iban
required, string
The International Bank Account Number (IBAN) for the account.
bacs
required, 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.
bacs
required, 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.
iban
required, string
The International Bank Account Number (IBAN) for the sender, if specified in the /payment_initiation/payment/create call.
refund_ids
array[string]
Refund IDs associated with the payment.
amount_refunded
object
The amount and currency of a payment
wallet_id
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
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.
adjusted_scheme
string
Payment scheme. If not specified - the default in the region will be used (e.g. SEPA_CREDIT_TRANSFER for EU). Using unsupported values will result in a failed payment. LOCAL_DEFAULT: The default payment scheme for the selected market and currency will be used. LOCAL_INSTANT: The instant payment scheme for the selected market and currency will be used (if applicable). Fees may be applied by the institution. 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.
consent_id
string
The payment consent ID that this payment was initiated with. Is present only when payment was initiated using the payment consent.
transaction_id
string
The transaction ID that this payment is associated with, if any. This is present only when a payment was initiated using virtual accounts.
end_to_end_id
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.
error
object
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
required, string
A broad categorization of the error. Safe for programmatic use.
error_code
required, string
The particular error code. Safe for programmatic use.
error_code_reason
string
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
required, string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
required, string
A user-friendly representation of the error code. null if the error is not related to user action. This may change over time and is not safe for programmatic use.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In 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
integer
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
string
Suggested steps for resolving the error
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.