Charge Actions

After a charge is successfully authorized, a client can perform several follow-up actions to manage the transaction lifecycle. These actions include increments, reversals, cancellations, clearing, and refunds. Actions can be performed using the Charge Action endpoints and referencing the original chargeKey. The applicability of these actions depend on how the initial charge was flagged.

Increments

The Increment Charge endpoint is used to perform an incremental authorization. This increases the total amount of a previously approved pre-authorization. This is ideal for hospitality or rental scenarios where the final transaction amount may increase after the initial authorization. If the final amount is lower than the reservation amount, a Reversal should be performed instead. The validity of an incremental authorization is the same as the pre-authorization. The request should contain the new total authorized amount in the replacementAmount field.

Requirements:

Can only be used when for the original charge the clearingMode = manual
Can only be used until the original charge is not cleared

Example Increment Request

Example Increment Response

Reversals

The Reverse Charge endpoint is used to reverse the authorization of the referenced charge. It supports full and partial reversals. It does not check if the charge has been partially or fully cleared. If the charge has already been cleared, the Refund Charge endpoint should be used instead. The request should contain the new total authorized amount in the replacementAmount field. The reversal only creates a 4XX ISO 8583 message and does not impact the clearing and settlement of the charge.

Requirements:

Can only be used when for the original charge the clearingMode = manual
Can only be used until the original charge is not cleared

Example Reversal Request

Example Reversal Response

Cancellations

The Cancel Charge endpoint is used to cancel the referenced charge. This performs two functions: it cancels the scheduled clearing and initiates a full reversal of the authorization. If the charge is already sent for clearing, this endpoint will return an HTTP 409 error with type set to /silverflow/problems/charge/clearing-already-submitted.

Requirements:

Can only be used when for the original charge the clearingMode = auto
Can only be used until the original charge is not cleared

If the referenced charge was created with the clearAfter property, the charge can be canceled up until the timestamp specified.

Example Cancel Request

Example Cancel Response

Refunds

The Refund Charge endpoint is used to the referenced charge. It supports full or partial refunds. Note that it does not check whether or not the referenced charge has been cleared already. One can use the Cancel Charge endpoint first, and if a 409 with /silverflow/problems/charge/clearing-already-submitted is returned, then call the refund endpoint instead to refund the charge.

Requirements:

Can only be used when for the original charge the clearingMode = auto
Can not be used when for the original charge the type.intent = refund
Can only be used if the initial charge
only be used until the initial charge is not cleared

Example Refund Request

Key fields:

refundAmount: Can be used for partial refunds; if omitted, the total amount will be refunded.
createRefundCharge: Allows clients to create a new charge for the corresponding refund, including authorization and clearing actions. This is an optional flow that will be made default following a deprecation procedure. Subsequently this property will property will be removed.
clearingMode: Only supported if createRefundCharge is set to true and determines the clearing method for the refund charge.
clearAfter: Can be provided when the clearing mode is auto to set a delay in the clearing of the refund.

Example Refund Response

The refundChargeKey returns the charge key of the newly created refund charge. Using the refundChargeKey clients can subsequently use the refund charge key to perform further actions. For example,

Retrieve refund charge details (GET /charges/{chargeKey})
Manually clear the refund (POST /charges/{chargeKey}/clear)
Cancel the refund (POST /charges/{chargeKey}/cancel)

Unreferenced Refunds

Refunds can also be performed using the Create Charge endpoint. Unlike a standard refund that is linked to a previous charge, this method generates a new, standalone charge object with a type.intent of refund. This approach provides clients with greater flexibility and granular control over the refund transaction. This method is ideal for issuing credits that are not tied to a specific sale or refunding a purchase originally made through a different payment method.