Cancel a charge (Refund)

Transfer money back from the merchant to the customer.

Overview

Canceling a charge transfers the money back from you (the merchant) to the customer. This is alternatively called refund. You can only perform the cancel transaction on an existing charge. This transaction is possible for all payment methods.

Refund on payment
It is NOT possible to do a refund on the payment resource itself.

Charge::cancel

Refund is triggered by calling the cancel of the charge object. You can call up the cancellation charge with an amount. In this case, only this part of the charge amount is transferred back. If you do not specify an amount, the entire charge is canceled. You can also provide transaction’s description during refund.

Request

$unzer  = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$charge = $unzer->fetchChargeById('s-pay-1', 's-chg-1');
$cancel = $charge->cancel();

$unzer  = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$charge = $unzer->fetchChargeById('s-pay-1', 's-chg-1');
$cancel = $charge->cancel(50.0);

Payment::cancelAmount

Even though, a direct cancel on the payment resource is not possible the SDK provides a function in the payment class that automatically performs cancellations on existing authorization and/or charges of that payment.

The method prioritizes canceling the authorization before charges. That means first the open authorization amount gets canceled. If there is still an amount left after that, the remaining cancel will be performed on existing charges.

$unzer   = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$payment = $unzer->fetchPayment('s-pay-1');
$cancel  = $payment->cancelAmount(59.5, null, 'Payment reference text', 50.0, 9.5);

Arguments to Charge::cancel | Payment::cancelAmount

Parameter	Type	Description
`amount`	`float`	The amount to cancel. The method will perform a full cancel of the charge (and payment) if the amount is not set. This is transmitted as `amountGross` in case of Unzer Installment. Required: false Default: null
`reasonCode`	`string` (`heidelpayPHP\Constants\CancelReasonCodes`)	The reason why the charge amount is reduced/cancelled. It can be one of the following: ‘CANCEL’, ‘RETURN’, ‘CREDIT’. Required: in case of Invoice payment type Default: null
`paymentReference`	`string`	The reference string displayed to the customer as text on their bank statement. Required: false Default: null
`amountNet`	`float`	The net amount to cancel. Required: only in case of Unzer Installment.* Default: null
`amountVat`	`float`	The VAT amount to cancel. Required: only in case of Unzer Installment.* Default: null

Transaction Results

The transaction response will be stored in the transaction object. It contains a paymentId (for example, s-pay-1) the transactionId and other properties of the response. The transaction object provides getter functions to access those properties. E.g. $cancel->getPaymentId()

The parameters isSuccess, isPending, and isError indicate the result of the transaction. Only one of these three can be true.

If a transaction fails, the Unzer API will return an error resource instead of a transaction. In the SDK this is handled as an UnzerApiException. Make sure to catch that case properly.

For an example transaction, see Cancel a charge.

try {
    $unzer     = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
    $charge    = $unzer->fetchCharge($paymentId, $chargeId);
    $charge->cancel(100.0);

   if ($cancelation->isSuccess) {
        // Handle successful Cancelation.
    }
} catch (UnzerApiException $e) {
    // Transaction failed. API returned error resource.
    $this->log($e->getClientMessage());
    $this->log($e->getMerchantMessage());
    // Handle failed Cancelation
} catch (RuntimeException $e) {
    $merchantMessage = $e->getMessage();
}

Important information