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.

For secured payment methods like invoice secured, paylater invoice, and installment secured, the charge is the confirmation of the shipment by you. It ensures the payout to you. Without the shipment or charge, your transaction will not be paid out. Read more in Confirm shipment page.

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');

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

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:

For a full list of the charges request parameter, please refer to API reference.

Additional transaction Data

For some transactions it can be necessary to set additionalTransactionData, in general these can be added to a Charge or Authorization transaction using the addAdditionalTransactinData($key, $value) method when needed. For specific fields extra setter methods are provided. Examples can be found below:

Setting card data PHP-SDK provides extra setter for setting card’s recurrenceType :

// create auth/charge transaction object...
$transaction->setRecurrenceType(RecurrenceTypes::ONE_CLICK);
// perform transaction ...

// create auth/charge transaction object...
$cardData = (new \UnzerSDK\Resources\EmbeddedResources\CardTransactionData())
  ->setRecurrenceType(RecurrenceTypes::ONE_CLICK)
  ->setExemptionType(ExemptionType::LOW_VALUE_PAYMENT);
  
$transaction->setCardTransactionData($cardData);
// perform transaction ...

Setting shipping data

// create auth/charge transaction object...
$shipping = (new ShippingData())
    ->setDeliveryService('deliveryService')
    ->setDeliveryTrackingId('deliveryTrackingId')
    ->setReturnTrackingId('returnTrackingId');

$transaction->setShipping($shipping);
// perform transaction ...

Setting riskData

// create auth/charge transaction object...
$riskData = (new RiskData())
    ->setThreatMetrixId('f544if49wo4f74ef1x')
    ->setCustomerGroup('TOP')
    ->setCustomerId('C-122345')
    ->setConfirmedAmount('1234')
    ->setConfirmedOrders('42')
    ->setRegistrationLevel('1')
    ->setRegistrationDate('20160412');


$transaction->setRiskData($riskData);
// perform transaction ...

[Deprecated] Arguments to Unzer::charge

Arguments to charge of payment type

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

Charge properties after authorization

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

[Deprecated] Arguments to Unzer::chargeAuthorization

Arguments to Authorization::charge

Arguments to Payment::charge

Transaction results

The authorization object is updated with the data from the Unzer 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 Unzer 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

• Cancel a charge (refund)
• Charge a payment
• Authentication reference
• Test data