# Balances API

REST 2.0 Balances API

**Version:** 2.5.1

## Servers

- `https://api-sandbox.nuvei.com/balance-api` — sandbox
- `https://api.nuvei.com/balance-api` — prod

## Tags

- **Balances**

## Security Schemes

### apiKeyAuth

- Type: `apiKey`
- In: `header`
- Header/Param Name: `X-API-KEY`

## Paths

### `/pix/entities/{entity-id}/balances`

#### GET

**Summary:** Retrieve Merchant Balances

Retrieves a merchant's balances from all PIX providers.

**Operation ID:** `getBalances`

**Tags:** Balances

**Security:** apiKeyAuth

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `entity-id` | path | string | Yes |  |

**Responses:**

- **200** — OK
  - Content-Type: `application/json`
  **Schema:** `BalancesResponse`

  - **balances** — _array_
    - **items** — _object_
      - **provider** — (`Provider`) — _string_ — **required** — enum: `P1`, `P2`, `P3`, `P4`, `P5`, `P6`
      - **accountId** — (`AccountId`) — _string_
      - **amount** — (`Amount`) — _number_
      - **currency** — (`Currency`) — _string_ — default: `"BRL"`
      - **lastUpdated** — _string_ — format: `date-time`
      - **status** — (`BaseResultStatus`) — _string_ — **required** — enum: `success`, `error` — Status of the request: success | error
      - **errors** — (`ResultError`) — _object_ — If an error occurred on the request side, an error code is returned in this parameter.
        - **code** — _string_ — **required** — example: `"7000.1000"` — If an error occurred on the request side, an error code is returned in this parameter.
        - **reason** — _string_ — example: `"Internal Processing Error"` — If an error occurred on the request side, then an error reason is returned in this parameter.
        - **reference** — _string_ — example: `"110.1260"` — Reference value for troubleshooting
  - **result** — (`BaseApiResultOutput`) — _object_ — **required**
    - **status** — (`BaseResultStatus`) — _string_ — **required** — enum: `success`, `error` — Status of the request: success | error
    - **errors** — (`ResultError`) — _object_ — If an error occurred on the request side, an error code is returned in this parameter.
      - **code** — _string_ — **required** — example: `"7000.1000"` — If an error occurred on the request side, an error code is returned in this parameter.
      - **reason** — _string_ — example: `"Internal Processing Error"` — If an error occurred on the request side, then an error reason is returned in this parameter.
      - **reference** — _string_ — example: `"110.1260"` — Reference value for troubleshooting

- **400** — Bad Request
  - Content-Type: `application/json`
  **Schema:** `BalancesResponse`

  - **balances** — _array_
    - **items** — _object_
      - **provider** — (`Provider`) — _string_ — **required** — enum: `P1`, `P2`, `P3`, `P4`, `P5`, `P6`
      - **accountId** — (`AccountId`) — _string_
      - **amount** — (`Amount`) — _number_
      - **currency** — (`Currency`) — _string_ — default: `"BRL"`
      - **lastUpdated** — _string_ — format: `date-time`
      - **status** — (`BaseResultStatus`) — _string_ — **required** — enum: `success`, `error` — Status of the request: success | error
      - **errors** — (`ResultError`) — _object_ — If an error occurred on the request side, an error code is returned in this parameter.
        - **code** — _string_ — **required** — example: `"7000.1000"` — If an error occurred on the request side, an error code is returned in this parameter.
        - **reason** — _string_ — example: `"Internal Processing Error"` — If an error occurred on the request side, then an error reason is returned in this parameter.
        - **reference** — _string_ — example: `"110.1260"` — Reference value for troubleshooting
  - **result** — (`BaseApiResultOutput`) — _object_ — **required**
    - **status** — (`BaseResultStatus`) — _string_ — **required** — enum: `success`, `error` — Status of the request: success | error
    - **errors** — (`ResultError`) — _object_ — If an error occurred on the request side, an error code is returned in this parameter.
      - **code** — _string_ — **required** — example: `"7000.1000"` — If an error occurred on the request side, an error code is returned in this parameter.
      - **reason** — _string_ — example: `"Internal Processing Error"` — If an error occurred on the request side, then an error reason is returned in this parameter.
      - **reference** — _string_ — example: `"110.1260"` — Reference value for troubleshooting

- **401** — Unauthorized
  - Content-Type: `application/json`
  **Schema:** `BalancesResponse`

  - **balances** — _array_
    - **items** — _object_
      - **provider** — (`Provider`) — _string_ — **required** — enum: `P1`, `P2`, `P3`, `P4`, `P5`, `P6`
      - **accountId** — (`AccountId`) — _string_
      - **amount** — (`Amount`) — _number_
      - **currency** — (`Currency`) — _string_ — default: `"BRL"`
      - **lastUpdated** — _string_ — format: `date-time`
      - **status** — (`BaseResultStatus`) — _string_ — **required** — enum: `success`, `error` — Status of the request: success | error
      - **errors** — (`ResultError`) — _object_ — If an error occurred on the request side, an error code is returned in this parameter.
        - **code** — _string_ — **required** — example: `"7000.1000"` — If an error occurred on the request side, an error code is returned in this parameter.
        - **reason** — _string_ — example: `"Internal Processing Error"` — If an error occurred on the request side, then an error reason is returned in this parameter.
        - **reference** — _string_ — example: `"110.1260"` — Reference value for troubleshooting
  - **result** — (`BaseApiResultOutput`) — _object_ — **required**
    - **status** — (`BaseResultStatus`) — _string_ — **required** — enum: `success`, `error` — Status of the request: success | error
    - **errors** — (`ResultError`) — _object_ — If an error occurred on the request side, an error code is returned in this parameter.
      - **code** — _string_ — **required** — example: `"7000.1000"` — If an error occurred on the request side, an error code is returned in this parameter.
      - **reason** — _string_ — example: `"Internal Processing Error"` — If an error occurred on the request side, then an error reason is returned in this parameter.
      - **reference** — _string_ — example: `"110.1260"` — Reference value for troubleshooting

- **403** — Forbidden
  - Content-Type: `application/json`
  **Schema:** `BalancesResponse`

  - **balances** — _array_
    - **items** — _object_
      - **provider** — (`Provider`) — _string_ — **required** — enum: `P1`, `P2`, `P3`, `P4`, `P5`, `P6`
      - **accountId** — (`AccountId`) — _string_
      - **amount** — (`Amount`) — _number_
      - **currency** — (`Currency`) — _string_ — default: `"BRL"`
      - **lastUpdated** — _string_ — format: `date-time`
      - **status** — (`BaseResultStatus`) — _string_ — **required** — enum: `success`, `error` — Status of the request: success | error
      - **errors** — (`ResultError`) — _object_ — If an error occurred on the request side, an error code is returned in this parameter.
        - **code** — _string_ — **required** — example: `"7000.1000"` — If an error occurred on the request side, an error code is returned in this parameter.
        - **reason** — _string_ — example: `"Internal Processing Error"` — If an error occurred on the request side, then an error reason is returned in this parameter.
        - **reference** — _string_ — example: `"110.1260"` — Reference value for troubleshooting
  - **result** — (`BaseApiResultOutput`) — _object_ — **required**
    - **status** — (`BaseResultStatus`) — _string_ — **required** — enum: `success`, `error` — Status of the request: success | error
    - **errors** — (`ResultError`) — _object_ — If an error occurred on the request side, an error code is returned in this parameter.
      - **code** — _string_ — **required** — example: `"7000.1000"` — If an error occurred on the request side, an error code is returned in this parameter.
      - **reason** — _string_ — example: `"Internal Processing Error"` — If an error occurred on the request side, then an error reason is returned in this parameter.
      - **reference** — _string_ — example: `"110.1260"` — Reference value for troubleshooting

- **404** — Not Found
  - Content-Type: `application/json`
  **Schema:** `BalancesResponse`

  - **balances** — _array_
    - **items** — _object_
      - **provider** — (`Provider`) — _string_ — **required** — enum: `P1`, `P2`, `P3`, `P4`, `P5`, `P6`
      - **accountId** — (`AccountId`) — _string_
      - **amount** — (`Amount`) — _number_
      - **currency** — (`Currency`) — _string_ — default: `"BRL"`
      - **lastUpdated** — _string_ — format: `date-time`
      - **status** — (`BaseResultStatus`) — _string_ — **required** — enum: `success`, `error` — Status of the request: success | error
      - **errors** — (`ResultError`) — _object_ — If an error occurred on the request side, an error code is returned in this parameter.
        - **code** — _string_ — **required** — example: `"7000.1000"` — If an error occurred on the request side, an error code is returned in this parameter.
        - **reason** — _string_ — example: `"Internal Processing Error"` — If an error occurred on the request side, then an error reason is returned in this parameter.
        - **reference** — _string_ — example: `"110.1260"` — Reference value for troubleshooting
  - **result** — (`BaseApiResultOutput`) — _object_ — **required**
    - **status** — (`BaseResultStatus`) — _string_ — **required** — enum: `success`, `error` — Status of the request: success | error
    - **errors** — (`ResultError`) — _object_ — If an error occurred on the request side, an error code is returned in this parameter.
      - **code** — _string_ — **required** — example: `"7000.1000"` — If an error occurred on the request side, an error code is returned in this parameter.
      - **reason** — _string_ — example: `"Internal Processing Error"` — If an error occurred on the request side, then an error reason is returned in this parameter.
      - **reference** — _string_ — example: `"110.1260"` — Reference value for troubleshooting

- **500** — Internal Server Error
  - Content-Type: `application/json`
  **Schema:** `BalancesResponse`

  - **balances** — _array_
    - **items** — _object_
      - **provider** — (`Provider`) — _string_ — **required** — enum: `P1`, `P2`, `P3`, `P4`, `P5`, `P6`
      - **accountId** — (`AccountId`) — _string_
      - **amount** — (`Amount`) — _number_
      - **currency** — (`Currency`) — _string_ — default: `"BRL"`
      - **lastUpdated** — _string_ — format: `date-time`
      - **status** — (`BaseResultStatus`) — _string_ — **required** — enum: `success`, `error` — Status of the request: success | error
      - **errors** — (`ResultError`) — _object_ — If an error occurred on the request side, an error code is returned in this parameter.
        - **code** — _string_ — **required** — example: `"7000.1000"` — If an error occurred on the request side, an error code is returned in this parameter.
        - **reason** — _string_ — example: `"Internal Processing Error"` — If an error occurred on the request side, then an error reason is returned in this parameter.
        - **reference** — _string_ — example: `"110.1260"` — Reference value for troubleshooting
  - **result** — (`BaseApiResultOutput`) — _object_ — **required**
    - **status** — (`BaseResultStatus`) — _string_ — **required** — enum: `success`, `error` — Status of the request: success | error
    - **errors** — (`ResultError`) — _object_ — If an error occurred on the request side, an error code is returned in this parameter.
      - **code** — _string_ — **required** — example: `"7000.1000"` — If an error occurred on the request side, an error code is returned in this parameter.
      - **reason** — _string_ — example: `"Internal Processing Error"` — If an error occurred on the request side, then an error reason is returned in this parameter.
      - **reference** — _string_ — example: `"110.1260"` — Reference value for troubleshooting

### `/pix/entities/{entity-id}/closing-balances/{report-date}`

#### GET

**Summary:** Retrieve Merchant Balances at the end of the specified date

Retrieves a merchant's balances from all PIX providers at the end of the specified date.

**Operation ID:** `getClosingBalances`

**Tags:** Balances

**Security:** apiKeyAuth

**Parameters:**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `entity-id` | path | string | Yes |  |
| `report-date` | path | string | Yes |  |

**Responses:**

- **200** — OK
  - Content-Type: `application/json`
  **Schema:** `BalancesResponse`

  - **balances** — _array_
    - **items** — _object_
      - **provider** — (`Provider`) — _string_ — **required** — enum: `P1`, `P2`, `P3`, `P4`, `P5`, `P6`
      - **accountId** — (`AccountId`) — _string_
      - **amount** — (`Amount`) — _number_
      - **currency** — (`Currency`) — _string_ — default: `"BRL"`
      - **lastUpdated** — _string_ — format: `date-time`
      - **status** — (`BaseResultStatus`) — _string_ — **required** — enum: `success`, `error` — Status of the request: success | error
      - **errors** — (`ResultError`) — _object_ — If an error occurred on the request side, an error code is returned in this parameter.
        - **code** — _string_ — **required** — example: `"7000.1000"` — If an error occurred on the request side, an error code is returned in this parameter.
        - **reason** — _string_ — example: `"Internal Processing Error"` — If an error occurred on the request side, then an error reason is returned in this parameter.
        - **reference** — _string_ — example: `"110.1260"` — Reference value for troubleshooting
  - **result** — (`BaseApiResultOutput`) — _object_ — **required**
    - **status** — (`BaseResultStatus`) — _string_ — **required** — enum: `success`, `error` — Status of the request: success | error
    - **errors** — (`ResultError`) — _object_ — If an error occurred on the request side, an error code is returned in this parameter.
      - **code** — _string_ — **required** — example: `"7000.1000"` — If an error occurred on the request side, an error code is returned in this parameter.
      - **reason** — _string_ — example: `"Internal Processing Error"` — If an error occurred on the request side, then an error reason is returned in this parameter.
      - **reference** — _string_ — example: `"110.1260"` — Reference value for troubleshooting

- **400** — Bad Request
  - Content-Type: `application/json`
  **Schema:** `BalancesResponse`

  - **balances** — _array_
    - **items** — _object_
      - **provider** — (`Provider`) — _string_ — **required** — enum: `P1`, `P2`, `P3`, `P4`, `P5`, `P6`
      - **accountId** — (`AccountId`) — _string_
      - **amount** — (`Amount`) — _number_
      - **currency** — (`Currency`) — _string_ — default: `"BRL"`
      - **lastUpdated** — _string_ — format: `date-time`
      - **status** — (`BaseResultStatus`) — _string_ — **required** — enum: `success`, `error` — Status of the request: success | error
      - **errors** — (`ResultError`) — _object_ — If an error occurred on the request side, an error code is returned in this parameter.
        - **code** — _string_ — **required** — example: `"7000.1000"` — If an error occurred on the request side, an error code is returned in this parameter.
        - **reason** — _string_ — example: `"Internal Processing Error"` — If an error occurred on the request side, then an error reason is returned in this parameter.
        - **reference** — _string_ — example: `"110.1260"` — Reference value for troubleshooting
  - **result** — (`BaseApiResultOutput`) — _object_ — **required**
    - **status** — (`BaseResultStatus`) — _string_ — **required** — enum: `success`, `error` — Status of the request: success | error
    - **errors** — (`ResultError`) — _object_ — If an error occurred on the request side, an error code is returned in this parameter.
      - **code** — _string_ — **required** — example: `"7000.1000"` — If an error occurred on the request side, an error code is returned in this parameter.
      - **reason** — _string_ — example: `"Internal Processing Error"` — If an error occurred on the request side, then an error reason is returned in this parameter.
      - **reference** — _string_ — example: `"110.1260"` — Reference value for troubleshooting

- **401** — Unauthorized
  - Content-Type: `application/json`
  **Schema:** `BalancesResponse`

  - **balances** — _array_
    - **items** — _object_
      - **provider** — (`Provider`) — _string_ — **required** — enum: `P1`, `P2`, `P3`, `P4`, `P5`, `P6`
      - **accountId** — (`AccountId`) — _string_
      - **amount** — (`Amount`) — _number_
      - **currency** — (`Currency`) — _string_ — default: `"BRL"`
      - **lastUpdated** — _string_ — format: `date-time`
      - **status** — (`BaseResultStatus`) — _string_ — **required** — enum: `success`, `error` — Status of the request: success | error
      - **errors** — (`ResultError`) — _object_ — If an error occurred on the request side, an error code is returned in this parameter.
        - **code** — _string_ — **required** — example: `"7000.1000"` — If an error occurred on the request side, an error code is returned in this parameter.
        - **reason** — _string_ — example: `"Internal Processing Error"` — If an error occurred on the request side, then an error reason is returned in this parameter.
        - **reference** — _string_ — example: `"110.1260"` — Reference value for troubleshooting
  - **result** — (`BaseApiResultOutput`) — _object_ — **required**
    - **status** — (`BaseResultStatus`) — _string_ — **required** — enum: `success`, `error` — Status of the request: success | error
    - **errors** — (`ResultError`) — _object_ — If an error occurred on the request side, an error code is returned in this parameter.
      - **code** — _string_ — **required** — example: `"7000.1000"` — If an error occurred on the request side, an error code is returned in this parameter.
      - **reason** — _string_ — example: `"Internal Processing Error"` — If an error occurred on the request side, then an error reason is returned in this parameter.
      - **reference** — _string_ — example: `"110.1260"` — Reference value for troubleshooting

- **403** — Forbidden
  - Content-Type: `application/json`
  **Schema:** `BalancesResponse`

  - **balances** — _array_
    - **items** — _object_
      - **provider** — (`Provider`) — _string_ — **required** — enum: `P1`, `P2`, `P3`, `P4`, `P5`, `P6`
      - **accountId** — (`AccountId`) — _string_
      - **amount** — (`Amount`) — _number_
      - **currency** — (`Currency`) — _string_ — default: `"BRL"`
      - **lastUpdated** — _string_ — format: `date-time`
      - **status** — (`BaseResultStatus`) — _string_ — **required** — enum: `success`, `error` — Status of the request: success | error
      - **errors** — (`ResultError`) — _object_ — If an error occurred on the request side, an error code is returned in this parameter.
        - **code** — _string_ — **required** — example: `"7000.1000"` — If an error occurred on the request side, an error code is returned in this parameter.
        - **reason** — _string_ — example: `"Internal Processing Error"` — If an error occurred on the request side, then an error reason is returned in this parameter.
        - **reference** — _string_ — example: `"110.1260"` — Reference value for troubleshooting
  - **result** — (`BaseApiResultOutput`) — _object_ — **required**
    - **status** — (`BaseResultStatus`) — _string_ — **required** — enum: `success`, `error` — Status of the request: success | error
    - **errors** — (`ResultError`) — _object_ — If an error occurred on the request side, an error code is returned in this parameter.
      - **code** — _string_ — **required** — example: `"7000.1000"` — If an error occurred on the request side, an error code is returned in this parameter.
      - **reason** — _string_ — example: `"Internal Processing Error"` — If an error occurred on the request side, then an error reason is returned in this parameter.
      - **reference** — _string_ — example: `"110.1260"` — Reference value for troubleshooting

- **404** — Not Found
  - Content-Type: `application/json`
  **Schema:** `BalancesResponse`

  - **balances** — _array_
    - **items** — _object_
      - **provider** — (`Provider`) — _string_ — **required** — enum: `P1`, `P2`, `P3`, `P4`, `P5`, `P6`
      - **accountId** — (`AccountId`) — _string_
      - **amount** — (`Amount`) — _number_
      - **currency** — (`Currency`) — _string_ — default: `"BRL"`
      - **lastUpdated** — _string_ — format: `date-time`
      - **status** — (`BaseResultStatus`) — _string_ — **required** — enum: `success`, `error` — Status of the request: success | error
      - **errors** — (`ResultError`) — _object_ — If an error occurred on the request side, an error code is returned in this parameter.
        - **code** — _string_ — **required** — example: `"7000.1000"` — If an error occurred on the request side, an error code is returned in this parameter.
        - **reason** — _string_ — example: `"Internal Processing Error"` — If an error occurred on the request side, then an error reason is returned in this parameter.
        - **reference** — _string_ — example: `"110.1260"` — Reference value for troubleshooting
  - **result** — (`BaseApiResultOutput`) — _object_ — **required**
    - **status** — (`BaseResultStatus`) — _string_ — **required** — enum: `success`, `error` — Status of the request: success | error
    - **errors** — (`ResultError`) — _object_ — If an error occurred on the request side, an error code is returned in this parameter.
      - **code** — _string_ — **required** — example: `"7000.1000"` — If an error occurred on the request side, an error code is returned in this parameter.
      - **reason** — _string_ — example: `"Internal Processing Error"` — If an error occurred on the request side, then an error reason is returned in this parameter.
      - **reference** — _string_ — example: `"110.1260"` — Reference value for troubleshooting

- **500** — Internal Server Error
  - Content-Type: `application/json`
  **Schema:** `BalancesResponse`

  - **balances** — _array_
    - **items** — _object_
      - **provider** — (`Provider`) — _string_ — **required** — enum: `P1`, `P2`, `P3`, `P4`, `P5`, `P6`
      - **accountId** — (`AccountId`) — _string_
      - **amount** — (`Amount`) — _number_
      - **currency** — (`Currency`) — _string_ — default: `"BRL"`
      - **lastUpdated** — _string_ — format: `date-time`
      - **status** — (`BaseResultStatus`) — _string_ — **required** — enum: `success`, `error` — Status of the request: success | error
      - **errors** — (`ResultError`) — _object_ — If an error occurred on the request side, an error code is returned in this parameter.
        - **code** — _string_ — **required** — example: `"7000.1000"` — If an error occurred on the request side, an error code is returned in this parameter.
        - **reason** — _string_ — example: `"Internal Processing Error"` — If an error occurred on the request side, then an error reason is returned in this parameter.
        - **reference** — _string_ — example: `"110.1260"` — Reference value for troubleshooting
  - **result** — (`BaseApiResultOutput`) — _object_ — **required**
    - **status** — (`BaseResultStatus`) — _string_ — **required** — enum: `success`, `error` — Status of the request: success | error
    - **errors** — (`ResultError`) — _object_ — If an error occurred on the request side, an error code is returned in this parameter.
      - **code** — _string_ — **required** — example: `"7000.1000"` — If an error occurred on the request side, an error code is returned in this parameter.
      - **reason** — _string_ — example: `"Internal Processing Error"` — If an error occurred on the request side, then an error reason is returned in this parameter.
      - **reference** — _string_ — example: `"110.1260"` — Reference value for troubleshooting