Approving authorizations
When a cardholder initiates a purchase, Rain’s system validates several criteria before sending the authorization request. This includes verifying card validity, checking the reserve balance, assessing spending limits, applying custom rules (such as merchant blocks), and evaluating fraud risk. If any of these checks fail, the transaction is declined immediately and you receive atransaction.created webhook with status: declined. No transaction.requested webhook is sent. If all checks pass, you receive a transaction.requested webhook to approve or decline the request. If you approve, place a hold on the funds to reserve them for settlement. At this stage, no funds are transferred.
Once Rain responds to the network, Rain sends you a transaction.created webhook. If the transaction is declined, it will have a status of declined. You will need to persist this data for logging purposes.
Declining authorizations
To decline a cardholder authorization request, respond to thetransaction.requested webhook event with any non-2xx HTTP status code, such as 401. Any 2xx response approves the authorization. You will then receive a transaction.created webhook with a status of “Declined” and amount of $0.
Rejection codes
When declining a transaction, in addition to having an HTTP status code of 401 or any 40X HTTP status code, you can include arejectionCode in your response body to indicate the reason for the decline.
The
rejectionCode field is optional but recommended: it determines the decline reason sent to the network. If you decline without one, Rain treats it as a general webhook decline.Incremental authorizations
Some merchants, such as hotels and gas stations, may need to increase the initial authorization amount. This typically occurs when the final transaction amount is not known upfront. For example, hotels may add room service charges, or gas stations may adjust for the total fuel cost. Rain’s system supports this through incremental authorizations, allowing merchants to request additional funds beyond the original authorization. Each increment undergoes the same validation process as the initial authorization. Rain notifies you with atransaction.requested webhook followed by a transaction.updated webhook with the new total amount (original amount + increment amount)
Partial reversals
When a merchant needs to reverse part of an authorization amount, the merchant can submit a partial reversal. Rain records the reversed amount and releases the authorization hold upon receiving the partial reversal. This is common in scenarios like gas stations, where the initial hold may be higher than the final amount. To notify you of this change and the release of the authorization hold, Rain sends you atransaction.updated webhook with a status of reversed.
If the transaction is partially reversed and the final settlement amount in the transaction.completed webhook does not reflect the partial reversal, the liability to fix this mismatch falls on the merchant/acquirer. To resolve, this is handled via Rain’s transaction issues and disputes process.
Full reversals
A full reversal cancels an authorization entirely. This typically happens when a transaction is canceled or times out. Rain’s system marks the authorization as reversed. As with partial reversals, the hold is released upon reception of the reversal or automatically on the stale authorization schedule. Rain sends you atransaction.updated webhook with a status of reversed and an amount of $0, simultaneously releasing the authorization hold.
If the transaction is fully reversed and the final settlement amount in the transaction.completed webhook does not reflect the full reversal (that is, a final amount other than $0), the liability to fix this mismatch falls on the merchant/acquirer. To resolve, this is handled via Rain’s transaction issues and disputes process.
Partial authorizations
Some merchants may request partial authorizations for the available balance when a cardholder has insufficient funds. This would allow a transaction to proceed with a reduced amount, which is common in scenarios such as pay-at-pump gas stations or retail transactions. Rain does not currently support partial authorizations. If the cardholder’s balance is insufficient for the full requested amount, the authorization is declined. You will receive atransaction.created webhook with a status of declined.
Refund authorizations
Occasionally, merchants may send an authorization before processing a refund to a card. This resembles a standard authorization but with a negative amount. The key difference is that the user’s ledger is not credited until the refund is fully settled. Rain sends atransaction.requested with a negative amount and upon your approval of this request (by responding with 200) you will receive a transaction.created webhook.
Stale authorization closure
If an authorization remains pending and never settles, it becomes stale and is automatically closed. The closure period depends on the transaction type:- Refunds: Closed after 31 days
- Low value positive transactions (≤$1000): Closed after 14 days
- High value positive transactions (>$1000): Closed after 31 days
- Travel and rental holds (cruise, lodging, and vehicle-rental merchant categories): Closed after 30 days
What’s next
Transaction events
See the full webhook payload and field reference for every transaction event.
Handle disputes & refunds
Walk through filing a dispute, refunds, and chargebacks.