alt

Important information

The API reference is now available here.
The deprecated API reference is available here.

Unzer

Manage Unzer Installment payment

Manage Unzer Installment payments.

icon info

If you are using payment type installment-secured, note that this method is now deprecated. It’s currently supported but there are no further developments planned for it.

If you want to access the relevant documentation, see Installment Secured.

After the successful authorize transaction, you can perform additional operations on the payment resource. Some of the important ones are described in the following section.

For a full reference of managing payments, go to relevant server-side integration documentation page: Manage API resources (direct API calls).

Full charge

Making a charge transaction signals you are shipping goods to your customer while capturing the respective order amount.

The charge call is a crucial API call that initiates two processes:

  • It starts the installment plan for the consumers. The customer will get the installment plan from Unzer with all relevant payment details in on it.
  • The other process, which is initiated, is the payout of the charged amount to the merchant
POST: https://api.unzer.com/v1/payments/s-pay-1/charges

{
}
<?php
$unzer     = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');

$payment = $unzer->fetchPayment('s-pay-1');
$transaction = $unzer->performChargeOnPayment($payment, new Charge());
Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
Charge charge = unzer.chargeAuthorization("s-pay-101");

The response looks similar to the following example:

{
    "id": "s-chg-1",
    "isSuccess": true,
    "isPending": false,
    "isResumed": false,
    "isError": false,
    "card3ds": false,
    "message": {
        "code": "COR.000.000.000",
        "merchant": "Transaction succeeded",
        "customer": "Your payments have been successfully processed."
    },
    "amount": "100.0000",
    "currency": "EUR",
    "date": "2023-04-25 09:28:44",
    "resources": {
        "customerId": "s-cst-72e4cfed0be5",
        "paymentId": "s-pay-1",
        "basketId": "s-bsk-1f4da5b7e014",
        "traceId": "20ff08289ea6ea977049e168dc75a2a7",
        "typeId": "s-pit-bfte2gs2u0kq"
    },
    "orderId": "ORD-8282",
    "invoiceId": "INV-7098",
    "paymentReference": "",
    "processing": {
        "uniqueId": "Tx-yr3nq9rrkze",
        "shortId": "Tx-yr3nq9rrkze",
        "traceId": "20ff08289ea6ea977049e168dc75a2a7"
    }
}

Provide shipping information

To allow Unzer to track the customer’s order, you can provide shipping information in your charges request. Based on the information provided payment plans can be paused for example, due to a refund.

Shipping information can be provided in the following fields:

ParameterTypeDescription
deliveryTrackingId (optional)stringTracking ID of the selected delivery service provider for the delivery to the customer.
returnTrackingId (optional)stringTracking ID of the selected delivery service provider if the customer is returning goods to you.
deliveryService (optional)stringDelivery service provider used for ship the goods to your customer (such as, DHL, UPS, and Hermes)
POST: https://api.unzer.com/v1/payments/s-pay-1/charges
{
    "amount": "50",
    "additionalTransactionData": {
        "shipping": {
          "deliveryTrackingId": "00340434286851877897",
           "returnTrackingId": "00123434286851877897",
          "deliveryService": "DHL"
        }
}
<?php
$unzer     = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');

$shipping = (new ShippingData())
->setDeliveryTrackingId("00340434286851877897")
->setReturnTrackingId("00340434286851877897")
->setDeliveryService("DHL");

$charge = (new Charge(50.00))
    ->setShipping($shipping);

$transaction = $unzer->performChargeOnPayment('s-pay-1', $charge);
Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");

ShippingTransactionData shippingData = new ShippingTransactionData()
    .setDeliveryService("DHL"))
    .setReturnTrackingId("00340434286851877897")
    .setDeliveryTrackingId("00340434286851877897");

Charge charge = new Charge()
    .setPaymentId("s-pay-1")
    .setAmount(new BigDecimal("50.00"))
    .setAdditionalTransactionData(
            new AdditionalTransactionData().setShipping(shippingData)
    );

Charge response = unzer.chargeAuthorization(charge);

Partial charge

If you ship an order in multiple steps, you can make a partial charge for each part you want to ship.

The charge call is a crucial API call that initiates two processes:

  • It starts the installment plan for the consumers. The customer will get the installment plan from Unzer with all relevant payment details in on it.
  • The other process, which is initiated, is the payout of the charged amount to the merchant
POST: https://api.unzer.com/v1/payments/s-pay-1/charges

{
  "amount" : "50",
}
<?php
$unzer     = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');

$payment = $unzer->fetchPayment('s-pay-1');
$transaction = $unzer->performChargeOnPayment($payment, new Charge(50.00));
Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");

Charge charge = unzer.chargeAuthorization("s-pay-1", new BigDecimal("50.00"));

The response looks similar to the following example:

{
    "id": "s-chg-1",
    "isSuccess": true,
    "isPending": false,
    "isResumed": false,
    "isError": false,
    "card3ds": false,
    "message": {
        "code": "COR.000.000.000",
        "merchant": "Transaction succeeded",
        "customer": "Your payments have been successfully processed."
    },
    "amount": "50.0000",
    "currency": "EUR",
    "date": "2023-04-25 09:28:44",
    "resources": {
        "customerId": "s-cst-72e4cfed0be5",
        "paymentId": "s-pay-1",
        "basketId": "s-bsk-1f4da5b7e014",
        "traceId": "20ff08289ea6ea977049e168dc75a2a7",
        "typeId": "s-pit-bfte2gs2u0kq"
    },
    "orderId": "ORD-8282",
    "invoiceId": "INV-7098",
    "paymentReference": "",
    "processing": {
        "uniqueId": "Tx-yr3nq9rrkze",
        "shortId": "Tx-yr3nq9rrkze",
        "traceId": "20ff08289ea6ea977049e168dc75a2a7"
    }
}

You should also provide the shipping information as previously explained in the full charge section.

Cancel before charge (reversal)

If the customer cancels an order completely before you ship the goods or if the goods are not available in stock, you must cancel the order by initializing a reversal.

icon
If the customer is not cancelling the order completely, you don’t need a reversal transaction. Only charge the remaining items as soon as you ship it.
POST: https://api.unzer.com/v1/payments/s-pay-71/authorize/cancels

{
}
<?php
$unzer = new Unzer('s-priv-xxxxxxxxxx');

$cancel = $unzer->cancelAuthorizedPayment('s-pay-1');
Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");

Cancel cancel = unzer.cancelAuthorization("s-pay-1");

The response looks similar to the following example:

{
    "id": "s-cnl-1",
    "isSuccess": true,
    "isPending": false,
    "isResumed": false,
    "isError": false,
    "card3ds": false,
    "message": {
        "code": "COR.000.000.000",
        "merchant": "Transaction succeeded",
        "customer": "Your payments have been successfully processed."
    },
    "amount": "899.5000",
    "currency": "EUR",
    "date": "2023-04-25 10:32:21",
    "resources": {
        "customerId": "s-cst-c697a3337a42",
        "paymentId": "s-pay-71",
        "basketId": "s-bsk-216c7c65ff5d",
        "traceId": "e3d93993a1723b4da001853599a7c892",
        "typeId": "s-pit-djs8ygsptueq"
    },
    "orderId": "order-1682418644054-775",
    "invoiceId": "iv_1682418644054",
    "paymentReference": "",
    "processing": {
        "uniqueId": "Tx-qprmnpt4wg3",
        "shortId": "Tx-qprmnpt4wg3",
        "traceId": "e3d93993a1723b4da001853599a7c892"
    }
}

Cancel after charge (refund)

In case you already charged a payment for an order that the customer wants to cancel/return, you can refund it up to the charged amount. To do this you have to make a cancels transaction on the respective paymentId.

POST: https://api.unzer.com/v1/payments/s-pay-101/charges/cancels

{
  "amount" : "10.00"
}
<?php
$unzer = new Unzer('s-priv-xxxxxxxxxx');

$cancel = $unzer->cancelChargedPayment('s-pay-1', new Cancellation(10.00));
Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");

Cancel cancel = unzer.cancelCharge("s-pay-1", new BigDecimal("10.00"));

The response looks similar to the following example:

{
    "id": "s-cnl-1",
    "isSuccess": true,
    "isPending": false,
    "isResumed": false,
    "isError": false,
    "card3ds": false,
    "message": {
        "code": "COR.000.000.000",
        "merchant": "Transaction succeeded",
        "customer": "Your payments have been successfully processed."
    },
    "amount": "10.0000",
    "currency": "EUR",
    "date": "2023-04-25 13:09:43",
    "resources": {
        "customerId": "s-cst-8bfeb8b5118c",
        "paymentId": "s-pay-101",
        "basketId": "s-bsk-c6135882e6ea",
        "traceId": "e936d7207bf71e6338286ba6a57b6bdd",
        "typeId": "s-pit-nknkqehrgrsw"
    },
    "orderId": "order-1682428147729-751",
    "invoiceId": "iv_1682428147729",
    "paymentReference": "",
    "processing": {
        "uniqueId": "Tx-fpnebaffkut",
        "shortId": "Tx-fpnebaffkut",
        "traceId": "e936d7207bf71e6338286ba6a57b6bdd"
    }
}
icon
The charges initialized after the authorize are actual payments and can be refunded by canceling them.