Balance update API

This method involves the use of the Update Account Balance (pws_update_balance) API , which allows you to update account balances.

The API is particularly suitable for situations where balances change due to external factors not immediately visible to Paymentology, such as Electronic Funds Transfer from an external account.

When using this API you will need to provide the actual balance "act_balance" and the blocked balance "blk_balance".

📓

The total available balance = act_balance - blk_balance

Maximum account limit

A maximum of 25 account records can be passed in the Update Account Balance API request. This means that a maximum of 25 accounts can be updated per Update Account Balance API call.

Balance update API failure

There are two main types of failures that could occur when calling the Update Account Balance API:

1. 1. Generic API failure
2. 2. Individual or selection of balance update failure(s)

1. Generic API failure

This is when the API response returns anything other than 0 in the "error_id" response field. With this type of failure the "error_desc" will also be provided to assist with your troubleshooting.

📓

You can find the full list of API error response codes and their descriptions here.

Example

{
    "header": {
        "error_id": 996,
        "error_desc": "Permission denied ! The client does not have access to this web service. Contact paymentology"
    },
    "body": {}
}

2. Individual or selection of balance update failure(s)

In this type of failure a list of failed account(s)/token(s) and the failure reason will be provided in the API response message field "failed_note".

The list of account(s)/token(s) are separated by a semicolon (;).

You are also provided with the total failed count of account(s)/token(s) based on the value returned in the "total_failed" response field.

📓

Note: for this type of failure the API response will return a 0 in the "error_id" with a "error_desc" of "success".

Example

{
    "header": {
        "error_id": 0,
        "error_desc": "success"
    },
    "body": {
        "total_count": 20,
        "total_success": 17,
        "total_failed": 3,
        "failed_note": "66961561234:Invalid account id;66954322234:Invalid account id;87876761234:Invalid account id;"
    }
}

📓

Best practices

For more information on how to best use the Balance update API for balance listing, you can refer to our Balance listing - Best practices.