Retrieving Your Funding Account Balance

Overview

Maya's Retrieve Balance endpoint allows Maya Partners to retrieve their funding account balance in real time, enabling partners to monitor their available and current balance during their operations and make informed decisions about transaction processing and fund management.

Note: Use of this endpoint for the scenarios described above may be deprecated in the future as part of ongoing platform alignment and product consolidation efforts.

When to use this

The Retrieve Balance endpoint is useful for monitoring your funding account balance. This endpoint is intended for low‑frequency use (for example, once daily) to retrieve the current funding account balance.

Note: There are rate limits applied to this endpoint. Please contact your Maya Relationship Manager for specific rate limit details.

Understanding Balance Values

The Retrieve Balance endpoint returns two balance values:

• Available Balance - The amount of funds available for immediate use in cash-in transactions.
• Current Balance - The total balance in your funding account, including pending transactions.

Both values are returned in PHP currency.

Build your Integration

This solution uses Basic Authentication, which requires API keys to authenticate incoming requests.

You may use the same Secret Key issued during onboarding for any of the following solutions:

• Cash-in via Maya Login
• Cash-in via Code
• Cash-in from Maya Mini Apps

Ensure that you use the Secret Key associated with the solution your account was provisioned for when making API requests.

Retrieve Your Balance

Call the Retrieve Balance endpoint to retrieve your funding account balance in real time.

1. Specify the request type and the API endpoint

• Set the request type to GET and ensure you use the correct API endpoint. Refer to the API reference for the correct API endpoint.

2. Add the Authorization Header

• This endpoint requires Basic Authentication. Include the SECRET KEY (sk-xxxx) as part of the Authorization header as a base64-encoded string.

3. Generate a unique request-reference-no

• Maya recommends using a UUID generator when creating your request-reference-no.

4. Execute the API call using the GET method
5. Parse the successful response and proceed accordingly

• The response will contain your available_balance and current_balance in PHP currency.

6. Handle error responses appropriately

• Refer to the Cash-in Errors page for a comprehensive list of errors and their proper handling methods.

Sample:

curl --request GET \
     --url https://sandbox.api.maya.ph/mi3-sandbox/balance \
     --header 'Authorization: Basic c2VydmljZS5hY2NvdW50OlBAc3N3MHJkIzEyMw==' \
     --header 'accept: application/json' \
     --header 'request-reference-no: a0309915-16b9-4528-82c0-cd11f0462f1b'

Sample Response:

{
  "balance": {
    "available_balance": {
      "currency": "PHP",
      "value": 458800
    },
    "current_balance": {
      "currency": "PHP",
      "value": 458800
    }
  }
}

Endpoints

FAQs

Q: What should I do if my available balance is insufficient?

Answer: If your available balance is insufficient for a transaction, you should contact your Maya Relationship Manager to discuss funding options.

Q: My balance retrieval is returning an error. How can I fix this?

Answer: First, ensure your Authorization header and request-reference-no are correctly formatted. If the issue persists, check the Sandbox Health Page to verify if the service is operational. If the service is up, retrieve the error code and use the search box in the Maya Developer Hub to find relevant guides on resolving it.