Appearance

Banking API ​

📘 Banking API Overview ​

The Banking API provides seamless and secure access to core banking functionalities, enabling integration with external systems and services. It supports real-time operations for customer and account management, as well as transactional services.

🔑 Key Features ​

  • User Management

    • User Information Retrieval: Fetch user details using either a Client ID or Client UUID.

    • User Onboarding: Create a new user, provisioning a savings account (and an optional merchant record).

  • Savings Account Operations

    • Current Balance Inquiry: Retrieve the current balance of a savings account.

    • All Accounts Lookup: List every savings account belonging to a client.

    • Transaction History: Get a paginated list of transactions for a savings account.

    • Transaction Details: View full details of a specific transaction using its Transaction ID.

  • Transaction Services

    • Debit Operation: Withdraw funds from a specified source account.

    • Credit Operation: Deposit funds into a specified destination account.

    • Fund Transfer: Transfer funds between two accounts (debit source, credit destination) in a single transaction.

  • Account Validation

    • Account Validation: Validate an account’s availability for transactions by checking balance and limit constraints.

    • Existing User Check: Determine whether a user already exists before onboarding.

🛡️ Use Cases ​

  • Digital banking applications

  • Third-party payment integrations

  • Financial service platforms needing real-time account access and funds movement

📘 Headers for API Request ​

Every request must include the five headers below. They are validated by the HmacAuthenticationFilter before the request reaches any endpoint. If any check fails, the API responds with 401 Unauthorized (see Authentication Errors).

X-API-KEY ​

  • Description: The unique API key issued to the partner. The server resolves the caller by hashing this value — apiKeyHash = Base64(HMAC-SHA256(PAYLOAD_SECRET_KEY, X-API-KEY)) — and looking up the partner by that hash. If no partner matches, the request is rejected with Invalid API key.

  • Usage: A long opaque string. Include it on every request.

User-Agent ​

  • Description: Identifies the calling system. This is a strict allowlist check, not just informational — the value must exactly match the User-Agent configured on the server (VALID_USER_AGENT).

  • Usage: Send the exact agreed-upon value. Any mismatch is rejected with Invalid User Agent.

X-Hmac-Timestamp ​

  • Description: The time the request was generated. It is included as the first part of the signed message.

  • Usage: A Unix timestamp in seconds (e.g. 1753178130). It must be the exact same value used when computing X-Hmac-Signature.

X-Hmac-Nonce ​

  • Description: A unique random value for the request. It is included as the second part of the signed message, ensuring two otherwise-identical payloads produce different signatures.

  • Usage: Typically a UUID or random string, generated fresh per request. It must be the exact same value used when computing X-Hmac-Signature.

X-Hmac-Signature ​

  • Description: The HMAC-SHA256 signature that authenticates and protects the integrity of the request. It is computed over the concatenation of the timestamp, nonce, and the compact JSON body.

  • Usage: A Base64-encoded HMAC-SHA256 digest (not hex). See Signature Construction below for the exact algorithm.

Signature Construction ​

The signature is built from the timestamp, the nonce, and the request body serialized as compact JSON (no spaces — equivalent to Python's json.dumps(body, separators=(',', ':'))). The server re-serializes the received body to this compact form before verifying, so the client must sign the compact JSON to get a matching signature.

message   = str(timestamp) + str(nonce) + compactJson(body)
signature = Base64( HMAC-SHA256( PAYLOAD_SECRET_KEY, message ) )
  • The same PAYLOAD_SECRET_KEY is shared between the partner and the server.
  • For GET requests with no body, compactJson(body) is the empty string.
  • timestamp and nonce must be byte-for-byte identical to the X-Hmac-Timestamp and X-Hmac-Nonce headers sent.

Replay protection: the timestamp and nonce are now enforced, not just signed.

  • Freshness: X-Hmac-Timestamp must be within HMAC_CLOCK_SKEW_SECONDS (default 300 seconds) of server time. Requests with a stale or future timestamp are rejected with Stale or future timestamp.
  • Single use: a given nonce may authenticate only one request within that window. Generate a fresh nonce per request; a reused nonce is rejected with Nonce already used.
  • All five headers are mandatory — a missing one is rejected with Missing authentication headers, and a non-numeric timestamp with Invalid timestamp.

Example of Request Headers ​

http
X-API-KEY: abc123xyz456
User-Agent: MyApp/1.0 (iPhone; iOS 14.0)
X-Hmac-Timestamp: 1753178130
X-Hmac-Nonce: 6a47c531-ef99-4cde-b8a3-dde87ec3a6de
X-Hmac-Signature: q1k9F4a5107d7b9b4a273c5b2fd3c04PvDx8sKQ2mZL0nA=

Authentication Errors ​

When a header is missing or a check fails, the filter returns 401 with this body:

json
{
    "code": 401,
    "status": "failed",
    "statusDesc": "Unauthorized",
    "data": {
        "errors": ["Invalid Signature"]
    }
}

The errors message reflects the specific failure: Invalid User Agent, Missing authentication headers, Invalid timestamp, Stale or future timestamp, Invalid API key, Invalid Signature, Nonce already used, or Invalid Signature or Payload.

User Management ​

Create User ​

Method: POST

URL: {{url}}/cbs/api/users

This endpoint creates a new user, provisioning a savings account and a mobile temporary record, with an optional merchant record.

Request Parameters ​

The request body should be in JSON format. Only the fields below are validated for format; most are optional KYC, employment, ID, and merchant details that enrich the customer record.

Required Fields ​

FieldTypeDescriptionValidation
firstnamestringThe user's first name.Letters, digits, spaces, and . only
middlenamestringThe user's middle name.Letters, digits, spaces, and . only
lastnamestringThe user's last name.Letters, digits, spaces, and . only
birthdatestringThe user's date of birth.YYYY-MM-DD
cpnumberstringThe user's contact/mobile number.09XXXXXXXXX (11 digits, starts with 09)

Personal Details (optional) ​

FieldTypeDescription
suffixnamestringName suffix (e.g. Jr, III).
genderstring1 = Male, 2 = Female.
civilstatusstring1 = Single, 2 = Married, 3 = Widow/er, 4 = Live-in.
birthplacestringPlace of birth.
nationalitystringNationality.
heightstringHeight.
weightstringWeight.
mmfirstnamestringMother's maiden first name.
mmmiddlenamestringMother's maiden middle name.
mmlastnamestringMother's maiden last name.

Address & Contact (optional) ​

FieldTypeDescription
addressdetails_presentstringPresent address details.
barangayid_presentstringBarangay ID for the present address.
addressdetails_permanentstringPermanent address details.
barangayid_permanentstringBarangay ID for the permanent address.
email_addressstringEmail address.

Fund Source / Employment (optional) ​

FieldTypeDescription
fundsourcestringSource of funds.
fundoccupationstringOccupation.
fundnamestringEmployer / business name.
fundaddressdetailsstringEmployer / business address.
fundbarangayidstringBarangay ID of the employer / business.
fundpositionstringPosition held.
fundcontactstringEmployer / business contact number.
fundyearstartstringYear employment / business started.
fundgrossincomestringGross income. Numeric value (e.g. 25000 or 25000.50).

Primary ID (optional) ​

FieldTypeDescription
id_typestringID type code. One of: 10–24, 26, 28, 29, 31–34, 36, 38, 39, 80–83, 90.
id_numberstringID number.
id_expirationstringID expiry date (YYYY-MM-DD).
date_issuedstringID issue date (YYYY-MM-DD).
place_issuedstringPlace the ID was issued.

Secondary ID (optional) ​

FieldTypeDescription
id2typestringSecondary ID type.
id2numberstringSecondary ID number.
date_issued_2stringSecondary ID issue date.
place_issued_2stringSecondary ID place of issue.

Photos (optional, base64) ​

Each value may be a raw base64 string or a data:image/<type>;base64,... data URI.

FieldTypeDescription
pic_normalstringSelfie / portrait photo.
pic_idfrontIdstringFront of the ID.
pic_idbackIdstringBack of the ID.
pic_signature1IdstringSignature image.
file_count_selfiestringNumber of selfie files attached.
file_count_idstringNumber of ID files attached.
file_count_signaturestringNumber of signature files attached.
file_count_attachmentstringNumber of general attachments.
file_count_risk_profilingstringNumber of risk-profiling files attached.

Beneficiary (optional) ​

FieldTypeDescription
beneficiary_firstnamestringBeneficiary first name.
beneficiary_middlenamestringBeneficiary middle name.
beneficiary_lastnamestringBeneficiary last name.
beneficiary_suffixnamestringBeneficiary name suffix.
beneficiary_contactnumberstringBeneficiary contact number.
beneficiary_relationshipstringRelationship to the user.

Partner / Bank & Account (optional) ​

FieldTypeDescription
partnerIdstringPartner identifier.
bank_bicfistringBank BIC/FI code.
bank_accountstringExternal bank account number.
savingsidstringExisting savings account ID, if linking.
clientid_previous_cbsstringClient ID from a previous CBS, for migration.
branchidstringBranch ID.
branchstringBranch name.
officeidstringOffice ID.
centeridstringCenter ID.
assetsizeidstringAsset size classification ID.
clienttypestringClient type.
orgtypestringOrganization type.

Flags & Risk (optional) ​

FieldTypeDescription
riskprofilestringRisk profile classification.
viptagstringVIP tag.
dosristringDOSRI (Directors, Officers, Stockholders, Related Interests) flag.
rptstringRelated-party transaction flag.
pepstringPolitically Exposed Person flag.
smsEnrolledstringSMS enrollment flag.
logstatusstringLog status.
viberacctstringViber account.
monthlytxnstringExpected monthly transaction volume.
userpin_keystringUser PIN key.
userpin_saltstringUser PIN salt.

Merchant (optional) ​

Set isMerchant to 1 to provision a merchant record alongside the user.

FieldTypeDescription
isMerchantstring0 = regular user, 1 = create merchant record.
merchant_idstringMerchant identifier.
merchant_chargestringMerchant charge amount.
merchant_charge_tagstringMerchant charge tag.
merchant_typestringMerchant type.
merchant_productidstringMerchant product ID.
merchant_labelstringMerchant display label.
paymentSystemUniqueIDstringPayment system unique identifier.

Example Request Body ​

A minimal request only needs the required fields. The example below shows a fuller request including optional KYC, employment, ID, photo, bank, beneficiary, and merchant fields. The pic_* fields take base64-encoded images (shown here as placeholders).

json
{
  "isMerchant": "1",
  "firstname": "Juan",
  "middlename": "Santos",
  "lastname": "Dela Cruz",
  "suffixname": "",
  "mmfirstname": "Pedro",
  "mmmiddlename": "Reyes",
  "mmlastname": "Dela Cruz",
  "gender": "1",
  "civilstatus": "1",
  "birthdate": "1990-05-14",
  "birthplace": "Quezon City",
  "nationality": "608",
  "cpnumber": "09171234567",
  "email_address": "juan.delacruz@example.com",
  "height": "5.0",
  "weight": "50",
  "addressdetails_present": "123 Mabini St.",
  "barangayid_present": "1123",
  "addressdetails_permanent": "456 Rizal Ave.",
  "barangayid_permanent": "1456",
  "fundsource": "0",
  "fundoccupation": "0",
  "fundname": "ABC Solutions Inc.",
  "fundaddressdetails": "7F Cyberpark Tower",
  "fundbarangayid": "1523",
  "fundposition": "Senior Developer",
  "fundcontact": "0288991122",
  "fundyearstart": "2018",
  "fundgrossincome": "85000",
  "id_type": "10",
  "id_number": "AB1234567",
  "id_expiration": "2030-01-01",
  "date_issued": "2025-01-01",
  "place_issued": "Pasig City",
  "pic_normal": "<base64-encoded image>",
  "pic_idfrontId": "<base64-encoded image>",
  "pic_idbackId": "<base64-encoded image>",
  "pic_signature1Id": "<base64-encoded image>",
  "partnerId": "7",
  "bank_bicfi": "BNORPHMM",
  "bank_account": "012345678901",
  "beneficiary_firstname": "Maria",
  "beneficiary_middlename": "Lopez",
  "beneficiary_lastname": "Dela Cruz",
  "beneficiary_suffixname": "",
  "beneficiary_contactnumber": "09181234567",
  "beneficiary_relationship": "1"
}

Expected Response Format ​

On success the server returns the newly created client ID and its associated savings account ID.

Example Response ​

json
{
    "code": 200,
    "status": "Success",
    "data": {
        "clientid": 10060630,
        "savingsid": 10000016
    }
}

Headers:

  • X-API-KEY: {{X-API-KEY}}
  • X-Hmac-Signature: {{X-Hmac-Signature}}
  • User-Agent: {{User-Agent}}
  • X-Hmac-Nonce: {{X-Hmac-Nonce}}
  • X-Hmac-Timestamp: {{X-Hmac-Timestamp}}

Example Request Body (minimal — required fields only):

json
{
    "firstname": "Juan",
    "middlename": "Santos",
    "lastname": "Dela Cruz",
    "birthdate": "1990-01-15",
    "cpnumber": "09171234567"
}

User Info ​

Method: GET

URL: {{url}}/cbs/api/users?clientid={clientid}

This endpoint allows you to get user information from the server.

HTTP Method ​

GET

Endpoint ​

{{url}}/cbs/api/users?clientid={clientid}

Request Parameters ​

clientid is passed as a query parameter (this is a GET request — there is no JSON body):

  • clientid (string): A unique identifier for the client (numeric ID or client UUID).

Example Request ​

http
GET {{url}}/cbs/api/users?clientid=10000016

Expected Response Format ​

The server will respond with a JSON object that typically includes a status message indicating the success or failure of the operation, along with any relevant data related to the user information submitted.

Example Response ​

json
{
    "code": 200,
    "status": "Success",
    "data": [
        {
            "clientid": 10000016,
            "clientid2": 10000016,
            "firstname": "FN10000016",
            "middlename": "MN10000016",
            "lastname": "LN10000016",
            "birthdate": "1990-01-15",
            "cpnumber": "09171234567",
            "email": null,
            "address": null
        }
    ]
}

Ensure that the clientid is valid to receive an appropriate response from the server.

Headers:

  • X-API-KEY: {{X-API-KEY}}
  • X-Hmac-Signature: {{X-Hmac-Signature}}
  • User-Agent: {{User-Agent}}
  • X-Hmac-Nonce: {{X-Hmac-Nonce}}
  • X-Hmac-Timestamp: {{X-Hmac-Timestamp}}

Example Request:

http
GET {{url}}/cbs/api/users?clientid=10060630

Check If Existing User ​

Method: GET (also available as POST /cbs/api/users/existence with a JSON body)

URL: {{url}}/cbs/api/users/existence-get

This endpoint checks whether a user already exists in the system based on their identifying details. It is useful for preventing duplicate user creation before onboarding a new user.

Request Parameters ​

Parameters are passed as query parameters (this is a GET request — there is no JSON body):

  • firstname (string): The user's first name.

  • middlename (string): The user's middle name.

  • lastname (string): The user's last name.

  • birthdate (string): The user's date of birth in YYYY-MM-DD format.

  • cpnumber (string): The user's contact/mobile number.

Example Request ​

http
GET {{url}}/cbs/api/users/existence-get?firstname=Juan&middlename=Santos&lastname=Dela%20Cruz&birthdate=1990-01-15&cpnumber=09171234567

Expected Response ​

When a matching user is found, the server returns code 200 with the existing client's identifiers. The data object contains:

  • clientid: The matched client's UUID / identifier.

  • clientid2: The matched client's numeric ID.

  • cpnumber (string): The contact number on record.

  • message (string): A message describing the match result.

If no matching user exists, the server returns a 404 with a descriptive message instead.

Example Response ​

json
{
    "code": 200,
    "status": "Success",
    "data": {
        "clientid": 10060630,
        "clientid2": 10000016,
        "cpnumber": "09171234567",
        "message": "Existing user"
    }
}

Headers:

  • X-API-KEY: {{X-API-KEY}}
  • X-SIGNATURE: {{X-SIGNATURE}}
  • User-Agent: {{User-Agent}}
  • X-Hmac-Nonce: {{X-Hmac-Nonce}}
  • X-Hmac-Signature: {{X-Hmac-Signature}}
  • X-Hmac-timestamp: {{X-Hmac-Timestamp}}

Example Request:

http
GET {{url}}/cbs/api/users/existence-get?firstname=Juan&middlename=Santos&lastname=Dela%20Cruz&birthdate=1990-01-15&cpnumber=09171234567

Savings ​

Savings Details ​

Method: GET

URL: {{url}}/cbs/api/savings/details-get

This endpoint is used to retrieve detailed information about a specific savings account identified by the savingsid.

Request Parameters ​

  • savingsid (string, required): The unique identifier for the savings account. This parameter is essential for the API to locate the correct account details.

Example Request ​

http
GET {{url}}/cbs/api/savings/details-get?savingsid=10000016

Expected Response ​

The response will include detailed information about the savings account associated with the provided savingsid. The expected JSON response structure is as follows:

json
{
  "code": 200,
  "status": "Success",
  "data": {
    "savingsid": 10000016,
    "client1id": 10060630,
    "currentbalance1": 1262.04,
    "currentbalance2": 3162.04,
    "accountType": 11,
    "productType": 1
  }
}

Response Fields ​

  • code (integer): The HTTP status code of the request. A value of 200 signifies a successful operation.

  • status (string): A status indicator related to the request (e.g. Success).

  • data (object): Contains the details of the savings account.

    • savingsid (integer): The identifier for the savings account.

    • client1id (integer): The primary client ID that owns the account.

    • currentbalance1 (number): The current balance of the savings account in the primary context.

    • currentbalance2 (number): The current balance of the savings account in an alternative context.

    • accountType (integer): The account type code.

    • productType (integer): The product type code.

Notes ​

  • Ensure that the savingsid provided is valid and corresponds to an existing savings account to avoid errors in the response.

  • The response may vary based on the account's status and the data available in the system.

This endpoint is used to retrieve detailed information about a specific savings account identified by the savingsid.

Request Parameters ​

  • savingsid (string, required): The unique identifier for the savings account. This parameter is essential for the API to locate the correct account details.

Example Request ​

http
GET {{url}}/cbs/api/savings/details-get?savingsid=10000016

Expected Response ​

The response will include detailed information about the savings account associated with the provided savingsid.

Response Format ​

  • Status Code: 200

  • Content-Type: application/json

Response Body Structure ​

json
{
  "code": 200,
  "status": "Success",
  "data": {
    "savingsid": 10000016,
    "client1id": 10060630,
    "currentbalance1": 1262.04,
    "currentbalance2": 3162.04,
    "accountType": 11,
    "productType": 1
  }
}

Notes ​

  • Ensure that the savingsid provided is valid and corresponds to an existing savings account to avoid errors in the response.

  • The response may vary based on the account's status and the data available in the system.

This endpoint is used to retrieve detailed information about a specific savings account identified by the savingsid.

Request Parameters ​

  • savingsid (string, required): The unique identifier for the savings account. This parameter is essential for the API to locate the correct account details.

Example Request ​

http
GET {{url}}/cbs/api/savings/details-get?savingsid=10000016

Expected Response ​

The response will include the following fields:

  • code (integer): Indicates the success or failure of the request. A value of 0 typically signifies success.

  • status (string): A message providing additional information about the request status.

  • data (object): Contains detailed information about the savings account, which may include:

    • savingsid (integer): The identifier for the savings account.

    • currentbalance1 (integer): The current balance of the account in the primary currency.

    • currentbalance2 (integer): The current balance of the account in an alternative currency, if applicable.

Notes ​

  • Ensure that the savingsid provided is valid and corresponds to an existing savings account to avoid errors in the response.

  • The response may vary based on the account's status and the data available in the system.

  • A successful request will return a status code of 200.

Headers:

  • X-API-KEY: {{X-API-KEY}}
  • X-SIGNATURE: {{X-SIGNATURE}}
  • User-Agent: {{User-Agent}}
  • X-Hmac-Timestamp: {{X-Hmac-Timestamp}}
  • X-Hmac-Nonce: {{X-Hmac-Nonce}}
  • X-Hmac-Signature: {{X-Hmac-Signature}}

Example Request:

http
GET {{url}}/cbs/api/savings/details-get?savingsid=10000016

Get All Savings Accounts ​

Method: GET

URL: {{url}}/cbs/api/savings/all-accounts-get

This endpoint retrieves all savings accounts associated with a given client, identified by the clientid.

Request Parameters ​

  • clientid (string, required): The unique identifier for the client whose savings accounts are being requested.

Example Request ​

http
GET {{url}}/cbs/api/savings/all-accounts-get?clientid=10060630

Expected Response ​

The response returns an array of savings account objects belonging to the client. Each object includes the following fields:

  • accountname (string): The name on the account.

  • type (integer): The account type code.

  • savingsid (integer): The identifier for the savings account.

  • savingsid_formatted (string): The formatted savings account number.

  • accountstatusid (integer): The numeric account status code (0 = Inactive, 1 = Active, 2 = Dormant).

  • accountstatus (string): The human-readable account status (e.g., Active).

  • corpclientid1 (integer): The corporate client ID, if applicable.

  • client1id … client4id (integer): The client IDs associated with the account (0 when unused).

  • currentbalance1 (string): The current balance in the primary context.

  • currentbalance2 (string): The current balance in an alternative context.

  • holdoutstatus (integer): Whether a hold-out is in effect (1) or not (0).

  • holdoutamount (string): The hold-out amount.

  • note1 (string): A note on the account.

  • productcode (string): The product code of the account.

  • minimumbalance (string): The minimum maintaining balance.

  • categoryname (string): The account category name.

  • onSavingsAccount (integer): Savings-account flag (1 = yes, 2 = no).

  • onOutward (string): Outward-transaction flag ("1" / "0").

  • onInward (string): Inward-transaction flag ("1" / "0").

Example Response ​

json
{
    "code": 200,
    "status": "Success",
    "data": [
        {
            "accountname": "Account O. Update",
            "type": 11,
            "savingsid": 10000016,
            "savingsid_formatted": "001-000-0016",
            "accountstatusid": 1,
            "accountstatus": "Active",
            "corpclientid1": 0,
            "client1id": 10060630,
            "client2id": 0,
            "client3id": 0,
            "client4id": 0,
            "currentbalance1": "1262.04",
            "currentbalance2": "3162.04",
            "holdoutstatus": 0,
            "holdoutamount": "0.00",
            "note1": "",
            "productcode": "ORD",
            "minimumbalance": "0.00",
            "categoryname": "SA#",
            "onSavingsAccount": 1,
            "onOutward": "1",
            "onInward": "1"
        }
    ]
}

Headers:

  • X-API-KEY: {{X-API-KEY}}
  • X-SIGNATURE: {{X-SIGNATURE}}
  • User-Agent: {{User-Agent}}
  • X-Hmac-Nonce: {{X-Hmac-Nonce}}
  • X-Hmac-Timestamp: {{X-Hmac-Timestamp}}
  • X-Hmac-Signature: {{X-Hmac-Signature}}

Example Request:

http
GET {{url}}/cbs/api/savings/all-accounts-get?clientid=10060630

Savings Transactions List ​

Method: GET

URL: {{url}}/cbs/api/savings/transactions-get

This endpoint allows users to retrieve a list of transactions associated with a specific savings account. It supports pagination and sorting to facilitate the retrieval of transaction data.

Request ​

Method: GET
URL: {{url}}/cbs/api/savings/transactions-get

Query Parameters:
Parameters are passed as query parameters (this is a GET request — there is no JSON body). The following parameters are required:

  • savingsid (string): The unique identifier of the savings account for which transactions are being requested.

  • page (integer): The page number of the results to retrieve, useful for pagination. The offset is computed as (page - 1) * limit.

  • limit (integer): The maximum number of transactions to return per page.

The following parameters are optional:

  • sortDirection (string): The direction of sorting for the transaction list. Acceptable values are "asc" (ascending) and "desc" (descending). Defaults to "desc" when omitted.

  • startDate (string): Only return transactions on or after this date. Format YYYY-MM-DD. An unparseable value is rejected with 400 (Invalid date format, expected yyyy-MM-dd).

  • endDate (string): Only return transactions on or before this date. Format YYYY-MM-DD. An unparseable value is rejected with 400 (Invalid date format, expected yyyy-MM-dd).

Example Request:

http
GET {{url}}/cbs/api/savings/transactions-get?savingsid=10000016&page=1&limit=10&sortDirection=desc&startDate=2022-07-10&endDate=2026-04-01

Response ​

Upon a successful request, the API will return a JSON response with the following structure:

  • code (integer): The HTTP status code of the response. A value of 200 indicates success.

  • status (string): A status indicator for the response (e.g. Success).

  • data (object): An object containing the transaction data.

    • transactions (array): An array of transaction objects, where each object includes:

      • savingsTxnId (integer): The unique identifier of the savings transaction.

      • amount (string): The amount of money involved in the transaction.

      • sourceAccount (integer): The source savings account number.

      • destinationAccount (integer): The destination savings account number.

      • transactionDate (string): The date when the transaction occurred.

      • transactionType (string): The type of transaction (debit or credit).

      • runningBalance (string): The account running balance after the transaction.

      • reference (string): The transaction reference number.

      • postingtime (string): The date and time the transaction was posted.

      • status (string): The current status of the transaction.

Example Response:

json
{
    "code": 200,
    "status": "Success",
    "data": {
        "transactions": [
            {
                "savingsTxnId": 60064,
                "amount": "115.00",
                "sourceAccount": 10000016,
                "destinationAccount": 10000016,
                "transactionDate": "2026-01-30",
                "transactionType": "debit",
                "runningBalance": "2357.04",
                "reference": "20260130RUGUPHM1XXXB785797684743156",
                "postingtime": "2026-01-30 08:48:53",
                "status": "Success"
            }
        ]
    }
}

Notes ​

  • Ensure that the savingsid provided corresponds to an existing savings account to receive valid transaction data.

  • Adjust the page and limit parameters based on the desired number of results and pagination needs.

Headers:

  • X-API-KEY: {{X-API-KEY}}
  • X-SIGNATURE: {{X-SIGNATURE}}
  • User-Agent: {{User-Agent}}
  • X-Hmac-Nonce: {{X-Hmac-Nonce}}
  • X-Hmac-Timestamp: {{X-Hmac-Timestamp}}
  • X-Hmac-Signature: {{X-Hmac-Signature}}

Example Request:

http
GET {{url}}/cbs/api/savings/transactions-get?savingsid=10000016&page=1&limit=10&sortDirection=desc&startDate=2022-07-10&endDate=2026-04-01

Savings Transactions Details ​

Method: GET

URL: {{url}}/cbs/api/savings/transactions-details-get

This endpoint is used to retrieve detailed information about a specific transaction in the savings account.

Request Parameters ​

Parameters are passed as query parameters (this is a GET request — there is no JSON body):

  • transactionid (string): The unique identifier for the transaction whose details are being requested.

Example Request ​

http
GET {{url}}/cbs/api/savings/transactions-details-get?transactionid=1697225

Expected Response Format ​

The response will return a JSON object containing the details of the specified transaction. The structure of the response will include relevant fields that provide insights into the transaction, such as amount, date, and status.

Example Response ​

json
{
    "code": 200,
    "status": "Success",
    "data": {
        "savingsTxnId": 1,
        "amount": "1015.00",
        "sourceAccount": "10000016",
        "destinationAccount": "10000016",
        "transactionDate": "2026-01-19",
        "transactionType": "debit",
        "runningBalance": "26693.29",
        "reference": "20260119RUGUPHM1XXXB383131108057690",
        "postingtime": "2026-01-19 01:20:32",
        "status": "Success",
        "fee": "0.00"
    }
}

Ensure that the transaction ID provided corresponds to a valid transaction in the system to receive accurate details.

This endpoint is used to retrieve detailed information about a specific transaction in the savings account.

Request Parameters ​

Parameters are passed as query parameters (this is a GET request — there is no JSON body):

  • transactionid (string): The unique identifier for the transaction whose details are being requested.

Example Request ​

http
GET {{url}}/cbs/api/savings/transactions-details-get?transactionid=1697225

Expected Response Format ​

The response will return a JSON object containing the details of the specified transaction. The structure of the response will include the following fields:

  • code (integer): The HTTP status code of the request (200 for success).

  • status (string): A status indicator for the transaction request (e.g. Success).

  • data (object): Contains detailed information about the transaction, including:

    • savingsTxnId (integer): The ID of the savings transaction.

    • amount (string): The amount involved in the transaction.

    • sourceAccount (string): The source savings account number.

    • destinationAccount (string): The destination savings account number.

    • transactionDate (string): The date when the transaction occurred.

    • transactionType (string): The type of transaction (debit or credit).

    • runningBalance (string): The account running balance after the transaction.

    • reference (string): The transaction reference number.

    • postingtime (string): The date and time the transaction was posted.

    • status (string): The current status of the transaction.

    • fee (string): The fee applied to the transaction.

Notes ​

Ensure that the transaction ID provided corresponds to a valid transaction in the system to receive accurate details. A successful request will return a status code of 200 along with the transaction details in the response.

Headers:

  • X-API-KEY: {{X-API-KEY}}
  • X-SIGNATURE: {{X-SIGNATURE}}
  • User-Agent: {{User-Agent}}
  • X-Hmac-Nonce: {{X-Hmac-Nonce}}
  • X-Hmac-Timestamp: {{X-Hmac-Timestamp}}
  • X-Hmac-Signature: {{X-Hmac-Signature}}

Example Request:

http
GET {{url}}/cbs/api/savings/transactions-details-get?transactionid=1

Bank Transfer ​

All three bank transfer endpoints (intra-fund-transfer, debit, credit) accept the same FundTransferRequest body.

Required fields: sourceAccount, amount, referenceNumber, savingsTxnCodeId.
Optional fields: customerId, destinationAccount, fee, description.

Note: referenceNumber and customerId must be alphanumeric only (no hyphens or spaces), and savingsTxnCodeId must be numeric. A channel field is sometimes sent by clients but is not part of the request and is ignored by the API.

Validation & error responses ​

These checks are applied before any posting; all return 400 with the message shown:

ConditionMessage
amount ≤ 0, missing, or more than 2 decimal placesamount must be greater than zero
fee negativefee must not be negative
Source balance does not cover amount + fee (debit / transfer)insufficient balance
referenceNumber already posted for this source accountreferenceNumber already used for this source account
sourceAccount equals destinationAccount (transfer)sourceAccount and destinationAccount must differ
sourceAccount / destinationAccount not numericsourceAccount must be numeric / destinationAccount is required and must be numeric
customerId present but not numericcustomerId must be numeric

Idempotency: referenceNumber is enforced unique per source account — a retried request that reuses a reference is rejected rather than posting the transfer twice. Use a fresh referenceNumber for each distinct transfer, and reuse the same one only to safely retry the same transfer.

Money values: amount and fee are exact decimal values (max 2 fraction digits). The debit leg of a transfer/debit deducts amount + fee from the source account.

About savingsTxnCodeId ​

savingsTxnCodeId is the numeric ID of a row in the core banking savings_transactioncodes table. Each code carries a multiplier that determines whether it credits or debits an account:

  • multiplier = +1 → credit code (money in)
  • multiplier = -1 → debit code (money out)

How each endpoint uses the code:

  • /banktransfer/intra-fund-transfer — pass the credit code (351, CM Intrabank Transfer). The matching debit leg (752, DM Intrabank FT) is applied automatically.
  • /banktransfer/debit — the code is used directly and must be a debit code (multiplier = -1), otherwise the request is rejected with savingsTxnCodeId is not a debit transaction code.
  • /banktransfer/credit — the code must be a credit code (multiplier = +1), otherwise the request is rejected with savingsTxnCodeId is not a credit transaction code.

A code that does not exist in the table is rejected with Invalid savingsTxnCodeId type.

Common transaction codes ​

IDNameType
1Cash DepositCredit (+1)
5Cash WithdrawalDebit (−1)
20Check DepositCredit (+1)
70Debit MemoDebit (−1)
351CM Intrabank TransferCredit (+1)
352CM Pesonet IBFTCredit (+1)
354CM Instapay IBFCredit (+1)
359CM RemittanceCredit (+1)
361CM Wallet TransferCredit (+1)
752DM Intrabank FTDebit (−1)
753DM Pesonet IBFTDebit (−1)
754DM Instapay IBFTDebit (−1)
759DM ATM WithdrawalDebit (−1)

The full table contains ~95 codes — 1xx cover deposits and clearing, 3xx credit memos (CM), 7xx debit memos (DM), and 9xx bank charges and fees.

Intra Fund Transfer ​

Method: POST

URL: {{url}}/cbs/api/banktransfer/intra-fund-transfer

This endpoint allows users to initiate an intra-fund transfer between two accounts within the same bank. It facilitates the transfer of funds from a source account to a destination account, including optional fees and a description for the transaction.

Request ​

Method: POST
Endpoint: {{url}}/cbs/api/banktransfer/intra-fund-transfer

Request Body ​

The request body should be in JSON format and include the following parameters:

  • customerId (string): The unique identifier of the customer initiating the transfer.

  • sourceAccount (string): The account number from which the funds will be withdrawn.

  • destinationAccount (string): The account number to which the funds will be transferred.

  • amount (string): The amount of money to be transferred.

  • fee (string): The transaction fee associated with the transfer.

  • description (string): A brief description of the transfer.

  • referenceNumber (string): A unique reference number for tracking the transaction.

  • type (string): The type of transaction, which should be set to "transfer". Options: transfer | debit | credit

  • channel (string): The channel through which the transfer is made, in this case, "intrabank".

Example Request Body ​

json
{
  "customerId": "1697225",
  "sourceAccount": "10000016",
  "destinationAccount": "10000024",
  "amount": "100.00",
  "fee": "10.00",
  "description": "Test Fund",
  "referenceNumber": "92183091231890",
  "type": "transfer",
  "channel": "intrabank",
  "savingsTxnCodeId": "351"
}

Response ​

On success the endpoint returns code 201 with details of both the debit and credit legs of the transfer. The data object contains:

  • code (integer): The HTTP status code (201 on success).

  • status (string): A status indicator for the transfer (e.g. Success).

  • data (object): Details about the transaction:

    • postingtime (string): The timestamp the transfer was posted (ISO-8601).

    • debitRunningBalance (number): The source account running balance after the debit.

    • debitCurrentBalance2 (number): The source account's secondary balance after the debit. Omitted when not available.

    • intraFundTxnId (integer): The intra-fund transfer transaction ID.

    • creditSavingsTxnId (integer): The savings transaction ID for the credit leg.

    • debitSavingsTxnId (integer): The savings transaction ID for the debit leg.

    • fee (number): The fee applied to the transfer.

Example Response ​

json
{
    "code": 201,
    "status": "Success",
    "data": {
        "postingtime": "2026-02-23T08:16:43.177361443Z",
        "debitRunningBalance": 1152.04,
        "debitCurrentBalance2": 3162.04,
        "intraFundTxnId": 90001,
        "creditSavingsTxnId": 60080,
        "debitSavingsTxnId": 60081,
        "fee": 0.0
    }
}

Notes ​

  • Ensure that all parameters are provided in the correct format to avoid errors during the transfer process.

  • The transaction fee is deducted from the source account along with the transfer amount.

Headers:

  • X-API-KEY: {{X-API-KEY}}
  • X-SIGNATURE: {{X-SIGNATURE}}
  • User-Agent: {{User-Agent}}
  • X-Hmac-TImestamp: {{X-Hmac-Timestamp}}
  • X-Hmac-Nonce: {{X-Hmac-Nonce}}
  • X-Hmac-Signature: {{X-Hmac-Signature}}

Example Request Body:

json
{
    "customerId": "1697225",
    "sourceAccount": "10000016",
    "destinationAccount": "10000024",
    "amount": "100.00",
    "fee": "10.00",
    "description": "Test Fund",
    "referenceNumber": "92183091231890",
    "type": "transfer", 
    "channel": "intrabank",
    "savingsTxnCodeId": "351"
}

Debit ​

Method: POST

URL: {{url}}/cbs/api/banktransfer/debit

This endpoint performs a debit-only operation, withdrawing funds from the specified source account. It accepts the same FundTransferRequest body shared by all bank transfer endpoints.

Request Parameters ​

The request body should be in JSON format. The following fields are required:

  • sourceAccount (string): The account number from which the funds will be withdrawn.

  • amount (number): The amount of money to be debited.

  • referenceNumber (string): A unique reference number for tracking the transaction.

  • savingsTxnCodeId (string): The savings transaction code identifier. For the debit endpoint this must be a debit code (multiplier = -1), e.g. 5 (Cash Withdrawal) or 70 (Debit Memo). A credit code is rejected with savingsTxnCodeId is not a debit transaction code. See About savingsTxnCodeId.

Optional fields: customerId, destinationAccount, fee, description. (destinationAccount is ignored by the debit endpoint — only the source account is affected.)

Example Request Body ​

json
{
  "customerId": "110298608",
  "sourceAccount": "10000016",
  "amount": 100.00,
  "fee": 0,
  "description": "Debit",
  "referenceNumber": "REF0002",
  "savingsTxnCodeId": "5"
}

Expected Response ​

The response confirms the debit and returns the updated running balance and the resulting savings transaction ID.

Example Response ​

json
{
    "code": 201,
    "status": "Success",
    "data": {
        "postingtime": "2026-02-23T08:16:58.132238413Z",
        "runningBalance": 1052.04,
        "currentBalance2": 3162.04,
        "savingsTxnId": 60069,
        "fee": 0.0
    }
}

Headers:

  • X-API-KEY: {{X-API-KEY}}
  • X-SIGNATURE: {{X-SIGNATURE}}
  • User-Agent: {{User-Agent}}
  • X-Hmac-Timestamp: {{X-Hmac-Timestamp}}
  • X-Hmac-Nonce: {{X-Hmac-Nonce}}
  • X-Hmac-Signature: {{X-Hmac-Signature}}

Example Request Body:

json
{
    "customerId": "110298608",
    "sourceAccount": "10000016",
    "amount": 100.00,
    "fee": 0,
    "description": "Debit",
    "referenceNumber": "REF0002",
    "savingsTxnCodeId": "5"
}

Credit ​

Method: POST

URL: {{url}}/cbs/api/banktransfer/credit

This endpoint performs a credit-only operation, depositing funds into the specified destination account. It accepts the same FundTransferRequest body shared by all bank transfer endpoints.

Request Parameters ​

The request body should be in JSON format. The following fields are required:

  • sourceAccount (string): The account number associated with the transaction.

  • amount (number): The amount of money to be credited.

  • referenceNumber (string): A unique reference number for tracking the transaction.

  • savingsTxnCodeId (string): The savings transaction code identifier. For the credit endpoint this must be a credit code (multiplier = +1), e.g. 1 (Cash Deposit) or 30 (Credit Memo). A debit code is rejected with savingsTxnCodeId is not a credit transaction code. See About savingsTxnCodeId.

Optional fields: customerId, destinationAccount, fee, description. (destinationAccount is ignored by the credit endpoint — the credit is posted to the source account.)

Example Request Body ​

json
{
  "customerId": "110298608",
  "sourceAccount": "10000016",
  "amount": 100.00,
  "fee": 0,
  "description": "Credit",
  "referenceNumber": "REF0003",
  "savingsTxnCodeId": "1"
}

Expected Response ​

The response confirms the credit and returns the updated running balance and the resulting savings transaction ID.

Example Response ​

json
{
    "code": 201,
    "status": "Success",
    "data": {
        "postingtime": "2026-02-23T08:17:37.867360889Z",
        "runningBalance": 1152.04,
        "currentBalance2": 3162.04,
        "savingsTxnId": 60070,
        "fee": 0.0
    }
}

Headers:

  • X-API-KEY: {{X-API-KEY}}
  • X-SIGNATURE: {{X-SIGNATURE}}
  • User-Agent: {{User-Agent}}
  • X-Hmac-Timestamp: {{X-Hmac-Timestamp}}
  • X-Hmac-Nonce: {{X-Hmac-Nonce}}
  • X-Hmac-Signature: {{X-Hmac-Signature}}

Example Request Body:

json
{
    "customerId": "110298608",
    "sourceAccount": "10000016",
    "amount": 100.00,
    "fee": 0,
    "description": "Credit",
    "referenceNumber": "REF0003",
    "savingsTxnCodeId": "1"
}

Accounts ​

Account Validation ​

Method: GET

URL: {{url}}/cbs/api/accounts/validation-get

This endpoint is used to validate an account based on the provided savings ID. It checks if the specified savings account exists and is valid within the system. This is particularly useful for applications that need to verify account details before proceeding with transactions or account-related operations.

Request ​

  • Method: GET

  • URL: {{url}}/cbs/api/accounts/validation-get

Query Parameters ​

Parameters are passed as query parameters (this is a GET request — there is no JSON body):

  • savingsid (string): The unique identifier for the savings account that needs to be validated. This ID is essential for the validation process.

Example Request:

http
GET {{url}}/cbs/api/accounts/validation-get?savingsid=10099786

Expected Response ​

Upon a successful request, the server will respond with a status code of 200 and a JSON object containing the following structure:

  • code (integer): Indicates the result of the validation operation (e.g., 0 for success).

  • status (string): A brief status message related to the validation process.

  • data (object): Contains additional information about the validation result:

    • rc (integer): A return code indicating the outcome of the validation (e.g., 0 for valid).

    • message (string): A message providing further details about the validation status.

    • partnerid (integer): Identifier for the partner associated with the account (if applicable).

    • AcctId (string): The account ID associated with the savings ID (if found).

    • source_channel (integer): The source channel identifier (if applicable).

    • clientid (null or string): The client ID associated with the request (if applicable).

Example Response:

json
{
    "code": 200,
    "status": "Success",
    "data": {
        "rc": 201,
        "message": "Partner account#",
        "partnerid": 10065,
        "AcctId": "10099786",
        "source_channel": 4,
        "clientid": 10060630
    }
}

Notes ​

  • Ensure that the savings ID provided is correct and exists in the system to avoid validation errors.

  • The response may vary based on the validity of the savings ID provided, and it is important to handle different return codes appropriately in your application.

Headers:

  • X-API-KEY: {{X-API-KEY}}
  • X-SIGNATURE: {{X-SIGNATURE}}
  • User-Agent: {{User-Agent}}
  • X-Hmac-Nonce: {{X-Hmac-Nonce}}
  • X-Hmac-Signature: {{X-Hmac-Signature}}
  • X-Hmac-timestamp: {{X-Hmac-Timestamp}}

Example Request:

http
GET {{url}}/cbs/api/accounts/validation-get?savingsid=10000016

Banking API Solutions by Asenso Solutions, Inc.

Copyright © 2025 Asenso Solutions, Inc.