Create a transaction

Create a mobile money transaction on the Tola Wallet platform.

A charge type request creates a Consumer to Business (C2B) transaction on the Tola Wallet platform. See the Charge Guide

A disbursement type request creates a Business to Consumer (B2C) transaction on the Tola Wallet platform. See the Disbursement Guide

A successful response does not mean that the transaction was successful, only that the transaction has been accepted by the Tola Wallet platform. The eventual result will be notified to you by your call to the Wallet Events API (preferable) or by Asynchronous Callback.

Handling uncertain transaction creation outcomes

If you experience a timeout or network error when calling POST /transaction, you may not know whether the transaction was successfully created.

In this case, you can use the Transaction Reference Check API with the same sourcereference specified in your original POST /transaction request to determine whether the transaction exists.

Headers

Prefer
Type: string

Selects a named response example when using the mock server. Set this to example=Failure to return the documented error payload. The request must also use Content-Type: application/json, which Scalar adds automatically for the JSON request body.

Body·

application/json

amount
Type: integer
required

The value of the transaction in cents. For example 1 KES would be 100
channel
Type: string
max length:
32
required

The channel identifier in the format '<COUNTRY>.<OPERATOR>'
currency
Type: string
min length:
3
max length:
3
required

The ISO 4217 currency code for this Transaction
msisdn
Type: string
max length:
16
required

The MSISDN for the Transaction, in full international format
sourcereference
Type: string
max length:
32
required

A unique identifier supplied from your application. This can be used to cross reference records between your application and Tola. Recent Duplicates (within 48hrs) will be rejected.
type
Type: string enum
required

The type of transaction
values
- disbursement
- charge
target
Type: string
max length:
16

The account identifier (or paybill number), only supply this when the default needs to be overriden.

Responses

application/json
400

Returned when we are unable to parse the parameters in the request, or when the relay URL is incorrect or inactive
401

Returned when your account with Tola Wallet is inactive
403

Returned when the relay URL is called with invalid or missing credentials or from an IP address that isnt in the relay URL's IP whitelist
429

Too Many Request. Returned when the application receives too many requests over a given time period. The request can be retried after 60 seconds.
503

Returned when the Tola Wallet is temporarily unavailable

Callbacks

post

transaction callback https://<merchant webhook>

Body·

application/json

These are optional webhook requests sent from Tola to your Merchant platform. However, Tola recommend using the Events API instead, as this provides better transactional integrity and more seamless operation at high transactional volumes.

These webhooks notify the final result of a previously attempted mobile-money funds-transfer. If funds were transfered, rejecting the request will not rollback the funds-transfer.

Tola will retry sending requests for which it did not receive the expected response including in cases such as network timeouts.

Below describes how you should handle different webhooks based on their type field:

Type : Notification

When a transaction created with POST /transaction has reached its final state Tola will send you a notification webhook with type=notification. It contains the final result of the previously attempted funds-transfer.

You should always respond with {"success": true} after checking if you have a matching Pending transaction so that Tola does not attempt further re-deliveries of the webhook.

Type : Lodgement

If configured for your integration, Tola will send webhooks with type=lodgement for consumer initiated lodgements.

It is vital that you perform an idempotency check on the reference field. This is to avoid duplicates being recorded on your merchant platform in case Tola retries the webhook.

After performing the duplicate check and potentially recording the new funds-transfer you should always respond with {"success": true} so that Tola does not attempt further re-deliveries of the webhook.

This payload is used in two cases:

in the Events API when the event.metadata.payload_format is "mobile-money"
in the Create Transaction Callback when callbacks are enabled

amount
Type: string
max length:
16
required

The value of the transaction in cents. For example 1 KES would be 100
amounttype
enum
const:
centile
required

Tola only uses centile values
values
- centile
campaignid
Type: string
max length:
32
required

Identifies a particular stream of traffic, eg. Lodgements on Paybill 00001, or Transactions created by a given Relay Endpoint
channel
Type: string
max length:
32
required

The API identifier in the format '<COUNTRY>.<OPERATOR>'
currency
Type: string
min length:
3
max length:
3
required

The ISO 4217 currency code for this Transaction
customerreference
Type: string
max length:
32
required

For type = notification, this will contain the reference you provided when calling POST /transaction.

For type = lodgement, this will contain the text entered by the consumer on their handset when performing the lodgement.
date
Type: string Format: date-time
required

The Date that the transaction was created (ISO 8601 UTC)
msisdn
Type: string
max length:
16
required

The MSISDN for the Transaction, in full international format
operatorreference
Type: string
max length:
32
required

The unique reference provided by the Operator for this transaction
reference
Type: string
max length:
32
required

The Tola.wallet platform reference of this notification
sourcereference
Type: string
max length:
32
required

For type=notification, the unique Tola reference of the originating Merchant request to Tola's POST /transaction.
success
Type: string enum
required

The outcome of the funds-transfer where true indicates that funds were transferred.
values
- true
- false

Responses

200
Type: object ·

Anything other than a successful response will tell us that the callback has not been consumed and we will continue to attempt to deliver it to the partner via a manual or automated retry process.

Anything other than {"success": true} will indicate that the callback has not been consumed. In this case we may attempt redelivery
success
Type: boolean
required

true if the callback has been consumed
application/json

post/transaction

curl https://wallet-mock.tolamobile.com/transaction \
  --request POST \
  --header 'Prefer: example=Successful - PIN' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
  --data '{
  "msisdn": "254000000001",
  "type": "disbursement",
  "channel": "KENYA.SAFARICOM",
  "currency": "KES",
  "amount": 100,
  "sourcereference": "8FD2KuZNJnBPLKmz"
}'

Show Schema

{
  "reference": "1.123.1435455096.1",
  "success": true
}

Tola responds to syntactically correct requests with a HTTP 200 response code.

Successful requests will include the reference field, which contains the unique Tola reference of the created transaction.

Unsuccessful requests will include the error object, which includes a code and human readable string describing the specific error (see Create Transaction Error Codes and Messages).

If you receive an undocumented http response code or format, or no response due to a timeout/network error you should assume that processing may have happened: set your transaction to Pending and reconcile using callback notifications, the Events API, or the Tola Web Portal search.