发起 PIX 付款（Cash-Out）

POST /api/pix/cash-out

POST https://api.avista.global/api/pix/cash-out

需要在 Authorization 头中提供 Bearer token。请参阅生成令牌获取。

向目标 PIX 密钥发送 PIX 付款。交易创建后状态为 PENDING，最终结果将通过 webhook 通知，或可通过轮询查询。

认证

需要在 Authorization 请求头中提供 Bearer 令牌。

在沙盒中测试？ 添加 X-Sandbox-Scenario 请求头以模拟错误场景，例如余额不足、无效 PIX 密钥和证件号码不匹配。请参阅沙盒测试指南。

请求体

字段	类型	必填	描述
`value`	number	是	金额（巴西雷亚尔，最多 2 位小数）。最小值：`0.01`
`externalId`	string	是	每个账户的唯一外部标识符
`description`	string	否	交易描述（最多 140 个字符）
`details`	object	是	目标 PIX 密钥信息
`details.key`	string	是	目标 PIX 密钥（格式见下表）
`details.keyType`	string	是	密钥类型：`DOCUMENT`、`EMAIL`、`PHONE`、`RANDOM`。必填，因为 API 不会查询 DICT
`details.name`	string	是	收款人姓名（仅供参考，最多 100 个字符）
`details.document`	string	是	持有人的 CPF（11 位数字）或 CNPJ（14 位数字）。所有 keyType 均为必填

`details.key` 的格式要求

`keyType`	格式	示例
`DOCUMENT`	CPF：11 位数字 / CNPJ：14 位数字（仅数字）	`12345678901`、`12345678000195`
`EMAIL`	有效的电子邮件地址	`usuario@exemplo.com`
`PHONE`	区号 + 号码（10-11 位数字，不含国际区号 +55）	`11999999999`
`RANDOM`	UUID（可带或不带连字符）	`a1b2c3d4-e5f6-4890-abcd-ef1234567890`

details.document 字段对于所有密钥类型均为必填，包括 EMAIL、PHONE 和 RANDOM。该字段会被发送至清算银行用于 DICT 验证。如果证件号码与 PIX 密钥持有人不匹配，银行将返回 TAX_ID_MISMATCH 错误。

请求示例

通过 CPF 付款 -- 最常见的场景。details.key 和 details.document 相同（都是 CPF）。

{
  "value": 150.00,
  "externalId": "PAG-2024-0001",
  "description": "Pagamento freelancer - Janeiro/2024",
  "details": {
    "key": "12345678901",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678901"
  }
}

通过 CNPJ 付款 -- 常见于 B2B 支付（供应商、发票）。

{
  "value": 4500.00,
  "externalId": "NF-2024-0089",
  "description": "NF 0089/2024 - Serviços de hospedagem",
  "details": {
    "key": "11222333000144",
    "keyType": "DOCUMENT",
    "name": "Cloud Provider Ltda",
    "document": "11222333000144"
  }
}

通过电子邮件密钥付款。请注意，details.document 必须是密钥持有人的 CPF/CNPJ（无法通过电子邮件推断）。

{
  "value": 89.90,
  "externalId": "COMM-2024-0456",
  "description": "Comissão venda #456",
  "details": {
    "key": "vendedor@loja.com.br",
    "keyType": "EMAIL",
    "name": "Roberto Vendas",
    "document": "98765432100"
  }
}

通过手机号码密钥付款。格式为区号 + 号码（10 或 11 位数字），不含国际区号 +55。

{
  "value": 25.00,
  "externalId": "REEMB-2024-0012",
  "description": "Reembolso uber colaborador",
  "details": {
    "key": "11987654321",
    "keyType": "PHONE",
    "name": "Pedro Almeida",
    "document": "11122233344"
  }
}

通过随机密钥（EVP/UUID）付款。由巴西中央银行生成，不包含个人信息。

{
  "value": 1250.00,
  "externalId": "RENT-2024-JAN",
  "description": "Aluguel janeiro/2024",
  "details": {
    "key": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
    "keyType": "RANDOM",
    "name": "Imobiliária Central",
    "document": "55666777000199"
  }
}

代码示例

cURL

curl -X POST "https://api.avista.global/api/pix/cash-out" \
  -H "Authorization: Bearer $AVISTA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "value": 150.00,
  "externalId": "PAG-2024-0001",
  "description": "Pagamento freelancer - Janeiro/2024",
  "details": {
    "key": "12345678901",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678901"
  }
}'

const axios = require('axios');

const response = await axios.post('https://api.avista.global/api/pix/cash-out',
  {
  "value": 150.00,
  "externalId": "PAG-2024-0001",
  "description": "Pagamento freelancer - Janeiro/2024",
  "details": {
    "key": "12345678901",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678901"
  }
},
  {
    headers: {
      'Authorization': `Bearer ${process.env.AVISTA_TOKEN}`,
      'Content-Type': 'application/json',
    },
  }
);
console.log(response.data);

import os, requests

response = requests.post(
    'https://api.avista.global/api/pix/cash-out',
    headers={
        'Authorization': f'Bearer {os.environ["AVISTA_TOKEN"]}',
        'Content-Type': 'application/json',
    },
    json={
  "value": 150.00,
  "externalId": "PAG-2024-0001",
  "description": "Pagamento freelancer - Janeiro/2024",
  "details": {
    "key": "12345678901",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678901"
  }
},
)
print(response.json())

$ch = curl_init('https://api.avista.global/api/pix/cash-out');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('AVISTA_TOKEN'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{
  "value": 150.00,
  "externalId": "PAG-2024-0001",
  "description": "Pagamento freelancer - Janeiro/2024",
  "details": {
    "key": "12345678901",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678901"
  }
}',
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

String body = """
    {
      "value": 150.00,
      "externalId": "PAG-2024-0001",
      "description": "Pagamento freelancer - Janeiro/2024",
      "details": {
        "key": "12345678901",
        "keyType": "DOCUMENT",
        "name": "Ana Costa",
        "document": "12345678901"
      }
    }
    """;
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.avista.global/api/pix/cash-out"))
    .header("Authorization", "Bearer " + System.getenv("AVISTA_TOKEN"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

响应 (201 Created)

字段	类型	描述
`transactionId`	string	生成的交易内部标识符（UUID）
`externalId`	string	请求中提供的外部标识符
`status`	string	初始状态：`PENDING`。通过 webhook 确认：`CONFIRMED` 或 `ERROR`
`generateTime`	string	交易生成日期/时间（ISO 8601 UTC）

{
  "transactionId": "8b3b85ac-394c-4144-9bcb-c5d12de3fa56",
  "externalId": "PAG-2024-0001",
  "status": "PENDING",
  "generateTime": "2024-01-15T10:30:00.000Z"
}

错误

当请求体未通过验证时返回。message 字段是一个数组，包含每个无效字段的错误消息。

{
  "statusCode": 400,
  "timestamp": "2026-04-10T15:30:34.560Z",
  "path": "/public/pix/cash-out",
  "method": "POST",
  "code": "HTTP_ERROR",
  "message": [
    "value must be at least 0.01",
    "details.keyType must be one of: EMAIL, PHONE, DOCUMENT, RANDOM"
  ],
  "userMessage": "Requisição inválida. Verifique os dados enviados.",
  "errorId": "a1b2c3d4e5f6789012345678abcdef01",
  "error": "Bad Request"
}

常见原因：

value 小于 0.01 或超过 2 位小数
details.keyType 值无效
details.key 与 keyType 的格式不匹配
details.document 为空或格式错误

可用余额小于交易金额 + 手续费。

{
  "statusCode": 400,
  "timestamp": "2026-04-10T15:30:34.560Z",
  "path": "/public/pix/cash-out",
  "method": "POST",
  "code": "PIX_INSUFFICIENT_BALANCE",
  "message": "Saldo insuficiente para realizar esta operação.",
  "userMessage": "Requisição inválida. Verifique os dados enviados.",
  "errorId": "b2c3d4e5f6a7890123456789abcdef02",
  "errorCode": "PIX_INSUFFICIENT_BALANCE"
}

同类别的其他业务错误：

错误码	描述
`PIX_INSUFFICIENT_BALANCE`	余额不足（金额 + 手续费）
`PIX_TRANSACTION_LIMIT_EXCEEDED`	金额超过单笔交易限额
`PIX_DAILY_LIMIT_EXCEEDED`	当日累计金额超过每日限额
`PIX_NIGHT_LIMIT_EXCEEDED`	夜间交易超过降低后的限额（20:00-06:00）
`PIX_INVALID_AMOUNT`	金额小于 0.01 或超过 2 位小数
`PIX_INVALID_PIX_KEY`	密钥格式与所提供的 `keyType` 不匹配

该 externalId 已在此账户中使用过。请使用新的标识符。返回状态码 400（非 409），details 中包含已有交易的 ID。

{
  "statusCode": 400,
  "timestamp": "2026-04-10T15:30:34.560Z",
  "path": "/public/pix/cash-out",
  "method": "POST",
  "code": "PIX_DUPLICATE_EXTERNAL_ID",
  "message": "Esta transação já existe no sistema.",
  "userMessage": "Requisição inválida. Verifique os dados enviados.",
  "errorId": "c57c14ee10aabd82e40dae9b940706e0",
  "errorCode": "PIX_DUPLICATE_EXTERNAL_ID",
  "details": {
    "externalId": "external-teste-002",
    "existingTransactionId": 466208
  }
}

externalId 用作幂等键。如果您使用相同的 externalId 发送两次相同的请求，第二次调用将返回错误 -- 确保付款不会重复。details.existingTransactionId 字段可用于查找原始交易。

当清算银行在交易创建之后拒绝了操作时，状态会变为 ERROR，并且 errorCode/errorMessage 字段将通过 Cash-Out webhook 发送：

`errorCode`	描述	可重试？
`TAX_ID_MISMATCH`	`details.document` 与 PIX 密钥持有人不匹配	否 -- 请修正 CPF/CNPJ
`INVALID_TAX_ID`	CPF/CNPJ 算法校验无效	否 -- 请修正证件号码
`BLOCKED_ACCOUNT`	目标账户被司法冻结	否
`ACCOUNT_CLOSED`	目标账户已注销	否
`ORDER_REJECTED`	目标银行拒绝了该操作	否
`PAYMENT_EXPIRED`	交易在处理前已过期	是 -- 请重新发送
`SETTLEMENT_TIMEOUT`	目标银行未及时响应	是 -- 请重新发送

包含错误的 webhook 载荷示例：

{
  "event": "CashOut",
  "status": "ERROR",
  "transactionType": "PIX",
  "movementType": "DEBIT",
  "transactionId": "466208",
  "externalId": "PAG-2024-0001",
  "endToEndId": "E17758345EYNKPHCJKMS",
  "pixKey": "12345678901",
  "feeAmount": 0.07,
  "originalAmount": 1,
  "finalAmount": 1.07,
  "processingDate": "2026-04-10T15:22:49.970Z",
  "errorCode": "TAX_ID_MISMATCH",
  "errorMessage": "O documento informado não corresponde ao titular da chave PIX",
  "counterpart": {
    "name": "João Silva",
    "document": "12345678901",
    "bank": {
      "bankISPB": "13140088",
      "bankName": "ACESSO SOLUÇÕES DE PAGAMENTO S.A.",
      "bankCode": "332",
      "accountBranch": null,
      "accountNumber": null
    }
  },
  "metadata": {}
}

当 status 为 CONFIRMED 时，errorCode 和 errorMessage 字段为 null。当 status 为 ERROR 时，它们表示拒绝的原因。

请参阅 PIX Cash-Out 集成指南，获取代码示例、密钥本地验证和最佳实践。

发起 PIX 付款（Cash-Out）

本页目录