--- title: "Simulate a payment event in Sandbox" method: POST path: "/sandbox/payment/simulate" tags: ["plaid"] --- # 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 - SandboxPaymentSimulateRequest — SandboxPaymentSimulateRequest defines the request schema for `/sandbox/payment/simulate` - `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` string, required — The ID of the payment to simulate - `webhook` string, required — The webhook url to use for any payment events triggered by the simulated status change. - `status` string, required — 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 `200` OK - SandboxPaymentSimulateResponse — SandboxPaymentSimulateResponse defines the response schema for `/sandbox/payment/simulate` - `request_id` string, required — A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. - `old_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](https://plaid.com/docs/payment-initiation/payment-status/). **`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](https://plaid.com/docs/payment-initiation/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` '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](https://plaid.com/docs/payment-initiation/payment-status/). **`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](https://plaid.com/docs/payment-initiation/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. ## Other responses - `default` — Error response. --- [API](https://skmtc.net/plaid/apis/the-plaid-api.md) · [All operations](https://skmtc.net/plaid/apis/the-plaid-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/plaid/the-plaid-api/versions/64c4514ea59b/schema)