Sandbox Testing

The sandbox lets you drive a transaction through its entire lifecycle without real money movement. Two tools make this possible: test data that triggers specific compliance behaviors, and a force-event endpoint that simulates the external callbacks (gateway webhooks, payout-network notifications) that normally advance a transaction.

Forcing Status Transitions

Endpoint: POST /organizations/{tenant}/fx/transactions/{transactionId}/events
Authentication: Agent-level
Availability: Sandbox/staging only — this endpoint does not exist in production.

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/fx/transactions/$TRANSACTION_ID/events \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY" \
  --data '{
  "event": "payment_authorized",
  "message": "Optional description"
}'

Available Events

If the transaction is not in a valid state for the event, the endpoint returns an error explaining the current state.

Typical Test Flow (Card + 3DS)

1. Create the transaction → status WaitingChallenge3ds, paymentStatus: ActionRequired
2. Force 3DS: { "event": "payment_authorized" }
3. Transaction auto-progresses → PayoutAccepted → ManualReview → ReviewApproved → PaymentCaptured → WaitingPayout
4. Force delivery: { "event": "payout_paid" }
5. Transaction reaches Completed

Typical Test Flow (ACH)

1. Create the transaction → progresses to WaitingSettlement
2. Force settlement: { "event": "ach_settled" }
3. Transaction auto-progresses → PaymentSettled → PaymentCaptured → WaitingPayout
4. Force delivery: { "event": "payout_paid" }
5. Transaction reaches Completed

Compliance Test Scenarios

Certain sender data values trigger specific compliance behaviors in the sandbox:

Payout-Network Hold

Use sender name JULIO SOLANO to trigger a compliance hold at the payout network:

{ "firstName": "JULIO", "lastName": "SOLANO", "...": "..." }

The transaction reaches PayoutHold after payout integration. Release it with the hold_released force event (or it is released by the network/backoffice).

Expected flow:

... → ProcessingPayout → PayoutHold → [hold released] → PayoutReleased → ...

Payout-Network Rejection (Missing Receiver Data)

Use zipcode 96738 on the sender's billing address to trigger receiver-data validation failure at the payout network:

{ "address": { "zipcode": "96738", "...": "..." } }

The rejection depends on missing beneficiary data (country, city, state). If the recipient has complete address data, the transaction is accepted regardless of zipcode.

Payment Decline

Use a card token that the gateway sandbox rejects, or an expired token. The transaction reaches PaymentDeclined → Cancelled.

3DS Decline

When redirected to the 3DS challenge page, choose "Decline" (where the sandbox offers it). The gateway reports the failure and the transaction moves to PaymentDeclined → Cancelled.

Test Cards

Use sandbox test cards to simulate 3DS scenarios. The full list is in Payments Gateway test cards. Common ones:

Tokenize these via the gateway SDK, then pass the token as paymentMethod.token when creating a funding account.

Polling for Status

After creating a transaction, poll GET /organizations/{tenant}/fx/transactions/{transactionId} and watch:

For the full transition audit trail, use GET /fx/transactions/{transactionId}/status — see Transaction. In production, prefer webhooks over polling.