> ## Documentation Index
> Fetch the complete documentation index at: https://diameterpay.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Simulate an Inbound Wire Payment in the Sandbox Env

> POST /v1/simulation/payments — Trigger a synthetic inbound wire in the sandbox environment to fund accounts and test your webhook integration end-to-end.

The simulation endpoint allows you to trigger synthetic payment events in the sandbox environment, enabling end-to-end testing of your integration without requiring real bank activity. Submitting a `WIRE_INBOUND` scenario credits the specified sandbox account with the given amount and fires a `PAYMENT_WIRE_INBOUND_POSTED` webhook event — exactly as if a real wire had arrived. This endpoint is not available in production and will return `403 Forbidden` if called outside of sandbox.

> [!WARNING]
>
> This endpoint is **sandbox only**. Calling it in a production environment will return `HTTP 403 Forbidden`. Never use real account numbers, real counterparty data, or sensitive PII in simulation requests.

## Endpoint

```
POST /v1/simulation/payments
```

**Required scope:** `com.diameterpay.api/payments.write`

## Request Headers

**Authorization** `string` *required*

Bearer token obtained from your OAuth2 token endpoint. Format: `Bearer {access_token}`

**x-idempotency-key** `string` *required*

A UUID v4 string that uniquely identifies this simulation request. Replaying the same key within the idempotency window returns the original response without re-triggering the simulation.

## Request Body

**scenario** `string` *required*

The payment scenario to simulate. Currently supported value:

* `WIRE_INBOUND` — simulates an inbound wire transfer crediting the target account

**bank** `string` *required*

The bank partner to simulate the payment through. Must be one of:

* `PORTAGE`
* `SLOVAK_SAVINGS_BANK`

**accountNumber** `string` *required*

The sandbox account number to credit. This must be a valid account number within your sandbox environment.

**amount** `string` *required*

The amount to simulate, expressed as a decimal string (e.g. `"500.00"`). Must be a positive value.

**type** `string`

Optional wire transfer classification:

* `DOMESTIC` — domestic wire
* `INTERNATIONAL` — international wire

Defaults to `DOMESTIC` if not specified.

**description** `string`

Optional description forwarded to the bank's simulation API. Useful for labeling test scenarios or associating simulated payments with test cases.

## Response

Returns **HTTP 201 Created** on success.

**success** `boolean`

`true` when the simulation was accepted and the payment event was triggered successfully.

**scenario** `string`

The scenario that was simulated (e.g. `WIRE_INBOUND`).

**bank** `string`

The bank partner used for the simulation.

**referenceKind** `string`

The type of reference returned by the bank simulation system. Value: `FILENAME`.

**referenceValue** `string`

The reference value generated by the bank simulation system for this simulated payment event.

> [!NOTE]
>
> A successful simulation triggers a `PAYMENT_WIRE_INBOUND_POSTED` webhook event and reflects a real balance credit in the sandbox. Verify your webhook handler is configured to receive events at the correct endpoint before running simulations.

## Example

```bash cURL theme={null}
curl --request POST \
  --url https://api.diameterpay.com/v1/simulation/payments \
  --header "Authorization: Bearer {access_token}" \
  --header "x-idempotency-key: 4a41b9c2-e7f3-4d5a-89bc-123456789abc" \
  --header "Content-Type: application/json" \
  --data '{
    "scenario": "WIRE_INBOUND",
    "bank": "PORTAGE",
    "accountNumber": "9876543210",
    "amount": "500.00",
    "type": "DOMESTIC",
    "description": "Test inbound wire for integration verification"
  }'
```

### Response

```json theme={null}
{
  "success": true,
  "scenario": "WIRE_INBOUND",
  "bank": "PORTAGE",
  "referenceKind": "FILENAME",
  "referenceValue": "wire_inbound_portage_20240601_123456.json"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.