Create Checkout

currency
Type: string
required

The ISO 4217 currency code for this Checkout
initiatorReference
Type: string
required

This is used to implement idempotency. The supplied initiatorReference must be unique within a recent time window (default 24 hours). If a initiatorReference that was recently seen is used again then we will return the same request as was returned the first time but with the 'idempotent-previously-seen' header set to true. The initiatorReference is also copied into the Merchant Reference field of any transactions created by the checkout session.
items
Type: array object[]
required

A minimum of 1 item must be specified.
- amountCentile
  Type: integer
  min:
  1
  required
  
  A centile amount for the item in the currency specified for the checkout request.
- description
  Type: string
  required
  
  A textual description of the item being purchased.
- productCode
  Type: string
  max length:
  32
  
  Optional field to associate product code with the item. An example of when this could be useful is in an e-commerce usecase, here the specified product code will be returned in the events stream when the checkout is finalised, this will allow exact identification of Items to be shipped.
- quantity
  Type: integer
  min:
  1
  
  The number of the specified item.
completionURL
Type: string
max length:
256

This is an optional URL that can be provided by the merchant, it is the URL which the consumer can be re-directed to once a checkout seession is finalised. The re-direct can be configured on the Tola side to be automatic once the checkout is completed or can be confgured to be triggered by a click on a "Return To Merchant" button on the Tola Checkout Result page.

When redirected, Tola will append the query string argument ?checkoutReference={ref} so that you can identify the returning consumer. In parallel the merchant must ensure to make use of the Events API to check whether funds were transferred or not.

Maximum length: 256 characters.
customerRemark
Type: string
max length:
48

A string that we will present to the customer describing the checkout. This may appear in the PIN Prompt in the case of Mobile Money. It does not need to be unique. It is not supported by all payment suppliers. Due to the non-uniform support of this we recommend not relying on it. eg. "Order 55"
merchantConsumerID
Type: string
max length:
48

The merchant can provide a consumer identifier if known, this can be useful in providing a more personalised experience for the consumer during the checkout which will work across multiple devices for the consumer. When not included, Tola can use its own consumerID cookie to provide a personalised experience (if configured) however this will be tied to a single device.
metadata
Type: object
A key value string pair object that a merchant can attach to the checkout. These are sometimes required where additional information needs to be supplied to Tola, or where you wish to store something into the Checkout session that is later accessible via the Events API.

Constraints
- Both the key and values need to be strings.
- The maximum number of key value pairs is 20.
- The maximum length of a key is 32 chars.
- The maximum length of a value is 64 chars.
If any of these conditions are violated an error code 13 ('Invalid Metadata') will be returned on the response. Example:
```
metadata: {
    "trackingRegion": "Kenya",
    "trackingId": "5"
}
```
- key
  Type: string

Examples

{
  "currency": "KES",
  "items": [
    {
      "description": "November Invoice",
      "amountCentile": 100
    }
  ],
  "initiatorReference": "7XMOjzw5YJGKPOqm",
  "completionURL": "https://merchantmock.example.com/transactionCompleted",
  "customerRemark": "NovInvoice"
}