Manage Invoice payment

Manage Invoice payments for your customers

After the successful charge 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), Manage API resources (PHP SDK), or Manage API resources (Java SDK).

Retrieve the payment plan and the SECCI link (CCD2 compliance) (work-in-progress)

The plans endpoint returns the payment plan for a given purchase amount, together with a secciUrl. This URL points to the Standard European Consumer Credit Information (SECCI) document, which makes the credit agreement accessible to your customer.

The SECCI (Standard European Consumer Credit Information) document must be provided to the customer in order to comply with the EU Consumer Credit Directive (CCD2), regardless of whether the authorization and charge process explicitly requires a “plans” call.

The returned plan is calculated for the amount you send in the request, so call the endpoint with the amount the customer is about to pay. If the basket amount changes, fetch the plan again to get a matching secciUrl.

Header parameters

Parameter	Type	Description
`Accept-Language` / `language` (optional)	string	Preferred language of SECCI PDF document (`DE`, `EN` or `FR`). Default from channel configuration is used if not provided.

Request parameters

Parameter	Type	Description
`amount` (required)	string	Total amount of the purchase.
`currency` (required)	string	The currency code of the transaction is a 3-letter code (EUR or CHF) according to ISO_4217. Only `EUR` and `CHF` supported.
`country` (required)	string	The customer’s country in ISO country code ISO 3166 ALPHA-2 (`DE`, `AT`, `CH`, or `NL`).
`customerType` (optional)	string	`B2C` or `B2B`. If not stated explicitly `B2C` is used as fallback.

GET: https://api.unzer.com/v1/types/paylater-invoice/plans?customerType=B2C&country=DE&amount=100&currency=EUR

{
}

The response looks similar to the following example. Note that this endpoint uses the same response model as installment, some of the fields are static for Invoice.

{
    "id": "Tg-f43bd312eab",
    "isSuccess": true,
    "isPending": false,
    "isResumed": false,
    "isError": false,
    "amount": "100.00",
    "currency": "EUR",
    "plans": [
        {
            "numberOfRates": 1,
            "totalAmount": "100.00",
            "interestAmount": "0.00",
            "minimumInstallmentFee": "0.00",
            "secciUrl": "https://payment-app.paylater.unzer.com/payolution-payment/infoport/creditagreementdraft/?channelId=auto-invoice&amount=100.00",
            "installmentRates": [
                {
                    "rate": "100.00"
                }
            ]
        }
    ],
    "error": false,
    "pending": false,
    "resumed": false,
    "success": true
}

Response fields

Parameter	Type	Description
`plans[].numberOfRates`	integer	Number of rates of the plan. Invoice is always paid in a single rate, so this is always `1`.
`plans[].totalAmount`	string	Total amount the customer pays, including interest and fees.
`plans[].interestAmount`	string	Interest charged on the purchase. `0.00` for Invoice.
`plans[].minimumInstallmentFee`	string	Minimum fee charged per rate. `0.00` for Invoice.
`plans[].secciUrl`	string	Link to the SECCI document (credit agreement draft) for this plan. Show it to your customer, for example as a link in your checkout.
`plans[].installmentRates`	array	The individual rates of the plan. For Invoice this is a single rate for the full amount.

Reauthorize the transaction

The authorization patch request changes a previously authorized amount of a purchase with Invoice, Installment, and Direct Debit methods. It contains the amount value. The customer information from the referenced authorization request is used for another internal risk check. Within a few seconds a response is returned:

Declined: The new amount was not accepted. The originally authorized amount is still valid.

Accepted: The previous amount of authorization is updated and the new one is reserved for charge.

PATCH: https://api.unzer.com/v1/payments/s-pay-1/authorize
{    
    "amount": "100",
    "currency": "EUR"
}

{
    "id": "s-aut-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": "2024-04-09 13:16:22",
    "resources": {
        "customerId": "s-cst-8cbf627620c7",
        "paymentId": "s-pay-4404",
        "basketId": "s-bsk-2c6e104c1dba"
        "payPageId": "",
        "traceId": "9d2a32cad5df366a0d4f5fa583e93b1d",
        "typeId": "s-piv-h4vaiv2bfh2a"
    },
    "additionalTransactionData": {
        "riskData": {
            "threatMetrixId": "f544if49wo4f74ef1x",
            "customerGroup": "TOP",
            "customerId": "C-122345",
            "confirmedAmount": "2569",
            "confirmedOrders": "14",
            "internalScore": "95",
            "registrationLevel": "1",
            "registrationDate": "20160412"
        }
    },
    "orderId": "ORD-123456",
    "invoiceId": "INV-123456",
    "processing": {
        "uniqueId": "Tx-8x66ypzjxt2",
        "shortId": "Tx-8x66ypzjxt2",
        "traceId": "9d2a32cad5df366a0d4f5fa583e93b1d"
    }
}

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 payment terms for the consumers. The merchant must either provide the bank account details (provided in the authorization call) with an invoice to the consumers or let Unzer inform the consumer via email about the amount to be paid. The latter can be configured by Unzer.
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-101/charges

{
}

$unzer = new Unzer('s-priv-xxxxxxxxxx');

$chargeInstance = new Charge();
$chargeTransaction = $unzer->performChargeOnPayment('s-pay-101', $chargeInstance);

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,
    "isError": false,
    "message": {
        "code": "COR.000.100.112",
        "merchant": "Request successfully processed in 'Merchant in Connector Test Mode'",
        "customer": "Your payments have been successfully processed in sandbox mode."
    },
    "amount": "100.0000",
    "currency": "EUR",
    "returnUrl": "http://unzer.com",
    "date": "2022-01-27 13:38:48",
    "resources": {
        "paymentId": "s-pay-101",
        "traceId": "2c1111f3353adb2ac7cc92b21e851683",
        "typeId": "s-piv-voi3gcbwinos"
    },
    "paymentReference": "",
    "processing": {
        "uniqueId": "31HA07BC8142298076A304089F5EA7A2",
        "shortId": "5072.1712.7263",
        "traceId": "2c1111f3353adb2ac7cc92b21e851683"
    }
}

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, the customer’s payment period will only start when the order has reached your customer.

Shipping information can be provided in the following fields:

Parameter	Type	Description
`deliveryTrackingId` (optional)	string	Tracking ID of the selected delivery service provider for the delivery to the customer.
`returnTrackingId` (optional)	string	Tracking ID of the selected delivery service provider if the customer is returning goods to you.
`deliveryService` (optional)	string	Delivery 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-101/charges
{
    "amount": "50",
    "additionalTransactionData": {
        "shipping": {
          "deliveryTrackingId": "00340434286851877897",
           "returnTrackingId": "00123434286851877897",
          "deliveryService": "DHL"
        }
}

$unzer = new Unzer('s-priv-xxxxxxxxxx');

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

$chargeInstance = new Charge();
$chargeInstance->setShipping($shipping);

$chargeTransaction = $unzer->performChargeOnPayment('s-pay-101', $chargeInstance);

Partial charge

If you ship an order in multiple steps, you can make 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 payment terms for the consumers. The merchant must either provide the bank account details (provided in the authorization call) with an invoice to the consumers or let Unzer inform the consumer via email about the amount to be paid. The latter can be configured by Unzer.
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-101/charges

{
  "amount" : "50",
}

$unzer = new Unzer('s-priv-xxxxxxxxxx');

$chargeInstance = new Charge(50);
$chargeTransaction = $unzer->performChargeOnPayment('s-pay-101', $chargeInstance);

Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
Charge charge = unzer.chargeAuthorization("s-pay-101", BigDecimal.valueOf(50.0));

The response looks similar to the following example:

{
    "id": "s-chg-1",
    "isSuccess": true,
    "isPending": false,
    "isError": false,
    "message": {
        "code": "COR.000.100.112",
        "merchant": "Request successfully processed in 'Merchant in Connector Test Mode'",
        "customer": "Your payments have been successfully processed in sandbox mode."
    },
    "amount": "50.0000",
    "currency": "EUR",
    "returnUrl": "http://unzer.com",
    "date": "2022-01-27 13:38:48",
    "resources": {
        "paymentId": "s-pay-101",
        "traceId": "2c1111f3353adb2ac7cc92b21e851683",
        "typeId": "s-piv-voi3gcbwinos"
    },
    "paymentReference": "",
    "processing": {
        "uniqueId": "31HA07BC8142298076A304089F5EA7A2",
        "shortId": "5072.1712.7263",
        "traceId": "2c1111f3353adb2ac7cc92b21e851683"
    }
}

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.

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-101/authorize/cancels

{
}

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

Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
Cancel cancel = unzer.cancelAuthorization("s-pay-101");

The response looks similar to the following example:

{
    "id": "s-cnl-1",
    "isSuccess": true,
    "isPending": false,
    "isError": false,
    "card3ds": false,
    "message": {
        "code": "COR.000.100.112",
        "merchant": "Request successfully processed in 'Merchant in Connector Test Mode'",
        "customer": "Your payments have been successfully processed in sandbox mode."
    },
    "amount": "10.0000",
    "currency": "EUR",
    "date": "2022-01-28 10:17:14",
    "resources": {
        "customerId": "s-cst-e692f3892497",
        "paymentId": "s-pay-101",
        "basketId": "s-bsk-116",
        "traceId": "585cc6669b665bb77f90a08a1db5ea68",
        "typeId": "s-piv-voi3gcbwinos"
    },
    "invoiceId": "INV-123456",
    "paymentReference": "",
    "processing": {
        "uniqueId": "31HA07BC819806096C643418C1F9D89A",
        "shortId": "5072.9143.3831",
        "traceId": "ba6df32648556affc95b39fef047ce46"
    }
}

Dunning delay (refund announcement)

This is the prior step required for refund (issued charge cancellation). The merchant announces the charge cancellation, and the fulfillment date will be moved accordingly.

Typical events are customer phone calls or printing return stickers (RMA). They help to prevent unjustified dunning of customers.

POST: https://api.unzer.com/v1/payments/s-pay-1/charges/dunning-delay

{
}

{
    "id": "s-dly-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": "0.0000",
    "currency": "EUR",
    "date": "2024-04-09 13:29:43",
    "resources": {
        "customerId": "s-cst-8cbf627620c7",
        "paymentId": "s-pay-4404",
        "basketId": "s-bsk-2c6e104c1dba",
        "metadataId": "s-mtd-nwttumjh10h6",
        "payPageId": "",
        "traceId": "cfc77817804cbd7d91c93429326f1485",
        "typeId": "s-piv-h4vaiv2bfh2a"
    },
    "orderId": "ORD-123456",
    "invoiceId": "INV-123456",
    "paymentReference": "",
    "processing": {
        "uniqueId": "Tx-oxaekrj95r2",
        "shortId": "Tx-oxaekrj95r2",
        "traceId": "cfc77817804cbd7d91c93429326f1485"
    }
}

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",
  "additionalTransactionData": {
    "shipping": {
      "returnTrackingId": "00340434286851877897",
      "deliveryService": "DHL"
    }
  }
}

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

Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
Cancel cancel = unzer.cancelCharge("s-pay-101", BigDecimal.valueOf(10.0));

The response looks similar to the following example:

{
    "id": "s-cnl-1",
    "isSuccess": true,
    "isPending": false,
    "isError": false,
    "card3ds": false,
    "message": {
        "code": "COR.000.100.112",
        "merchant": "Request successfully processed in 'Merchant in Connector Test Mode'",
        "customer": "Your payments have been successfully processed in sandbox mode."
    },
    "amount": "10.0000",
    "currency": "EUR",
    "date": "2022-01-28 10:35:58",
    "resources": {
        "customerId": "s-cst-e692f3892497",
        "paymentId": "s-pay-101",
        "basketId": "s-bsk-116",
        "traceId": "ba6df32648556affc95b39fef047ce46",
        "typeId": "s-piv-lzuw2oj57cde"
    },
    "additionalTransactionData": {
        "shipping": {
          "returnTrackingId": "00340434286851877897",
          "deliveryService": "DHL"
        }
    },
    "invoiceId": "INV-123456",
    "paymentReference": "",
    "processing": {
        "uniqueId": "31HA07BC819806096C6421B6C3D6DC32",
        "shortId": "5072.9255.8633",
        "traceId": "ba6df32648556affc95b39fef047ce46"
    }
}

The charges initialized after the authorize are actual payments and can be refunded by canceling them.

UnzerAI

Welcome to UnzerAI!

UnzerAI is currently unavailable

Manage Invoice payment

Retrieve the payment plan and the SECCI link (CCD2 compliance) (work-in-progress)

Header parameters

Request parameters

Response fields

Reauthorize the transaction

Full charge

Provide shipping information

Partial charge

Cancel before charge (reversal)

Dunning delay (refund announcement)

Cancel after charge (refund)