Execute a single payment using consent
POST /payment_initiation/consent/payment/execute
The /payment_initiation/consent/payment/execute endpoint can be used to execute payments using payment consent.
Request Body
Required
PaymentInitiationConsentPaymentExecuteRequest defines the request schema for /payment_initiation/consent/payment/execute
Parameters
client_id
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
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
The consent ID.
amount
The amount and currency of a payment
currency
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
The amount of the payment. Must contain at most two digits of precision e.g.
1.23. Minimum accepted value is 1.
idempotency_key
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.
reference
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.
scope
processing_mode
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 to obtain real-time updates on the payment status. This is ideal for non user-present flows.
Response
PaymentInitiationConsentPaymentExecuteResponse defines the response schema for /payment_initiation/consent/payment/execute
Response Properties
payment_id
A unique ID identifying the payment
status
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.
request_id
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
error
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
A broad categorization of the error. Safe for programmatic use.
error_code
The particular error code. Safe for programmatic use.
error_code_reason
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
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
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
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
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
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
The URL of a Plaid documentation page with more information about the error
suggested_action
Suggested steps for resolving the error