transaction webhooks: requested, created, updated, and completed. The settlement amount, the order of events, and the sign of the amount differ depending on what the merchant does. These examples show how each common settlement pattern appears in the webhooks you receive, so you can reconcile transactions and manage holds in your ledger correctly.
Every example shows the whole delivery: the id, resource, action, and version envelope fields, then the body. The version reflects the schema version of the body, so the value you receive depends on the version your tenant is on. Rain signs each delivery, so verify the signature before you process it. See Webhook delivery for the envelope fields, lifecycle, and retry behavior, and Set up webhooks for signature verification.
Full lifecycle
The base case: an authorization for $100.00 is created, adjusted down by $20.00, and settled at $80.00. Watch howamount and status change at each step.
1
transaction.requested
Rain forwards the authorization attempt for $100.00 (
amount: 10000). The transaction is pending.transaction.requested
2
transaction.created
Rain approves the authorization and creates the transaction, still
pending for $100.00.transaction.created
3
transaction.updated
The merchant reverses $20.00. The status changes to
reversed, authorizationUpdateAmount is -2000, and the amount drops to $80.00.transaction.updated
4
transaction.completed
The transaction settles at $80.00. The status is
completed and postedAt is set.transaction.completed
requested → created → completed sequence. Each one highlights only the webhook where the behavior differs.
Partial capture
The merchant settles less than the authorized amount. Thetransaction.completed amount ($90.00) is lower than authorizedAmount ($100.00). Reconcile against the settled amount, not the authorization.
transaction.completed
Over capture
The merchant settles more than the authorized amount. Thetransaction.completed amount ($110.00) is higher than authorizedAmount ($100.00).
transaction.completed
Multi-capture
The merchant settles one authorization in more than one piece (here $70.00, then $30.00). The transaction stayspending until the full amount settles, then Rain sends a single transaction.completed for the total ($100.00).
transaction.completed
Force capture
A force capture settles without a prior authorization. The merchant bypasses the authorization phase and settles directly, so you receive a singletransaction.completed with no preceding requested or created events. This happens in offline scenarios, such as in-flight purchases where the merchant has no connectivity. Rain populates authorizedAt and authorizedAmount from the settlement message itself, not from a prior authorization step.
transaction.completed
Refund
A refund appears as a spend transaction with negative amounts, withamount and authorizedAmount negative throughout.
In Partner-Managed programs, the refund follows the same requested → created → completed sequence. In Rain-Managed programs, Rain decides the authorization, so you receive created and then completed without a requested event.
transaction.completed
transactionId, because Rain can process refunds as standalone transaction authorizations. When no transactionId link exists, treat merchantName as a heuristic only: it is neither unique nor stable, so combine it with other signals such as amount, card, and timing before you associate a refund with a specific spend. If you cannot match with confidence, leave the refund unlinked rather than risk a wrong association.
What’s next
Transaction events
See the full field reference behind every payload shown above.
Decline reasons
Look up what a
declinedReason value means and what to do about it.