Refund

Simulate refunding a settled transaction to test merchant refund flows.

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. Must belong to your tenant or one of its subtenants.

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	Yes	The refund amount in cents (merchant currency). To refund in full, pass the settled amount. Must be between 1 and 2147483647. Unknown fields return 400.

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 a card authorization, 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.
422 Unprocessable Entity	The simulated refund was not processed, so no refund was recorded.
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
  }'