To retrieve their transactional account balances with the PIX providers Nuvei offers, merchants can send a GET /balance-api/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: 1-5. | 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": "1", "accountId": "<string>", "amount": 200, "currency": "BRL", "lastUpdated": "2024-09-11T12:57:23.870Z", "status": "success" }, { "provider": "2", "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" } } }