๐Ÿ“ณUSSD Statement Collection

Allow Customers to leverage existing USSD infrastructure to digitize bank statements. Retrieving bank statements for processing, categorizing and storing transactional and account data.

Using the Customers mobile number that is registered to their bank account, a Customer can send their bank statements to our Gathr USSD service.

USSD Statement Collection

POST {{baseUrl}}/bank-accounts/:bank_account_id/ussd

Create a USSD statement collection webviewURL to initiate the Gathr USSD process.

Path Parameters

NameTypeDescription

bank_account_id*

String

The UUID for a Bank Account that gets generated and returned in the POST Create new Bank Account response. It ensures that the transactional data and statements retrieved in the USSD session are saved to the correct Bank Account.

Request Body

KeyValueDescription

webhook_url

String

Add a value for this parameter to send the outcome of the ussd statement collection session.

i.e. the URL to which you would like to receive the results of the ussd statement collection session (successful, failed, in progress).

You can save the value in the environment variable {{webhookUrl}}.

category_engine

String

To enable refined transaction categorisation you will need to set the category_engine to

x-finch. For more information refer to the Transaction Categorisation page.

allow_redirect

Boolean

Set allow_redirect to "true" if you would like to redirect the end-user/customer after they have completed the online process. By default, it is null and therefore the redirect_url will not work unless allow_redirect = true.

redirect_url

String

Add a value for this parameter to dictate where the end-user/Customer is redirected to after they have successfully completed the USSD process.

i.e. the URL of the page to which you want the end-user/Customer to return/progress to once their transactional data and bank statements have been collected.

You can save the value in the environment variable {{redirectUrl}}.

{
    "data": {
        "uuid": "ad1ab3a6-b13e-4dad-9d52-a9957cc5873f",
        "state": "session created",
        "ussd_session_code": "G1cl8p",
        "webviewUrl": "https://apply.fincheck.co.za/test/ussd-portal/G1cl8p"
    }
}

Webhook Requirements | webhook_url

As this is a specific post query, we need to make sure we are sending customer/clients to a safe destination, as such, there is validation done on the Redirect and Webhook URL.

The Filed under validation must have a valid A or AAAA record when querying the dns_get_record PHP function.

A a simple guideline:

  • Must be RFC compliant

  • Must include the hostname

  • Be careful with special characters that might mess with the structure of the post request

Webhook Response

The following is the payload that gets sent to the url that is provided in the webhook_url parameter in the POST USSD Statement Collection request.

The webhook gets triggered once the processing of the transactions in the statement(s) is successful. Once you receive this successful payload, you can query any of the /transactions, /statements, /accounts and /transaction-reports endpoints to retrieve the affordability data you require.

USSD โ€“ Statement Success

```postman_json
{
"data": {
"bank": "standard-bank",
"session": "tG4536",
"success": true,
"code": "statement-success",
"tenant": "{{tenantid}}",
"message": "Success.โ€,
"bank_account_id": "{{bankaccountid}}โ€
}
}
```

USSD โ€“ Statement Failure

```postman_json
{
"data": {
"bank": "standard-bank",
"session": "tG4536",
"success": false,
"code": "statement-success",
"tenant": "{{tenantid}}",
"message": "Failedโ€,
"bank_account_id": "{{bankaccountid}}โ€
}
}
```

USSD โ€“ Statement Expiry

```postman_json
{
"data": {
"bank": "standard-bank",
"session": "tG4536",
"success": false,
"code": "session-expired",
"tenant": "{{tenantid}}",
"message": "Session expired after 30 minutes.โ€,
"bank_account_id": "{{bankaccountid}}โ€
}
}
```

Last updated