---
updatedAt: 2026-06-05T20:13:09.000Z
agentTools:
  projectIndex: https://docs.moderntreasury.com/payments/llms.txt
---

# Simulate a Payment Action

## Overview

The Sandbox lets you test [Payment Action](https://docs.moderntreasury.com/payments/docs/create-a-payment-action) workflows for **Stop Payment** actions on check payments. This works with both **Bring Your Own Bank** and **PSP** accounts.

When you create a Stop Payment Action in the Sandbox, the system simulates different outcomes based on the counterparty name on the original payment order. This lets you test success and failure scenarios without interacting with a real bank.

For **Bring Your Own Bank** accounts, if the Payment Action is not linked to a Payment Order, set `details.payee_name` directly on the Payment Action with the same test values to control the simulation outcome.

## Scenarios

### Simulate a Successful Payment Action

Create a check payment order to any counterparty whose name **does not** contain one of the special test strings described below, then create a Stop Payment Action on that payment order.

**Result:**

* The Payment Action transitions to `acknowledged`.
* The Payment Order transitions to `stopped`.

This simulates the bank successfully processing the stop request.

### Simulate a Failed Payment Action

Create a check payment order to a counterparty whose name contains **`payment_action_failed`** (e.g., `"Test payment_action_failed Co."`), then create a Stop Payment Action on that payment order.

**Result:**

* The Payment Action transitions to `failed`.
* The Payment Order is **not affected**.

This simulates the bank rejecting the stop request.

### Simulate a Payment Action Stuck in Sent

Create a check payment order to a counterparty whose name contains **`payment_action_sent`** (e.g., `"Test payment_action_sent Co."`), then create a Stop Payment Action on that payment order.

**Result:**

* The Payment Action remains in `sent` status and does not progress.
* The Payment Order is **not affected**.

This simulates the stop request being sent to the bank with no response received.

## Steps

### 1. Create a Counterparty

Create a counterparty with the appropriate name for the scenario you want to test. Include the relevant test string for failure or sent simulations; for the default success scenario, any name works.

Because stop payment actions target check payments, the counterparty's external account must include a `party_address`. In the Sandbox, use a [recognized test address](https://docs.moderntreasury.com/payments/docs/test-counterparties) (e.g., `"7 Hogsmeade Ave."`) to pass address validation.

```curl Default (Success) Counterparty
curl --request POST \
  -u $ORGANIZATION_ID:$API_KEY \
  --url https://app.moderntreasury.com/api/counterparties \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Stop Payment Test Counterparty",
    "accounts": [
      {
        "account_type": "checking",
        "party_address": {
          "line1": "7 Hogsmeade Ave.",
          "locality": "San Francisco",
          "region": "California",
          "postal_code": "94108",
          "country": "US"
        },
        "routing_details": [
          {
            "routing_number_type": "aba",
            "routing_number": "121141822"
          }
        ],
        "account_details": [
          {
            "account_number": "123456789"
          }
        ]
      }
    ]
  }'
```
```curl Failure Counterparty
curl --request POST \
  -u $ORGANIZATION_ID:$API_KEY \
  --url https://app.moderntreasury.com/api/counterparties \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Test payment_action_failed Co.",
    "accounts": [
      {
        "account_type": "checking",
        "party_address": {
          "line1": "7 Hogsmeade Ave.",
          "locality": "San Francisco",
          "region": "California",
          "postal_code": "94108",
          "country": "US"
        },
        "routing_details": [
          {
            "routing_number_type": "aba",
            "routing_number": "121141822"
          }
        ],
        "account_details": [
          {
            "account_number": "123456789"
          }
        ]
      }
    ]
  }'
```
```curl Sent (No Response) Counterparty
curl --request POST \
  -u $ORGANIZATION_ID:$API_KEY \
  --url https://app.moderntreasury.com/api/counterparties \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Test payment_action_sent Co.",
    "accounts": [
      {
        "account_type": "checking",
        "party_address": {
          "line1": "7 Hogsmeade Ave.",
          "locality": "San Francisco",
          "region": "California",
          "postal_code": "94108",
          "country": "US"
        },
        "routing_details": [
          {
            "routing_number_type": "aba",
            "routing_number": "121141822"
          }
        ],
        "account_details": [
          {
            "account_number": "123456789"
          }
        ]
      }
    ]
  }'
```

### 2. Create a Check Payment Order

Create a check payment order using the External Account ID from the counterparty creation response.

```shell
curl --request POST \
  -u $ORGANIZATION_ID:$API_KEY \
  --url https://app.moderntreasury.com/api/payment_orders \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "check",
    "amount": 10000,
    "direction": "credit",
    "currency": "USD",
    "originating_account_id": "YOUR_INTERNAL_ACCOUNT_ID",
    "receiving_account_id": "COUNTERPARTY_EXTERNAL_ACCOUNT_ID"
  }'
```

Wait for the Payment Order to reach `sent` status. In the Sandbox, this takes seconds.

### 3. Create a Stop Payment Action

Once the Payment Order reaches `sent` status, create a Stop Payment Action via the API or from the Dashboard by selecting **Stop Check Payment** in the **Actions** dropdown.

```shell
curl --request POST \
  -u $ORGANIZATION_ID:$API_KEY \
  --url https://app.moderntreasury.com/api/payment_actions \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "stop",
    "actionable_id": "PAYMENT_ORDER_ID",
    "actionable_type": "payment_order"
  }'
```

### Alternative: Create a Payment Action Without a Payment Order (Bring Your Own Bank Only)

For Bring Your Own Bank accounts, you can create a Stop Payment Action without an associated Payment Order. Provide your `internal_account_id` and set `details.payee_name` to the test string to control the sandbox outcome.

```shell
curl --request POST \
  -u $ORGANIZATION_ID:$API_KEY \
  --url https://app.moderntreasury.com/api/payment_actions \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "stop",
    "internal_account_id": "YOUR_INTERNAL_ACCOUNT_ID",
    "details": {
      "payee_name": "payment_action_failed",
      "amount": 10000,
      "currency": "USD",
      "check_number": "1234",
      "issue_date": "2026-01-15",
      "originating_account_number": "123456789"
    }
  }'
```

The same test values apply: use `payment_action_failed` to simulate a failure or `payment_action_sent` to simulate a stuck-in-sent state. Any other value follows the default success path.

### 4. Observe the Result

The Sandbox processes the Payment Action within seconds. Check the Payment Action and Payment Order statuses to verify the expected outcome.

| Scenario          | Test Value              | Payment Action Status | Payment Order Status |
| :---------------- | :---------------------- | :-------------------- | :------------------- |
| Success (default) | *(any name)*            | `acknowledged`        | `stopped`            |
| Failure           | `payment_action_failed` | `failed`              | *unchanged*          |
| Stuck in sent     | `payment_action_sent`   | `sent`                | *unchanged*          |

Set the test value via the counterparty name on the original payment order, or via `details.payee_name` on the Payment Action when there is no associated Payment Order (Bring Your Own Bank only).