🌏Sync Online Banking Accounts

Generate a GathrLink iFrame in order to allow a Customer to login to their internet banking profile and retrieve transactional data and PDF bank statements.

Sync Online Banking Accounts

GET {{baseUrl}}/bank-accounts/:bank_account_id/sync?redirect_url={{redirectUrl}}

Path Parameters

Key	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 online login session are saved to the correct Bank Account.

Query Parameters

Key	Type	Description
result_url	String	Add a value for this parameter to send the outcome of the online login session. i.e. the URL to which you would like to receive the results of the online login session (successful, failed, in progress). You can save the value in the environment variable {{resultUrl}}.
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.
repeat_application	Boolean	Set repeat_application to "true" if you would like to enable the functionality of repeating a Customer's online login. See Repeat Online Login page for further explanation.
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 online process. i.e. the URL of the page to which you want the end-user/customer to return/progress to once their transaction data and bank statements have been collected. You can save the value in the environment variable {{redirectUrl}}.

Status Codes

201 - Created

Online Login Session Created

{
    "data": {
        "uuid": "4381620d-3766-4851-b7a9-07eabbecdd99",
        "state": "Session started",
,

        "accounts_loading": 90,
        "statements_loading": 90,
        "login_loading": 90,
        "has_pin": 0,
        "has_otp": 0
    }
}

404 - Not Found

Bank Account ID Not Found

{
    "errors": {
        "code": "entity_not_found",
        "message": "Record not found in module_bank_accounts"
    }
}

422 - Unprocessable Content

Bank Account Type Incorrect

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

Webhook Requirements | result_url

The following is the payload that gets sent to the url that is provided in the result_url parameter in the POST Sync Online Banking Accounts request.

The webhook gets triggered once transaction and statement(s) has successfully been collected. Once you receive the relevant successful payloads, you can query the relevant/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 Result 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 Success Notifications

Transaction Success

Once you receive the transaction successful payload, you can query /transactions and /transaction-reports endpoints to retrieve the transactional data you require.

{
    "data": {
        "bank": "fnb",
        "session": "elmlW5D7iKAW",
        "success": true,
        "code": "transactions-success",
        "message": "Success",
        "bank_account_id": "88e58beb-87fb-4258-a8e9-e20ead9c4cb3",
        "tenant": "testing"
    }
}

Statement Success

Once you receive the statement successful payload, you can query /statements and /accounts endpoints to retrieve the statement and account data you require.

{
    "data": {
        "bank": "fnb",
        "session": "elmlW5D7iKAW",
        "success": true,
        "code": "statement-success",
        "message": "Success",
        "bank_account_id": "88e58beb-87fb-4258-a8e9-e20ead9c4cb3",
        "tenant": "testing"
    }
}

Webhook Failure Notifications

Transaction Failure

Transaction Failure Codes

• LOGIN_FAILED = "login-failed"

• OTP_FAILED = "otp-failed"

• LOGIN_UNATHORISED = "login-unauthorised"

• USER_ACCOUNT_FAILED = "user-accounts-failed"

• ACCOUNT_SELECTION_FAILED = "accounts-failed"

• STATEMENT_FAILED = "statement-failed"

• TRANSACTION_FAILED = "transactions-failed"

{
    "data": {
        "bank": "fnb",
        "session": "HxJxRxRVOXvz",
        "success": false,
        "code": "login-failed",
        "message": "We were unable to login with the provided details. Please check your details and try again.",
        "bank_account_id": "753326e7-70f8-43d8-a554-c657b9847e8f",
        "tenant": "testing"
    }
}

Statement Failure

{
    "data": {
        "bank": "fnb",
        "session": "HxJxRxRVOXvz",
        "success": false,
        "code": "statement-failed",
        "message": "Failed",
        "bank_account_id": "753326e7-70f8-43d8-a554-c657b9847e8f",
        "tenant": "testing"
    }
}

Session Expired

{
    "data": {
        "bank": "fnb",
        "session": "HxJxRxRVOXvz",
        "success": false,
        "code": "session-exoired",
        "message": "Session expired after 30 minutes",
        "bank_account_id": "753326e7-70f8-43d8-a554-c657b9847e8f",
        "tenant": "testing"
    }
}

IFrame Events

Clients can subscribe to specific events triggered within the iframe, enabling real-time monitoring and integration with their systems.

Client IFrame Events

• "LOGIN_BUTTON_CLICKED"

• "ACCOUNT_SELECTION_CHECKBOX_CHECKED"

• "ACCOUNT_SELECTION_BUTTON_CLICKED"

• "OTP_BUTTON_CLICKED"

• "EXIT_BUTTON_CLICKED"

• "ACCOUNT_SELECTION_CHECKBOX_UNCHECKED"

• "RETRY_BUTTON_CLICKED"

• "CONNECTION_LOST_ERROR"

• "CONNECTION_LOST_RETRY_WARNING"

{
    "bankAccountId": string,
    "data": any | null,
    "event": string, //see list of client and server events
    "eventType": string, //"start" | "in-progress" | "success" | "error" | "reconnecting" | "email" | "failed" | "expired"
    "message": string,
    "sessionId": string,
    "source": string, //"client" | "server"
    "timestamp": string
}