Sign in
plaid

Execute a single payment using consent

The /payment_initiation/consent/payment/execute endpoint can be used to execute payments using payment consent.

post/payment_initiation/consent/payment/execute

Request body

client_idstring

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.

secretstring

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_idstring required

The consent ID.

idempotency_keystring required

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.

referencestring nullable

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'ME_TO_ME' | 'EXTERNAL' nullable

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.

processing_mode'ASYNC' | 'IMMEDIATE'

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

OK

payment_idstring required

A unique ID identifying the payment

status'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' required

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: The payment has been authorised and accepted by the financial institution. In many EU markets, PAYMENT_STATUS_EXECUTED is not supported, and a payment will remain in PAYMENT_STATUS_INITIATED until the funds settle, making this a terminal success state in those cases. A payment in PAYMENT_STATUS_INITIATED should be treated as a successfully submitted payment; do not gate downstream processing on reaching PAYMENT_STATUS_EXECUTED. For a full explanation of payment statuses and how to handle each, see the Payment Status guide.

PAYMENT_STATUS_EXECUTED: Terminal. The funds have left the payer's account and the payment is en route to settlement. Note that this status does not confirm that funds have arrived in the recipient's account; do not use it as proof of fund receipt. 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_idstring required

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

Changes

Changed in 12 of the 52 revisions of this API.3511

  • 94406d9a4d271See the full diff
    • ○

      request property scope/allOf[subschema #1: PaymentInitiationConsentScope]/ deprecated

      request-property-deprecated

  • a1bbca01816026See the full diff
    • ●

      added the new ASSETS_ERROR enum value to the error/error_type response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new ASSETS_ERROR enum value to the error_type response property for the response status default

      response-property-enum-value-added

    • ●

      added the new CRA_MONITORING_ERROR enum value to the error/error_type response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new CRA_MONITORING_ERROR enum value to the error_type response property for the response status default

      response-property-enum-value-added

    • ●

      added the new CREDIT_PROFILE_REPORT_ERROR enum value to the error/error_type response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new CREDIT_PROFILE_REPORT_ERROR enum value to the error_type response property for the response status default

      response-property-enum-value-added

    • ●

      added the new ENCOMPASS_ERROR enum value to the error/error_type response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new ENCOMPASS_ERROR enum value to the error_type response property for the response status default

      response-property-enum-value-added

    • ●

      added the new ENRICH_ERROR enum value to the error/error_type response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new ENRICH_ERROR enum value to the error_type response property for the response status default

      response-property-enum-value-added

    • ●

      added the new FRAUD_INSIGHTS_ERROR enum value to the error/error_type response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new FRAUD_INSIGHTS_ERROR enum value to the error_type response property for the response status default

      response-property-enum-value-added

    • ●

      added the new FREDDIE_MAC_ERROR enum value to the error/error_type response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new FREDDIE_MAC_ERROR enum value to the error_type response property for the response status default

      response-property-enum-value-added

    • ●

      added the new LINK_DELIVERY_ERROR enum value to the error/error_type response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new LINK_DELIVERY_ERROR enum value to the error_type response property for the response status default

      response-property-enum-value-added

    • ●

      added the new PROFILE_ERROR enum value to the error/error_type response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new PROFILE_ERROR enum value to the error_type response property for the response status default

      response-property-enum-value-added

    • ●

      added the new RECURRING_TRANSACTIONS_ERROR enum value to the error/error_type response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new RECURRING_TRANSACTIONS_ERROR enum value to the error_type response property for the response status default

      response-property-enum-value-added

    • ●

      added the new STATEMENTS_ERROR enum value to the error/error_type response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new STATEMENTS_ERROR enum value to the error_type response property for the response status default

      response-property-enum-value-added

    • ●

      added the new TRANSFER_RECURRING_ERROR enum value to the error/error_type response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new TRANSFER_RECURRING_ERROR enum value to the error_type response property for the response status default

      response-property-enum-value-added

    • ●

      added the new TRANSFER_REFUND_ERROR enum value to the error/error_type response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new TRANSFER_REFUND_ERROR enum value to the error_type response property for the response status default

      response-property-enum-value-added

    This revision also has 3 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 80d23bfdc2e52See the full diff
    • ●

      added the new IDEMPOTENCY_ERROR enum value to the error/error_type response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new IDEMPOTENCY_ERROR enum value to the error_type response property for the response status default

      response-property-enum-value-added

  • fb8c3f188d8b2See the full diff
    • ●

      added the new BASE_REPORT_ERROR enum value to the error/error_type response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new BASE_REPORT_ERROR enum value to the error_type response property for the response status default

      response-property-enum-value-added

    This revision also has 8 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 465584b48c994See the full diff
    • ○

      added the optional property error/provided_account_subtypes to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property error/required_account_subtypes to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property provided_account_subtypes to the response with the default status

      response-optional-property-added

    • ○

      added the optional property required_account_subtypes to the response with the default status

      response-optional-property-added

    This revision also has 4 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 4abee1c569292See the full diff
    • ○

      removed the IDENTITY_ERROR enum value from the error/error_type response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the IDENTITY_ERROR enum value from the error_type response property for the response status default

      response-property-enum-value-removed

  • f8b9f1a857672See the full diff
    • ●

      added the new IDENTITY_ERROR enum value to the error/error_type response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new USER_ERROR enum value to the error/error_type response property for the response status 200

      response-property-enum-value-added

    This revision also has 4 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • af4b6e71d87f1See the full diff
    • ●

      added the new SIGNAL_ERROR enum value to the error/error_type response property for the response status 200

      response-property-enum-value-added

  • b0b8ac37e34d1See the full diff
    • ○

      added the optional property error to the response with the 200 status

      response-optional-property-added

    This revision also has 4 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • b0263533029b1See the full diff
    • ○

      request property scope deprecated

      request-property-deprecated