To retrieve their transactional account balances with the PIX providers Nuvei offers, merchants can use the processing entity ID provided by Nuvei to send a GET /pix/entities/{entity-id}/balances request in one of these environments:
- Live:
https://api.nuvei.com/balance-api/pix/entities/{entity-id}/balances - Test:
https://api-sandbox.nuvei.com/balance-api/pix/entities/{entity-id}/balances
Balances appear in local Brazilian currency (BRL).
/balances Response Parameters
| Parameter | Description | Type | Max Length |
|---|---|---|---|
| balances.provider | PIX provider. Possible values: P1-P5. | String | |
| balances.accountId | Merchant account ID with the provider. | String | |
| balances.amount | Balance amount with this provider. | Number | |
| balances.currency | Balance currency. | String | 3 |
| balances.status | Status of the balance request from this provider. Possible values: success – The balance was retrieved. error – An error occurred when Nuvei requested the balance from this provider. | String | |
| balances.error.code | The error code from the provider; appears if balances.status = "error". | String | 11 |
| balances.error.reason | The error reason from the provider; appears if balances.status = "error". | String | 400 |
| balances.lastUpdated | Date on which the balance was last updated. | String | |
| result.status | Status of the /balances API request the merchant sent to Nuvei.Possible values: success – The /balances request was successful. If balances are available from providers, they were retrieved.error – An error occurred processing the /balances request. | String | |
| result.error.code | The API request error code; appears if result.status = "error". | String | 11 |
| result.error.reason | The API request error reason; appears if result.status = "error". | String | 400 |
Possible Responses from the Provider
When Nuvei requests the balance from a provider and the response is HTTP Status 200, then the merchant’s balance with the provider appears as balance.amount.
If the provider’s response to Nuvei’s request is any other HTTP status, the following appears in the balances block of Nuvei’s response to the merchant’s /balances API request:
{
"provider": "<PIX provider>",
"status": "error",
"errors": {
"code": "7100.1001",
"reason": "Balance is currently unavailable"
}
}
Example /balances Response with result.status: “success”
{
"balances": [
{
"provider": "P1",
"accountId": "<string>",
"amount": 200,
"currency": "BRL",
"lastUpdated": "2024-09-11T12:57:23.870Z",
"status": "success"
},
{
"provider": "P2",
"accountId": "<string>",
"status": "error",
"errors": {
"code": "7100.1001",
"reason": "Balance is currently unavailable"
}
}
],
"result": {
"status": "success"
}
}
Example /balances Response with result.status: “error”
{
"result": {
"status": "error",
"errors": {
"code": "7300.1000",
"reason": "Authentication error"
}
}
}
Last modified January 2025