📳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.

USSD Statement Collection

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

Path Parameters

Name	Type	Description
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

Key	Value	Description
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}}.

Status Codes

201 - Created

USSD Session Created

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

422 - Unprocessable Content

Invalid USSD Bank

{
    "errors": [
        "This is not a Ussd bank account. Please create a Ussd bank account and try again."
    ]
}

Redirect Required

{
    "errors": {
        "redirect_url": [
            "The redirect url is required when allow_redirect is set as true."
        ]
    }
}

Webhook Requirements | webhook_url

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.

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

USSD – Statement Success

{
"data": {
"bank": "standard-bank",
"session": "tG4536",
"success": true,
"code": "statement-success",
"tenant": "{{tenantid}}",
"message": "Success.”,
"bank_account_id": "{{bankaccountid}}”
}
}

USSD – Statement Failure

{
"data": {
"bank": "standard-bank",
"session": "tG4536",
"success": false,
"code": "statement-success",
"tenant": "{{tenantid}}",
"message": "Failed”,
"bank_account_id": "{{bankaccountid}}”
}
}

USSD – Statement Expiry

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