--- 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`:** 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](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`:** 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](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. ## Changes - **2025-12-11** `465584b48c99` — 2 info - added the optional property `provided_account_subtypes` to the response with the `default` status - added the optional property `required_account_subtypes` to the response with the `default` status - **2025-11-19** `4abee1c56929` — 1 info - removed the `IDENTITY_ERROR` enum value from the `error_type` response property for the response status `default` - **2025-11-12** `f8b9f1a85767` — 2 warning - added the new `IDENTITY_ERROR` enum value to the `error_type` response property for the response status `default` - added the new `USER_ERROR` enum value to the `error_type` response property for the response status `default` - **2025-10-22** `af4b6e71d87f` — 1 warning - added the new `SIGNAL_ERROR` enum value to the `error_type` response property for the response status `default` - **2025-05-01** `89dcf373f0a2` — 1 breaking - added the new required request property `webhook` [Full history](https://skmtc.dev/plaid/apis/the-plaid-api/changes/sandbox/payment/simulate/post.md) --- [API](https://skmtc.dev/plaid/apis/the-plaid-api.md) · [All operations](https://skmtc.dev/plaid/apis/the-plaid-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/plaid/the-plaid-api/revisions/cd6c86bfb523/schema)