Orders and items

It's important to make sure you get the details of the Order creation request correct, to avoid errors with some orders. The Order creation request is POST /v1/payment/orders.

In particular, you need to ensure the amounts on each Order Item are consistent and all sum to make the total_amount of the Order, especially when rounding is taken into account.

This page details the things you need to keep in mind during the Order creation part of the integration.

The Order creation is in Step 2a of the Integration Guide.

You can provide historical data about the Customer in the order metadata to improve Hokodo's risk decisioning (see In Depth).

The 5 unbreakable rules of Order Items

Follow these 5 rules to ensure you are sending Order Items correctly.

• Include Taxes: For each item, total_amount and unit_price must include taxes.
• Sum the quantities correctly: make sure that for each item: total_amount = quantity × unit_price.
• Discounts should be added as an Order Item with a negative total amount – see Item 3 in the table below.
• Shipping should be added as an Order Item – see Item 4 in the table below.
• Round off the amount. We accept up to 5 digits after the decimal point.

Example items

Here are the calculations for an example order.

Each column in this table is an item in the order, and the final column gives the total for the total amount and for the tax.

Each quantity is in minor units, meaning cents for EUR or pence for GBP. Tax rate is a percentage.

	Item 1	Item 2	Item 3 (Discount)	Item 4 (Shipping)	Order Total
unit_price	1200	30000	-50000	111.93
quantity	5	10	1	1
total_amount	6000	300000	-50000	111.93	256111.93
tax_rate	20.00	20.00	20.00	20.00
tax_amount	1200	60000	-10000	22.386	51222.386

Example requests

Total order

The total_amount and tax_amount in the Order must be the sum of the item totals.

  ...
  "status": "pending",
  "pay_method": "directdebit",
  "currency": "GBP",
  "total_amount": 256111.93,  # total amount including tax
  "tax_amount": 51222.386,  # tax amount
  "order_date": "2021-12-25",
  "invoice_date": "2021-12-25",
  "due_date": "2022-01-25",
  ...

Item 1

Each item must have the correct total_amount = quantity × unit_price and tax_amount = total_amount × tax / 100

{
  "item_id": "1",
  "type": "product",  # or discount, shipping, etc.
  "description": "Super ergonomic chair",
  "metadata": {"color": "black", "name": "Karmus", "variant": "M"},
  "reference": "702.611.50",
  "category": "Furniture > Chairs",
  "supplier_id": "7363",
  "supplier_name": "Cool chair wholesaler",
  "quantity": "5.00",
  "unit_price": 1200,  # includes tax
  "tax_rate": "20.00",
  "total_amount": 6000,
  "tax_amount": 1200,
  "fulfilled_quantity": 0,
  "fulfillment_info": null,
  "cancelled_quantity": 0,
  "cancelled_info": null,
  "returned_quantity": 0,
  "returned_info": null
},

Item 3 - Discount

Pre-sale discounts are Order Items with negative amounts.

If you're submitting a discount post-sale, use the void endpoint, or use the refund endpoint if the order has already been captured.

{
  "item_id": "3",
  "type": "discount",  # or product, shipping, etc.
  "description": "Super discount",
  "metadata": null,
  "reference": null,
  "category": null,
  "supplier_id": null,
  "supplier_name": null,
  "quantity": "1.00",
  "unit_price": -50000,  
  "tax_rate": "20.00",
  "total_amount": -50000,
  "tax_amount": -10000,
  "fulfilled_quantity": 0,
  "fulfillment_info": null,
  "cancelled_quantity": 0,
  "cancelled_info": null,
  "returned_quantity": 0,
  "returned_info": null
},

Item 4 - Shipping

Shipping is an ordinary Order Item.

{
  "item_id": "3",
  "type": "shipping",  # or product, discount, etc.
  "description": "shipping",
  "metadata": null,
  "reference": null,
  "category": null,
  "supplier_id": null,
  "supplier_name": null,
  "quantity": "1.00",
  "unit_price": 111.93,  # includes tax
  "tax_rate": "20.00",
  "total_amount": 111.93,
  "tax_amount": 22.386,
  "fulfilled_quantity": 0,
  "fulfillment_info": null,
  "cancelled_quantity": 0,
  "cancelled_info": null,
  "returned_quantity": 0,
  "returned_info": null
}

Marketplaces: multivendor orders

If you’re a marketplace and you sometimes have a single “checkout” with a number of different vendors selling goods for that checkout, it’s important to remember to include all those different vendors' contributions to the checkout in the Hokodo order.

Submitting your Order number

You should submit a unique_id in the Order creation POST request to ensure we have a shared language with the buyer and your operations team for discussing orders. It should be the order number you use on your side.

If the order number is only created after the completion of the checkout on your platform, you can update the unique_id at that time using a PATCH request.

PATCH /v1/payment/orders/<order_id> HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "unique_id": "MERCH-31459",
}