alt

Important information

There was an update of Unzer TLS/SSL certificates. Learn more

Unzer

Charge a payment

Transfer money form the customer to the merchant.

Overview

The charge resource is used for activating the flow of transferring the money from the customer to you (merchant). When the customer initiates a payment, based on your configuration, a direct charge request or authorization request is created. You can either charge directly or authorize the payment and then charge it later.

Check Payment methods page to see what payment methods support direct charge (most do) and charge after authorization.

Charge directly

Direct charge debits the customer’s account without any prior authorization.

A direct charge is triggered by calling the charge function of the Unzer object or with an amount, currency, order ID, and a reference to a payment method. Alternatively you can use the charge function of a created payment type object

  // basic charge example
  $unzer  = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
  $chargeInstance = new Charge(12.99, 'EUR', 'https://your.return.url');
  $typeId = 's-crd-9wmri5mdlqps';
  $charge = $unzer->performCharge($chargeInstance, $typeId);
  // basic charge example
  $unzer  = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
  $card   = $unzer->fetchPaymentType('s-crd-9wmri5mdlqps');
  $charge = $card->charge(100.0, 'EUR', 'https://your.return.url');
icon info
Some payment types require a customer resource, which can be passed as additional parameter to the transaction.
Refer to the Manage Customer section to learn more about adding a customer reference.

Arguments to Unzer::performCharge

Expand/Collapse argument list
Parameter Type Description
charge
(required)
Charge The Charge object containing transaction specific information.
paymentType
(required)
BasePaymentType | string The payment type object or the ID of the payment type to use.
customer* Customer |string A reference to the customer resource corresponding to this payment.
This can be either a customer object or the ID of an existing customer resource.
For more details, see Manage customer.
metadata* Metadata The Metadata object containing custom information for the payment.
basket* Basket A reference to the basket corresponding to this payment.
For more details, see Manage baskets.
* If an object is used, the ID for which is not set (the resource is currently not available in the Payment API), the customer resource is automatically created and referenced with the transaction call.

Charge properties

The charge object used in the performCharge method needs certain properties set in oder to create a proper transaction that are listed below:

Expand/Collapse property list
Parameter Type Description
amount float The amount to be charged
Required: true
currency string The currency of the amount.
Required: true
returnUrl string The URL the customer will be redirected to after a transaction.
This needs to be set to a valid URL, no matter whether a redirect is necessary or not.
Required: true
orderId string The ID of the order in your store.
This ID can be used to fetch the payment resource from the PAPI using the method Unzer::fetchPaymentByOrderId($YourOrderId)
Required: false
Default: null
card3ds boolean Allows to switch between a 3DS and non-3DS channel, if both are configured for the merchant. Otherwise it will be ignored.
Required: false
Default: null
invoiceId string This is used to transmit the invoice ID from your shop to the API. For Unzer Invoice payments, the invoice ID is required.
paymentReference string This is a reference string to show the customer the purpose of the transaction. This will be shown on the bank statement of the buyer.
Required: false
Default: null
additionalTransactionData stdClass This can be used to add additional information to your transaction if requiered/supported by the payment method. (e.g. used to set recurrence type for card payments.)

[Deprecated]Arguments to Unzer::charge

Expand/Collapse argument list
Parameter Type Description
amount float The amount to be charged
Required: true
currency string The currency of the amount.
Required: true
paymentType string | BasePaymentType The PaymentType object or the ID of the PaymentType to use.

The charge function of payment types don’t have this parameter, the other parameters are the same.

Required: true
returnUrl string The URL the customer will be redirected to after a transaction.
This needs to be set to a valid URL, no matter whether a redirect is necessary or not.
Required: true
customer* string | UnzerSDK\Resources\Customer A reference to the customer resource corresponding to this payment.
This can be either a customer object or the ID of an existing customer resource. If a customer object is used whose ID is not set (i. e. the resource does not exist yet in the PAPI) the customer resource will automatically be created and referenced with the transaction call.
For more details, see Manage customer.
Required: false
Default: null
orderId string The ID of the order in your store.
This ID can be used to fetch the payment resource from the PAPI using the method Unzer::fetchPaymentByOrderId($YourOrderId)
Required: false
Default: null
metadata* UnzerSDK\Resources\Metadata A reference to the metadata corresponding to this payment.
The metadata object can be used to pass along custom information which you wish to reference to the payment.
For more details, see Manage metadata
Required: false
Default: null
basket* UnzerSDK\Resources\Basket A reference to the basket corresponding to this payment.
For more details, see Manage baskets
Required: false
Default: null
card3ds boolean Allows to switch between a 3DS and non-3DS channel, if both are configured for the merchant. Otherwise it will be ignored.
Required: false
Default: null
invoiceId string This is used to transmit the invoice ID from your shop to the API. For Unzer Invoice payments, the invoice ID is required.
paymentReference string This is a reference string to show the customer the purpose of the transaction. This will be shown on the bank statement of the buyer.
Required: false
Default: null
recurrenceType string Recurrence type used for recurring payment.

Required: false
Default: null
additionalTransactionData stdClass This can be used to add additional information to your transaction if requiered/supported by the payment method. (e.g. used to set recurrence type for card payments.)
* If an object is used, the ID for which is not set (the resource is currently not available in the Payment API), the customer resource is automatically created and referenced with the transaction call.

Arguments to charge of payment type

Expand/Collapse argument list
Parameter Type Description
amount float The amount to be charged
Required: true
currency string The currency of the amount.
Required: true
paymentType string | BasePaymentType The PaymentType object or the ID of the PaymentType to use.

The charge function of payment types don’t have this parameter, the other parameters are the same.

Required: true
returnUrl string The URL the customer will be redirected to after a transaction.
This needs to be set to a valid URL, no matter whether a redirect is necessary or not.
Required: true
customer* string | UnzerSDK\Resources\Customer A reference to the customer resource corresponding to this payment.
This can be either a customer object or the ID of an existing customer resource. If a customer object is used whose ID is not set (i. e. the resource does not exist yet in the PAPI) the customer resource will automatically be created and referenced with the transaction call.
For more details, see Manage customer.
Required: false
Default: null
orderId string The ID of the order in your store.
This ID can be used to fetch the payment resource from the PAPI using the method Unzer::fetchPaymentByOrderId($YourOrderId)
Required: false
Default: null
metadata* UnzerSDK\Resources\Metadata A reference to the metadata corresponding to this payment.
The metadata object can be used to pass along custom information which you wish to reference to the payment.
For more details, see Manage metadata
Required: false
Default: null
basket* UnzerSDK\Resources\Basket A reference to the basket corresponding to this payment.
For more details, see Manage baskets
Required: false
Default: null
card3ds boolean Allows to switch between a 3DS and non-3DS channel, if both are configured for the merchant. Otherwise it will be ignored.
Required: false
Default: null
invoiceId string This is used to transmit the invoice ID from your shop to the API. For Unzer Invoice payments, the invoice ID is required.
paymentReference string This is a reference string to show the customer the purpose of the transaction. This will be shown on the bank statement of the buyer.
Required: false
Default: null
recurrenceType string Recurrence type used for recurring payment.

Required: false
Default: null
additionalTransactionData stdClass This can be used to add additional information to your transaction if requiered/supported by the payment method. (e.g. used to set recurrence type for card payments.)
* If an object is used, the ID for which is not set (the resource is currently not available in the Payment API), the customer resource is automatically created and referenced with the transaction call.

Charge after Authorization

If an authorization transaction has been performed the authorized amount can be charged. It is possible to perform several charges until the authorized amount is reached. The SDK provides multiple ways to perform this task.

Option 1: Charge full amount

  // charge authorized amount by payment ID
  $unzer  = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
  
  $chargeTransaction = $unzer->performChargeOnPayment('s-pay-1', new Charge());
// charge authorized amount by authorization object
$unzer         = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$authorization = $unzer->fetchAuthorization('s-pay-1');
$charge        = $authorization->charge();
// charge authorized amount by payment object
$unzer   = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$payment = $unzer->fetchPayment('s-pay-1');
$charge  = $payment->charge();

Option 2: Charge partial amount

You can also partially charge a payment. This is useful if you shipped some goods to the customer and only want to invoice the shipped goods. If you are charging partially, and charge more than the total charge amount, an error is displayed.

// part charge authorization by payment ID
$unzer   = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');

$charge1 = $unzer->performChargeOnPayment('s-pay-1', new Charge(60.00));
$charge2 = $unzer->performChargeOnPayment('s-pay-1', new Charge(40.00));
// part charge authorization by authorization object
$unzer         = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$authorization = $unzer->fetchAuthorization('s-pay-1');
$charge1 = $authorization->charge(50.0);
$charge2 = $authorization->charge(50.0);
// part charge authorization by payment object
$unzer   = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$payment = $unzer->fetchPayment('s-pay-1');
$charge1 = $payment->charge(50.0);
$charge2 = $payment->charge(50.0);

Arguments to Unzer::performChargeOnPayment

Expand/Collapse argument list
Parameter Type Description
payment string | UnzerSDK\Resources\Payment The ID of the payment resource or the payment object itself can be entered here.
Required: true
charge
(required)
Charge The Charge object containing transaction specific information.

Charge properties after Authorization

The list below contains properties that are relevant for a charge of an authorized payment.

Expand/Collapse property list
Parameter Type Description
amount float The amount to charge of the authorization. The method will perform a full charge of the authorization if the amount is not set.
Required: false
Default: null
orderId string The ID of the order in your store.
This ID can be used to fetch the payment resource from the PAPI using the method Unzer::fetchPaymentByOrderId($YourOrderId)
Required: false
Default: null
invoiceId string This is the invoiceId from your shop.
Required: false
Default: null
paymentReference string This is a reference string to show the customer the purpose of the transaction. This will be shown on the bank statement of the buyer.
Required: false
Default: null

[Deprecated]Arguments to Unzer::chargeAuthorization

Expand/Collapse property list
Parameter Type Description
payment string or UnzerSDK\Resources\Payment The ID of the payment resource or the payment object itself can be entered here.
Required: true
amount float The amount to charge of the authorization. The method will perform a full charge of the authorization if the amount is not set.
Required: false
Default: null
orderId string The ID of the order in your store.
This ID can be used to fetch the payment resource from the PAPI using the method Unzer::fetchPaymentByOrderId($YourOrderId)
Required: false
Default: null
invoiceId string This is the invoiceId from your shop.
Required: false
Default: null

Arguments to Authorization::charge

Parameter Type Description
amount float The amount to charge the authorization. The method will perform a full charge of the authorization if the amount is not set.
Required: false
Default: null

Arguments to Payment::charge

Parameter Type Description
amount float The amount to charge the authorization. The method will perform a full charge of the authorization if the amount is not set.
Required: false
Default: null
currency string The currency of the amount.
Required: false
Default: null

Transaction Results

Transaction results

The authorization object is updated with the data from the payment API response. It contains the paymentId (for example, s-pay-1), the transactionId, and other properties. The transaction object provides getter functions to access these properties.

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

If the transaction fails, the payment API returns an error resource. In the SDK, this is handled as an UnzerSDK\Exceptions\UnzerApiException. Make sure to catch the exception type and handle it as properly.

For an example transaction, see Authorize a payment.

try {
    $unzer     = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
    
    $charge = new Charge(100.00, 'EUR', $returnUrl);
    $unzer->performCharge($charge, $typeId);

    if ($charge->isSuccess) {
        $this->redirectToSuccess();
    }
    // Transaction has to be pending at this point.
    $this->redirectToPending();
} catch (UnzerApiException $e) {
    // Transaction failed. API returned error resource.
    $this->log($e->getClientMessage());
    $this->log($e->getMerchantMessage());
    $this->redirectToFailure(); // redirect to the failure page of your shop
} catch (RuntimeException $e) {
    $merchantMessage = $e->getMessage();
}

See also