> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.redpincompany.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.redpincompany.com/_mcp/server.

# Test webhooks with the simulator

> Trigger sandbox payment event sequences and verify your webhook handler receives each callback correctly

The webhook event simulator is a sandbox tool that publishes a scripted sequence of payment lifecycle events for a session you choose. Use it to exercise your webhook handler against every status transition - funded, FX completed, payout initiated, payout credited, completed, cancelled, bounced back.

> **Info**
>
> The simulator runs only against the sandbox. Events flow through the same delivery pipeline as production webhooks, so payload shape and delivery order behave identically.

## Prerequisites

Before you begin, make sure you have:

#### Sandbox credentials

A working sandbox account. If you do not have one, see [Sandbox to production](/api-guide/getting-started/sandbox-to-production).

#### A registered webhook subscription

A `PAYMENT STATUS` subscription registered against your sandbox account. See the [Webhooks overview](/api-guide/webhooks) for setup details.

#### A sandbox session

The simulator works with hosted sessions created via the [Create Payment Session](/api-reference/customers/hosted-experience/sessions/create-payment-session) endpoint. Create one in the sandbox and use the returned session ID to drive the simulator.

The session reaches `AWAITING_FUNDS` once the user clicks **Continue to Payment** in the hosted session flow. This is the state from which a new scenario run begins.

You can also load a session that has already moved past `AWAITING_FUNDS` and continue it stage-by-stage in **Manual** mode — useful for resuming a flow after a browser reload or for inspecting a partially-driven session.

The simulator is available to anyone with sandbox credentials at [simulator.sandbox.redpincompany.com](https://simulator.sandbox.redpincompany.com). No additional access request is required.

## How it works

#### You provide a session ID

The simulator looks up the session and surfaces the payment reference, recipients and the callback URL registered for `PAYMENT STATUS` events on the account that owns this session.

#### You pick an action and an execution mode

Each action is a predefined sequence of payment lifecycle events. **Auto** mode publishes the full sequence back-to-back from `AWAITING_FUNDS`. **Manual** mode publishes one stage per click, gated by the session's current status, so you can verify your handler between stages.

#### The simulator publishes the events

Each event is published in turn and delivered to your registered callback URL through the same delivery pipeline used in production.

#### You verify what was delivered

The **Webhook deliveries** panel queries the delivery history for this session so you can confirm your handler received every callback.

## Walkthrough

### 1. Open the simulator

Navigate to [simulator.sandbox.redpincompany.com](https://simulator.sandbox.redpincompany.com). The **Webhook Simulator** page opens with a short **Getting started** panel and an empty **Session ID** field.

![Webhook Simulator landing page with the Getting started panel expanded and an empty Session ID field](/_fern-files/_img/2000e762ceb9fdb477e2ce67631aa67687cb1cb4d3c17f5cb6b87ea864978033.webp)

### 2. Load a session

If you do not have a session yet, create one with the [Create Payment Session](/api-reference/customers/hosted-experience/sessions/create-payment-session) endpoint in the sandbox.

Paste a sandbox session ID into the **Session ID** field and click **Load session**. The simulator displays:

* **Payment reference** and **Client reference** for the session
* **Current status** of the payment
* **Recipients** count
* **Customer** identifier
* **Callback URL** registered to receive webhook events for this session

> **Note**
>
> If **Callback URL** is empty, no `PAYMENT STATUS` subscription is registered for your account. Register a subscription using the [Subscribe to Webhook](/api-reference/customers/api-integration/webhooks/create-webhook) endpoint before running an action.

![Webhook Simulator showing a loaded session with payment reference, client reference, current status, recipients, customer ID and callback URL](/_fern-files/_img/ec2c8ba24f7e1414b4de1935f42403fbcebc2044a5ec1f109bbf37a86162111a.webp)

### 3. Pick an action

The **Simulated Test Cases** panel exposes the **Action** dropdown once a `PAYMENT STATUS` webhook subscription exists for the account that owns this session. If no subscription is registered, the panel shows an inline message pointing you to register one first.

Open the **Action** dropdown and choose the sequence you want to run. See [Available actions](#available-actions) below for what each one does.

![Simulated Test Cases panel with the Action dropdown open, showing Successful Payment Completion and Cancel Payment options](/_fern-files/_img/49070fd425e53ede0b435fdbe4a0716513ced76802deed09f3fe5d70879adcbc.webp)

### 4. Choose an execution mode

The **Execution mode** control selects how stages are published:

* **Auto** — publishes the full sequence back-to-back, waiting the configured delay between stages. Auto is available **only** when the session status is `AWAITING_FUNDS`. Once the session has moved past `AWAITING_FUNDS`, Auto is hidden and the panel falls back to Manual.
* **Manual** — publishes one stage per click. Available at any session status. Each stage is gated by its `requires_status`: the stage publishes only when the session's current status matches the stage's prerequisite. Manual mode lets you verify your handler between stages and resume a partially-driven session after a reload.

### 5. Run the sequence

#### Auto

Click **Run**. The simulator publishes each event in order, waiting the configured delay between stages. A progress indicator shows the current step and a table records each publish result.

![Simulated Test Cases panel mid-run, showing the progress bar at step 4 of 5 and a table of completed steps with their statuses](/_fern-files/_img/70036e4fc54bfc399971ac2bc1a91984e7939936169b24a132bebb4918ac10d7.webp)

When the sequence finishes, you will see a success summary if every step published cleanly, or an error breakdown if any step failed.

#### Manual

Manual mode renders:

* The **Latest session status** caption — the most recent status observed for this session.
* A **Stage overview** table — every stage in the chosen action with its `Event`, `Requires status`, `Per recipient` flag and `State` (`Done`, `Next`, `Pending`, or `Failed`).
* A primary button whose label depends on the current state.

![Simulated Test Cases panel in Manual mode showing the Execution mode radio, the latest session status caption, the Stage overview table and the Publish next stage button](/_fern-files/_img/6516125ed5107aac8528966751003f500b3e9e137d7c2ccbd4dea1abbdf243f9.webp)

Stages publish one at a time. Each click follows this rule:

#### Re-read the session status

The simulator fetches the latest session status before deciding what to do.

#### Match a stage

The simulator locates the stage whose `requires_status` matches the current session status.

#### Publish or wait

* If a matching stage is found and the previous publish has already propagated, the button reads **Publish next stage: `<EVENT>`** and the click publishes that stage.
* If the previous stage was published but the session status has not yet moved forward, the button reads **Refresh status**. Clicking it re-reads the status without republishing. Once your downstream has advanced the status to the next stage's prerequisite, the same click publishes the next stage.
* If no stage in the action applies to the current status, the button is disabled and the panel explains why.

> **Info**
>
> After a browser reload, Manual mode reconstructs progress from the session's current status against the sequence chain. Already-completed stages show **Done** even though the in-memory publish log is empty.

### 6. Verify webhook deliveries

Scroll to the **Webhook deliveries** panel and click **Refresh**. The panel queries the delivery history for this session and lists every webhook delivered to your callback URL, including event type, status and the full payload.

![Webhook deliveries panel populated with the events the simulator delivered to the registered callback URL](/_fern-files/_img/c0c22bdae69e4eed7ad496643c3be4557fc18cd7839d1c8cf937ef8a89bab55c.webp)

If your handler is correctly subscribed and reachable, every event in the sequence should appear here. Use the payloads to confirm your handler parsed each event correctly.

## Available actions

> **Note**
>
> This list reflects the actions available today. New actions are added periodically; check back if you do not see one you expect.

#### Successful Payment Completion

Simulates a payment that funds, converts, pays out to every recipient and settles successfully.

| Step | Event                              | Requires status    |
| ---- | ---------------------------------- | ------------------ |
| 1    | `RECEIVED_FUNDS`                   | `AWAITING_FUNDS`   |
| 2    | `FX_COMPLETED`                     | `RECEIVED_FUNDS`   |
| 3    | `PAYOUT_INITIATED` (per recipient) | `FX_COMPLETED`     |
| 4    | `PAYOUT_CREDITED` (per recipient)  | `PAYOUT_INITIATED` |
| 5    | `PAYMENT_COMPLETED`                | `PAYOUT_CREDITED`  |

Steps marked **per recipient** publish one event for each recipient on the session. A session with three recipients produces three `PAYOUT_INITIATED` events and three `PAYOUT_CREDITED` events.

The **Requires status** column shows the session status each stage gates on. In Manual mode, a stage publishes only when the session's current status matches its prerequisite. In Auto mode, the stages run back-to-back from `AWAITING_FUNDS`.

Use this action to verify your handler correctly transitions a payment through the full happy path.

#### Cancel Payment — Funding Failure

Simulates a payment that is funded and then cancelled before FX conversion (e.g., due to customer instruction or manual intervention).

| Step | Event            | Requires status  |
| ---- | ---------------- | ---------------- |
| 1    | `RECEIVED_FUNDS` | `AWAITING_FUNDS` |
| 2    | `CANCELLED`      | `RECEIVED_FUNDS` |

Use this action to verify your handler correctly processes a cancellation after funds have been received but before payout initiation.

#### Cancel Payment — Payout Failure

Simulates a payment that completes FX, initiates payouts, and is then cancelled due to a downstream banking rejection/failure during the payout phase.

| Step | Event                              | Requires status    |
| ---- | ---------------------------------- | ------------------ |
| 1    | `RECEIVED_FUNDS`                   | `AWAITING_FUNDS`   |
| 2    | `FX_COMPLETED`                     | `RECEIVED_FUNDS`   |
| 3    | `PAYOUT_INITIATED` (per recipient) | `FX_COMPLETED`     |
| 4    | `CANCELLED` (per recipient)        | `PAYOUT_INITIATED` |

Use this action to verify your handler correctly processes a cancellation or rejection during the payout phase.

#### Bounced Back

Simulates a payment that completes successfully but where the recipient's bank subsequently rejects and returns the funds (e.g., due to an invalid account number or closed account).

| Step | Event                              | Requires status    |
| ---- | ---------------------------------- | ------------------ |
| 1    | `RECEIVED_FUNDS`                   | `AWAITING_FUNDS`   |
| 2    | `FX_COMPLETED`                     | `RECEIVED_FUNDS`   |
| 3    | `PAYOUT_INITIATED` (per recipient) | `FX_COMPLETED`     |
| 4    | `PAYOUT_CREDITED` (per recipient)  | `PAYOUT_INITIATED` |
| 5    | `BOUNCED_BACK` (per recipient)     | `PAYOUT_CREDITED`  |

Use this action to verify your handler correctly processes a bounced back status and handles the returned funds.

> **Tip**
>
> For the exact payload shape of each event, see the [Payment Status Updated Event](/api-reference/webhooks) in the Webhook Reference.

## Troubleshooting

#### Session not found

The session ID does not exist in the sandbox. Verify the ID against the session you created and try again.

#### Action dropdown is not visible

The **Simulated Test Cases** panel hides the dropdown when no `PAYMENT STATUS` webhook subscription is registered for your account. Register one using the [Subscribe to Webhook](/api-reference/customers/api-integration/webhooks/create-webhook) endpoint, then reload the session.

#### Auto mode is not offered, only Manual

Auto mode is available only when the session status is `AWAITING_FUNDS`. Once the session has moved past `AWAITING_FUNDS`, the panel offers Manual mode only — pick up stage-by-stage from where the session currently is, or load a fresh session at `AWAITING_FUNDS` to run Auto.

#### Manual mode button says 'Refresh status' and won't publish

The previous stage published successfully, but the session status has not yet moved forward to the next stage's `Requires status`. Verify your handler completed processing the last event, then click **Refresh status**. When the status has advanced, the same click publishes the next stage.

#### Manual mode says no stages apply to this status

None of the stages in the chosen action have a `Requires status` matching the session's current status. Pick a different action whose first applicable stage matches the current status, or load a session at an earlier state in the lifecycle.

#### Refresh returns no deliveries

The **Webhook deliveries** panel only shows deliveries from the point the session reached `AWAITING_FUNDS`. If the session has not progressed that far yet, run an action that includes `RECEIVED_FUNDS` first, wait for it to complete, then click **Refresh**.

If deliveries still do not appear after a completed run, check:

* Your callback URL is publicly reachable from the internet
* Your handler returns a `2xx` status code within the response timeout

See the [Webhooks overview](/api-guide/webhooks) for more on handler setup.

#### An action ran but my handler did not receive anything

Confirm the **Callback URL** displayed after loading the session matches the endpoint you are monitoring. If they match but your handler still received nothing, click **Refresh** in the **Webhook deliveries** panel to see the delivery history and any failure details.

## Scope and limits

> **Info**
>
> The simulator is built for integration verification, not load or performance testing.

* **Sandbox only.** No real funds move and no real bank instructions are sent.
* **Same delivery pipeline as production.** Payload shape and delivery order match what your handler will see in production.
* **One session at a time.** Each run targets a single session; load a different session ID to test another flow.

## Next steps

#### [Webhooks overview](/api-guide/webhooks)

Set up webhook subscriptions and process payment status events.

#### [Payment reconciliation](/api-guide/webhooks/reconciliation)

Reconcile webhook events with payment state in your system.

#### [Webhook Reference](/api-reference/webhooks)

Inspect the payload shape of each event the simulator publishes.

#### [Making your first payment](/api-guide/getting-started/making-your-first-payment)

Create a sandbox session you can drive through the simulator.