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 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 for example, 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"
  }
}

The charge(s) received after the initial charge are actual inbound cash payments. You can refund these cash payments by cancelling the charges.