Simulate a payment event in Sandbox

POST /sandbox/payment/simulate

Use the /sandbox/payment/simulate endpoint to simulate various payment events in the Sandbox environment. This endpoint will trigger the corresponding payment status webhook.

Request Body

Required

SandboxPaymentSimulateRequest defines the request schema for /sandbox/payment/simulate

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 ID of the payment to simulate
webhook
required, string
The webhook url to use for any payment events triggered by the simulated status change.
status
required, string
The status to set the payment to. Valid statuses include:
  • PAYMENT_STATUS_INITIATED
  • PAYMENT_STATUS_INSUFFICIENT_FUNDS
  • PAYMENT_STATUS_FAILED
  • PAYMENT_STATUS_EXECUTED
  • PAYMENT_STATUS_SETTLED
  • PAYMENT_STATUS_CANCELLED
  • PAYMENT_STATUS_REJECTED

Response

SandboxPaymentSimulateResponse defines the response schema for /sandbox/payment/simulate

Response Properties

request_id
required, string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
old_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.
new_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.