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 of object
    required

    A minimum of 1 item must be specified.

    Properties: 4
  • 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 object that a merchant can attach to the checkout. Metadata is available later through the Events API.

    The following fields may optionally be supplied as strings to prepopulate information required by a supplier's checkout flow:

    • msisdn — the consumer's mobile number.
    • first_name — the consumer's first name.
    • last_name — the consumer's last name.
    • email — the consumer's email address.

    Metadata constraints

    • Keys and values must be strings.
    • Maximum of 20 key/value pairs.
    • Maximum key length: 32 characters.
    • Maximum value length: 64 characters.

    If a constraint is violated, the response will include error code 13 ('Invalid Metadata').

    Example:

    {
  "restrict_msisdn": "263780000001",
  "first_name": "Alex",
  "last_name": "Example",
  "email": "alex@example.com"
}

    Metadata required by specific suppliers

    The Omari and Mukuru payment methods require restrict_msisdn. If this value is not provided, these payment methods will not be listed as available when the consumer opens the checkout link.

    Properties: 1
  • supplierTags
    Type: array of string
    max length:  
    32    enum

    Optional list of supplier tags to constrain the hosted checkout to a specific supplier choice. When a single supplier is specified, Tola can skip the supplier-selection step in the hosted checkout flow. When omitted, the hosted flow will present the consumer with the available supplier options configured for the merchant.

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