Partners

Test webhooks with the simulator

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.

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:

1

Sandbox credentials

A working sandbox account. If you do not have one, see Sandbox to production.

2

A registered webhook subscription

A PAYMENT STATUS subscription registered against your sandbox account. See the Webhooks overview for setup details.

3

A sandbox session

The simulator works with hosted sessions created via the 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 the simulator can publish events.

The simulator is available to anyone with sandbox credentials at simulator.sandbox.redpincompany.com. No additional access request is required.

How it works

1

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.

2

You pick an action

Each action is a predefined sequence of payment lifecycle events published in order.

3

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.

4

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. 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

2. Load a session

If you do not have a session yet, create one with the 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

If Callback URL is empty, no PAYMENT STATUS subscription is registered for your account. Register a subscription using the Subscribe to 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

3. Pick an action

The Simulated Test Cases panel only exposes the Action dropdown when the session is ready to be driven:

  • A PAYMENT STATUS webhook subscription exists for the account that owns this session (so a callback URL is available for the simulator to deliver to), and
  • The session status is AWAITING_FUNDS.

If either condition is not met, the panel shows an inline message explaining what to do next. Once both conditions are met, open the Action dropdown and choose the sequence you want to run. See 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

4. Run the sequence

Click Run. The simulator publishes each event in order, waiting the configured delay between steps. 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

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

5. 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

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

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

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

StepEvent
1RECEIVED_FUNDS
2FX_COMPLETED
3PAYOUT_INITIATED (per recipient)
4PAYOUT_CREDITED (per recipient)
5PAYMENT_COMPLETED

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.

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

Simulates a payment that funds and is then cancelled before payout.

StepEvent
1RECEIVED_FUNDS
2CANCELLED

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

For the exact payload shape of each event, see the Payment Status Updated Event in the Webhook Reference.

Troubleshooting

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

The Simulated Test Cases panel gates the dropdown behind two conditions. The panel itself surfaces an inline message that points to the cause:

  • “Test scenario simulation requires a subscribed webhook callback” — no PAYMENT STATUS subscription is registered for your account. Register one using the Subscribe to Webhook endpoint, then reload the session.
  • “Test scenario simulation is available only when the session status is AWAITING_FUNDS” — the session is past or before AWAITING_FUNDS. Drive a fresh session to AWAITING_FUNDS and load that one instead.

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 for more on handler setup.

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

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

Set up webhook subscriptions and process payment status events.

Payment reconciliation

Reconcile webhook events with payment state in your system.

Webhook Reference

Inspect the payload shape of each event the simulator publishes.

Making your first payment

Create a sandbox session you can drive through the simulator.