Avistadocs

生成 PIX 收款（Cash-In）

POST /api/pix/cash-in

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

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

生成动态二维码，用于通过 PIX 接收付款。收款创建后状态为 PENDING，付款成功后状态将通过 webhook 变更为 CONFIRMED。

认证

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

在沙盒中测试？ 添加 X-Sandbox-Scenario 请求头以模拟 webhook 的错误和延迟场景。请参阅沙盒测试指南获取完整的场景列表。

请求体

字段类型必填描述
transactionobject是交易数据
transaction.valuenumber是金额（巴西雷亚尔，最多 2 位小数）。最小值：0.01
transaction.descriptionstring是交易描述（最多 140 个字符）
transaction.externalIdstring是外部交易 ID（每个账户的唯一标识符）
transaction.expirationTimenumber否过期时间（秒）。最短 30 秒，最长 7 天。默认值：86400（24 小时）。部分提供商要求更高的最小值 — 参见 按提供商的限制
transaction.generateQrCodeboolean否如果为 true，以 Base64 格式返回二维码。默认值：false
payerobject是付款人数据（仅供参考 -- 不会发送给 PSP）
payer.fullNamestring是付款人姓名。仅供参考 -- 可使用固定值（如：账户的公司名称）。最多 100 个字符
payer.documentstring是CPF（11 位数字）或 CNPJ（14 位数字）。仅供参考 -- 可使用集成方自身的 CNPJ
additionalInfoobject否附加信息（string:string 键值对，最多 10 个键）
splitsarray否分账接收人列表（最多 10 个）。当 PIX-IN 确认后，金额将自动分配。所有分账金额之和不能超过交易金额
splits[].pixKeystring是分账接收人的 PIX 密钥（最多 255 个字符）
splits[].pixKeyTypestring是密钥类型：EMAIL、PHONE、CPF、CNPJ、RANDOM
splits[].namestring是接收人姓名（最多 255 个字符）
splits[].documentstring是CPF（11 位数字）或 CNPJ（14 位数字），仅数字
splits[].typestring是分账类型：FIXED（固定金额，单位为雷亚尔）或 PERCENTAGE（占总金额的百分比）
splits[].valuenumber是分账金额。FIXED：雷亚尔金额，最多 2 位小数（例如：10.50）。PERCENTAGE：直接填写百分比（例如：10 = 10%）。最小值：0.01
splits[].immediateboolean否如果为 true，分账在 PIX-IN 确认后立即执行。默认值：false（遵循账户配置的频率）

请求示例

最简场景：生成收款，不含二维码，不含附加信息。

{
  "transaction": {
    "value": 49.90,
    "description": "Assinatura mensal - Plano Básico",
    "externalId": "SUB-2024-001"
  },
  "payer": {
    "fullName": "Maria Silva",
    "document": "12345678901"
  }
}

最常见场景：生成二维码供付款人扫描，附带订单元数据，过期时间为 1 小时。

{
  "transaction": {
    "value": 189.90,
    "description": "Pedido #8842 - Loja Virtual",
    "externalId": "ORD-8842-20240115",
    "expirationTime": 3600,
    "generateQrCode": true
  },
  "payer": {
    "fullName": "Carlos Oliveira",
    "document": "98765432000188"
  },
  "additionalInfo": {
    "orderId": "8842",
    "storeName": "Tech Solutions",
    "customerEmail": "carlos@email.com"
  }
}

大额收款（B2B），过期时间为 7 天，付款方为 CNPJ。

{
  "transaction": {
    "value": 15750.00,
    "description": "NF 2024/0042 - Consultoria em TI",
    "externalId": "NF-2024-0042",
    "expirationTime": 604800,
    "generateQrCode": true
  },
  "payer": {
    "fullName": "Empresa ABC Ltda",
    "document": "11222333000144"
  },
  "additionalInfo": {
    "nfNumber": "2024/0042",
    "contractId": "CTR-789"
  }
}

Marketplace 场景：R$ 200 的付款分配给卖家（70%）、平台（20%）和配送员（固定 R$ 10）。分账将按照账户配置的频率执行。

{
  "transaction": {
    "value": 200.00,
    "description": "Pedido #12345 - Marketplace",
    "externalId": "MKT-12345",
    "generateQrCode": true
  },
  "payer": {
    "fullName": "João Pereira",
    "document": "12345678901"
  },
  "splits": [
    {
      "pixKey": "vendedor@email.com",
      "pixKeyType": "EMAIL",
      "name": "Loja do João",
      "document": "98765432000188",
      "type": "PERCENTAGE",
      "value": 70
    },
    {
      "pixKey": "11222333000144",
      "pixKeyType": "CNPJ",
      "name": "Marketplace Ltda",
      "document": "11222333000144",
      "type": "PERCENTAGE",
      "value": 20
    },
    {
      "pixKey": "11999887766",
      "pixKeyType": "PHONE",
      "name": "Entregador Silva",
      "document": "98765432100",
      "type": "FIXED",
      "value": 10.00
    }
  ]
}

付款确认后的结果：

接收方类型计算方式金额
Loja do João70%R$ 200 × 70%R$ 140,00
Marketplace Ltda20%R$ 200 × 20%R$ 40,00
Entregador Silva固定—R$ 10,00
剩余余额—R$ 200 - R$ 190R$ 10,00

单笔即时分账：付款确认后，立即自动将款项转给服务提供方（无需等待账户配置的频率）。

{
  "transaction": {
    "value": 350.00,
    "description": "Serviço de consultoria - Projeto Alpha",
    "externalId": "SVC-ALPHA-001",
    "generateQrCode": true
  },
  "payer": {
    "fullName": "Empresa XYZ S.A.",
    "document": "55666777000199"
  },
  "splits": [
    {
      "pixKey": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
      "pixKeyType": "RANDOM",
      "name": "Consultor Freelancer",
      "document": "12345678901",
      "type": "PERCENTAGE",
      "value": 80,
      "immediate": true
    }
  ]
}

请参阅分账付款指南，了解有关类型、计算方式、频率和高级示例的完整详情。

代码示例

cURL
curl -X POST "https://api.avista.global/api/pix/cash-in" \
  -H "Authorization: Bearer $AVISTA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "transaction": {
    "value": 49.90,
    "description": "Assinatura mensal - Plano Básico",
    "externalId": "SUB-2024-001"
  },
  "payer": {
    "fullName": "Maria Silva",
    "document": "12345678901"
  }
}'
const axios = require('axios');

const response = await axios.post('https://api.avista.global/api/pix/cash-in',
  {
  "transaction": {
    "value": 49.90,
    "description": "Assinatura mensal - Plano Básico",
    "externalId": "SUB-2024-001"
  },
  "payer": {
    "fullName": "Maria Silva",
    "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-in',
    headers={
        'Authorization': f'Bearer {os.environ["AVISTA_TOKEN"]}',
        'Content-Type': 'application/json',
    },
    json={
  "transaction": {
    "value": 49.90,
    "description": "Assinatura mensal - Plano Básico",
    "externalId": "SUB-2024-001"
  },
  "payer": {
    "fullName": "Maria Silva",
    "document": "12345678901"
  }
},
)
print(response.json())
$ch = curl_init('https://api.avista.global/api/pix/cash-in');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('AVISTA_TOKEN'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{
  "transaction": {
    "value": 49.90,
    "description": "Assinatura mensal - Plano Básico",
    "externalId": "SUB-2024-001"
  },
  "payer": {
    "fullName": "Maria Silva",
    "document": "12345678901"
  }
}',
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
String body = """
    {
      "transaction": {
        "value": 49.90,
        "description": "Assinatura mensal - Plano Básico",
        "externalId": "SUB-2024-001"
      },
      "payer": {
        "fullName": "Maria Silva",
        "document": "12345678901"
      }
    }
    """;
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.avista.global/api/pix/cash-in"))
    .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)

字段类型描述
transactionIdstring生成的交易唯一标识符
correlationIdstring交易关联 ID（UUID）
externalIdstring外部交易 ID（与输入值相同）
statusstring交易状态：PENDING（等待付款）
pixCodestring标准 EMV 格式的 PIX 代码（复制粘贴）
generateTimestringPIX 生成日期和时间（ISO 8601）
expirationDatestringPIX 过期日期和时间（ISO 8601）
qrCodeImagestringBase64 格式的二维码（仅当 generateQrCode=true 时返回）
{
  "transactionId": "7845",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "externalId": "ORD-8842-20240115",
  "status": "PENDING",
  "pixCode": "00020126580014br.gov.bcb.pix0136550e8400-e29b-41d4-a716-4466554400005204000053039865802BR5916Tech Solutions Ltda6009SAO PAULO62070503***63041D3D",
  "generateTime": "2024-01-15T10:30:00.000Z",
  "expirationDate": "2024-01-15T11:30:00.000Z",
  "qrCodeImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAAAB5fY51..."
}

错误

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

{
  "statusCode": 400,
  "timestamp": "2026-04-10T15:27:36.608Z",
  "path": "/public/pix/cash-in",
  "method": "POST",
  "code": "HTTP_ERROR",
  "message": [
    "transaction.value must be at least 0.01",
    "transaction.value must have a maximum of 2 decimal places",
    "transaction.description should not be empty",
    "transaction.description must be a string"
  ],
  "userMessage": "Requisição inválida. Verifique os dados enviados.",
  "errorId": "31b5dc36b86c598e51a2a5389a37060d",
  "error": "Bad Request"
}

常见原因：

  • transaction.value 小于 0.01 或超过 2 位小数
  • transaction.description 或 transaction.externalId 为空
  • expirationTime 小于 30（秒）或大于 604800（7 天）
  • expirationTime 小于账户提供商的最小值（errorCode PROVIDER_EXPIRATION_BELOW_MINIMUM）— 参见 按提供商的限制
  • 分账金额之和超过交易金额

令牌缺失、已过期或无效。

{
  "statusCode": 401,
  "timestamp": "2026-04-10T15:30:00.000Z",
  "path": "/public/pix/cash-in",
  "method": "POST",
  "code": "HTTP_ERROR",
  "message": "Unauthorized",
  "userMessage": "Token de autenticação inválido ou expirado.",
  "errorId": "a9f3e2b1c4d5678e90123456abcdef01",
  "error": "Unauthorized"
}

与 PIX 提供商通信失败。请重试。

{
  "statusCode": 500,
  "timestamp": "2026-04-10T15:30:00.000Z",
  "path": "/public/pix/cash-in",
  "method": "POST",
  "code": "HTTP_ERROR",
  "message": "Internal Server Error",
  "userMessage": "Erro ao gerar cobrança PIX. Tente novamente em alguns instantes.",
  "errorId": "c7d8e9f0a1b2345678901234abcdef56",
  "error": "Internal Server Error"
}

查询账户余额

查询账户的可用余额。

发起 PIX 付款（Cash-Out）

向目标 PIX 密钥发起 PIX 付款。

本页目录

POST /api/pix/cash-in认证请求体请求示例代码示例响应 (201 Created)错误