动态 QR Code 指南

本指南说明如何使用动态 QR Code 生成 PIX 收款。

概述

动态 QR Code 允许您创建具有指定金额、过期时间和付款人信息的唯一收款。适用于以下场景：

电子商务 - 订单付款
账单 - 发票和账单
服务 - 服务费用支付

集成流程

┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│   Create    │      │   Customer  │      │   Webhook   │
│   Charge    │ ───► │   Pays QR   │ ───► │   Received  │
└─────────────┘      └─────────────┘      └─────────────┘
      │                                          │
      ▼                                          ▼
  Returns EMV                              Confirms
  and payload                              Payment

第一步：创建收款（动态 QR Code）

请求

curl -X POST "https://api.corpxapi.com/v1/accounts/{accountId}/pix/qr-code/dynamic" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: {tenant_id}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345" \
  -d '{
    "pixKey": "your-pix-key-here",
    "value": 150.75,
    "expirationDate": "2026-02-10T15:30:00Z",
    "identifier": "order-12345",
    "message": "Payment for order #12345"
  }'

请求体参数

字段	类型	必填	描述
`pixKey`	string	是	收款账户的 PIX 密钥（必须已注册）
`value`	number	是	收款金额（BRL）。最多 2 位小数（例如 150.75）
`expirationDate`	datetime	是	过期日期/时间（RFC3339 格式，例如 `2026-02-10T15:30:00Z`）
`identifier`	string	是	唯一的收款标识符（最多 35 个字符）
`message`	string	否	向付款人显示的消息（最多 140 个字符）
`allowChangeValue`	boolean	否	是否允许在付款时更改金额（默认：false）
`allowedPayerTaxNumber`	string	否	授权付款的特定 CPF/CNPJ

重要请求头

请求头	描述
`Idempotency-Key`	唯一标识符，用于防止重复创建收款

成功响应 (201 Created)

{
  "statusCode": 201,
  "title": "created",
  "type": "dynamic_immediate",
  "message": "QR code created successfully",
  "data": {
    "chave": "8026ff12-cb4a-4d19-9638-08bb15d450e2",
    "identifier": "order-12345",
    "location": "00020101021226790014br.gov.bcb.pix2557brcode.starkinfra.com/v2/88a38a908a92441a98dac228ee1d95075204000053039865802BR5912iDez Digital6004Lins62070503***63040BFF",
    "payload": "00020101021226790014br.gov.bcb.pix2557brcode.starkinfra.com/v2/88a38a908a92441a98dac228ee1d95075204000053039865802BR5912iDez Digital6004Lins62070503***63040BFF",
    "status": "ATIVA",
    "txid": "88a38a908a92441a98dac228ee1d9507"
  }
}

字段	描述
`data.chave`	用于收款的 PIX 密钥
`data.identifier`	唯一的收款 ID（用于查询）
`data.payload`	PIX 复制粘贴代码（EMV 字符串）
`data.location`	与 payload 相同 - QR code 的 EMV 字符串
`data.status`	收款状态（`ATIVA` = 有效）
`data.txid`	内部交易 ID

第二步：显示 QR Code

使用 PIX 复制粘贴

将 payload 字段展示给客户进行复制：

<input type="text" 
       value="00020101021226790014br.gov.bcb.pix..." 
       readonly />
<button onclick="navigator.clipboard.writeText(this.previousElementSibling.value)">
  Copy
</button>

提示

您可以使用任何 QR code 库（例如 qrcode.js、python-qrcode）从 payload 字符串生成 QR code 图片。

第三步：查询收款状态

通过 identifier 轮询收款状态：

请求

curl -X GET "https://api.corpxapi.com/v1/accounts/{accountId}/pix/qr-code?identifier=order-12345" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: {tenant_id}"

可能的状态

状态	描述
`active`	等待付款
`paid`	付款已确认
`refunded`	付款已退款（您已退回款项）
`expired`	收款已过期，未收到付款
`cancelled`	收款已手动取消

各状态的响应示例

有效（等待付款）

{
  "txid": "88a38a908a92441a98dac228ee1d9507",
  "identifier": "order-12345",
  "accountId": "6ff57bc1-e4a9-403b-be62-42378b8aafd7",
  "pixKey": "8026ff12-cb4a-4d19-9638-08bb15d450e2",
  "value": 150.75,
  "status": "active",
  "type": "dynamic",
  "createdAt": "2026-02-09T01:50:36Z",
  "expiresAt": "2026-02-09T02:50:34Z",
  "description": "Payment for order #12345",
  "emv": "00020101021226790014br.gov.bcb.pix2557brcode.starkinfra.com/v2/88a38a90...",
  "location": "00020101021226790014br.gov.bcb.pix2557brcode.starkinfra.com/v2/88a38a90...",
  "reconciled": false
}

已支付（付款已确认）

{
  "txid": "b091da7bba6a45d1a9f709daaba04e30",
  "identifier": "order-12345",
  "accountId": "6ff57bc1-e4a9-403b-be62-42378b8aafd7",
  "pixKey": "8026ff12-cb4a-4d19-9638-08bb15d450e2",
  "value": 150.75,
  "status": "paid",
  "type": "dynamic",
  "createdAt": "2026-02-05T22:08:02Z",
  "expiresAt": "2026-02-05T23:08:00Z",
  "description": "Payment for order #12345",
  "emv": "00020101021226790014br.gov.bcb.pix...",
  "location": "00020101021226790014br.gov.bcb.pix...",
  "paidAt": "2026-02-05T22:10:25.055",
  "paidAmount": 150.75,
  "endToEndId": "E303062942026020522100000005EXVX",
  "payer": {
    "name": "John Smith",
    "document": "12345678901",
    "bankCode": "30306294",
    "branch": "0020",
    "account": "004912314"
  },
  "reconciled": true,
  "reconciledAt": "2026-02-05T22:10:25Z",
  "transactionId": "e094058f-de94-40a8-99a0-cdd5cb4cc832"
}

已退款（您已退回付款）

当您使用 POST /v1/accounts/{accountId}/pix/out/refund 退还收到的付款时，QR code 状态变为 refunded：

{
  "txid": "b091da7bba6a45d1a9f709daaba04e30",
  "identifier": "order-12345",
  "accountId": "6ff57bc1-e4a9-403b-be62-42378b8aafd7",
  "pixKey": "8026ff12-cb4a-4d19-9638-08bb15d450e2",
  "value": 150.75,
  "status": "refunded",
  "type": "dynamic",
  "createdAt": "2026-02-05T22:08:02Z",
  "paidAt": "2026-02-05T22:10:25.055",
  "paidAmount": 150.75,
  "endToEndId": "E303062942026020522100000005EXVX",
  "payer": {
    "name": "John Smith",
    "document": "12345678901"
  },
  "reconciled": true,
  "reconciledAt": "2026-02-05T22:10:25Z",
  "transactionId": "e094058f-de94-40a8-99a0-cdd5cb4cc832",
  "refundEndToEndId": "D303062942026020613020000005Ft76",
  "refundedAt": "2026-02-06T13:02:16Z",
  "refundAmount": 150.75,
  "refunds": [
    {
      "id": "refund-001",
      "amount": 150.75,
      "status": "DEVOLVIDO",
      "endToEndId": "D303062942026020613020000005Ft76",
      "requestedAt": "2026-02-06T13:02:00Z",
      "processedAt": "2026-02-06T13:02:16Z"
    }
  ],
  "totalRefundAmount": 150.75
}

已过期（收款已过期）

{
  "txid": "c1234567890abcdef1234567890abcde",
  "identifier": "order-99999",
  "accountId": "6ff57bc1-e4a9-403b-be62-42378b8aafd7",
  "pixKey": "8026ff12-cb4a-4d19-9638-08bb15d450e2",
  "value": 50.00,
  "status": "expired",
  "type": "dynamic",
  "createdAt": "2026-02-01T10:00:00Z",
  "expiresAt": "2026-02-01T10:30:00Z",
  "emv": "00020101021226790014br.gov.bcb.pix...",
  "reconciled": false
}

字段参考

字段	何时出现	描述
`txid`	始终	内部 QR code 交易 ID
`identifier`	始终	您的唯一收款标识符
`value`	始终	收款金额（BRL）
`status`	始终	当前状态（`active`、`paid`、`refunded`、`expired`、`cancelled`）
`type`	始终	QR code 类型（`dynamic` 或 `static`）
`emv`	始终	PIX 复制粘贴代码
`expiresAt`	始终	收款过期日期
`reconciled`	始终	是否已与账单交易关联
`paidAt`	已支付时	付款时间戳
`paidAmount`	已支付时	实际支付金额（BRL）
`endToEndId`	已支付时	PIX E2E 标识符（在 PIX 系统中唯一）
`payer`	已支付时	付款人信息（name、document、bankCode、branch、account）
`transactionId`	已对账时	用于账单查询的交易 ID
`refundEndToEndId`	已退款时	退款 E2E 标识符
`refundedAt`	已退款时	退款时间戳
`refundAmount`	已退款时	退款金额（BRL）
`refunds`	已退款时	退款详情数组（支持部分退款）
`totalRefundAmount`	已退款时	所有退款总额（BRL）

查询端点（高级搜索）

使用专用查询端点按 qrcodeId 或 endToEndId 搜索：

curl -X GET "https://api.corpxapi.com/v1/accounts/{accountId}/pix/qr-code/lookup?identifier=order-12345" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: {tenant_id}"

每次只能使用一个参数：?identifier=X、?qrcodeId=X 或 ?endToEndId=X。

第四步：接收付款 Webhook

当客户完成付款时，您会收到一个 pix.in.completed webhook，其中 method: QR_CODE_DYNAMIC：

{
  "event": "qrcode.paid",
  "timestamp": "2026-02-05T22:10:25Z",
  "tenantId": "tenant-yourcompany",
  "data": {
    "identifier": "order-12345",
    "txid": "b091da7bba6a45d1a9f709daaba04e30",
    "status": "PAID",
    "value": 150.75,
    "paidAmount": 150.75,
    "endToEndId": "E303062942026020522100000005EXVX",
    "payer": {
      "name": "John Smith",
      "document": "12345678901"
    }
  }
}

提示

通过 POST /v1/webhooks 配置 webhooks，事件类型为 qrcode.paid。参见 Webhooks 指南。

第五步：取消收款（可选）

在收款被支付之前取消待处理的收款：

curl -X DELETE "https://api.corpxapi.com/v1/accounts/{accountId}/pix/qr-code?identifier=order-12345" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: {tenant_id}"

第六步：列出所有 QR Code

列出账户的 QR code，可选择按状态筛选：

curl -X GET "https://api.corpxapi.com/v1/accounts/{accountId}/pix/qr-codes?status=PAID" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: {tenant_id}"

响应

{
  "items": [
    {
      "txid": "8ab8a37b2e274c8dae51128a379c909a",
      "identifier": "order-67890",
      "status": "paid",
      "value": 50.00,
      "paidAmount": 50.00,
      "endToEndId": "E303062942026020522130000005EYaT",
      "reconciled": true,
      "createdAt": "2026-02-05T22:09:32Z"
    }
  ],
  "count": 1
}

完整示例：电子商务集成

#!/bin/bash

# Configuration
API_URL="https://api.corpxapi.com"
TOKEN="your_token_here"
TENANT_ID="tenant-yourcompany"
ACCOUNT_ID="your-account-id"
PIX_KEY="your-pix-key"

# 1. Create charge for order
ORDER_ID="order-$(date +%s)"
AMOUNT=299.90
EXPIRATION=$(date -u -v+30M +"%Y-%m-%dT%H:%M:%SZ")  # 30 minutes

echo "Creating charge: $ORDER_ID for R\$$AMOUNT..."

response=$(curl -s -X POST "$API_URL/v1/accounts/$ACCOUNT_ID/pix/qr-code/dynamic" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $ORDER_ID" \
  -d "{
    \"pixKey\": \"$PIX_KEY\",
    \"value\": $AMOUNT,
    \"expirationDate\": \"$EXPIRATION\",
    \"identifier\": \"$ORDER_ID\",
    \"message\": \"Store Purchase - $ORDER_ID\",
  }")

# 2. Extract information
IDENTIFIER=$(echo $response | jq -r '.data.identifier')
PAYLOAD=$(echo $response | jq -r '.data.payload')

echo "Charge created!"
echo "ID: $IDENTIFIER"
echo "PIX Copy and Paste: $PAYLOAD"

# 3. Poll for payment (alternative to webhook)
while true; do
  sleep 10
  
  status_response=$(curl -s "$API_URL/v1/accounts/$ACCOUNT_ID/pix/qr-code?identifier=$IDENTIFIER" \
    -H "Authorization: Bearer $TOKEN" \
    -H "X-Tenant-Id: $TENANT_ID")
  
  current_status=$(echo $status_response | jq -r '.status')
  
  if [ "$current_status" = "paid" ]; then
    paid_amount=$(echo $status_response | jq -r '.paidAmount')
    e2e=$(echo $status_response | jq -r '.endToEndId')
    echo "Payment confirmed! Amount: R\$$paid_amount, E2E: $e2e"
    break
  elif [ "$current_status" = "expired" ]; then
    echo "Charge expired"
    break
  fi
  
  echo "Awaiting payment... Status: $current_status"
done

最佳实践

使用 Idempotency Key - 每笔收款始终发送唯一标识符以防止重复
设置合适的过期时间 - 结账页面设置 30 分钟，发票设置 24 小时
配置 webhooks - 不要仅依赖轮询，使用 qrcode.paid 事件
所有金额使用 BRL - 最多 2 位小数（例如 150.75 表示 R$150,75）
处理过期情况 - 当收款过期时通知客户
保存 identifier - 用于查询状态和对账

常见错误

错误	原因	解决方案
`400 - pixKey is required`	缺少 PIX 密钥	提供已注册的有效 PIX 密钥
`400 - value must be greater than zero`	无效金额	发送正数的 BRL 金额
`400 - value has too many decimal places`	超过 2 位小数	最多使用 2 位小数（例如 150.75）
`400 - identifier is required`	缺少标识符	提供唯一的收款标识符
`400 - expirationDate must be a valid RFC3339 timestamp`	无效日期	使用 RFC3339 格式（例如 `2026-02-10T15:30:00Z`）
`404 - QR code not found`	未找到收款	检查 identifier 和 accountId

后续步骤

Cash Out 指南 - 发起 PIX 转账
退款指南 - 撤销已收到的付款
Webhooks - 配置通知

概述​

集成流程​

第一步：创建收款（动态 QR Code）​

请求​

请求体参数​

重要请求头​

成功响应 (201 Created)​

第二步：显示 QR Code​

使用 PIX 复制粘贴​

第三步：查询收款状态​

请求​

可能的状态​

各状态的响应示例​

有效（等待付款）​

已支付（付款已确认）​

已退款（您已退回付款）​

已过期（收款已过期）​

字段参考​

查询端点（高级搜索）​

第四步：接收付款 Webhook​

第五步：取消收款（可选）​

第六步：列出所有 QR Code​

响应​

完整示例：电子商务集成​

最佳实践​

常见错误​

后续步骤​

概述