NAV
HTTP cURL

Introduction

Hokodo provides a set of API endpoints to facilitate Deferred Payments, also known as credit terms, or "Buy Now, Pay Later" (BNPL) for B2B platforms, such as marketplaces or e-commerce sites.

This reference documentation details how developers may use Hokodo to implement credit terms into their customer journey, from checking whether a customer can be eligible for credit terms, to submitting a customer's orders to Hokodo. Hokodo APIs are organized around REST, with predictable, resource-oriented URLs, and use HTTP response codes to indicate API errors.

Our API expects incoming data to be valid JSON objects with requests containing the header Content-Type: application/json, unless explicitly stated otherwise.

All responses of the API, including errors, are in JSON, except for some endpoints returning PDF documents, Excel files or CSV files, that will be clearly indicated as such.

You can view request/response examples in the dark area to the right, and you can switch between raw representation and curl command with tabs in the top right.

The base URL of the API in the sandbox (see environments) is https://api-sandbox.hokodo.co/

What is BNPL?

BNPL (Buy Now Pay Later) or Deferred Payment are different names for the same thing. They refer to a feature at your checkout whereby customers can complete their purchase without having to pay for the purchase upfront. Instead, they are granted “credit terms” by Hokodo meaning they settle the purchase a number of days later. Hokodo offers different payment options such as “Pay in 30 days” or “Pay at end of month”, and we will configure one or more of these payment options to be available to your customers as part of your onboarding process. 

Although your customers may be paying 30 days or more after the purchase, as a merchant you will get paid following your shipment of the goods (fulfillment). 

Hokodo's service comprises:

All this is available via our REST APIs, making for straightforward integration.

Quickstart guide

In this section we talk through the key steps you will go through (and the associated API calls) to put in place a deferred payment facility for one of your customers.

Identify your customer's company

Hokodo's solutions are available for B2B customers. In other words, we don't provide deferred payment to consumers, but only to registered companies (and in some cases sole traders). This means that we need to be clear on which legal entity your customer represents.

In some cases our merchants already collect a unique identifier like a UK Companies House number or a French SIREN, in which case you can use our Companies endpoint to obtain Hokodo's unique identifier for this firm. More frequently people just have a free text name of the company, in which case the same endpoint will provide a search functionality to allow you (or your customer) to identify the correct legal entity.

Create the User and Organisation

When one of your customers wishes to benefit from Deferred Payment, we need you to tell us which individual at the company is making the purchase. To do this you create a User. The user will typically correspond to a unique login on your platform (e.g. an e-mail address).

Because some of our merchants' B2B customers include quite large companies, we allow them to create Organisations, which are groups of users who all work for the same company (for example a particular branch or department of the company). All the users within an organisation will share information about the Deferred Payments any of them have made, any cards or direct debit mandates any of them have set up etc. For small companies there may just be a single Organisation covering the whole company.

Steps 1 and 2 only need to be done once for any given user or company. The steps below take place each time a customer navigates to your checkout to make a purchase.

Tell Hokodo about the basket being purchased (Order) and get Deferred Payment Offers

In order to find out whether a particular purchase is going to be eligible for Deferred Payment you need to provide Hokodo with the details of the purchase. You do this by creating an Order. The Order endpoint allows you to provide information such as the contents of the basket, the gross/net order value, and the identity of the customer.

Once the order has been created, you can then use the Payment Offers endpoint to find out what Deferred Payment terms are available for this Order. Hokodo will return a list of the payment terms that are available (if any) – for example: Pay in 30 days, Pay in installments, along with details of each (for example what the payment due date(s) will be). You are then able to present these options for your customer to select from on the check-out page.

Creation of the Deferred Payment

When your customer clicks on one of the Deferred Payment options (e.g. Pay in 30 days) you will redirect them to the URL that Hokodo provided you as part of the Payment Offer response. This will take the customer to Hokodo's Payment confirmation page, where the customer will be able to confirm their acceptance of deferred payment and provide any additional information we need from them (e.g. approving a direct debit mandate).

Once this has happened, we will redirect the customer back to your site (typically to a confirmation page, where you will confirm completion of the purchase).

The act of the customer clicking the Deferred Payment option will create a Deferred Payment object, which is the way we manage the payment obligation through its lifecycle.

Fulfillment

Finally, at some point after your customer completes the purchase, you will ship the goods to the customer (or deliver your service). We refer to this as Fulfillment. Once this has happened, you notify Hokodo of fulfillment, and this is our trigger for settling payment to you.

At this point the journey is complete. We now take care of collecting payment from the customer and dealing with any non-payment issues.

Beyond this “core” journey, Hokodo also provides API endpoints for a range of other situations such as:

All of these are described in more detail in the relevant sections of the documentation.

Glossary

In the document, we will use the following terms, with a specific meaning:

Organisations and Users

Because Hokodo focuses on B2B sales, the buyers on your platform will consist of Companies, who have employees, and those employees may be organised into teams or departments. Hokodo deals with this complexity through the concept of Organisations and Users.

A User is an individual employee at a company.
An Organisation is a group of Users who are all able to see or take action on that company's orders on your platform. Each Organisation must be associated with a Company.

In many cases the company will just have a single Organisation, and any employees of the company (Users) will be members of that Organisation. In this case, any one of those Users will be able to see or take actions on any of the company's orders on your platform. For example, if a member of the Organisation has set up a direct debit mandate, then any other member of that Organisation can make purchases using the mandate.

In other cases (for larger companies), there may be several Organisations - perhaps one associated to each department in the company. In this case, Users can only see the orders associated with their Organisation.

Authorization

To authentify pass the correct header with each request:

GET /v1/me HTTP/1.1
Authorization: Token <your_api_key>
curl --request GET \
  --url https://api-sandbox.hokodo.co/v1/me/ \
  --header "Authorization: Token <your_api_key>"

Make sure to replace <your_api_key> with your API key from https://sandbox.hokodo.co.

Use your secret key in your API requests. You can manage your keys in your Developer dashboard. Be sure to keep your key secure and do not share it in publicly-accessible areas, such as GitHub, in your client-side Javascript code, etc.

Authorization to the API is done by providing the key in Authorization header preceded by Token keyword. The API key can also be provided as user with no password through HTTP Basic Auth.

All API requests must be made over HTTPS. Calls made over plain HTTP or without proper authentication will fail.

Testing the API

Please make sure to test your integration thoroughly in our sandbox before going live. After registering, you will be given your test API keys. Those are safe to use for development. When you are ready, make sure to replace those keys with live ones.

While testing, the API will not return real credit approvals and limits. If you want to simulate how well we can cover your clients, please do not hesitate to get in touch with our team at support@hokodo.co.

API versioning

The BNPL API is in version beta. Your feedback is most appreciated for any improvement.

Backwards compatible changes are made regularly to improve the API. You can find the changelog in the partner dashboard.

Pagination

For example to get 10 orders starting with the 51st order:

GET /v1/payment/orders/?limit=10&offset=50 HTTP/1.1
curl --request GET \
  --url https://api-sandbox.hokodo.co/v1/payment/orders/?limit=10&offset=50 \
  --header "Authorization: Token <your_api_key>"

The answer is a JSON looking like this:

{
    "count": 95,  # Total number of orders
    "next": "http://api-sandbox.hokodo.co/v1/payment/orders/?limit=10&offset=60",
    "previous": null,
    "results": [
        {
            ... # 51st order in the list
        },
        {
            ... # 52nd order in the list
        },
        ...
    ]
}

The API returns paginated results, for list endpoints where the response might contain many items in a large list. By default, the number of items returned is 25.

You can control the page size and position by using the query parameters limit and offset. limit controls the number of items displayed, offset the index of the first item of the list, starting from 0. The defaults if no value is passed are thus offset=0 and limit=25.

See examples on the right.

Expansion

For example let's consider the following request:

GET /v1/payment/offers/offer-kEFDnwu8cnkETeagWAcqF4 HTTP/1.1
curl --request GET \
  --url https://api-sandbox.hokodo.co/v1/payment/offers/offer-kEFDnwu8cnkETeagWAcqF4 \
  --header "Authorization: Token <your_api_key>"

It's returning the following JSON response (compacted for the example):

{
    "url": "http://api-sandbox.hokodo.co/v1/payment/offers/offer-kEFDnwu8cnkETeagWAcqF4",
    "id": "offer-kEFDnwu8cnkETeagWAcqF4",
    "order": "order-TiehJCGZmFRkKoL8NsM3d6",
    "status": "accepted",
    ...  # Other payment offer fields
}

We can use ?expand=order for example:

GET /v1/payment/offers/offer-kEFDnwu8cnkETeagWAcqF4?expand=order HTTP/1.1
curl --request GET \
  --url https://api-sandbox.hokodo.co/v1/payment/offers/offer-kEFDnwu8cnkETeagWAcqF4?expand=order \
  --header "Authorization: Token <your_api_key>"

As a response we get:

{
    "url": "http://api-sandbox.hokodo.co/v1/payment/offers/offer-kEFDnwu8cnkETeagWAcqF4",
    "id": "quo-kEFDnwu8cnkETeagWAcqF4",
    "order": {
        "id": "order-TiehJCGZmFRkKoL8NsM3d6",
        ...  # Other order fields
    },
    "status": "accepted",
    ...  # Other payment offer fields
}

The API returns some items as API identifiers. The designated resource can be expanded, meaning that the identifier is replaced in the response with a dictionary representing the resource itself. You can control which field is expanded using the query parameter expand. Expected value is a comma separated list of field names, for example ?expand=order,payment.

Note: At the moment, only read requests can use expansion. You can't use resource expansion for requests where you create and modify resources.

See examples on the right.

Environments

Test environment (aka Sandbox)

Register at: https://sandbox.hokodo.co
API base URL: https://api-sandbox.hokodo.co/

This is the test environment for our API clients, where you can integrate your own software with our API without consequences. It will always run the same version(s), expect the same request format and return the same response format as the production environment.

Data such as credit scores or payment offers will not be real however, and no payment is provided. Non-sensitive data, such as companies search, will be as close as possible to the production data.

Production

Apply at: https://www.hokodo.co/contact
API base URL: https://api.hokodo.co/

This is the live, production environment, where:

Data formats

Countries

Requests

  • buyer countries
GET /v1/countries/debtor HTTP/1.1
curl --request GET \
    --url https://api-sandbox.hokodo.co/v1/countries/debtor

Response

200 Ok
Content-Type: application/json
[
  {
    "code": "GB",
    "name": "United Kingdom"
  },
  {
    "code": "FR",
    "name": "France"
  }
]

Where a country input field is required by the API, you can use either the ISO 3166-1 alpha-2 code or the country's name. See below on how to obtain a full list of accepted countries.

Obtain a list of valid countries for a buyer/customer.

Dates and times

When a date, or date and time field is required by the API, it is expected in ISO 8601 notation, for example:

Type Format Example
Date yyyy-mm-dd 2018-10-31
Datetime yyyy-mm-ddThh:mm:ss.ffffff 2018-10-31T16:53:00.12345
Datetime UTC yyyy-mm-ddThh:mm:ss.ffffffZ 2018-10-31T16:53:00.12345Z

For order issue and due dates for example, there is no time associated and the API expects only a date, no time nor timezone. Be careful if you are internally converting a datetime with timezone to a date, e.g. 2018-10-31T00:00:00+02:00 could become 2018-10-30T22:00:00Z when converted to UTC and then 2018-10-30 in the request to the API, which wouldn't fit the user input.

Currencies

When a currency field is used by the API, it is an ISO 4217 code, such as GBP, EUR or USD.

Amounts

When a money amount is expected or returned by the API, it is always in minor units, ie cents. For example:

Companies

Companies represent the legal entities associated with your customers. To be able to provide accurate credit approval and limits, and payment plans, we need to properly identify the companies.

If you already store a unique company identifier such as a Companies House number (UK) or SIREN (France) then you can use our Companies endpoint to obtain the Hokodo ID for the company.

More commonly, however, merchants simply store a free text name for their customers' companies. Because there can often be many different companies with similar sounding names (including different subsidiaries of the same parent), we typically recommend adopting the following process to make sure you are supplying the correct company identifiers:

  1. presenting your user with text box(es), where they can enter their company's name, and/or address, and/or registration number,
  2. using that information in our company search API, to obtain a list of companies which are potential matches to the text you supplied.
  3. asking the user to pick among the choices our company search API has returned.

Companies endpoints

Company object

{
  "url": "https://api-sandbox.hokodo.co/v1/companies/co-bqRyKAGaFrEEN8JMjWJiqk",
  "id": "co-bqRyKAGaFrEEN8JMjWJiqk",
  "name": "Hokodo Ltd",
  "creation_date": "2018-02-20",
  "status": "Active",
  "legal_form": "Private limited with share capital",
  "country": "GB",
  "address": "35 Kingsland Road, London, E2 8AA",
  "city": "London",
  "postcode": "E2 8AA",
  "email": "",
  "phone": "",
  "sectors": [
    {
      "system": "SIC2007",
      "code": "64999"
    },
    {
      "system": "SIC2007",
      "code": "62012"
    },
    {
      "system": "SIC2007",
      "code": "66220"
    }
  ],
  "identifiers": [
    {
      "idtype": "reg_number",
      "country": "GB",
      "value": "11215527"
    }
  ]
}
field type description
url string API endpoint to access the company
id string(uuid) API unique identifier for the company
name string Company name
creation_date date Date of inception of the company
status string Current status of the company. You are generally interested about Active or ACT companies
legal_form string Legal form of the company. The list of possible legal forms varies from country to country.
country country Registered address: country code
address string Registered address: full postal address
city string Registered address: city name
postcode string Registered address: postcode
email string Contact email address for the company
phone string Contact phone number for the company
sectors list The list of sectors the company operate in.
sectors[*][system] string The system of reference to interprete the code (SIC2007 in UK, NAF_2008 in FR)
sectors[*][code] string Sector code in the given system
identifiers list The list of official identifiers know for this company, e.g. Companies House registration number, VAT number, etc.
identifiers[*][id_type] string The type of identifier (reg_number for a registration number, lei for an indentifier of the Global LEI System, vat_number for a tax identifier)
identifiers[*][country] country Country in which the identifier is relevant when it applies. Can be blank.
identifiers[*][value] string Identifier

Request

POST /v1/companies/search HTTP/1.1
Content-Type: application/json

{
  "name": "Hokodo Ltd",
  "country": "GB"
}
curl --request POST \
  --url https://api-sandbox.hokodo.co/v1/companies/search \
  --header "Content-Type: application/json"
  --data-binary "{
    \"name\": \"Hokodo Ltd\",
    \"country\": \"GB\"
}"

Responses

  • regular response
200 OK
Content-Type: application/json
{
  "matches": [
    {
      "url": "https://api-sandbox.hokodo.co/v1/companies/co-EWzoaRqbvsdq8FW7dB6evL",
      "id": "co-EWzoaRqbvsdq8FW7dB6evL",
      "country": "GB",
      "name": "HOKODO LTD",
      "address": "35 Kingsland Road, London, United Kingdom, E2 8AA",
      "city": "London",
      "postcode": "E2 8AA",
      "legal_form": "",
      "sectors": [],
      "creation_date": "2018-02-20",
      "identifiers": [
        {
          "idtype": "reg_number",
          "country": "GB",
          "value": "11215527"
        }
      ],
      "email": "",
      "phone": "",
      "status": "Undefined",
      "confidence": null
    },
    {
      "url": "https://api-sandbox.hokodo.co/v1/companies/co-JbTDrzejAhRafYrKSFEGi4",
      "id": "co-JbTDrzejAhRafYrKSFEGi4",
      "country": "GB",
      "name": "Hokodo Services Ltd",
      "address": "35 Kingsland Road, London, E2 8AA",
      "city": "London",
      "postcode": "E2 8AA",
      "legal_form": "Private limited with share capital",
      "sectors": [],
      "creation_date": "2018-05-09",
      "identifiers": [
        {
          "idtype": "reg_number",
          "country": "GB",
          "value": "11351988"
        }
      ],
      "email": "",
      "phone": "",
      "status": "Active",
      "confidence": null
    }
  ]
}
  • no results
200 OK
Content-Type: application/json
{
  "matches": []
}
  • error response (country field missing)
{
  "country": [
    "This field is required."
  ]
}
  • error response (name and reg_number fields missing)
400 Bad Request
Content-Type: application/json
{
  "non_field_errors": [
    "Not enough information to identify company. Provide at least country and either name or registration number."
  ]
}

Search for a company by country, name, registration number if available. Country is mandatory, and one of name or registration number must be provided. The API will try to find the best match and return a list of potential matches.

field description requirement
country Country the company is registered in required
name Name of the company required *
reg_number Registration number in country required *
address Address of the company optional

(at least one of fields, marked with * is required)

Errors:

code description
400 a required field is missing

View Company

Request

GET /v1/companies/{company_id} HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>
curl --request POST \
  --url https://api-sandbox.hokodo.co/v1/companies/{company_id} \
  --header "Authorization: Token <your_api_key>"
  --header "Content-Type: application/json"

Responses

  • regular response
200 OK
Content-Type: application/json
{
  "url": "https://api-sandbox.hokodo.co/v1/companies/co-EWzoaRqbvsdq8FW7dB6evL",
  "id": "co-EWzoaRqbvsdq8FW7dB6evL",
  "country": "GB",
  "name": "HOKODO LTD",
  "address": "35 Kingsland Road, London, United Kingdom, E2 8AA",
  "city": "London",
  "postcode": "E2 8AA",
  "legal_form": "",
  "sectors": [],
  "creation_date": "2018-02-20",
  "identifiers": [
    {
      "idtype": "reg_number",
      "country": "GB",
      "value": "11215527"
    }
  ],
  "email": "",
  "phone": "",
  "status": "Undefined",
}
  • not found
404 Not Found
Content-Type: application/json
{
  "detail": "Not found."
}

Look up a previously found company.

Errors:

code description
404 the company_id is probably invalid, and the company has not been found

Organisations

Organisation concept

Because Hokodo focuses on B2B sales, the buyers on your platform will consist of Companies, who have employees, and those employees may be organised into teams or departments. Hokodo deals with this complexity through the concept of Organisations and Users. A User is an individual employee at a company. An Organisation is a group of Users who are all able to see or take action on that company's orders on your platform. Each Organisation must be associated with a Company.

In many cases the company will just have a single Organisation, and any employees of the company (Users) will be members of that Organisation. In this case, any one of those Users will be able to see or take actions on any of the company's orders on your platform. For example, if a member of the Organisation has set up a direct debit mandate, then any other member of that Organisation can make purchases using the mandate.

In other cases (for larger companies), there may be several Organisations - perhaps one associated to each department in the company. In this case, Users can only see the Orders associated with their Organisation.

It is also possible for a single user to be a member of several Organisations. For example, a company director may make purchases on behalf of several companies which he's a director of. In this case his User would be associated with each of those Organisations. The user, members of the organisation, can have different roles and permissions.

The organisation provides us with important information to

This is a typical API flow to use organisations:

User roles within organisations

Users can have one of the following roles in an organisation:

Organisation endpoints

Organisation object

{
  "id": "org-9RxFsXTgnWqwjK4apxBAn8",
  "unique_id": "c105b862-f1ba-4197-9d97-57db63196b00",
  "registered": "2017-06-01T14:37:12Z",
  "company": null,
  "users": []
}
field type flags description
id string(uuid) read-only API unique identifier for the organisation
unique_id string required Unique identifier of the organisation on your platform
registered datetime required When the organisation registered on your platform
company string optional Hokodo unique identifier of the company
users list read-only List of users attached to the organisation

Note that registered is the organisation's registration date on your platform, not with Hokodo.

Create an organisation

Request

POST /v1/organisations HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "unique_id": "c105b862-f1ba-4197-9d97-57db63196b00",
  "registered": "2017-06-01T14:37:12Z",
  "company": "co-bqRyKAGaFrEEN8JMjWJiqk"
}
curl --request POST
  --url https://api-sandbox.hokodo.co/v1/organisations \
  --header "Authorization: Token <your_api_key>" \
  --header "Content-Type: application/json" \
  --data-binary "{
    \"unique_id\": \"c105b862-f1ba-4197-9d97-57db63196b00\",
    \"registered\": \"2017-06-01T14:37:12Z"\,
    \"company\": \"co-bqRyKAGaFrEEN8JMjWJiqk\"
}"

Responses

  • organisation created successfully
201 Created
Content-Type: application/json
{
  "id": "org-pHr6VCyzQJALUsePkatPBo",
  "unique_id": "c105b862-f1ba-4197-9d97-57db63196b00",
  "registered": "2017-06-01T14:37:12Z",
  "company": "co-bqRyKAGaFrEEN8JMjWJiqk",
  "users": []
}
  • organisation already exists (identified by unique_id), it is updated
200 Ok
Content-Type: application/json
{
  "id": "org-pHr6VCyzQJALUsePkatPBo",
  "unique_id": "c105b862-f1ba-4197-9d97-57db63196b00",
  "registered": "2017-06-01T14:37:12Z",
  "company": "co-bqRyKAGaFrEEN8JMjWJiqk",
  "users": []
}

To create an organisation, you create an Organisation object.

Errors

errors description
400 a required field is missing or a field has incorrect format

List organisations

Request

GET /v1/organisations HTTP/1.1
Authorization: Token <your_api_key>
curl --request GET
  --url https://api-sandbox.hokodo.co/v1/organisations \
  --header "Authorization: Token <your_api_key>"

Response

200 Ok
Content-Type: application/json
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "org-pHr6VCyzQJALUsePkatPBo",
      "unique_id": "c105b862-f1ba-4197-9d97-57db63196b00",
      "registered": "2017-06-01T14:37:12Z",
      "company": "co-bqRyKAGaFrEEN8JMjWJiqk",
      "users": []
    }
  ]
}

List organisations created by your platform

View organisation

Request

GET /v1/organisations/<organisation_id> HTTP/1.1
Authorization: Token <your_api_key>
curl --request GET
  --url https://api-sandbox.hokodo.co/v1/organisations/org-pHr6VCyzQJALUsePkatPBo \
  --header "Authorization: Token <your_api_key>"

Response

200 Ok
Content-Type: application/json
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "org-pHr6VCyzQJALUsePkatPBo",
      "unique_id": "c105b862-f1ba-4197-9d97-57db63196b00",
      "registered": "2017-06-01T14:37:12Z",
      "company": "co-bqRyKAGaFrEEN8JMjWJiqk",
      "users": []
    }
  ]
}

Retrieve an organisation created by your platform

Errors

errors description
404 the organisation_id is probably invalid, the organisation has not been found

Modify organisation

Request

PATCH /v1/organisations/<organisation_id> HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "unique_id": "c105b862-f1ba-4197-9d97-57db63196b01",
  "registered": "2018-06-01T14:37:12Z",
  "company": "co-bqRyKAGaFrEEN8JMjWJiqk"
}
curl --request PATCH
  --url https://api-sandbox.hokodo.co/v1/organisations/org-pHr6VCyzQJALUsePkatPBo \
  --header "Authorization: Token <your_api_key>" \
  --header "Content-Type: application/json" \
  --data-binary "{
    \"unique_id\": \"c105b862-f1ba-4197-9d97-57db63196b01\",
    \"registered\": \"2018-06-01T14:37:12Z"\,
    \"company\": \"co-bqRyKAGaFrEEN8JMjWJiqk\"
}"

Response

200 Ok
Content-Type: application/json
{
  "id": "org-pHr6VCyzQJALUsePkatPBo",
  "unique_id": "c105b862-f1ba-4197-9d97-57db63196b01",
  "registered": "2018-06-01T14:37:12Z",
  "company": "co-bqRyKAGaFrEEN8JMjWJiqk",
  "users": []
}

Modify an organisation created by your platform

Errors

errors description
404 the organisation_id is probably invalid, the organisation has not been found
400 a required field is missing or a field has incorrect format

Delete an organisation

Request

DELETE /v1/organisations/<organisation_id> HTTP/1.1
Authorization: Token <your_api_key>
curl --request DELETE
  --url https://api-sandbox.hokodo.co/v1/organisations/org-pHr6VCyzQJALUsePkatPBo \
  --header "Authorization: Token <your_api_key>"

Responses

  • regular response
204 No Content
  • can not delete organisation, it has objects attached
409 Conflict
Content-Type: application/json
{
  "detail": "Organisation has undeletable objects attached, it cannot be deleted."
}

Delete an organisation created by your platform. Please note, that you can not delete an organisation that has payment-related objects attached to it (such as deferred payments or offers, etc.)

Errors

errors description
404 the organisation_id is probably invalid, the organisation has not been found
409 an organisation can not be deleted because it has objects attached to it

Manage users in organisation

Our API provides two alternative endpoint collections to manage relation between users and organisations. Below is the list of methods from the perspective of an organisation. For the list of methods from the perspective of a user, please refer to section Manage organisations of user

Organisation users endpoints

Organisation user object

{
  "id": "user-mECT3e5n9i7gVGrbn2Pd38",
  "email": "johnny@hokodo.co",
  "role": "admin"
}
field type flags description
id string(uuid) required API unique identifier for the user
email string read-only Email of the user
role role required Role of the user in the organisation

Add user to organisation

Request

POST /v1/organisations/<organisation_id>/users HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "id": "user-mECT3e5n9i7gVGrbn2Pd38",
  "role": "admin"
}
curl --request POST
  --url https://api-sandbox.hokodo.co/v1/organisations/org-pHr6VCyzQJALUsePkatPBo/users \
  --header "Authorization: Token <your_api_key>" \
  --header "Content-Type: application/json" \
  --data-binary "{
    \"id\": \"user-mECT3e5n9i7gVGrbn2Pd38\",
    \"role\": \"admin"\
}'

Responses

  • regular response
201 Created
Content-Type: application/json
{
  "id": "user-mECT3e5n9i7gVGrbn2Pd38",
  "email": "johnny@hokodo.co",
  "role": "admin"
}
  • user already added to the organisation
200 Ok
Content-Type: application/json
{
  "id": "user-mECT3e5n9i7gVGrbn2Pd38",
  "email": "johnny@hokodo.co",
  "role": "admin"
}
  • error (user not found and/or incorrect user role)
400 Bad Request
Content-Type: application/json
{
  "id": [
    "Invalid pk \"user-mECT3e5n9i7gVGrbn2Pd39\" - object does not exist."
  ],
  "role": [
    "\"reader\" is not a valid choice."
  ]
}

Attach previously created user to the organisation. When a user is already added to the organisation, but a different role is provided in the request, his existing role will be updated.

Users can have one of the following roles in an organisation:

To create a user, see the relevant section.

Errors

errors description
400 a required field is missing or a field has incorrect format

View users of organisation

Request

GET /v1/organisations/<organisation_id>/users HTTP/1.1
Authorization: Token <your_api_key>
curl --request GET
  --url https://api-sandbox.hokodo.co/v1/organisations/org-pHr6VCyzQJALUsePkatPBo/users \
  --header "Authorization: Token <your_api_key>"

Response

200 Ok
Content-Type: application/json
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "user-mECT3e5n9i7gVGrbn2Pd38",
      "email": "johnny@hokodo.co",
      "role": "admin"
    }
  ]
}

List all current users of an organisation

View individual user of organisation

Request

GET /v1/organisations/<organisation_id>/users/<user_id> HTTP/1.1
Authorization: Token <your_api_key>
curl --request GET
  --url https://api-sandbox.hokodo.co/v1/organisations/org-pHr6VCyzQJALUsePkatPBo/users/user-mECT3e5n9i7gVGrbn2Pd38 \
  --header "Authorization: Token <your_api_key>"

Response

200 Ok
Content-Type: application/json
{
  "id": "user-mECT3e5n9i7gVGrbn2Pd38",
  "email": "johnny@hokodo.co",
  "role": "admin"
}

Retrieve one specific user of an organisation

Errors

errors description
404 the user_id is probably invalid, the user has not been found

Modify user role in organisation

Request

PATCH /v1/organisations/<organisation_id>/users/<user_id> HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "role": "member"
}
curl --request POST
  --url https://api-sandbox.hokodo.co/v1/organisations/org-pHr6VCyzQJALUsePkatPBo/users/user-mECT3e5n9i7gVGrbn2Pd38 \
  --header "Authorization: Token <your_api_key>" \
  --header "Content-Type: application/json" \
  --data-binary "{
    \"role\": \"member"\
}'

Responses

  • regular response
200 Ok
Content-Type: application/json
{
  "id": "user-mECT3e5n9i7gVGrbn2Pd38",
  "email": "johnny@hokodo.co",
  "role": "member"
}
  • error (incorrect user role)
400 Bad Request
Content-Type: application/json
{
  "role": [
    "\"reader\" is not a valid choice."
  ]
}

Modify the role of a specific user in an organisation

Errors

errors description
400 the role field is missing or has incorrect value

Remove user from organisation

Request

DELETE /v1/organisations/<organisation_id>/users/<user_id> HTTP/1.1
Authorization: Token <your_api_key>
curl --request DELETE
  --url https://api-sandbox.hokodo.co/v1/organisations/org-pHr6VCyzQJALUsePkatPBo/users/user-mECT3e5n9i7gVGrbn2Pd38 \
  --header "Authorization: Token <your_api_key>"

Response

204 No Content

Remove one specific user from the organisation

Errors

errors description
404 the user_id is probably invalid, the user has not been found

Users

Users represent the individual customers on your platform. They are associated to one or multiple organisations, which themselves represent the company of these customers. A user can have different roles and permissions in each organisation.

Users not linked to an organisation cannot access orders, payment offers or deferred payments. Therefore we suggest creating the organisation first, then create users linked to the organisation with the proper role.

User endpoints

User object

{
  "id": "user-VG4i93EPLRamVFK6oXpvt9",
  "email": "johnny@hokodo.co",
  "email_validated": True,
  "unique_id": "",
  "name": "John",
  "phone": "",
  "registered": "2017-06-01T14:37:12Z",
  "organisations": [
    {
      "id": "org-FEjrdMsmhdNp34HxaZ6n63",
      "role": "member"
    }
  ]
}
field type flags description
id string(uuid) read-only API unique identifier for the user
email string required Email of the user
email_validated boolean required Has the email address already been validated by your platform
unique_id string optional Unique identifier of the user on your platform (currently we don't validate its uniqueness and store it for your reference only)
name string required Full name of the user
phone string optional Phone number of the user
registered datetime required Date of user registration on your platform
organisations list optional List of organisations to which the user is linked
organisations[*][id] string(uuid) required API identifier of the organisation
organisations[*][role] role required Role of the user in the organisation

Note that registered is the user's registration date on your platform, not with Hokodo.

Create a user

Request

POST /v1/users HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "name": "John",
  "email": "johnny@hokodo.co",
  "registered": "2017-06-01T14:37:12Z",
  "organisations": [
    {
      "id": "org-FEjrdMsmhdNp34HxaZ6n63",
      "role": "member"
    }
  ]
}
curl --request POST \
  --url https://api-sandbox.hokodo.co/v1/users \
  --header "Authorization: Token <your_api_key>"
  --header "Content-Type: application/json"
  --data-binary="{
    \"name\": \"John\",
    \"email\": \"johnny@hokodo.co\",
    \"registered\": \"2017-06-01T14:37:12Z\",
    \"organisations\": [
      {
        \"id\": \"org-FEjrdMsmhdNp34HxaZ6n63\",
        \"role\": \"member\"
      }
    ]
}"

Response

  • regular response
201 Created
Content-Type: application/json
{
  "id": "user-VG4i93EPLRamVFK6oXpvt9",
  "email": "johnny@hokodo.co",
  "unique_id": "",
  "name": "John",
  "phone": "",
  "registered": "2017-06-01T14:37:12Z",
  "organisations": [
    {
      "id": "org-FEjrdMsmhdNp34HxaZ6n63",
      "role": "member"
    }
  ]
}
  • error response
400 Bad Request
Content-Type: application/json
{
  "email": [
    "This field is required."
  ],
  "name": [
    "This field is required."
  ],
  "registered": [
    "This field is required."
  ],
  "organisations": [
    "This field is required."
  ]
}

To create a user, you create a User object.

Note: Repeated POST requests with user information that contains the same email address will trigger partial updates on the existing user. Still, organisations field must be omitted on the repeated POST requests, as it will generate a validation exception:{ "organisations": "You can't set this field for an existing user." }

errors description
400 a required field is missing

List users

Request

GET /v1/users HTTP/1.1
Authorization: Token <your_api_key>
curl --request GET \
  --url https://api-sandbox.hokodo.co/v1/users \
  --header "Authorization: Token <your_api_key>"

Response

200 OK
Content-Type: application/json
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "user-mECT3e5n9i7gVGrbn2Pd38",
      "email": "johnny@hokodo.co",
      "unique_id": "",
      "name": "John",
      "phone": "",
      "registered": "2017-06-01T14:37:12Z",
      "organisations": [
        {
          "id": "org-FEjrdMsmhdNp34HxaZ6n63",
          "role": "member"
        }
      ]
    }
  ]
}

List all users associated with your platform.

Get user

Request

GET /v1/users/<user_id> HTTP/1.1
Authorization: Token <your_api_key>
curl --request GET \
  --url https://api-sandbox.hokodo.co/v1/users/user-mECT3e5n9i7gVGrbn2Pd38 \
  --header "Authorization: Token <your_api_key>"

Response

  • regular response
200 OK
Content-Type: application/json
{
  "id": "user-mECT3e5n9i7gVGrbn2Pd38",
  "email": "johnny@hokodo.co",
  "unique_id": "",
  "name": "John",
  "phone": "",
  "registered": "2017-06-01T14:37:12Z",
  "organisations": [
    {
      "id": "org-FEjrdMsmhdNp34HxaZ6n63",
      "role": "member"
    }
  ]
}
  • user not found
404 Not Found
Content-Type: application/json
{
  "detail": "Not found."
}

Look up a previously created user.

errors description
404 the user_id is probably invalid, the user has not been found

Modify user

Request

PATCH /v1/users/<user_id> HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "id": "user-mECT3e5n9i7gVGrbn2Pd38",
  "email": "johnny@hokodo.co",
  "unique_id": "some-unique-id",
  "name": "Johnny",
  "phone": "+1234567890",
  "registered": "2018-06-01T14:37:10Z"
}

Response

200 OK
Content-Type: application/json
{
  "id": "user-mECT3e5n9i7gVGrbn2Pd38",
  "email": "johnny@hokodo.co",
  "unique_id": "some-unique-id",
  "name": "Johnny",
  "phone": "+1234567890",
  "registered": "2018-06-01T14:37:10Z",
  "organisations": [
    {
      "id": "org-FEjrdMsmhdNp34HxaZ6n63",
      "role": "member"
    }
  ]
}

Update a previously created user.

Please note that organisation membership can not be updated via this endpoint.

errors description
404 the user_id is probably invalid, the user has not been found
400 updating a user failed or some of the fields have incorrect format

Delete user

Request

DELETE /v1/users/<user_id> HTTP/1.1
Authorization: Token <your_api_key>
curl --request DELETE \
  --url https://api-sandbox.hokodo.co/v1/users/user-mECT3e5n9i7gVGrbn2Pd38 \
  --header "Authorization: Token <your_api_key>"

Response

  • regular response
204 No Content
  • user not found
404 Not Found
Content-Type: application/json
{
  "detail": "Not found."
}

Delete a previously created user.

Errors

errors description
404 the user_id is probably invalid, the user has not been found

Manage organisations of user

You can manage users memberships and roles in various organisations. Please refer to section Organisations regarding creating and managing organisations.

Our API provides two alternative endpoint collections to manage relation between users and organisations. Below is the list of methods from the perspective of a user. For the list of methods from the perspective of an organisation, please refer to section Manage users in organisation

User organisations endpoints

User organisation object

{
  "id": "org-pHr6VCyzQJALUsePkatPBo",
  "role": "admin"
}
field type flags description
id string(uuid) required API unique identifier for the organisation
role role required Role of the user in the organisation

Add user to organisation

Request

POST /v1/users/<user_id>/organisations HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "id": "org-pHr6VCyzQJALUsePkatPBo",
  "role": "admin"
}
curl --request POST
  --url https://api-sandbox.hokodo.co/v1/users/user-mECT3e5n9i7gVGrbn2Pd38/organisations \
  --header "Authorization: Token <your_api_key>" \
  --header "Content-Type: application/json" \
  --data-binary "{
    \"id\": \"org-pHr6VCyzQJALUsePkatPBo\",
    \"role\": \"admin"\
}'

Responses

  • regular response
201 Created
Content-Type: application/json
{
  "id": "org-pHr6VCyzQJALUsePkatPBo",
  "role": "admin"
}
  • user already added to the organisation
200 Ok
Content-Type: application/json
{
  "id": "org-pHr6VCyzQJALUsePkatPBo",
  "role": "admin"
}
  • error (organisation not found and/or incorrect user role)
400 Bad Request
Content-Type: application/json
{
  "id": [
    "Invalid pk \"org-mECT3e5n9i7gVGrbn2Pd39\" - object does not exist."
  ],
  "role": [
    "\"reader\" is not a valid choice."
  ]
}

Attach existing user to a previously created organisation. When a user is already added to the organisation, but a different role is provided in the request, his existing role will be updated.

To create a user, see the relevant section.

Errors

errors description
400 a required field is missing or a field has incorrect format

View organisations of a user

Request

GET /v1/users/<user_id>/organisations HTTP/1.1
Authorization: Token <your_api_key>
curl --request GET
  --url https://api-sandbox.hokodo.co/v1/users/user-mECT3e5n9i7gVGrbn2Pd38/organisations \
  --header "Authorization: Token <your_api_key>"

Response

200 Ok
Content-Type: application/json
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "org-pHr6VCyzQJALUsePkatPBo",
      "role": "admin"
    }
  ]
}

List all organisations of a user

View individual organisation of user

Request

GET /v1/users/<user_id>/organisations/<organisation_id> HTTP/1.1
Authorization: Token <your_api_key>
curl --request GET
  --url https://api-sandbox.hokodo.co/v1/users/user-mECT3e5n9i7gVGrbn2Pd38/organisations/org-pHr6VCyzQJALUsePkatPBo \
  --header "Authorization: Token <your_api_key>"

Response

200 Ok
Content-Type: application/json
{
  "id": "org-pHr6VCyzQJALUsePkatPBo",
  "role": "admin"
}

Retrieve one specific organisation of a user

Errors

errors description
404 the organisation_id is probably invalid, the organisation has not been found

Modify user role in organisation

Request

PATCH /v1/users/<user_id>/organisations/<organisation_id> HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "role": "member"
}
curl --request POST
  --url https://api-sandbox.hokodo.co/v1/users/user-mECT3e5n9i7gVGrbn2Pd38/organisations/org-pHr6VCyzQJALUsePkatPBo \
  --header "Authorization: Token <your_api_key>" \
  --header "Content-Type: application/json" \
  --data-binary "{
    \"role\": \"member"\
}'

Responses

  • regular response
200 Ok
Content-Type: application/json
{
  "id": "org-pHr6VCyzQJALUsePkatPBo",
  "role": "member"
}
  • error (incorrect user role)
400 Bad Request
Content-Type: application/json
{
  "role": [
    "\"reader\" is not a valid choice."
  ]
}

Modify the role of the user in a specific organisation

Errors

errors description
400 the role field is missing or has incorrect value

Remove user from organisation

Request

DELETE /v1/users/<user_id>/organisations/<organisation_id> HTTP/1.1
Authorization: Token <your_api_key>
curl --request DELETE
  --url https://api-sandbox.hokodo.co/v1/users/user-mECT3e5n9i7gVGrbn2Pd38/organisations/org-pHr6VCyzQJALUsePkatPBo \
  --header "Authorization: Token <your_api_key>"

Response

204 No Content

Remove the user from a specific organisation

Errors

errors description
404 the organisation_id is probably invalid, the organisation has not been found

Credit Limits

Depending on the customer's company, the history of their orders and repayments, Hokodo can offer them deferred payments.

There are two situations where you might want to check whether one of your customers can obtain credit.

  1. Your customer is at the checkout, and you want to check if that particular purchase is eligible for deferred payment. To do that, you use the Orders endpoint to inform Hokodo about the purchase, and the Payment Offers endpoint to check eligibility of the Order.

  2. Your customer has not decided what they want to purchase, but you may wish to proactively inform them that they will be eligible for Deferred Payment. For example, you could display a banner at the top of the page with their credit limit or perhaps add a credit limit section to their "My Account" page. The CreditLimit endpoint is designed for this second situation.

To find out your customer's credit limit, please use the following endpoint, with the associated customer Company in the URL.

POST /v1/payment/credit_limits/company/<company_id>

You will get one of the two possible responses:

Credit limits endpoint

Credit limit object

{
    "company": "co-74cgmhG9U79oTWGEW4jeDW",
    "status": "eligible",
    "rejection_reason": null,
    "credit_limit": {
        "currency": "GBP",
        "amount_available": "987654",
        "amount_in_use": "123456",
        "amount": "1111110",
    }
}
field type description
company string(uuid) API unique identifier for the company
status string Current credit approval status (eligible or declined)
rejection_reason dictionary If status is declined, details about why, otherwise null
credit_limit dictionary Current credit limit if approved
credit_limit[currency] currency ISO 4217 currency code (e.g. GBP, EUR)
credit_limit[amount_available] int Credit limit currently available
credit_limit[amount_in_use] int Credit limit currently in use
credit_limit[amount] int Total credit limit

Please note that in general the amount will equal amount_available plus amount_in_use.

Therefore, it’s better to only share amount_available and amount_in_use with the customer.

Request company credit limit

Requests

POST /v1/payment/credit_limits/company/co-74cgmhG9U79oTWGEW4jeDW/ HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "currency": "GBP"
}
curl --request POST \
  --url https://api-sandbox.hokodo.co/v1/payment/credit_limits/company/co-74cgmhG9U79oTWGEW4jeDW/ \
  --header "Authorization: Token <your_api_key>"
  --header "Content-Type: application/json"
  --data-binary '{
  "currency": "GBP"
}'

Responses

  • eligible
200 OK
Content-Type: application/json
{
    "company": "co-74cgmhG9U79oTWGEW4jeDW",
    "status": "eligible",
    "rejection_reason": null,
    "credit_limit": {
        "currency": "GBP",
        "amount_available": "987654",
        "amount_in_use": "123456",
        "amount": "1111110",
    }
}
  • declined
200 OK
Content-Type: application/json
{
    "company": "co-74cgmhG9U79oTWGEW4jeDW",
    "status": "declined",
    "rejection_reason": {
      "code": "buyer-country",
      "detail": "We're currently unable to provide payment plans to Buyers domiciled in {debtor_country}.",
      "params": {
        "debtor_country": "Ireland",
      }
    },
    "credit_limit": {
        "currency": "GBP",
        "amount_available": null,
        "amount_in_use": null,
        "amount": null,
    }
}

The currency is optional in the request, and defaults to EUR if not provided.

field description requirement
currency currency Desired currency for the credit limit, as a ISO 4217 currency code (e.g. GBP, EUR)

Errors

errors description
400 A field is not in the expected format

Credit Limits (Legacy)

Depending on the customer's company, the history of their orders and repayments, Hokodo can offer them deferred payments.

There are two situations where you might want to check whether one of your customers can obtain credit.

  1. Your customer is at the checkout, and you want to check if that particular purchase is eligible for deferred payment. To do that, you use the Orders endpoint to inform Hokodo about the purchase, and the Payment Offers endpoint to check eligibility of the Order.

  2. Your customer has not decided what they want to purchase, but you may wish to proactively inform them that they will be eligible for Deferred Payment. For example, you could display a banner at the top of the page with their credit limit or perhaps add a credit limit section to their "My Account" page. The CreditLimit endpoint is designed for this second situation.

To find out your customer's credit limit, please use the following endpoint, with the associated customer Company in the URL.

GET /v1/payment/credit_limits/company/<company_id>

You will get one of the two possible responses:

CreditLimit endpoints

CreditLimit object

{
    "company": "co-74cgmhG9U79oTWGEW4jeDW",
    "status": "eligible",
    "current_credit_limit": {
        "currency": "GBP",
        "amount": 200000,
        "amount_in_use": 99700,
        "amount_available": 100300,
    },
    "credit_limit_history": [
        {
            "valid_from": "2020-07-16T08:44:49.059Z",
            "valid_to": null,
            "currency": "GBP",
            "amount": 200000
        },
        {
            "valid_from": "2020-06-02T09:12:34.059Z",
            "valid_to": "2020-07-16T08:44:49.059Z",
            "currency": "GBP",
            "amount": 150000
        },
        {
            "valid_from": "2020-05-18T18:18:18.059Z",
            "valid_to": "2020-06-02T09:12:34.059Z",
            "currency": "GBP",
            "amount": 100000
        }
    ]
}
field type flags description
company string(uuid) required API unique identifier of the associated company
status string read-only Current credit approval status (eligible or declined)
current_credit_limit dictionary read-only Current credit limit if approved
current_credit_limit[currency] string read-only ISO 4217 currency code (e.g. GBP, EUR)
current_credit_limit[amount] int read-only Total credit limit available, in cents
current_credit_limit[amount_in_use] int read-only Credit limit currently in use by deferred payments, in cents
current_credit_limit[amount_available] int read-only Credit limit currently available, in cents
credit_limit_history list read-only Current credit limit if approved
credit_limit_history[*][currency] string read-only ISO 4217 currency code (e.g. GBP, EUR)
credit_limit_history[*][amount] int read-only Total credit limit available, in cents
credit_limit_history[*][valid_from] date read-only From when the historical credit limit was valid
credit_limit_history[*][valid_to] date read-only Until when the historical credit limit was valid

Request a new Credit approval and limit

Request

GET /v1/payment/credit_limits/company/{company_id} HTTP/1.1
Content-Type: application/json
curl --request GET \
  --url https://api-sandbox.hokodo.co/v1/payment/credit_limits/company/{company_id} \
  --header "Content-Type: application/json"

Responses

  • Customer rejected
200 OK
Content-Type: application/json
{
    "company": "co-74cgmhG9U79oTWGEW4jeDW",
    "status": "declined",
    "current_credit_limit": null,
    "credit_limit_history": []
}
  • Customer accepted
200 OK
Content-Type: application/json
{
    "company": "co-74cgmhG9U79oTWGEW4jeDW",
    "status": "eligible",
    "current_credit_limit": {
        "currency": "GBP",
        "amount": 200000,
        "amount_in_use": 99700,
        "amount_available": 100300,
    },
    "credit_limit_history": [
        {
            "valid_from": "2020-07-16T08:44:49.059Z",
            "valid_to": null,
            "currency": "GBP",
            "amount": 200000
        },
        {
            "valid_from": "2020-06-02T09:12:34.059Z",
            "valid_to": "2020-07-16T08:44:49.059Z",
            "currency": "GBP",
            "amount": 150000
        },
        {
            "valid_from": "2020-05-18T18:18:18.059Z",
            "valid_to": "2020-06-02T09:12:34.059Z",
            "currency": "GBP",
            "amount": 100000
        }
    ]
}

This endpoint is used to query credit approval and credit limits for your customer. The only required field is company, in the URL.

It returns:

field type flags description
company string(uuid) required API unique identifier of the customer company queried

Orders

An order describes an instance of buying or selling something on your platform. An order consists of a basket of order items, plus details about who the company making the purchase is. Orders can be paid for at the time of the order or benefit from credit terms.

Orders serve two purposes in an integration with Hokodo:

a) Orders can be used to inform Hokodo about purchases the customer has made on your platform which Hokodo was not involved in. For example, you may have given the customer trade credit in the past, which has been successfully settled. Or the customer may have made purchases which were settled upfront (e.g. paid by card). Both of these are indicators which enhance our confidence that this is a genuine client and are favourable risk indicators. So providing Hokodo with data on these orders helps us to assess the customer's creditworthiness and to set the right credit limits for them.

b) You will also create an order when a customer shops on your platform so that you can obtain Deferred Payment Offers from Hokodo.

As we explain below, there are some commonalities between use cases a) and b) – for example in both cases we need to know who the buyer was, the value of the order, the date of the order etc. But there are also some differences. For example when you inform us about historical orders, you would tell us what payment terms were involved, whereas when you create an order for the purposes of getting deferred payment offers, Hokodo will be determining the payment terms via the offers we return.

Having more of the orders of the customers allows us to provide finer and higher credit limits, as well as reduce fraud.

Order endpoints

Order Documents

There are also post-sale order endpoints described in a dedicated section:

Order object

{
  "url": "https://api-sandbox.hokodo.co/v1/payment/orders/order-yQKxbtCg9aTS5JYnsRVA9B",
  "id": "order-yQKxbtCg9aTS5JYnsRVA9B",
  "unique_id": "876987-987uinjojna-I8UH98Jnj",
  "customer": {
    "organisation": "org-...",
    "user": "user-...",
    "type": "registered" / "guest"
    "delivery_address": {
      "name": "John Smith",
      "company_name": "",
      "address_line1": "1 Station Street",
      "address_line2": "Flat B",
      "address_line3": "",
      "city": "London",
      "region": "",
      "postcode": "SE11 6NQ",
      "country": "GB",
      "phone": "",
      "email": ""
    },
    "invoice_address": {...}
  },
  "status": "pending",
  "pay_method": "directdebit",
  "currency": "GBP",
  "total_amount": 12000,  # total amount including tax
  "tax_amount": 2000,  # tax amount
  "order_date": "2018-04-25",
  "invoice_date": "2018-04-25",
  "due_date": "2018-05-25",
  "paid_date": "2018-05-27",
  "items": [
    {
      "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": "10.000",
      "unit_price": 1000,  # includes tax
      "tax_rate": "20.00",
      "total_amount": 10000,
      "tax_amount": 1667
    },
    {
      "item_id": "2",
      "type": "shipping",
      "description": "Delivery fee",
      "quantity": "1.000",
      "unit_price": 2000,
      "tax_rate": "20.00",
      "total_amount": 2000,
      "tax_amount": 333
    }
  ],
  "metadata": {}  # store key-values for your internal references
  "po_number": "P-45612",
  "payment_offer": null,
  "deferred_payment": null,
}

The Order object contains many fields that are optional for historical orders. See below for an example of a minimal historical order.

field type flags description
url string read-only API endpoint to access the order
id string(uuid) read-only API unique identifier for the order
unique_id string required Unique identifier of the order in your platform
customer dictionary required Customer making the order (see guest/registered users)
customer[type] string required "registered" or "guest"
customer[organisation] string(uuid) required API unique identifier of the organisation of the customer (if registered) (can be expanded to a full Organisation object)
customer[user] string(uuid) required API unique identifier of the user of the customer (if registered) (can be expanded to a full User object)
customer[delivery_address] dictionary required Delivery/shipping address for this order. See Addresses for a description of the fields
customer[invoice_address] dictionary optional Invoice address for this order. Used for customers paying by invoice. See Addresses for a description of the fields
status string required Order status
pay_method string optional Payment method if the order has already been paid
currency currency required Currency of order amounts
total_amount int required Total amount including tax, in minor units (cents)
tax_amount int required Total amount of the taxes, in minor units (cents)
order_date date required Date of the order
invoice_date date optional Date of issuance of the invoice, if different from order date
due_date date optional Date due of the order (assuming the customer was given credit terms – if no credit terms were offered, then this would simply be the order_date)
paid_date date optional Date when the order was paid in full (assuming credit terms were offered – otherwise this would simply be the order_date)
items list required The list of items that constitute the order
items[*][item_id] string required Your identifier for this line of the order, e.g. 1, 2, 3...
items[*][type] string required Type of the item. Can be one of the following: product, service, digital, shipping, fee, discount
items[*][decription] string required Description of the item
items[*][metadata] dictionary optional Key-value pairs attached to the item, for example describing the color, variant, specific options, to help identify the item post-sale
items[*][reference] string optional Item reference number, SKU, etc.
items[*][category] string optional Category of the item, as per owner's internal classification
items[*][supplier_id] string optional An id of the supplier of the items (if applicable), can be your internal identifier of the supplier, for example "152"
items[*][supplier_name] string optional The name of the supplier of the items (if applicable)
items[*][quantity] decimal required Number of items in the order
items[*][unit_price] int required Price of a single unit, including tax, in minor units (cents)
items[*][tax_rate] decimal required Tax rate on this item, in percent (e.g. "19.50" for 19.5%)
items[*][total_amount] int required Total amount for this item, including tax, in minor units (cents)
items[*][tax_amount] int required Amount of the tax for this item, in minor units (cents)
items[*][fulfillment_info] list read-only Information about shipping of the items (see section Fulfillment)
items[*][fulfillment_info][*][shipped_quantity] decimal read-only Number of items in the shipment
items[*][fulfillment_info][*][shipping_id] string read-only Tracking id when the item has shipped (add when shipped)
items[*][fulfillment_info][*][shipping_provider] string read-only Name of the shipping provider (add when shipped)
items[*][fulfillment_info][*][shipping_date] date read-only Date of fulfillment (add when shipped)
metadata dictionary optional Set of key-value pairs you can attach to the object. You can use this to store your custom data in the object and read it back later.
po_number string optional Purchase order number from the customer (for their benefit, as reference)
payment_offer string(uuid) read-only API unique identifier for the deferred payment offer (if created, can be expanded to a full Payment Offer object)
deferred_payment string(uuid) read-only API unique identifier for the deferred payment in place (if created, can be expanded to a full Deferred payment object)

Order status

The order status must be one of:

On draft orders

Draft order status can be used for orders that the user has not yet committed to, eg. they put something in their cart but did not yet complete the checkout. If the customer goes on to pay via a payment method other than Hokodo Deferred Payment (e.g. they pay by card) then you should amend the order status to paid. In this case the paid order becomes part of the payment history that Hokodo can take into account when assessing this customer for Deferred Payment in the future.

If the customer abandons the checkout and so never completes the purchase, then the order will remain in draft status, and so we will know not to include it in any analysis of the customer's historical payment behaviour.

If the customer ends up completing the purchase using a Hokodo Deferred Payment, then we will automatically move the status to unpaid, and ultimately to paid.

Making changes to orders

When you supply information on Orders for the purposes of informing Hokodo about a customer's payment history, you are able to amend those orders freely using the Modify Order endpoint, or even delete them using the Delete Order endpoint.

However, once you create a draft order and then request Hokodo payment options, the Order can no longer be freely amended. Instead you must use the dedicated endpoints for dealing with Amendments, Cancellations, Refunds/Discounts and Returns, which are described in the post-sale Order actions section.

Payment method

The payment_method must be one of:

Please contact us to add more payment methods for purchases not made via Hokodo, to match closely your platform. This information helps us to provide finer and higher credit limits.

Guest users / registered users

Hokodo needs to identify the customer and their company to be able to provide deferred payments, whether they are a registered and logged in user on your platform, or they are a guest user making a single purchase.

Both cases require a User and Organisation. For registered users, this will be a one-time creation. For guests users, you can re-use a User and Organisation you have already created, or create a fresh one each time.

This flow will work the same for both guest users and registered users:

  1. Create User with the email address of the user (which may be an unverified email address for guest customers)

  2. User uniqueness on Hokodo's side is based on email address. If we detect that they have already been registered as a User on your platform, Hokodo API will return the existing user and identifier, complete with links to Organisation and Company saved before.

  3. If no organisation was linked to the user, or they wish to link a different one, search and identify the company via company search.

  4. Create the Organisation linked to that Company.

  5. Attach the User to the Organisation.

Registered user

If the customer is a registered user on your platform, you should create or have created an Organisation (to represent their team / company), and a User (to represent the individuals within that team / company). Then, use that organisation and user in the customer field of the Order.

Registered user

  "customer": {
    "organisation": "...",
    "user": "...",
    "type": "registered",
    "delivery_address": {
      ...
    }
  }

Guest user

If the customer is a guest user, and has not registered on your platform, you should collect some information to help us identify the customer, and create a User and Organisation in the same way as for registered user. When you create the User object, Hokodo may return an existing User object, if you had previously created a User with the same email address. In that case, it may also have the correct Organisation filled in already.

Guest user

  "customer": {
    "organisation": "...",
    "user": "...",
    "type": "guest",
    "delivery_address": {
      ...
    }
  }

Addresses

{
  "name": "John Smith",
  "company_name": "",
  "address_line1": "1 Station Street",
  "address_line2": "Flat B",
  "address_line3": "",
  "city": "London",
  "region": "",
  "postcode": "SE11 6NQ",
  "country": "GB",
  "phone": "",
  "email": ""
}

The fields used in addresses are:

field type flags description
name string required Full name
company_name string optional (for delivery) Name of the company for delivery if it differs from the legal entity's name
address_line1 string required Line 1 of the address
address_line2 string optional Line 2 of the address
address_line3 string optional Line 3 of the address
city string required City
region string optional State or Region
postcode string required Postal/ZIP code
country country required Country code
phone string optional Phone number associated to the address (eg to handle delivery)
email string optional Email associated to the address (eg to handle delivery notifications)

Create order

Requests

  • minimal historical order of a registered user
POST /v1/payment/orders HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "unique_id": "876987-987uinjojna-I8UH98Jnj",
  "customer": {
    "type": "registered",
    "organisation": "org-ypTaHiLv5kgqSn4TzCr7xb",
    "user": "user-nNqgg5AFymQMumaU7EdrLa",
    "delivery_address": {
      "name": "John Smith",
      "address_line1": "1 Station Street",
      "address_line2": "Flat B",
      "city": "London",
      "postcode": "SE11 6NQ",
      "country": "GB"
    },
  },
  "status": "paid",
  "currency": "GBP",
  "total_amount": 12000,
  "tax_amount": 2000,
  "order_date": "2018-04-25",
  "invoice_date": "2018-04-25",
  "due_date": "2018-05-25",
  "paid_date": "2018-06-10",
  "pay_method": "directdebit"
}
curl --request POST \
     --url https://api-sandbox.hokodo.co/v1/payment/orders \
     --header "Content-Type: application/json" \
     --header "Authorization: <your_api_key>" \
     --data-binary '{
  "unique_id": "876987-987uinjojna-I8UH98Jnj",
  "customer": {
    "type": "registered",
    "organisation": "org-ypTaHiLv5kgqSn4TzCr7xb",
    "user": "user-nNqgg5AFymQMumaU7EdrLa",
    "delivery_address": {
      "name": "John Smith",
      "address_line1": "1 Station Street",
      "address_line2": "Flat B",
      "city": "London",
      "postcode": "SE11 6NQ",
      "country": "GB"
    },
  },
  "status": "paid",
  "currency": "GBP",
  "total_amount": 12000,
  "tax_amount": 2000,
  "order_date": "2018-04-25",
  "invoice_date": "2018-04-25",
  "due_date": "2018-05-25",
  "paid_date": "2018-06-10",
  "pay_method": "directdebit"
}'
  • new order of a registered user
POST /v1/payment/orders HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "unique_id": "876987-987uinjojna-I8UH98Jnj",
  "customer": {
    "type": "registered",
    "organisation": "org-ypTaHiLv5kgqSn4TzCr7xb",
    "user": "user-nNqgg5AFymQMumaU7EdrLa",
    "delivery_address": {
      "name": "John Smith",
      "address_line1": "1 Station Street",
      "address_line2": "Flat B",
      "city": "London",
      "postcode": "SE11 6NQ",
      "country": "GB"
    },
  },
  "status": "draft",
  "currency": "GBP",
  "total_amount": 12000,
  "tax_amount": 2000,
  "order_date": "2018-04-25",
  "items": [
    {
      "item_id": "1",
      "type": "product",
      "description": "Super ergonomic chair",
      "metadata": {"color": "black", "name": "Karmus", "variant": "M"},
      "reference": "702.611.50",
      "category": "Furniture > Chairs",
      "supplier_id": "7363",
      "quantity": "10.000",
      "unit_price": 1000,
      "tax_rate": "20.00",
      "total_amount": 10000,
      "tax_amount": 1667
    },
    {
      "item_id": "2",
      "type": "shipping",
      "description": "Delivery fee",
      "quantity": "1.000",
      "unit_price": 2000,
      "tax_rate": "20.00",
      "total_amount": 2000,
      "tax_amount": 333
    }
  ],
  "metadata": {
    "customer_id": "2055b445-3d95-4d2f-bd80-3e336217905f",
    "checkout_id": "c0185e68-89aa-42d5-93e9-476d01d4c97f"
  }
}
curl --request POST \
     --url https://api-sandbox.hokodo.co/v1/payment/orders \
     --header "Content-Type: application/json" \
     --header "Authorization: <your_api_key>" \
     --data-binary '{
  "unique_id": "876987-987uinjojna-I8UH98Jnj",
  "customer": {
    "type": "registered",
    "organisation": "org-ypTaHiLv5kgqSn4TzCr7xb",
    "user": "user-nNqgg5AFymQMumaU7EdrLa",
    "delivery_address": {
      "name": "John Smith",
      "address_line1": "1 Station Street",
      "address_line2": "Flat B",
      "city": "London",
      "postcode": "SE11 6NQ",
      "country": "GB"
    },
  },
  "status": "draft",
  "currency": "GBP",
  "total_amount": 12000,
  "tax_amount": 2000,
  "order_date": "2018-04-25",
  "items": [
    {
      "item_id": "1",
      "type": "product",
      "description": "Super ergonomic chair",
      "metadata": {"color": "black", "name": "Karmus", "variant": "M"},
      "reference": "702.611.50",
      "category": "Furniture > Chairs",
      "supplier_id": "7363",
      "quantity": "10.000",
      "unit_price": 1000,
      "tax_rate": "20.00",
      "total_amount": 10000,
      "tax_amount": 1667
    },
    {
      "item_id": "2",
      "type": "shipping",
      "description": "Delivery fee",
      "quantity": "1.000",
      "unit_price": 2000,
      "tax_rate": "20.00",
      "total_amount": 2000,
      "tax_amount": 333
    }
  ],
  "metadata": {
    "customer_id": "2055b445-3d95-4d2f-bd80-3e336217905f",
    "checkout_id": "c0185e68-89aa-42d5-93e9-476d01d4c97f"
  }
}'
  • new order of a guest user
POST /v1/payment/orders HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "unique_id": "876987-987uinjojna-I8UH98Jnj",
  "customer": {
    "type": "guest",
    "organisation": "org-ypTaHiLv5kgqSn4TzCr7xb",
    "user": "user-nNqgg5AFymQMumaU7EdrLa",
    "delivery_address": {
      "name": "John Smith",
      "address_line1": "1 Station Street",
      "address_line2": "Flat B",
      "city": "London",
      "postcode": "SE11 6NQ",
      "country": "GB"
    },
  },
  "status": "draft",
  "currency": "GBP",
  "total_amount": 12000,
  "tax_amount": 2000,
  "order_date": "2018-04-25",
  "items": [
    {
      "item_id": "1",
      "type": "product",
      "description": "Super ergonomic chair",
      "metadata": {"color": "black", "name": "Karmus", "variant": "M"},
      "reference": "702.611.50",
      "category": "Furniture > Chairs",
      "supplier_id": "7363",
      "quantity": "10.000",
      "unit_price": 1000,
      "tax_rate": "20.00",
      "total_amount": 10000,
      "tax_amount": 1667
    },
    {
      "item_id": "2",
      "type": "shipping",
      "description": "Delivery fee",
      "quantity": "1.000",
      "unit_price": 2000,
      "tax_rate": "20.00",
      "total_amount": 2000,
      "tax_amount": 333
    }
  ],
  "metadata": {
    "customer_id": "2055b445-3d95-4d2f-bd80-3e336217905f",
    "checkout_id": "c0185e68-89aa-42d5-93e9-476d01d4c97f"
  }
}
curl --request POST \
     --url https://api-sandbox.hokodo.co/v1/payment/orders \
     --header "Content-Type: application/json" \
     --header "Authorization: <your_api_key>" \
     --data-binary '{
  "unique_id": "876987-987uinjojna-I8UH98Jnj",
  "customer": {
    "type": "registered",
    "company": "org-QdKZ5mdD8BrG5CKxGok2Q4",
    "email": "john@example.com",
    "name": "John Smith",
    "phone": "+44 123 456 7890",
    "delivery_address": {
      "name": "John Smith",
      "address_line1": "1 Station Street",
      "address_line2": "Flat B",
      "city": "London",
      "postcode": "SE11 6NQ",
      "country": "GB"
    },
  },
  "status": "draft",
  "currency": "GBP",
  "total_amount": 12000,
  "tax_amount": 2000,
  "order_date": "2018-04-25",
  "items": [
    {
      "item_id": "1",
      "type": "product",
      "description": "Super ergonomic chair",
      "metadata": {"color": "black", "name": "Karmus", "variant": "M"},
      "reference": "702.611.50",
      "category": "Furniture > Chairs",
      "supplier_id": "7363",
      "quantity": "10.000",
      "unit_price": 1000,
      "tax_rate": "20.00",
      "total_amount": 10000,
      "tax_amount": 1667
    },
    {
      "item_id": "2",
      "type": "shipping",
      "description": "Delivery fee",
      "quantity": "1.000",
      "unit_price": 2000,
      "tax_rate": "20.00",
      "total_amount": 2000,
      "tax_amount": 333
    }
  ],
  "metadata": {
    "customer_id": "2055b445-3d95-4d2f-bd80-3e336217905f",
    "checkout_id": "c0185e68-89aa-42d5-93e9-476d01d4c97f"
  }
}'

Responses

  • success response
201 Created
Content-Type: application/json
{
  "url": "https://api-sandbox.hokodo.co/v1/payment/orders/order-yQKxbtCg9aTS5JYnsRVA9B",
  "id": "order-yQKxbtCg9aTS5JYnsRVA9B",
  "unique_id": "48b0ce9a-f8a3-4dff-be56-26af747b3d98",
  "customer": {
    "type": "registered",
    "organisation": "org-ypTaHiLv5kgqSn4TzCr7xb",
    "user": "user-nNqgg5AFymQMumaU7EdrLa",
    "delivery_address": {
      "name": "John Smith",
      "address_line1": "1 Station Street",
      "address_line2": "Flat B",
      "address_line3": "",
      "city": "London",
      "region": "",
      "postcode": "SE11 6NQ",
      "country": "GB",
      "phone": "",
      "email": ""
    },
  },
  "status": "draft",
  "currency": "GBP",
  "pay_method": "",
  "total_amount": 12000,
  "tax_amount": 2000,
  "order_date": "2018-04-25",
  "invoice_date": null,
  "due_date": null,
  "paid_date": null,
  "items": [
    {
      "item_id": "1",
      "type": "product",
      "description": "Super ergonomic chair",
      "metadata": {"color": "black", "name": "Karmus", "variant": "M"},
      "reference": "702.611.50",
      "category": "Furniture > Chairs",
      "supplier_id": "7363",
      "supplier_name": "",
      "quantity": "10.000",
      "unit_price": 1000,
      "tax_rate": "20.00",
      "total_amount": 10000,
      "tax_amount": 1667,
      "fulfillment_info": null
    },
    {
      "item_id": "2",
      "type": "shipping",
      "description": "Delivery fee",
      "metadata": {},
      "reference": "",
      "category": "",
      "supplier_id": "",
      "supplier_name": "",
      "quantity": "1.000",
      "unit_price": 2000,
      "tax_rate": "20.00",
      "total_amount": 2000,
      "tax_amount": 333,
      "fulfillment_info": null
    }
  ],
  "metadata": {
    "customer_id": "2055b445-3d95-4d2f-bd80-3e336217905f",
    "checkout_id": "c0185e68-89aa-42d5-93e9-476d01d4c97f"
  },
  "payment_offer": null,
  "deferred_payment": null
}
  • error response (example)
400 Bad Request
Content-Type: application/json
{
  "organisation": [
    "Invalid pk \"org-AgBGknk7D8KixY2ntbJtmA\" - object does not exist."
  ],
  "user": [
    "Bad prefix. Expected a UUID prefixed by \"user\", but got xyz."
  ]
}

To create an order, you create an Order object.

Many fields are optional. However to obtain a Deferred Payment Offer later the system must be provided with the following information at least:

The more information is provided at order creation, the more accurate the Payment Offer Hokodo can provide, and the less friction there will be for your customer later on to complete the purchase.

Errors

errors description
400 a required field is missing or some of the fields have incorrect value

List orders

Request

GET /v1/payment/orders HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>
curl --request GET \
     --url https://api-sandbox.hokodo.co/v1/payment/orders \
     --header "Content-Type: application/json" \
     --header "Authorization: <your_api_key>"

Response

200 Ok
Content-Type: application/json
{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "url": "https://api-sandbox.hokodo.co/v1/payment/orders/order-yQKxbtCg9aTS5JYnsRVA9B",
      "id": "order-yQKxbtCg9aTS5JYnsRVA9B",
      "unique_id": "48b0ce9a-f8a3-4dff-be56-26af747b3d98",
      "customer": {
        "type": "registered",
        "organisation": "org-ypTaHiLv5kgqSn4TzCr7xb",
        "user": "user-nNqgg5AFymQMumaU7EdrLa",
        "delivery_address": {
          "name": "John Smith",
          "address_line1": "1 Station Street",
          "address_line2": "Flat B",
          "address_line3": "",
          "city": "London",
          "region": "",
          "postcode": "SE11 6NQ",
          "country": "GB",
          "phone": "",
          "email": ""
        },
      },
      "status": "draft",
      "currency": "GBP",
      "pay_method": "",
      "total_amount": 12000,
      "tax_amount": 2000,
      "order_date": "2018-04-25",
      "invoice_date": null,
      "due_date": null,
      "paid_date": null,
      "items": [
        {
          "item_id": "1",
          "type": "product",
          "description": "Super ergonomic chair",
          "metadata": {"color": "black", "name": "Karmus", "variant": "M"},
          "reference": "702.611.50",
          "category": "Furniture > Chairs",
          "supplier_id": "7363",
          "supplier_name": "",
          "quantity": "10.000",
          "unit_price": 1000,
          "tax_rate": "20.00",
          "total_amount": 10000,
          "tax_amount": 1667,
          "fulfillment_info": null
        },
        {
          "item_id": "2",
          "type": "shipping",
          "description": "Delivery fee",
          "metadata": {},
          "reference": "",
          "category": "",
          "supplier_id": "",
          "supplier_name": "",
          "quantity": "1.000",
          "unit_price": 2000,
          "tax_rate": "20.00",
          "total_amount": 2000,
          "tax_amount": 333,
          "fulfillment_info": null
        }
      ],
      "metadata": {
        "customer_id": "2055b445-3d95-4d2f-bd80-3e336217905f",
        "checkout_id": "c0185e68-89aa-42d5-93e9-476d01d4c97f"
      },
      "payment_offer": null,
      "deferred_payment": null
    },
    {
      "url": "https://api-sandbox.hokodo.co/v1/payment/orders/order-LitFGLodQh9qQHTFcjUvfm",
      "id": "order-LitFGLodQh9qQHTFcjUvfm",
      "unique_id": "8751729d-7e96-4d38-87bc-fe241ca1d4d7",
      "customer": {
        "type": "registered",
        "organisation": "org-dLWYumjHaqChNggScx5inV",
        "user": "user-czNtrBwLY63rJkqmgyQaEF",
        "delivery_address": {
          "name": "John Smith",
          "address_line1": "1 Station Street",
          "address_line2": "Flat B",
          "address_line3": "",
          "city": "London",
          "region": "",
          "postcode": "SE11 6NQ",
          "country": "GB",
          "phone": "",
          "email": ""
        },
      },
      "status": "draft",
      "currency": "GBP",
      "pay_method": "",
      "total_amount": 12000,
      "tax_amount": 2000,
      "order_date": "2018-04-25",
      "invoice_date": null,
      "due_date": null,
      "paid_date": null,
      "items": [
        {
          "item_id": "1",
          "type": "product",
          "description": "Super ergonomic chair",
          "metadata": {"color": "black", "name": "Karmus", "variant": "M"},
          "reference": "702.611.50",
          "category": "Furniture > Chairs",
          "supplier_id": "7363",
          "supplier_name": "",
          "quantity": "10.000",
          "unit_price": 1000,
          "tax_rate": "20.00",
          "total_amount": 10000,
          "tax_amount": 1667,
          "fulfillment_info": null
        },
        {
          "item_id": "2",
          "type": "shipping",
          "description": "Delivery fee",
          "metadata": {},
          "reference": "",
          "category": "",
          "supplier_id": "",
          "supplier_name": "",
          "quantity": "1.000",
          "unit_price": 2000,
          "tax_rate": "20.00",
          "total_amount": 2000,
          "tax_amount": 333,
          "fulfillment_info": null
        }
      ],
      "metadata": {
        "customer_id": "584eaf27-250c-4b83-826f-909cbaa1f54a",
        "checkout_id": "59e278cd-305a-4bbe-a275-f038f9319b1c"
      },
      "payment_offer": null,
      "deferred_payment": null
    }
  ]
}

List orders created by your platform

View order

Requests

  • without expanding referenced objects
GET /v1/payment/orders/<order_id> HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>
curl --request GET \
     --url https://api-sandbox.hokodo.co/v1/payment/orders/<order_id> \
     --header "Authorization: <your_api_key>"
  • with expanding referenced organisation, payment_offer
GET /v1/payment/orders/<order_id>?expand=organisation,payment_offer HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>
curl --request GET \
     --url https://api-sandbox.hokodo.co/v1/payment/orders/<order_id>?extend=organisation,payment_offer \
     --header "Content-Type: application/json" \
     --header "Authorization: <your_api_key>"

Responses

  • regular response (with optional expansion)
200 Ok
Content-Type: application/json
{
  "url": "https://api-sandbox.hokodo.co/v1/payment/orders/order-yQKxbtCg9aTS5JYnsRVA9B",
  "id": "order-yQKxbtCg9aTS5JYnsRVA9B",
  "unique_id": "48b0ce9a-f8a3-4dff-be56-26af747b3d98",
  "customer": {
    "type": "registered",
    "organisation": {
      "id": "org-ypTaHiLv5kgqSn4TzCr7xb",
      "unique_id": "c105b862-f1ba-4197-9d97-57db63196b00",
      "registered": "2017-06-01T14:37:12Z",
      "company": "co-bqRyKAGaFrEEN8JMjWJiqk",
      "users": ["user-nNqgg5AFymQMumaU7EdrLa"]
    }
    "user": "user-nNqgg5AFymQMumaU7EdrLa",
    "delivery_address": {
      "name": "John Smith",
      "address_line1": "1 Station Street",
      "address_line2": "Flat B",
      "address_line3": "",
      "city": "London",
      "region": "",
      "postcode": "SE11 6NQ",
      "country": "GB",
      "phone": "",
      "email": ""
    },
  },
  "status": "draft",
  "currency": "GBP",
  "pay_method": "",
  "total_amount": 12000,
  "tax_amount": 2000,
  "order_date": "2018-04-25",
  "invoice_date": null,
  "due_date": null,
  "paid_date": null,
  "items": [
    {
      "item_id": "1",
      "type": "product",
      "description": "Super ergonomic chair",
      "metadata": {"color": "black", "name": "Karmus", "variant": "M"},
      "reference": "702.611.50",
      "category": "Furniture > Chairs",
      "supplier_id": "7363",
      "supplier_name": "",
      "quantity": "10.000",
      "unit_price": 1000,
      "tax_rate": "20.00",
      "total_amount": 10000,
      "tax_amount": 1667,
      "fulfillment_info": null
    },
    {
      "item_id": "2",
      "type": "shipping",
      "description": "Delivery fee",
      "metadata": {},
      "reference": "",
      "category": "",
      "supplier_id": "",
      "supplier_name": "",
      "quantity": "1.000",
      "unit_price": 2000,
      "tax_rate": "20.00",
      "total_amount": 2000,
      "tax_amount": 333,
      "fulfillment_info": null
    }
  ],
  "metadata": {
    "customer_id": "2055b445-3d95-4d2f-bd80-3e336217905f",
    "checkout_id": "c0185e68-89aa-42d5-93e9-476d01d4c97f"
  },
  "payment_offer": {
    "url": "https://api-sandbox.hokodo.co/v1/payment/offers/offer-EzH6BixNSHvaByEpXcFW5h",
    "id": "offer-bqRyHAGaFrDEN8JNjXJirp",
    "order": "order-dTHo9Q2idffT7CMPCVjztA",
    "status": "eligible",
    "offered_payment_plans": [
      {
          "id": "pln-bqRyHAGaFrDEN8JNjXJirp",
          "name": "net30",
          "currency": "GBP",
          "scheduled_payments": [
            {
              "date": "2020-10-16",
              "amount": 100000,
              "allowed_payment_methods": [
                {"type": "card"},
                {"type": "direct_debit"},
                {"type": "invoice"}
              ]
            }
          ],
          "merchant_fee": {
            "currency": "GBP",
            "amount": 1000
          },
          "customer_fee": {
            "currency": "GBP",
            "amount": 0
          },
          "price": {
            "amount": 100000,
            "currency": "GBP"
          },
          "valid_until": "2020-09-16T12:44:49.059Z",
          "payment_url": "https://payment.app.hokodo.co/plans/pln-bqRyHAGaFrDEN8JNjXJirp"
          "status": "active"
      },
      {
          "id": "pln-gJdDHAGaFrDLDvJNXJird",
          "name": "4x",
          "currency": "GBP",
          "scheduled_payments": [
            {
              "date": "2020-09-16",
              "amount": 25100,
              "allowed_payment_methods": [
                {"type": "card"}
              ]
            },
            {
              "date": "2020-10-16",
              "amount": 25100,
              "allowed_payment_methods": [
                {"type": "card"}
              ]
            },
            {
              "date": "2020-11-16",
              "amount": 25100,
              "allowed_payment_methods": [
                {"type": "card"}
              ]
            },
            {
              "date": "2020-12-16",
              "amount": 25100,
              "allowed_payment_methods": [
                {"type": "card"}
              ]
            }
          ],
          "merchant_fee": {
            "currency": "GBP",
            "amount": 2000
          },
          "customer_fee": {
            "currency": "GBP",
            "amount": 400
          },
          "price": {
            "amount": 100000,
            "currency": "GBP"
          },
          "valid_until": "2020-09-16T12:44:49.059Z",
          "payment_url": "https://payment.app.hokodo.co/plans/pln-gJdDHAGaFrDLDvJNXJird"
          "status": "active"
      },
    ],
    "rejection_reason": null,
    "urls": {
      "success": "https://merchant.com/payment/ok",
      "failure": "https://merchant.com/checkout",
      "cancel": "https://merchant.com/checkout",
      "notification": "https://backend.merchant.com/payment/notifications",
      "merchant_terms": "https://merchant.com/terms"
    },
    "locale": "en-gb",
    "metadata": {}
  },
  "deferred_payment": null
}
  • order not found
404 Not Found
Content-Type: application/json
{
  "detail": "Not found."
}

Look up a previously created order.

Errors

errors description
404 the order_id is probably invalid, the order has not been found

Modify order

Request (e.g. update when an invoice has been paid)

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

{
  "status": "paid",
  "paid_date": "2018-06-10",
  "pay_method": "bank"
}
curl --request PATCH \
     --url https://api-sandbox.hokodo.co/v1/payment/orders/<order_id> \
     --header "Content-Type: application/json" \
     --header "Authorization: <your_api_key>" \
     --data-binary '{
  "status": "paid",
  "paid_date": "2018-06-10",
  "pay_method": "bank"
}'

Response

200 Ok
Content-Type: application/json
{
  "url": "https://api-sandbox.hokodo.co/v1/payment/orders/order-yQKxbtCg9aTS5JYnsRVA9B",
  "id": "order-yQKxbtCg9aTS5JYnsRVA9B",
  "unique_id": "876987-987uinjojna-I8UH98Jnj",
  "customer": {
    "type": "registered",
    "organisation": "org-ypTaHiLv5kgqSn4TzCr7xb",
    "user": "user-nNqgg5AFymQMumaU7EdrLa",
    "delivery_address": {
      "name": "John Smith",
      "address_line1": "1 Station Street",
      "address_line2": "Flat B",
      "address_line3": "",
      "city": "London",
      "region": "",
      "postcode": "SE11 6NQ",
      "country": "GB",
      "phone": "",
      "email": ""
    },
  },
  "status": "paid",
  "currency": "GBP",
  "pay_method": "",
  "total_amount": 12000,
  "tax_amount": 2000,
  "order_date": "2018-04-25",
  "invoice_date": "2018-04-25",
  "due_date": "2018-05-25",
  "paid_date": "2018-06-10",
  "pay_method": "bank",
  "items": [],
  "metadata": null,
  "payment_offer": null,
  "deferred_payment": null
}

An order cannot be modified once a Hokodo Deferred Payment has been made. Instead you will need to use the dedicated post-sale endpoints to notify us about Amendments, Cancellations, Returns and Refunds/Discounts (HTTP response with status 409 Conflict will be returned).

A historical order or another made with a payment method other than Hokodo can be updated.

Errors

errors description
400 a required field is missing or some of the fields have incorrect value
409 the order is already insured, modification is not allowed

Delete order

Request

DELETE /v1/payment/orders/<order_id> HTTP/1.1
Authorization: Token <your_api_key>
curl --request DELETE \
     --url https://api-sandbox.hokodo.co/v1/payment/orders/<order_id> \
     --header "Authorization: <your_api_key>"

Responses

  • regular response
204 No Content
  • order not found
404 Not Found
Content-Type: application/json
{
  "detail": "Not found."
}
  • order can not be deleted
409 Conflict
Content-Type: application/json

Delete a previously created order.

Errors

errors description
404 the order_id is probably invalid, the order has not been found
409 the order can not be deleted

Order Documents

OrderDocuments are documents such as an invoice, credit note, or a shipping document associated with a particular order.

Invoices

Invoices are normally sent by the merchant to the customer at the time of delivery. Hokodo need these invoices to support the collections process, because it is very common for customers to ask for the invoice to be re-sent to them before they make payment. Therefore, once the merchant generates the invoice, it should also be shared with Hokodo using this endpoint.

Credit Notes

Credit notes are sent by the merchant to the customer whenever a post-sale action such as a discount or return is applied to an order. If you issue credit notes when processing discounts or returns, you can save your operations team a significant amount of time by uploading the credit note to Hokodo using this endpoint at the time they are raised. This allows Hokodo to respond to the customer and resolve any queries without the need to liaise with your operations team.

Shipping documents

Shipping documents are documents associated with delivery, such as a copy of the delivery confirmation signed by the recipient. These documents are useful should there be any disputes about whether delivery occurred. If merchants are routinely capturing delivery confirmation documents, then systematically sharing these with Hokodo using this endpoint will save on operational hassle for Hokodo and the merchant if/when they are ever needed.

Other

Other can be used for any other documents that the merchant wishes to share with Hokodo

OrderDocument Object

{
    "id": "odoc-afapG98cKaCL5VRjVfQQ2S",
    "order": "order-yQKxbtCg9aTS5JYnsRVA9B",
    "doc_type": "invoice",
    "description": "Invoice sent to customer",
    "amount": 10000,
    "metadata": {"unique_id": "some_unique_id"}
    "file": "https://hokodo-sandbox-clientdocuments.s3.amazonaws.com/media/order_documents/..."
}
field type description
id string(uuid) API unique identifier of the order document
order string(uuid) API identifier of the linked order
doc_type string Type of document, see below
description string Description of the document
amount int Value of the document in minor units (e.g. a credit note worth £100, will have amount=10000)
metadata dict Set of key-value pairs you can attach to the object. You can use this to store your custom data in the object and read it back later.
file string(uri) Link to the document

OrderDocument type

Possible order document types are:

Create OrderDocument

POST /v1/payment/orders/<order_id>/documents HTTP/1.1
Host: api-sandbox.hokodo.co
Content-Type: multipart/form-data; boundary=X-CLIENT-BOUNDARY
Authorization: Token <your_api_key>
Accept: */*
Content-Length: <some_length>
curl --request POST \
  --url https://api-sandbox.hokodo.co/v1/payment/orders/<order_id>/documents \
  --header 'Authorization: Token <your_api_key>' \
  --form doc_type=invoice \
  --form description=invoice_description \
  --form amount=invoice_amount \
  --form metadata=invoice_metadata \
  --form file=@/path/to/file

To create an OrderDocument, you'll need to make a post request with the Content-Type set to multipart form data. In the request body please include the file you wish to upload.

You can optionally include doc_type, description, amount, and metadata.

field type flags description
file file required Content of the document
doc_type string optional Type of document, see above
description string optional Description of the document
amount int optional Value of the document in minor units (e.g. a credit note worth £100, will have amount=10000)
metadata dict optional Set of key-value pairs you can attach to the object. You can use this to store your custom data in the object and read it back later.

Errors

errors description
400 a required field is missing

View order document

Requests

GET /v1/payment/orders/<order_id>/documents/<document_id> HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>
curl --request GET \
     --url https://api-sandbox.hokodo.co/v1/payment/orders/<order_id>/documents/<document_id> \
     --header "Authorization: <your_api_key>"

Responses

200 Ok
Content-Type: application/json
{
    "id": "odoc-afapG98cKaCL5VRjVfQQ2S",
    "order": "order-yQKxbtCg9aTS5JYnsRVA9B",
    "doc_type": "invoice",
    "description": "Invoice Description",
    "amount": 10000,
    "metadata": {"unique_id": "some_unique_id"},
    "file": "https://hokodo-sandbox-clientdocuments.s3.amazonaws.com/media/order_documents/..."
}
  • order document not found
404 Not Found
Content-Type: application/json
{
  "detail": "Not found."
}

Look up a previously created order document.

Errors

errors description
404 the order_document_id is probably invalid, the order document has not been found

Payment Offers

The Offer API is used to create a set of payment plans for your customer. Simply provide an order id and Hokodo will return a list of payment plans that you can share with your customer at checkout, or over email or text message.

Offer Endpoints

Offer Object

{
  "url": "https://api-sandbox.hokodo.co/v1/payment/offers/offer-bqRyHAGaFrDEN8JNjXJirp",
  "id": "offer-bqRyHAGaFrDEN8JNjXJirp",
  "order": "order-dTHo9Q2idffT7CMPCVjztA",
  "offered_payment_plans": [
    {
        "id": "pln-bqRyHAGaFrDEN8JNjXJirp",
        "name": "net30",
        "currency": "GBP",
        "scheduled_payments": [
          {
            "date": "2020-10-16",
            "amount": 100000,
            "allowed_payment_methods": [
              {"type": "card"},
              {"type": "direct_debit"},
              {"type": "invoice"}
            ]
          }
        ],
        "merchant_fee": {
          "currency": "GBP",
          "amount": 1000
        },
        "customer_fee": {
          "currency": "GBP",
          "amount": 0
        },
        "valid_until": "2020-09-16T12:44:49.841Z",
        "payment_url": "https://payment.app.hokodo.co/plans/pln-bqRyHAGaFrDEN8JNjXJirp"
        "status": "offered",
        "rejection_reason": null
    },
    {
        "id": "pln-gJdDHAGaFrDLDvJNXJird",
        "name": "4x",
        "currency": "GBP",
        "scheduled_payments": [
          {
            "date": "2020-09-16",
            "amount": 25100,
            "allowed_payment_methods": [
              {"type": "card"}
            ]
          },
          {
            "date": "2020-10-16",
            "amount": 25100,
            "allowed_payment_methods": [
              {"type": "card"}
            ]
          },
          {
            "date": "2020-11-16",
            "amount": 25100,
            "allowed_payment_methods": [
              {"type": "card"}
            ]
          },
          {
            "date": "2020-12-16",
            "amount": 25100,
            "allowed_payment_methods": [
              {"type": "card"}
            ]
          }
        ],
        "merchant_fee": {
          "currency": "GBP",
          "amount": 2000
        },
        "customer_fee": {
          "currency": "GBP",
          "amount": 400
        },
        "valid_until": "2020-09-16T12:44:49.841Z",
        "payment_url": "https://payment.app.hokodo.co/plans/pln-gJdDHAGaFrDLDvJNXJird"
        "status": "offered",
        "rejection_reason": null
    },
  ],
  "urls": {
    "success": "https://merchant.com/payment/ok",
    "failure": "https://merchant.com/checkout",
    "cancel": "https://merchant.com/checkout",
    "notification": "https://backend.merchant.com/payment/notifications",
    "merchant_terms": "https://merchant.com/terms"
  },
  "locale": "en-gb",
  "metadata": {}
}
field type description
url string API endpoint to access the Offer
id string(uuid) API identifier for the Offer
order string(uuid) API identifier for the attached Transaction
offered_payment_plans list List of payment plans you can offer to your customer
legals dictionary An internal field which is subject to change
urls dictionary Redirection and callback URLs
urls[merchant_terms] string(url) URL for the terms and conditions of your platform, to display to the user
urls[success] string(url) URL to redirect the customer to if the deferred payment application is a success
urls[failure] string(url) URL to redirect the customer to if the deferred payment application is rejected. For example the checkout page to finish with another payment method
urls[cancel] string(url) URL to redirect the customer to if they cancel the application before completing it. For example the checkout page to finish with another payment method
urls[notification] string(url) Callback URL to receive notifications about the deferred payment application
locale string Language and region of the customer (RFC 1766), for example "en-gb" or "fr-fr"
metadata dictionary Set of key-value pairs to store additional information about the Offer.

Payment Plan Object

field type description
id string(uuid) API identifier for the Payment Plan
name string Payment plan name (e.g. Pay in 30 days, Pay in 3 installments)
currency string string
scheduled_payments list The re-payment schedule for the plan (e.g. your customer will pay £x amount on YYYY-MM-DD date)
scheduled_payments[date] string Date when the payment is due (e.g. 2020-09-16)
scheduled_payments[amount] int Amount your customer will pay on this date in pence/cents
scheduled_payments[allowed_payment_methods] list List of payment method types allowed to make a payment with
merchant_fee dictionary Amount and currency of the fees for you for this payment plan
customer_fee dictionary Amount and currency of the fees for the customer for this payment plan (included in the scheduled payments)
valid_until date Time when payment plan offer expires. After this date, your customer cannot avail of this plan.
payment_url string Link where your customer can apply for the payment plan
status string Current status of the payment plan (e.g. offered, accepted, declined, expired, cancelled).
rejection_reason dictionary Rejection reason if Offer is declined, see rejection reasons
rejection_reason[code] string A text label identifying the reason
rejection_reason[detail] string A detailed explanation of why the Offer was declined. This can be shared with your customer
rejection_reason[params] dictionary A dictionary of dynamic key-value pairs which can be used to customize the rejection reason

Note: When your customer clicks on the Payment plan's payment_url a Deferred Payment object will be created automatically.

Request a New Offer

Request

POST /v1/payment/offers HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "order": "order-dTHo9Q2idffT7CMPCVjztA",
  "urls": {
    "success": "https://merchant.com/payment/ok",
    "failure": "https://merchant.com/checkout",
    "cancel": "https://merchant.com/checkout",
    "notification": "https://backend.merchant.com/payment/notifications",
    "merchant_terms": "https://merchant.com/terms"
  },
  "locale": "en-gb",
  "metadata": {}
}
curl --request POST \
     --url https://api-sandbox.hokodo.co/v1/payment/offers \
     --header "Content-Type: application/json" \
     --header "Authorization: <your_api_key>" \
     --data-binary '{
  "order": "order-dTHo9Q2idffT7CMPCVjztA",
  "urls": {
    "success": "https://merchant.com/payment/ok",
    "failure": "https://merchant.com/checkout",
    "cancel": "https://merchant.com/checkout",
    "notification": "https://backend.merchant.com/payment/notifications",
    "merchant_terms": "https://merchant.com/terms"
  },
  "locale": "en-gb",
  "metadata": {}
}'

Responses

  • Offer Offered
201 Created
Content-Type: application/json
{
  "url": "https://api-sandbox.hokodo.co/v1/payment/offers/offer-EzH6BixNSHvaByEpXcFW5h",
  "id": "offer-bqRyHAGaFrDEN8JNjXJirp",
  "order": "order-dTHo9Q2idffT7CMPCVjztA",
  "offered_payment_plans": [
    {
        "id": "pln-bqRyHAGaFrDEN8JNjXJirp",
        "name": "net30",
        "currency": "GBP",
        "scheduled_payments": [
          {
            "date": "2020-10-16",
            "amount": 100000,
            "allowed_payment_methods": [
              {"type": "card"},
              {"type": "direct_debit"},
              {"type": "invoice"}
            ]
          }
        ],
        "merchant_fee": {
          "currency": "GBP",
          "amount": 1000
        },
        "customer_fee": {
          "currency": "GBP",
          "amount": 0
        },
        "valid_until": "2020-09-16T12:44:49.841Z",
        "payment_url": "https://payment.app.hokodo.co/plans/pln-bqRyHAGaFrDEN8JNjXJirp"
        "status": "offered",
        "rejection_reason": null
    },
    {
        "id": "pln-gJdDHAGaFrDLDvJNXJird",
        "name": "4x",
        "currency": "GBP",
        "scheduled_payments": [
          {
            "date": "2020-09-16",
            "amount": 25100,
            "allowed_payment_methods": [
              {"type": "card"}
            ]
          },
          {
            "date": "2020-10-16",
            "amount": 25100,
            "allowed_payment_methods": [
              {"type": "card"}
            ]
          },
          {
            "date": "2020-11-16",
            "amount": 25100,
            "allowed_payment_methods": [
              {"type": "card"}
            ]
          },
          {
            "date": "2020-12-16",
            "amount": 25100,
            "allowed_payment_methods": [
              {"type": "card"}
            ]
          }
        ],
        "merchant_fee": {
          "currency": "GBP",
          "amount": 2000
        },
        "customer_fee": {
          "currency": "GBP",
          "amount": 400
        },
        "valid_until": "2020-09-16T12:44:49.841Z",
        "payment_url": "https://payment.app.hokodo.co/plans/pln-gJdDHAGaFrDLDvJNXJird"
        "status": "offered",
        "rejection_reason": null
    }
  ],
  "urls": {
    "success": "https://merchant.com/payment/ok",
    "failure": "https://merchant.com/checkout",
    "cancel": "https://merchant.com/checkout",
    "notification": "https://backend.merchant.com/payment/notifications",
    "merchant_terms": "https://merchant.com/terms"
  },
  "locale": "en-gb",
  "metadata": {}
}
  • Offer Rejected
201 Created
Content-Type: application/json
{
  "url": "https://api-sandbox.hokodo.co/v1/payment/offers/offer-3VezfMFGKX6U247jRhXAkQ",
  "id": "offer-3VezfMFGKX6U247jRhXAkQ",
  "order": "order-yQKxbtCg9aTS5JYnsRVA9B",
  "offered_payment_plans": [
    {
        "id": "pln-bqRyHAGaFrDEN8JNjXJirp",
        "name": "net30",
        "currency": "GBP",
        "scheduled_payments": [
          {
            "date": "2020-10-16",
            "amount": 100000,
            "allowed_payment_methods": [
              {"type": "card"},
              {"type": "direct_debit"},
              {"type": "invoice"}
            ]
          }
        ],
        "merchant_fee": {
          "currency": "GBP",
          "amount": 1000
        },
        "customer_fee": {
          "currency": "GBP",
          "amount": 0
        },
        "valid_until": "2020-09-16T12:44:49.841Z",
        "payment_url": "https://payment.app.hokodo.co/plans/pln-bqRyHAGaFrDEN8JNjXJirp"
        "status": "declined",
        "rejection_reason": {
          "code": "buyer-country",
          "detail": "We're currently unable to provide payment plans to Buyers domiciled in {debtor_country}.",
          "params": {
            "debtor_country": "Ireland",
          }
        },
    },
    {
        "id": "pln-gJdDHAGaFrDLDvJNXJird",
        "name": "4x",
        "currency": "GBP",
        "scheduled_payments": [
          {
            "date": "2020-09-16",
            "amount": 25100,
            "allowed_payment_methods": [
              {"type": "card"}
            ]
          },
          {
            "date": "2020-10-16",
            "amount": 25100,
            "allowed_payment_methods": [
              {"type": "card"}
            ]
          },
          {
            "date": "2020-11-16",
            "amount": 25100,
            "allowed_payment_methods": [
              {"type": "card"}
            ]
          },
          {
            "date": "2020-12-16",
            "amount": 25100,
            "allowed_payment_methods": [
              {"type": "card"}
            ]
          }
        ],
        "merchant_fee": {
          "currency": "GBP",
          "amount": 2000
        },
        "customer_fee": {
          "currency": "GBP",
          "amount": 400
        },
        "valid_until": "2020-09-16T12:44:49.841Z",
        "payment_url": "https://payment.app.hokodo.co/plans/pln-gJdDHAGaFrDLDvJNXJird"
        "status": "declined",
        "rejection_reason": {
          "code": "buyer-country",
          "detail": "We're currently unable to provide payment plans to Buyers domiciled in {debtor_country}.",
          "params": {
            "debtor_country": "Ireland",
          }
        },
    }
  ],
  "urls": {
    "success": "https://merchant.com/payment/ok",
    "failure": "https://merchant.com/checkout",
    "cancel": "https://merchant.com/checkout",
    "notification": "https://backend.merchant.com/payment/notifications",
    "merchant_terms": "https://merchant.com/terms"
  },
  "locale": "en-gb",
  "metadata": {}
}

This endpoint is used to create a list of payment options for your customer. The required fields are

You can optionally include a metadata object to store additional information about the Offer.

field type flags description
order string(uuid) required API unique identifier of the order
urls dictionary required Redirection and callback URLs
urls[merchant_terms] string(url) optional URL for the terms and conditions of your platform, to display to the user
urls[success] string(url) required URL to redirect the customer to if the deferred payment application is a success
urls[failure] string(url) required URL to redirect the customer to if the deferred payment application is rejected. For example the checkout page to finish with another payment method
urls[cancel] string(url) required URL to redirect the customer to if they cancel the application before completing it. For example the checkout page to finish with another payment method
urls[notification] string(url) optional Callback URL to receive notifications about the deferred payment application
locale string optional Language and region of the customer (RFC 1766), for example "en-gb" or "fr-fr"
metadata dictionary optional Set of key-value pairs to store additional information about the Offer.

Errors

errors description
400 a required field is missing
409 can't obtain an offer as order has already been paid

List Offers

Request

GET /v1/payment/offers HTTP/1.1
Authorization: Token <your_api_key>
curl --request GET \
     --url https://api-sandbox.hokodo.co/v1/payment/offers \
     --header "Authorization: <your_api_key>"
}"

Response

200 Ok
Content-Type: application/json
{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "url": "https://api-sandbox.hokodo.co/v1/payment/offers/offer-EzH6BixNSHvaByEpXcFW5h",
      "id": "offer-bqRyHAGaFrDEN8JNjXJirp",
      "order": "order-dTHo9Q2idffT7CMPCVjztA",
      "offered_payment_plans": [
        {
            "id": "pln-bqRyHAGaFrDEN8JNjXJirp",
            "name": "net30",
            "currency": "GBP",
            "scheduled_payments": [
              {
                "date": "2020-10-16",
                "amount": 100000,
                "allowed_payment_methods": [
                  {"type": "card"},
                  {"type": "direct_debit"},
                  {"type": "invoice"}
                ]
              }
            ],
            "merchant_fee": {
              "currency": "GBP",
              "amount": 1000
            },
            "customer_fee": {
              "currency": "GBP",
              "amount": 0
            },
            "valid_until": "2020-09-16T12:44:49.841Z",
            "payment_url": "https://payment.app.hokodo.co/plans/pln-bqRyHAGaFrDEN8JNjXJirp"
            "status": "offered",
            "rejection_reason": null
        },
        {
            "id": "pln-gJdDHAGaFrDLDvJNXJird",
            "name": "4x",
            "currency": "GBP",
            "scheduled_payments": [
              {
                "date": "2020-09-16",
                "amount": 25100,
                "allowed_payment_methods": [
                  {"type": "card"}
                ]
              },
              {
                "date": "2020-10-16",
                "amount": 25100,
                "allowed_payment_methods": [
                  {"type": "card"}
                ]
              },
              {
                "date": "2020-11-16",
                "amount": 25100,
                "allowed_payment_methods": [
                  {"type": "card"}
                ]
              },
              {
                "date": "2020-12-16",
                "amount": 25100,
                "allowed_payment_methods": [
                  {"type": "card"}
                ]
              }
            ],
            "merchant_fee": {
              "currency": "GBP",
              "amount": 2000
            },
            "customer_fee": {
              "currency": "GBP",
              "amount": 400
            },
            "valid_until": "2020-09-16T12:44:49.841Z",
            "payment_url": "https://payment.app.hokodo.co/plans/pln-gJdDHAGaFrDLDvJNXJird"
            "status": "offered",
            "rejection_reason": null
        },
      ],
      "urls": {
        "success": "https://merchant.com/payment/ok",
        "failure": "https://merchant.com/checkout",
        "cancel": "https://merchant.com/checkout",
        "notification": "https://backend.merchant.com/payment/notifications",
        "merchant_terms": "https://merchant.com/terms"
      },
      "locale": "en-gb",
      "metadata": {}
    },
    {
      "url": "https://api-sandbox.hokodo.co/v1/payment/offers/offer-3VezfMFGKX6U247jRhXAkQ",
      "id": "offer-3VezfMFGKX6U247jRhXAkQ",
      "order": "order-yQKxbtCg9aTS5JYnsRVA9B",
      "offered_payment_plans": [
        {
            "id": "pln-bqRyHAGaFrDEN8JNjXJirp",
            "name": "net30",
            "currency": "GBP",
            "scheduled_payments": [
              {
                "date": "2020-10-16",
                "amount": 100000,
                "allowed_payment_methods": [
                  {"type": "card"},
                  {"type": "direct_debit"},
                  {"type": "invoice"}
                ]
              }
            ],
            "merchant_fee": {
              "currency": "GBP",
              "amount": 1000
            },
            "customer_fee": {
              "currency": "GBP",
              "amount": 0
            },
            "valid_until": "2020-09-16T12:44:49.841Z",
            "payment_url": "https://payment.app.hokodo.co/plans/pln-bqRyHAGaFrDEN8JNjXJirp"
            "status": "declined",
            "rejection_reason": {
              "code": "buyer-country",
              "detail": "We're currently unable to provide payment plans to Buyers domiciled in {debtor_country}.",
              "params": {
                "debtor_country": "Ireland",
              }
            },
        },
        {
            "id": "pln-gJdDHAGaFrDLDvJNXJird",
            "name": "4x",
            "currency": "GBP",
            "scheduled_payments": [
              {
                "date": "2020-09-16",
                "amount": 25100,
                "allowed_payment_methods": [
                  {"type": "card"}
                ]
              },
              {
                "date": "2020-10-16",
                "amount": 25100,
                "allowed_payment_methods": [
                  {"type": "card"}
                ]
              },
              {
                "date": "2020-11-16",
                "amount": 25100,
                "allowed_payment_methods": [
                  {"type": "card"}
                ]
              },
              {
                "date": "2020-12-16",
                "amount": 25100,
                "allowed_payment_methods": [
                  {"type": "card"}
                ]
              }
            ],
            "merchant_fee": {
              "currency": "GBP",
              "amount": 2000
            },
            "customer_fee": {
              "currency": "GBP",
              "amount": 400
            },
            "valid_until": "2020-09-16T12:44:49.841Z",
            "payment_url": "https://payment.app.hokodo.co/plans/pln-gJdDHAGaFrDLDvJNXJird"
            "status": "declined",
            "rejection_reason": {
              "code": "buyer-country",
              "detail": "We're currently unable to provide payment plans to Buyers domiciled in {debtor_country}.",
              "params": {
                "debtor_country": "Ireland",
              }
            },
        }
      ],
      "urls": {
        "success": "https://merchant.com/payment/ok",
        "failure": "https://merchant.com/checkout",
        "cancel": "https://merchant.com/checkout",
        "notification": "https://backend.merchant.com/payment/notifications",
        "merchant_terms": "https://merchant.com/terms"
      },
      "locale": "en-gb",
      "metadata": {}
    }
  ]
}

List all previously requested Offers

View Offer

Request

GET /v1/payment/offers/<offer_id> HTTP/1.1
Authorization: Token <your_api_key>
curl --request GET \
     --url https://api-sandbox.hokodo.co/v1/payment/offers/<offer_id> \
     --header "Authorization: <your_api_key>"
}"

Responses

  • Regular Response
200 Ok
Content-Type: application/json
{
  "url": "https://api-sandbox.hokodo.co/v1/payment/offers/offer-EzH6BixNSHvaByEpXcFW5h",
  "id": "offer-bqRyHAGaFrDEN8JNjXJirp",
  "order": "order-dTHo9Q2idffT7CMPCVjztA",
  "offered_payment_plans": [
    {
        "id": "pln-bqRyHAGaFrDEN8JNjXJirp",
        "name": "net30",
        "currency": "GBP",
        "scheduled_payments": [
          {
            "date": "2020-10-16",
            "amount": 100000,
            "allowed_payment_methods": [
              {"type": "card"},
              {"type": "direct_debit"},
              {"type": "invoice"}
            ]
          }
        ],
        "merchant_fee": {
          "currency": "GBP",
          "amount": 1000
        },
        "customer_fee": {
          "currency": "GBP",
          "amount": 0
        },
        "valid_until": "2020-09-16T12:44:49.841Z",
        "payment_url": "https://payment.app.hokodo.co/plans/pln-bqRyHAGaFrDEN8JNjXJirp"
        "status": "offered",
        "rejection_reason": null
    },
    {
        "id": "pln-gJdDHAGaFrDLDvJNXJird",
        "name": "4x",
        "currency": "GBP",
        "scheduled_payments": [
          {
            "date": "2020-09-16",
            "amount": 25100,
            "allowed_payment_methods": [
              {"type": "card"}
            ]
          },
          {
            "date": "2020-10-16",
            "amount": 25100,
            "allowed_payment_methods": [
              {"type": "card"}
            ]
          },
          {
            "date": "2020-11-16",
            "amount": 25100,
            "allowed_payment_methods": [
              {"type": "card"}
            ]
          },
          {
            "date": "2020-12-16",
            "amount": 25100,
            "allowed_payment_methods": [
              {"type": "card"}
            ]
          }
        ],
        "merchant_fee": {
          "currency": "GBP",
          "amount": 2000
        },
        "customer_fee": {
          "currency": "GBP",
          "amount": 400
        },
        "valid_until": "2020-09-16T12:44:49.841Z",
        "payment_url": "https://payment.app.hokodo.co/plans/pln-gJdDHAGaFrDLDvJNXJird"
        "status": "offered",
        "rejection_reason": null
    },
  ],
  "urls": {
    "success": "https://merchant.com/payment/ok",
    "failure": "https://merchant.com/checkout",
    "cancel": "https://merchant.com/checkout",
    "notification": "https://backend.merchant.com/payment/notifications",
    "merchant_terms": "https://merchant.com/terms"
  },
  "locale": "en-gb",
  "metadata": {}
}
  • Not Found
404 Not Found
Content-Type: application/json
{
  "detail": "Not found."
}

Retrieve a Previously Requested Offer

Errors

Errors Description
404 The Offer id is probably incorrect, a Offer has not been found

Delete Offer

Request

DELETE /v1/payment/offers/<offer_id> HTTP/1.1
Authorization: Token <your_api_key>
curl --request DELETE \
     --url https://api-sandbox.hokodo.co/v1/payment/offers/<offer_id> \
     --header "Authorization: <your_api_key>"
}"

Responses

  • Regular Response
204 No Content
  • Not Found
404 Not Found
Content-Type: application/json
{
  "detail": "Not found."
}
  • Unable to Delete Accepted Offer
409 Conflict
Content-Type: application/json

Delete a Previously Requested Offer

Errors

errors description
404 The Offer id is probably incorrect, a Offer has not been found
409 Can't delete the Offer, probably because it's already been accepted

Mail offer to customer

Request

PUT /v1/payment/payment_plans/pln-bqRyHAGaFrDEN8JNjXJirp/send_offer_email HTTP/1.1
Authorization: Token <your_api_key>
curl --request PUT \
     --url https://api-sandbox.hokodo.co/v1/payment/payment_plans/pln-bqRyHAGaFrDEN8JNjXJirp/send_offer_email \
     --header "Authorization: <your_api_key>"

Responses

  • Offer sent to customer by email
200 OK
Content-Type: application/json
{
    "detail": "Payment plan email sent."
}

You can use this endpoint to have Hokodo send an email to the customer, with a link to a specific payment plan.

Errors

errors description
400 Payment Plan invalid (for example declined)

Post-sale Order actions

After a PaymentOffer has been accepted by the customer, you will need to use the following endpoints to make modifications to the Order.

These will not all be necessary for every order. The base flow would be:

  1. Create the Order.
  2. Request the PaymentOffer.
  3. The customer accepts one of the payment plans and confirms the order.
  4. You mark the order as fulfilled as you ship it.
  5. Hokodo sends you the money immediately.
  6. The customer pays Hokodo later.

Post-sale Order endpoints

Fulfillment

Request

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

{
  "items": [
    {
      "item_id": "1",
      "quantity": "10.000",
      "total_amount": 10000,
      "tax_amount": 1667,
      "shipping_id": "DX49581904385",
      "shipping_provider": "Postal service"
    },
    {
      "item_id": "2",
      "quantity": "1.000",
      "total_amount": 2000,
      "tax_amount": 333,
      "shipping_id": "DX49581904385",
      "shipping_provider": "Postal service"
    }
  ]
}
curl --request PATCH \
     --url https://api-sandbox.hokodo.co/v1/payment/orders/<order_id>/fulfill \
     --header "Content-Type: application/json" \
     --header "Authorization: <your_api_key>" \
     --data-binary '{
  "items": [
    {
      "item_id": "1",
      "quantity": "10.000",
      "total_amount": 10000,
      "tax_amount": 1667,
      "shipping_id": "DX49581904385",
      "shipping_provider": "Postal service"
    },
    {
      "item_id": "2",
      "quantity": "1.000",
      "total_amount": 2000,
      "tax_amount": 333,
      "shipping_id": "DX49581904385",
      "shipping_provider": "Postal service"
    }
  ]
}'

Response

200 Ok
Content-Type: application/json
{
  "url": "https://api-sandbox.hokodo.co/v1/payment/orders/order-yQKxbtCg9aTS5JYnsRVA9B",
  "id": "order-yQKxbtCg9aTS5JYnsRVA9B",
  "unique_id": "876987-987uinjojna-I8UH98Jnj",
  "customer": {
    "type": "registered",
    "organisation": "org-ypTaHiLv5kgqSn4TzCr7xb",
    "user": "user-nNqgg5AFymQMumaU7EdrLa",
    "delivery_address": {
      "name": "John Smith",
      "address_line1": "1 Station Street",
      "address_line2": "Flat B",
      "address_line3": "",
      "city": "London",
      "region": "",
      "postcode": "SE11 6NQ",
      "country": "GB",
      "phone": "",
      "email": ""
    },
  },
  "status": "pending",
  "currency": "GBP",
  "pay_method": "",
  "total_amount": 12000,
  "tax_amount": 2000,
  "order_date": "2018-04-25",
  "invoice_date": "2018-04-25",
  "due_date": "2018-06-25",
  "paid_date": null,
  "items": [
    {
      "item_id": "1",
      "type": "product",
      "description": "Super ergonomic chair",
      "metadata": {"color": "black", "name": "Karmus", "variant": "M"},
      "reference": "702.611.50",
      "category": "Furniture > Chairs",
      "supplier_id": "7363",
      "supplier_name": "",
      "quantity": "10.000",
      "unit_price": 1000,
      "tax_rate": "20.00",
      "total_amount": 10000,
      "tax_amount": 1667,
      "fulfillment_info": [
        {
          "quantity": "10.000",
          "total_amount": 10000,
          "tax_amount": 1667,
          "shipping_id": "DX49581904385",
          "shipping_provider": "Postal service",
          "shipping_date": "2018-04-26"
        }
      ]
    },
    {
      "item_id": "2",
      "type": "shipping",
      "description": "Delivery fee",
      "metadata": {},
      "reference": "",
      "category": "",
      "supplier_id": "",
      "supplier_name": "",
      "quantity": "1.000",
      "unit_price": 2000,
      "tax_rate": "20.00",
      "total_amount": 2000,
      "tax_amount": 333,
      "fulfillment_info": [
        {
          "quantity": "1.000",
          "total_amount": 2000,
          "tax_amount": 333,
          "shipping_id": "DX49581904385",
          "shipping_provider": "Postal service",
          "shipping_date": "2018-04-26"
        }
      ]
    }
  ],
  "metadata": {
    "customer_id": "2055b445-3d95-4d2f-bd80-3e336217905f",
    "checkout_id": "c0185e68-89aa-42d5-93e9-476d01d4c97f"
  },
  "payment_offer": "offer-cqfxJVUwXBrkyZHRQaknJS",
  "deferred_payment": "defpay-7PiKMX2gEpJmasb8Du65zn"
}

Fulfillment refers to the process of shipping the goods to the customer, or providing them with the service they have purchased. It is important that you notify Hokodo when fulfillment occurs since this is the trigger for our payment to you. This endpoint is usually called when the package has been handed over to the logistics carrier. Hint: Make sure that your fulfillment department (or external partner) has access to the API. Often, this requires some planning ahead.

Fulfillment information must include date and all items that have actually been delivered to the customer in the format similar to the list of items in the Order.

You can either ship the full order or only parts of the order. In case you initially only ship parts of the order:

field type flags description
items list required The list of items that got shipped, each with the fields described below
item_id string required Your identifier for this line of the order, e.g. 1, 2, 3...
quantity decimal required Number of items shipped
total_amount int required Total amount including tax of the items that shipped, in minor units (cents)
tax_amount int required Total amount of the taxes of the items that shipped, in minor units (cents)
shipping_id string optional Tracking id of the shipping provider
shipping_provider string optional Name of the shipping provider

Errors

errors description
404 the order_id is probably invalid, the order has not been found
400 a required field is missing or some of the fields have incorrect value

Cancellation

Request

  • partial cancellation of half the items in the Order
PUT /v1/payment/orders/<order_id>/cancel HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "items": [
    {
      "item_id": "1",
      "quantity": "5.000",
      "total_amount": 5000,
      "tax_amount": 834
    }
  ]
}
curl --request PATCH \
     --url https://api-sandbox.hokodo.co/v1/payment/orders/<order_id>/cancel \
     --header "Content-Type: application/json" \
     --header "Authorization: <your_api_key>" \
     --data-binary '{
  "items": [
    {
      "item_id": "1",
      "quantity": "5.000",
      "total_amount": 5000,
      "tax_amount": 834
    }
  ]
}'

Response

200 Ok
Content-Type: application/json
{
  "url": "https://api-sandbox.hokodo.co/v1/payment/orders/order-yQKxbtCg9aTS5JYnsRVA9B",
  "id": "order-yQKxbtCg9aTS5JYnsRVA9B",
  "unique_id": "876987-987uinjojna-I8UH98Jnj",
  "customer": {
    "type": "registered",
    "organisation": "org-ypTaHiLv5kgqSn4TzCr7xb",
    "user": "user-nNqgg5AFymQMumaU7EdrLa",
    "delivery_address": {
      "name": "John Smith",
      "address_line1": "1 Station Street",
      "address_line2": "Flat B",
      "address_line3": "",
      "city": "London",
      "region": "",
      "postcode": "SE11 6NQ",
      "country": "GB",
      "phone": "",
      "email": ""
    },
  },
  "status": "pending",
  "currency": "GBP",
  "pay_method": "",
  "total_amount": 7000,
  "tax_amount": 1166,
  "order_date": "2018-04-25",
  "invoice_date": "2018-04-25",
  "due_date": "2018-06-25",
  "paid_date": null,
  "items": [
    {
      "item_id": "1",
      "type": "product",
      "description": "Super ergonomic chair",
      "metadata": {"color": "black", "name": "Karmus", "variant": "M"},
      "reference": "702.611.50",
      "category": "Furniture > Chairs",
      "supplier_id": "7363",
      "supplier_name": "",
      "quantity": "5.000",
      "unit_price": 1000,
      "tax_rate": "20.00",
      "total_amount": 5000,
      "tax_amount": 833,
      "fulfillment_info": null
    },
    {
      "item_id": "2",
      "type": "shipping",
      "description": "Delivery fee",
      "metadata": {},
      "reference": "",
      "category": "",
      "supplier_id": "",
      "supplier_name": "",
      "quantity": "1.000",
      "unit_price": 2000,
      "tax_rate": "20.00",
      "total_amount": 2000,
      "tax_amount": 333,
      "fulfillment_info": null
    }
  ],
  "metadata": {
    "customer_id": "2055b445-3d95-4d2f-bd80-3e336217905f",
    "checkout_id": "c0185e68-89aa-42d5-93e9-476d01d4c97f"
  },
  "payment_offer": "offer-cqfxJVUwXBrkyZHRQaknJS",
  "deferred_payment": "defpay-7PiKMX2gEpJmasb8Du65zn"
}

If an order or individual items from an order are being cancelled by the customer before shipping, you need to notify us of the cancellation.

You can either cancel the full order or only parts of the order. In case you only cancel parts of the order:

Returns

Request

  • partial return of half the items in the Order
PUT /v1/payment/orders/<order_id>/return HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "items": [
    {
      "item_id": "1",
      "quantity": "5.000",
      "total_amount": 5000,
      "tax_amount": 834
    }
  ]
}
curl --request PATCH \
     --url https://api-sandbox.hokodo.co/v1/payment/orders/<order_id>/return \
     --header "Content-Type: application/json" \
     --header "Authorization: <your_api_key>" \
     --data-binary '{
  "items": [
    {
      "item_id": "1",
      "quantity": "5.000",
      "total_amount": 5000,
      "tax_amount": 834
    }
  ]
}'

Response

200 Ok
Content-Type: application/json
{
  "url": "https://api-sandbox.hokodo.co/v1/payment/orders/order-yQKxbtCg9aTS5JYnsRVA9B",
  "id": "order-yQKxbtCg9aTS5JYnsRVA9B",
  "unique_id": "876987-987uinjojna-I8UH98Jnj",
  "customer": {
    "type": "registered",
    "organisation": "org-ypTaHiLv5kgqSn4TzCr7xb",
    "user": "user-nNqgg5AFymQMumaU7EdrLa",
    "delivery_address": {
      "name": "John Smith",
      "address_line1": "1 Station Street",
      "address_line2": "Flat B",
      "address_line3": "",
      "city": "London",
      "region": "",
      "postcode": "SE11 6NQ",
      "country": "GB",
      "phone": "",
      "email": ""
    },
  },
  "status": "pending",
  "currency": "GBP",
  "pay_method": "",
  "total_amount": 7000,
  "tax_amount": 1166,
  "order_date": "2018-04-25",
  "invoice_date": "2018-04-25",
  "due_date": "2018-06-25",
  "paid_date": null,
  "items": [
    {
      "item_id": "1",
      "type": "product",
      "description": "Super ergonomic chair",
      "metadata": {"color": "black", "name": "Karmus", "variant": "M"},
      "reference": "702.611.50",
      "category": "Furniture > Chairs",
      "supplier_id": "7363",
      "supplier_name": "",
      "quantity": "5.000",
      "unit_price": 1000,
      "tax_rate": "20.00",
      "total_amount": 5000,
      "tax_amount": 833,
      "fulfillment_info": [
        {
          "quantity": "10.000",
          "total_amount": 10000,
          "tax_amount": 1667,
          "shipping_id": "DX49581904385",
          "shipping_provider": "Postal service",
          "shipping_date": "2018-04-26"
        }
      ]
    },
    {
      "item_id": "2",
      "type": "shipping",
      "description": "Delivery fee",
      "metadata": {},
      "reference": "",
      "category": "",
      "supplier_id": "",
      "supplier_name": "",
      "quantity": "1.000",
      "unit_price": 2000,
      "tax_rate": "20.00",
      "total_amount": 2000,
      "tax_amount": 333,
      "fulfillment_info": [
        {
          "quantity": "10.000",
          "total_amount": 10000,
          "tax_amount": 1667,
          "shipping_id": "DX49581904385",
          "shipping_provider": "Postal service",
          "shipping_date": "2018-04-26"
        }
      ]
    }
  ],
  "metadata": {
    "customer_id": "2055b445-3d95-4d2f-bd80-3e336217905f",
    "checkout_id": "c0185e68-89aa-42d5-93e9-476d01d4c97f"
  },
  "payment_offer": "offer-cqfxJVUwXBrkyZHRQaknJS",
  "deferred_payment": "defpay-7PiKMX2gEpJmasb8Du65zn"
}

If a shipped order (or individual items from an order) are being returned by the customer after shipping, you need to notify us of the return.

You can either return the full order or only parts of the order. In case you only return parts of the order:

Refunds / discounts

Request

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

{
  "items": [
    {
      "item_id": "99",
      "description": "Discount following our email conversation",
      "quantity": "1.000",
      "unit_price": -120,
      "tax_rate": "20.00",
      "total_amount": -120,
      "tax_amount": -20
    }
  ]
}
curl --request PATCH \
     --url https://api-sandbox.hokodo.co/v1/payment/orders/<order_id>/discount \
     --header "Content-Type: application/json" \
     --header "Authorization: <your_api_key>" \
     --data-binary '{
  "items": [
    {
      "item_id": "99",
      "description": "Discount following our email conversation",
      "quantity": "1.000",
      "unit_price": -120,
      "tax_rate": "20.00",
      "total_amount": -120,
      "tax_amount": -20
    }
  ]
}'

Response

200 Ok
Content-Type: application/json
{
  "url": "https://api-sandbox.hokodo.co/v1/payment/orders/order-yQKxbtCg9aTS5JYnsRVA9B",
  "id": "order-yQKxbtCg9aTS5JYnsRVA9B",
  "unique_id": "876987-987uinjojna-I8UH98Jnj",
  "customer": {
    "type": "registered",
    "organisation": "org-ypTaHiLv5kgqSn4TzCr7xb",
    "user": "user-nNqgg5AFymQMumaU7EdrLa",
    "delivery_address": {
      "name": "John Smith",
      "address_line1": "1 Station Street",
      "address_line2": "Flat B",
      "address_line3": "",
      "city": "London",
      "region": "",
      "postcode": "SE11 6NQ",
      "country": "GB",
      "phone": "",
      "email": ""
    },
  },
  "status": "pending",
  "currency": "GBP",
  "pay_method": "",
  "total_amount": 11880,
  "tax_amount": 1980,
  "order_date": "2018-04-25",
  "invoice_date": "2018-04-25",
  "due_date": "2018-06-25",
  "paid_date": null,
  "items": [
    {
      "item_id": "1",
      "type": "product",
      "description": "Super ergonomic chair",
      "metadata": {"color": "black", "name": "Karmus", "variant": "M"},
      "reference": "702.611.50",
      "category": "Furniture > Chairs",
      "supplier_id": "7363",
      "supplier_name": "",
      "quantity": "10.000",
      "unit_price": 1000,
      "tax_rate": "20.00",
      "total_amount": 10000,
      "tax_amount": 1667,
      "fulfillment_info": [
        {
          "quantity": "10.000",
          "total_amount": 10000,
          "tax_amount": 1667,
          "shipping_id": "DX49581904385",
          "shipping_provider": "Postal service",
          "shipping_date": "2018-04-26"
        }
      ]
    },
    {
      "item_id": "2",
      "type": "shipping",
      "description": "Delivery fee",
      "metadata": {},
      "reference": "",
      "category": "",
      "supplier_id": "",
      "supplier_name": "",
      "quantity": "1.000",
      "unit_price": 2000,
      "tax_rate": "20.00",
      "total_amount": 2000,
      "tax_amount": 333,
      "fulfillment_info": [
        {
          "quantity": "1.000",
          "total_amount": 2000,
          "tax_amount": 333,
          "shipping_id": "DX49581904385",
          "shipping_provider": "Postal service",
          "shipping_date": "2018-04-26"
        }
      ]
    },
    {
      "item_id": "99",
      "type": "discount",
      "description": "Discount following our email conversation",
      "metadata": {},
      "reference": "",
      "category": "",
      "supplier_id": "",
      "supplier_name": "",
      "quantity": "1.000",
      "unit_price": -120,
      "tax_rate": "20.00",
      "total_amount": -120,
      "tax_amount": -20,
      "fulfillment_info": null
    }
  ],
  "metadata": {
    "customer_id": "2055b445-3d95-4d2f-bd80-3e336217905f",
    "checkout_id": "c0185e68-89aa-42d5-93e9-476d01d4c97f"
  },
  "payment_offer": "offer-cqfxJVUwXBrkyZHRQaknJS",
  "deferred_payment": "defpay-7PiKMX2gEpJmasb8Du65zn"
}

If a customer files a complaint, but does not return any items and you want to refund some of the money, you can send us an unspecified refund or discount.

This refund or discount becomes a new line of the Order.

Disputes

If a customer files a complaint on a shipped order, and you can’t settle the dispute in a timely manner, we need to make sure, that we don’t debit the customer before the dispute is resolved. For that reason you need to send us a dispute notification, that then needs to be lifted once the dispute has been resolved.

As a result of an accepted dispute notification Hokodo will refrain from debiting the customer until the dispute has been actively resolved.

Note: If we already paid you, we will hold back the disputed sum from your next merchant payment until the dispute is resolved.

This endpoint is not available yet.

Deferred Payments

A Deferred Payment object is created when your customer completes the process to pay with Hokodo.

Deferred Payment Endpoints

Deferred Payment Object

{
  "url": "https://api-sandbox.hokodo.co/v1/payment/deferred_payments/defpay-bqRyGIGaORKiK8bhMVPirp",
  "id": "defpay-bqRyGIGaORKiK8bhMVPirp",
  "number": "P-7WR2-PR0S",  
  "payment_plan": "pln-gJdDHAGaFrDLDvJNXJird",
  "order": "order-dTHo9Q2idffT7CMPCVjztA",
  "status": "pending_review"
}
field type description
url string API endpoint to access the Deferred Payment
id string(uuid) API unique identifier for the Deferred Payment
number string The Deferred Payment's customer friendly public identifier (e.g. "P-7WR2-PR0S")
payment_plan string(uuid) API unique identifier of the personalised payment plan attached to the deferred payment
order string(uuid) API identifier for the Order
status string Deferred Payment status

Deferred Payment status

When it is created, the deferred payment status can be one of:

code description
accepted the payment has been accepted
pending_review the payment is pending manual review by Hokodo, you will be notified of the result
customer_action_required more information is required by the customer (e.g. upload KYC documents)
rejected the payment has been rejected by Hokodo

After that, the deferred payment status can become one of:

code description
cancelled the payment has been cancelled
part_fulfilled the order has been partially fulfilled
fulfilled the order has been entirely fulfilled
reversed

We will be adding more statuses here soon to help you monitor the state of fulfillment and disbursment of funds from Hokodo to you.

View Deferred Payment

Request

GET /v1/payment/deferred_payments/<deferredpayment_id> HTTP/1.1
Authorization: Token <your_api_key>
curl --request GET \
     --url https://api-sandbox.hokodo.co/v1/payment/deferred_payments/<deferredpayment_id> \
     --header "Authorization: <your_api_key>"
}"

Responses

  • Regular Response
200 Ok
Content-Type: application/json
{
  "url": "https://api-sandbox.hokodo.co/v1/payment/deferred_payments/defpay-bqRyGIGaORKiK8bhMVPirp",
  "id": "defpay-bqRyGIGaORKiK8bhMVPirp",
  "number": "P-7WR2-PR0S",  
  "payment_plan": "pln-gJdDHAGaFrDLDvJNXJird",
  "order": "order-dTHo9Q2idffT7CMPCVjztA",
  "status": "pending_review"
}
  • Not Found
404 Not Found
Content-Type: application/json
{
  "detail": "Not found."
}

Retrieve an Existing Deferred Payment

Webhooks / Notifications / Callbacks

Sample content

Deferred Payment Application Complete

{
    "created": "2021-01-01T12:00:00Z",
    "data": {
        "order": { 
            "id": "order-QWLGzh3ciDXo3P4QkPtrnH",
            "unique_id": "",
            "po_number": "",
            "customer": {
                "organisation": {
                    "id": "org-mSuTHdaodb5pjDmKsBj5Z4",
                    "unique_id": "1",
                    "registered": "2010-06-30T00:00:00Z",
                    "company": null,
                    "users": [
                        "96608083-4783-44e3-a474-4bad3fa6e82a"
                    ]
                },
                "user": {
                    "id": "user-pHm3kfFQXwzs8ND8HYNTYV",
                    "email": "syTnvfVbZjFv@email.com",
                    "unique_id": "",
                    "name": "name_SUUgVUVuRVaB",
                    "phone": "",
                    "registered": "2010-06-30T00:00:00Z",
                    "type": "registered"
                },
                "invoice_address": {
                    "name": "name_LGDZJAFYLRus",
                    "company_name": "company_name_touyMqWkVyAn",
                    "address_line1": "address_line1_gKmCACesrqbd",
                    "address_line2": "address_line2_shliflLciPie",
                    "address_line3": "",
                    "city": "city_edqpaQOKqUXI",
                    "region": "",
                    "postcode": "E1 1D0",
                    "country": "GB",
                    "phone": "",
                    "email": ""
                },
                "delivery_address": {
                    "name": "name_tLoyeGeGMXlc",
                    "company_name": "company_name_DgcvLcFejRbl",
                    "address_line1": "address_line1_XKWMakHAilHa",
                    "address_line2": "address_line2_MzczHXdoRqQR",
                    "address_line3": "",
                    "city": "city_jSjusADEJkuE",
                    "region": "",
                    "postcode": "E1 1D1",
                    "country": "GB",
                    "phone": "",
                    "email": ""
                },
                "billing_address": {
                    "name": "name_LGDZJAFYLRus",
                    "company_name": "company_name_touyMqWkVyAn",
                    "address_line1": "address_line1_gKmCACesrqbd",
                    "address_line2": "address_line2_shliflLciPie",
                    "address_line3": "",
                    "city": "city_edqpaQOKqUXI",
                    "region": "",
                    "postcode": "E1 1D0",
                    "country": "GB",
                    "phone": "",
                    "email": ""
                }
            },
            "created": "2020-11-10T08:31:39.915557Z",
            "currency": "EUR",
            "order_date": "2020-11-10",
            "invoice_date": null,
            "due_date": null,
            "paid_date": null,
            "total_amount": 1000,
            "tax_amount": 200,
            "metadata": null,
            "items": [
                {
                    "item_id": "0",
                    "type": "",
                    "description": "",
                    "metadata": null,
                    "reference": "",
                    "category": "",
                    "supplier_id": "",
                    "supplier_name": "",
                    "quantity": "10.000",
                    "unit_price": 100,
                    "total_amount": 1000,
                    "tax_amount": 200,
                    "tax_rate": "25.00",
                    "fulfilled_quantity": "0.000",
                    "cancelled_quantity": "0.000"
                }
            ],
            "payment_offer": {
                "url": "/v1/payment/offers/offr-SFRufpfb4wMh8Jkr84W8Gf",
                "id": "offr-SFRufpfb4wMh8Jkr84W8Gf",
                "order": "order-QWLGzh3ciDXo3P4QkPtrnH",
                "offered_payment_plans": [
                    {
                        "id": "ppln-E8tWZ3MahpeDp798k9fzVH",
                        "name": "",
                        "template": "pptemp-MNhaDZyoRatSZTyizGTgtb",
                        "currency": "EUR",
                        "scheduled_payments": [],
                        "merchant_fee": {
                            "currency": "EUR",
                            "amount": 0
                        },
                        "customer_fee": {
                            "currency": "EUR",
                            "amount": 0
                        },
                        "valid_until": "2020-11-17T08:31:40.059Z",
                        "payment_url": "https://api-sandbox.hokodo.co/?order=order-QWLGzh3ciDXo3P4QkPtrnH&plan=ppln-E8tWZ3MahpeDp798k9fzVH&key=cjuHbDjF3txeTaHgtDUilQ9UdYqHllC2iFFarKdJemU&template=pptemp-MNhaDZyoRatSZTyizGTgtb",
                        "status": "offered",
                        "rejection_reason": null
                    }
                ],
                "urls": {
                    "success": "",
                    "failure": "",
                    "cancel": "",
                    "notification": "",
                    "merchant_terms": ""
                },
                "locale": "",
                "metadata": null
            },
            "deferred_payment": {
                "url": "/v1/payment/deferred_payments/defpay-8BvTZ9T6K5gj6LeSqvfqzm",
                "id": "defpay-8BvTZ9T6K5gj6LeSqvfqzm",
                "number": "P-PMNE-DN6C",
                "payment_plan": {
                    "id": "ppln-E8tWZ3MahpeDp798k9fzVH",
                    "name": "",
                    "template": "pptemp-MNhaDZyoRatSZTyizGTgtb",
                    "currency": "EUR",
                    "scheduled_payments": [],
                    "merchant_fee": {
                        "currency": "EUR",
                        "amount": 0
                    },
                    "customer_fee": {
                        "currency": "EUR",
                        "amount": 0
                    },
                    "valid_until": "2020-11-17T08:31:40.059Z",
                    "payment_url": "https://api-sandbox.hokodo.co/?order=order-QWLGzh3ciDXo3P4QkPtrnH&plan=ppln-E8tWZ3MahpeDp798k9fzVH&key=cjuHbDjF3txeTaHgtDUilQ9UdYqHllC2iFFarKdJemU&template=pptemp-MNhaDZyoRatSZTyizGTgtb",
                    "status": "offered",
                    "rejection_reason": null
                },
                "order": "order-QWLGzh3ciDXo3P4QkPtrnH",
                "outstanding_balance": {
                    "amount": null,
                    "currency": "EUR"
                },
                "next_payment_date": null,
                "payments": null,
                "status": "accepted"
            },
            "status": "draft",
            "pay_method": "unknown"
        }
    }
}

Hokodo uses webhooks to notify your application when an event happens in your account. For example, when one of your customers has their deferred payment application approved.

Webhooks allow you to avoid polling and instead receive notifications when changes related to an Order, Offer or DeferredPayment object occur.

Webhook Payload

The webhook payload will include a full Order object.

field type description
created string Time the notification was sent (e.g. 2021-01-01T12:00:00Z)
data dictionary Dictionary containing the Order object
data[order] dictionary The Order object

The Order object will have the following fields expanded(if available):

Events

You will receive a notification when any of the following events occur:

Please note that the payload for all of the events will contain the latest version of the Order object with the expanded fields (if available) as described above.

Getting Started

1. Select Integration Option

Depending on your use-case Hokodo can configure your account so that all notifications will be sent to the same webhook. Alternatively, when you create an Offer you can include a notification url in the request and we'll send all notifications related to that specific Offer to this url. Changes to related objects such as the underlying Order or a DeferredPayment will also be sent to this url.

If you prefer the first option please let us know at support@hokodo.co and we will be happy to configure your account.

No additional setup is required if you prefer the second option. Note, if you do select this option, you won't receive any notifications about Order changes until you create an Offer.

2. Secure Your Webhook (optional)

For enhanced security, Hokodo can include an authentication string in the Authorization header of all notifications. If you're interested in this option please let us know at support@hokodo.co

Notes

  1. Your endpoint must be using HTTPS.

  2. In production, our API will verify the validity of the HTTPS certificate. In sandbox, you can use a self-signed certitificate.

  3. Our API will send a POST request, with the content of the Order in the POST request body as JSON.

  4. Our API expects a 2xx status code from your endpoint for a successful response.

  5. Our API will retry up to 3 times if it can't connect successfully to your endpoint. It will wait 0, 2, and 4 seconds respectively before the 1st, 2nd and 3rd retry.

Error codes

The Hokodo API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The requested function is not available for your account.
404 Not Found -- The specified object could not be found.
405 Method Not Allowed -- You tried to access an object with an invalid method.
409 Conflict -- The requested action conflicts with the current state of the object.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.