Check Transaction Reference

​

This method is used to verify whether a transaction was successfully created on the Tola platform.

The intended usage is to call this if a timeout or network error occurs after making a Create transaction request and you don't know whether that creation happened or not.

It's important to note that this is not a "transaction status" API.

How it works

Transaction reference check sequence diagram

Checking whether a transaction was created

Use this method when you call POST /transaction and then encounter a timeout, network error, or any other issue that leaves you unsure whether Tola received the request and created the transaction.

To check:

  1. Submit the transaction using POST /transaction with a sourcereference.
  2. If you do not receive a reliable response and are unsure whether the transaction was created, call POST /transactionRefCheck using the same sourcereference.
  3. Inspect the reference field in the response:
    • If reference contains a Tola transaction reference such as 1.2.3.4, the transaction was successfully created within the last 48 hours.
    • If reference is null, no matching transaction was found within the last 48 hours.

Important behavior

  • This check only works for transactions created through POST /transaction.
  • It does not apply to transactions created through /checkout.
  • If transactionRefCheck returns reference: null, the provided sourcereference cannot be reused to create a new transaction until 48 hours have passed.
Headers
  • Prefer
    Type: string

    Selects a named response example when using the mock server. The request must also use Content-Type: application/json, which Scalar adds automatically for the JSON request body.

Body·
application/json
  • sourcereference
    Type: string
    max length:  
    32
    required

    A unique identifier previously supplied from your application. We will check if this sourcereference has been associated with a Transaction on Tola in the past 48 hours.

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

Request Example for post/transactionRefCheck
curl https://wallet-mock.tolamobile.com/transactionRefCheck \
  --request POST \
  --header 'Prefer: example=transaction-found' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
  --data '{
  "sourcereference": "merchant-idempotent-key-1"
}'

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

If a reference string is returned a pre-existing Tola transaction was found.

If a null reference is returned a pre-existing Tola Transaction could not be located within the last 48 hours and the provided sourcereference cannot be re-used.