NTX Paydocs
接口端点

查询余额

概述

GET /accounts/balances 接口端点以兼容中央银行规范的格式返回已认证账户的余额。

接口端点

GET /accounts/balances

身份认证

stringobrigatorio

通过 /oauth/token 获取的 Bearer 令牌。

请求

curl -X GET https://api.ntxpay.com/accounts/balances \
  -H "Authorization: Bearer <token>"
const response = await fetch('https://api.ntxpay.com/accounts/balances', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const balance = await response.json();
import requests

response = requests.get(
    'https://api.ntxpay.com/accounts/balances',
    headers={
        'Authorization': f'Bearer {token}',
    }
)

balance = response.json()

响应

{
  "data": [
    {
      "eventDate": "2025-01-15T10:30:00.000Z",
      "balanceAmount": {
        "available": 48734.90,
        "blocked": 1500.00,
        "overdraft": 0
      }
    }
  ]
}
{
  "statusCode": 401,
  "message": "Token não fornecido ou inválido",
  "error": "Unauthorized"
}

响应字段

dataarray

余额列表。当前仅返回一条记录。

余额类型

类型描述
available可立即用于转账的余额
blocked为正在处理的操作预留的金额
overdraft额外信用额度（尚未实现）

总余额计算

totalBalance = available + blocked

available 余额已扣除 blocked 金额。

与标准 API 的对比

标准 API (GET /balance)BACEN API (GET /accounts/balances)
grossBalanceavailable + blocked
blockedBalanceblocked
netBalanceavailable
consultedAteventDate

等价示例

// 标准 API
{
  "grossBalance": 50234.90,
  "blockedBalance": 1500.00,
  "netBalance": 48734.90,
  "consultedAt": "2025-01-15T10:30:00.000Z"
}

// BACEN API（等价）
{
  "data": [{
    "eventDate": "2025-01-15T10:30:00.000Z",
    "balanceAmount": {
      "available": 48734.90,
      "blocked": 1500.00,
      "overdraft": 0
    }
  }]
}

操作中的余额变化

PIX 转出（转账）

sequenceDiagram
    participant App
    participant API
    participant Bank

    Note over App,Bank: 初始状态：available=1000，blocked=0

    App->>API: POST /dict/pix (R$ 100)
    API-->>App: { type: "PENDING" }

    Note over App,Bank: 状态：available=900，blocked=100

    Bank->>API: Confirmation
    API->>App: Webhook TRANSFER (LIQUIDATED)

    Note over App,Bank: 最终状态：available=900，blocked=0

PIX 转入（收款）

sequenceDiagram
    participant Payer
    participant API
    participant App

    Note over Payer,App: 初始状态：available=1000

    Payer->>API: Pays QR Code
    API->>App: Webhook RECEIVE (LIQUIDATED)

    Note over Payer,App: 最终状态：available=1100

最佳实践

常见错误

状态码错误解决方案
401未提供令牌包含 Authorization: Bearer <token> 请求头
401令牌无效检查令牌是否正确
401令牌已过期通过 /oauth/token 获取新令牌

后续步骤

创建收款

生成二维码以接收 PIX

PIX 转账

向其他账户发送 PIX

PIX 转账

向 DICT 密钥发起 PIX 转账

概述

了解 PIX Bacen API 中使用的 V2 Webhook 格式

本页目录

概述接口端点身份认证请求响应响应字段余额类型总余额计算与标准 API 的对比等价示例操作中的余额变化PIX 转出（转账）PIX 转入（收款）最佳实践常见错误后续步骤