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.

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.

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

cURL

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

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