Manage Unzer Invoice Secured payment

Manage Unzer Invoice Secured payments for your customers

Full shipment

Making a shipment transaction activates the insurance. The insurance will not be activated without the shipment transaction, making it a crucial step in the process.

POST: https://api.unzer.com/v1/payments/s-pay-172586/shipments

{
  "invoiceId": "InvoiceId",
  "resources": {
    "basketId": "",
    "customerId": "s-cst-b9c6eb8605d6",
    "metadataId": "",
    "typeId": "s-ivg-68rtqpua9tte"
  }
}
$unzer = new Unzer('s-priv-xxxxxxxxxx');
$shipment = $unzer->ship('s-pay-xxxxxxxxxx', 'InvoiceId');

Unzer unzer = new Unzer("s-priv-xxxxxxxxxx");
Shipment shipment = unzer.shipment("s-pay-xxxxxxxxxx");

The response looks similar to the following example:

{
  "id": "s-shp-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",
  "date": "2021-06-03 13:56:00",
  "resources": {
    "customerId": "s-cst-b9c6eb8605d6",
    "paymentId": "s-pay-172586",
    "basketId": "",
    "metadataId": "",
    "payPageId": "",
    "traceId": "3f95b7f8e9006cfa2e6acef1d48e88bf",
    "typeId": "s-ivg-68rtqpua9tte"
  },
  "invoiceId": "InvoiceId",
  "paymentReference": "",
  "processing": {
    "uniqueId": "31HA07BC8184FB9FAC1832879C77091B",
    "shortId": "4866.5496.0065",
    "traceId": "3f95b7f8e9006cfa2e6acef1d48e88bf"
  }
}

With the insurance activated you will receive the money regardless if the customer pays or not.
The customer has a specific time to transfer the money. The length of this period may differ depending on the merchant configuration at Unzer.

Partial shipment

If you ship only some of the goods and make a partial shipment transaction, the balance amount from the charge is automatically canceled. In the example below, from the total charge of 55 EUR if you ship goods for 50 EUR, the balance 5 EUR is automatically canceled.

POST: https://api.unzer.com/v1/payments/s-pay-172586/shipments

{
  "invoiceId": "InvoiceId",
  "amount": 50.0,
  "resources": {
    "basketId": "",
    "customerId": "s-cst-b9c6eb8605d6",
    "metadataId": "",
    "typeId": "s-ivs-68rtqpua9tte"
  }
}
Partial shipment is not yet available with the PHP SDK.

Partial shipment is not yet available with the Java SDK.

The response looks similar to the following example:

{
  "id": "s-shp-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",
  "date": "2021-06-04 11:42:35",
  "resources": {
    "customerId": "s-cst-57c85aa3944f",
    "paymentId": "s-pay-172783",
    "basketId": "s-bsk-41228",
    "metadataId": "",
    "payPageId": "",
    "traceId": "87247d0ad11ce9d7bc0c75de12d569b0",
    "typeId": "s-ivs-68rtqpua9tte"
  },
  "orderId": "b16228069443756",
  "invoiceId": "i16228069541852",
  "paymentReference": "",
  "processing": {
    "uniqueId": "31HA07BC8198C2F9107E47BA236150C2",
    "shortId": "4867.3335.5395",
    "traceId": "87247d0ad11ce9d7bc0c75de12d569b0"
  }
}

Cancel before money receipt (reversal)

If the customer returns an item from the order or cancels it all together, before the money has been received, then this amount is deducted from the charge amount. The shipment is now only applicable for the reduced charge amount. In the following example, if the customer cancels goods worth 15 EUR, it is deducted from the total amount of 70 EUR and 55 EUR is now the updated total amount.

Note that you must always specify a valid reason for cancel with Invoice Secured.
Reason code Description
CANCEL The customer cancels the order
RETURN The customer returns the goods
CREDIT The merchant (you) gives credit to the customer
POST: https://api.unzer.com/v1/payments/s-pay-xxxxxxx/charges/s-chg-1/cancels

{
  "amount": 50.0,
  "paymentReference": "Test cancel transaction",
  "reasonCode": "CANCEL",
  "resources": {
    "basketId": "s-bsk-41226",
    "customerId": "s-cst-a6debd8ba7f6",
    "metadataId": "",
    "typeId": "s-ivs-weohgfturjfa"
  }
}
$cancellation = $unzer->cancelChargeById(
  's-pay-xxxxxxxxx,
  's-chg-1',
  50.0,
  CancelReasonCodes::REASON_CODE_CANCEL
);

Cancel reasons are currently not supported by the Java SDK.

The response looks similar to the following example:

{
  "id": "s-cnl-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",
  "date": "2021-06-04 08:49:34",
  "resources": {
    "customerId": "s-cst-0d269aff3552",
    "paymentId": "s-pay-172781",
    "basketId": "s-bsk-41227",
    "metadataId": "",
    "payPageId": "",
    "traceId": "d271acb67f25789b4da04c99190f2625",
    "typeId": "s-ivs-yhgpu0g6xx5c"
  },
  "orderId": "b16227965643249",
  "paymentReference": "Test cancel transaction",
  "processing": {
    "uniqueId": "31HA07BC8198C2F9107E3ACB038A1EBB",
    "shortId": "4867.2297.4229",
    "traceId": "d271acb67f25789b4da04c99190f2625"
  }
}
The reversal is always done on the initial transaction, thus the ID is always s-chg-1 or p-chg-1 respectively.

Cancel after money receipt (refund)

In case you already received a payment for an order the customer wants to cancel, you can refund it up to the amount of the received payments. To do this you have to make a cancel transaction on charge(s) received via notification.

POST: https://api.unzer.com/v1/payments/s-pay-xxxxxxx/charges/s-chg-2/cancels

{
  "amount": 50.0,
  "paymentReference": "Test cancel transaction",
  "reasonCode": "CANCEL",
  "resources": {
    "basketId": "s-bsk-41226",
    "customerId": "s-cst-a6debd8ba7f6",
    "metadataId": "",
    "typeId": "s-ivs-weohgfturjfa"
  }
}
$cancellation = $unzer->cancelChargeById(
  's-pay-xxxxxxxxx,
  's-chg-2',
  50.0
  CancelReasonCodes::REASON_CODE_RETURN,
  'Test cancel transaction'
);
Cancel reasons are currently not supported by the Java SDK.

The response looks similar to the following example:

{
  "id": "s-cnl-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",
  "date": "2021-06-04 08:49:34",
  "resources": {
    "customerId": "s-cst-0d269aff3552",
    "paymentId": "s-pay-172781",
    "basketId": "s-bsk-41227",
    "metadataId": "",
    "payPageId": "",
    "traceId": "d271acb67f25789b4da04c99190f2625",
    "typeId": "s-ivs-yhgpu0g6xx5c"
  },
  "orderId": "b16227965643249",
  "paymentReference": "Test cancel transaction",
  "processing": {
    "uniqueId": "31HA07BC8198C2F9107E3ACB038A1EBB",
    "shortId": "4867.2297.4229",
    "traceId": "d271acb67f25789b4da04c99190f2625"
  }
}
The charge received after the initial charge are actual payments and if required, you can refund them by canceling.