Unzer Docs

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

icon
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"
  }
}
icon
The reversal is always done on the initial transaction, thus the ID is always s-chg-1 or p-chg-1 respectively.

Cancel after shipment

If the customer requests a refund or cancels the order, you can execute a cancel on a charge and this amount is deducted from the transaction amount. You must always specify the reason code for a cancel.

Possible reason codes are:

reasonCode Description
CANCEL You can use CANCEL if you like to cancel a remaining amount, for instance if you are not going to ship certain goods.
RETURN RETURN is used if you want to refund a certain amount for goods the customer returned to you.
CREDIT CREDIT can be used if you want to reduce the order amount after goods are shipped, e.g. to grant a discount for defect goods.
POST https://api.unzer.com)/payments/{{order_id}}/charges/{{charge_id}}/cancels
{
  "amount" : "15",
  "reasonCode": "RETURN"
}
POST https://api.unzer.com)/payments/{{order_id}}/charges/{{charge_id}}/cancels
{
    "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": "15.0000",
    "currency": "EUR",
    "date": "2021-08-13 09:19:35",
    "resources": {
        "customerId": "s-cst-138b70861e6c",
        "paymentId": "s-pay-6985",
        "basketId": "s-bsk-4",
        "metadataId": "",
        "payPageId": "",
        "traceId": "3ced3c97f67f1b23042804547344e5f5",
        "typeId": "s-ivs-lghxo7dplglq"
    },
    "invoiceId": "INV-123456",
    "paymentReference": "your reference",
    "processing": {
        "uniqueId": "31HA07BC8109A3046EBC4A560FE00ACE",
        "shortId": "4927.7277.3621",
        "traceId": "3ced3c97f67f1b23042804547344e5f5"
    }
}

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"
  }
}
icon
The charge(s) received after the initial charge are actual inbound cash payments. You can refund these cash payments by cancelling the charges.