Unzer Docs

Manage Unzer Invoice payment

Manage Unzer Invoice payments for your customers

icon

If you are using payment types invoice or invoice-secured, note that these methods are now deprecated. They are currently supported but there are no further developments planned for them.

If you want to access the relevant documentation, see Unzer Invoice and Unzer Invoice Secured.

After the successful authorize transaction, you can perform additional operations on the payment resource. Below you can see the most important cases for Unzer Invoice. For a full reference of managing payments, please refer to the 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 very crucial API call and it 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

{
}
Currently not supported
Currently not supported

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"
        }
}

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 very crucial API call and it 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",
}
Currently not supported
Currently not supported

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.

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

{
}
Currently not supported
Currently not supported

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"
    }
}

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"
    }
  }
}
Currently not supported
Currently not supported

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"
    }
}
icon
The charges initialized after the authorize are actual payments and can be refunded by canceling them.