Create a checkout

Create a hosted web checkout session on the Tola Wallet platform. Returns a consumerURL to redirect the consumer to complete payment.

See the Checkout API Guide for full usage details.

Body·

application/json

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

Responses

application/json

post/checkout

curl https://wallet-mock.tolamobile.com/checkout \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
  --data '{
  "currency": "KES",
  "initiatorReference": "merchant-unique-ref-123XYZ",
  "completionURL": "https://tolamobile.com",
  "items": [
    {
      "description": "Test Product",
      "amountCentile": 100
    }
  ]
}'

Show Schema

{
  "response": {
    "checkoutReference": "00FF859C5TX",
    "consumerURL": "https://apidocs.tolamobile.com/c/123/00FF8X1C5TX"
  },
  "success": true
}