Refund

Simulate refunding a settled transaction to test merchant refund flows.

Beta Feature

The Transaction Simulations feature is currently in beta. API endpoints and behavior may change as we continue to refine the product. Simulation endpoints are available in development environments only — production returns 404 Not Found.

Simulate refunding a settled transaction — for example, when a merchant issues a refund after the original purchase was captured. This creates a credit back to the cardholder.

Use this to test how your integration handles refunds, including the transaction.spend.completed webhook with a refund completion reason.

Endpoint

POST /v1/simulate/transactions/:transactionId/refund

Path parameters

Parameter	Type	Required	Description
transactionId	string (UUID)	Yes	The ID of an existing settled transaction to refund.

Headers

Header	Type	Required	Description
Api-Key	string	Yes	Your tenant API key. The tenant scope is resolved from this key.
Content-Type	application/json	Yes	—

Body

Field	Type	Required	Description
amount	integer	No	The refund amount in cents (merchant currency). If omitted, refunds the full settlement amount.

Example request

{
  "amount": 2500
}

Response

A successful response returns the transaction ID and settled status with a refund completion reason.

200 OK

{
  "transactionId": "f3a1c92e-1b3d-4d1e-bb22-12c0a4d5b8f9",
  "status": "settled",
  "completionReason": "REFUND"
}

Field	Type	Description
transactionId	string (UUID)	The transaction ID.
status	string	The transaction status: settled.
completionReason	string	The completion type: REFUND.

Errors

Status	When
400 Bad Request	Transaction is not yet settled, no card associated with the transaction, or the card has no processor ID.
404 Not Found	Endpoint not available in production, simulations are not enabled for your tenant, or the transaction does not exist.
500 Internal Server Error	Invalid currency or unhandled error during simulation.

Behavior notes

• Transaction must be settled. You can only refund transactions that have already been settled.
• FX conversion applies. The refund amount is converted using the transaction’s original merchant and billing currencies.
• Triggers webhooks. The refund fires the same webhooks as a real refund, including transaction.spend.completed with completionReason: "REFUND".

Example

curl -X POST https://api-dev.rain.xyz/v1/simulate/transactions/f3a1c92e-1b3d-4d1e-bb22-12c0a4d5b8f9/refund \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2500
  }'