Authorization Reversals

Beta FeatureThe 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 reversing an open authorization — for example, when a merchant cancels a transaction before settlement or reduces the authorized amount. Reversals release the hold on the cardholder’s balance without creating a posted transaction. Use this to test how your integration handles authorization reversals, including partial reversals where only a portion of the original hold is released.

Full vs. partial reversal

Full reversal — Omit newAmount to release the entire hold. The transaction amount becomes 0.
Partial reversal — Provide newAmount to specify the remaining authorized amount. The difference is released back to the cardholder’s available balance.

Endpoint

POST /v1/simulate/transactions/:transactionId/reverse

Path parameters

Parameter	Type	Required	Description
`transactionId`	string (UUID)	Yes	The ID of an existing authorized transaction to reverse.

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
`newAmount`	integer	No	The remaining authorized amount in cents after the reversal. Omit for a full reversal. Must be a non-negative integer.

Full reversal (release entire hold)

{}

Partial reversal (reduce authorized amount to $4.00)

{
  "newAmount": 400
}

Response

A successful response returns the transaction ID and status.

200 OK

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

Field	Type	Description
`transactionId`	string (UUID)	The transaction ID.
`status`	string	The transaction status: `authorized`.

Errors

Status	When
`400 Bad Request`	Invalid body (negative `newAmount`), transaction is already settled, transaction is already closed, 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`	Unhandled error during simulation.

Behavior notes

Transaction must be an open authorization. You can only reverse authorizations that have not yet settled or closed.
Reversals release holds, not funds. Unlike refunds, reversals do not move posted funds — they release authorization holds.
Triggers webhooks. The reversal fires the same webhooks as a real authorization reversal.

Example

Full reversal

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

Partial reversal

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

Introduction

Plan & Set Up Your Program

Build Your Program

Run Your Program

Rewards

Embedded Wallets

Authorization Reversals

Full vs. partial reversal

Endpoint

Path parameters

Headers

Body

Response

Errors

Behavior notes

Example

​Full vs. partial reversal

​Endpoint

​Path parameters

​Headers

​Body

​Response

​Errors

​Behavior notes

​Example

Full vs. partial reversal

Endpoint

Path parameters

Headers

Body

Response

Errors

Behavior notes

Example