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 Instalment.
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 secured payment type
Default: null
paymentReference string The reference string is show to the customer as reference text on his bank statement.
Required: false
Default: null
amountNet float The net amount to cancel.
Required: only in case of Unzer Instalment.*
Default: null
amountVat float The VAT amount to cancel.
Required: only in case of Unzer Instalment.*
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 payment 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.

You can find an example transaction response on the Cancel a charge page.

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();
}

See also