使用示例

本页提供了使用 cURL 与 CorpX API 交互的实用示例，按典型集成的逻辑顺序排列。

环境变量

运行示例前请先配置以下变量：

# OAuth Credentials (provided during onboarding)
export CLIENT_ID="your_client_id"
export CLIENT_SECRET="your_client_secret"

# Account identifiers
export TENANT_ID="your-tenant-uuid"
export ACCOUNT_ID="your-account-uuid"

# Environment URLs
export API_URL="https://api.corpxapi.com"
export AUTH_URL="https://auth.corpxapi.com"

1. 认证

第一步是使用您的客户端凭据获取 OAuth2 访问令牌。

curl -X POST "${AUTH_URL}/oauth2/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials" \
     -d "client_id=${CLIENT_ID}" \
     -d "client_secret=${CLIENT_SECRET}"

成功响应：

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

保存令牌以供后续调用使用：

export JWT="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

2. 查询余额

实时查看您账户的可用余额和冻结余额。

curl -X GET "${API_URL}/v1/accounts/${ACCOUNT_ID}/balance" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}"

响应：

{
  "accountId": "2e6b725b-84a0-400d-8740-22a5ba0f23e6",
  "total": 15000.00,
  "locked": 500.00,
  "available": 14500.00,
  "currency": "BRL",
  "updatedAt": "2024-01-15T10:30:00Z",
  "locks": [
    {
      "lockId": "lock-abc123",
      "amount": 500.00,
      "currency": "BRL",
      "reason": "MED investigation",
      "medId": "med-12345",
      "status": "active",
      "createdAt": "2024-01-10T14:00:00Z"
    }
  ]
}

3. 生成动态 QR Code（收款）

生成一个动态 QR Code 以接收指定金额的 PIX 收款。

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/qr-code/dynamic" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "pixKey": "contact@mycompany.com",
       "value": 150.00,
       "expirationDate": "2024-12-31T23:59:59Z",
       "allowChangeValue": false,
       "message": "Payment for order #12345",
       "identifier": "order-12345",
     }'

值	描述
`IMAGE`	返回 QR Code 的 Base64 图片
`EMV`	仅返回复制粘贴字符串

4. 生成静态 QR Code

静态 QR Code 不会过期，适合永久展示。

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/qr-code/static" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "pixKey": "contact@mycompany.com",
       "value": 50.00,
       "message": "Donation to project XYZ",
       "identifier": "doacao-xyz-001",
     }'

5. 查询 QR Code 状态

查看此前生成的 QR Code 是否已被支付或仍处于待支付状态。

curl -X GET "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/qr-code?identifier=order-12345" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}"

6. PIX Out（通过密钥转账）

通过第三方密钥发送 PIX（出账转账）。

需要在没有 PIX 密钥的情况下发送 PIX？ 如果您只有收款人的银行信息（ISPB、分行和账号），请使用专用端点 POST /v1/accounts/{accountId}/pix/out/bank-account。详情请参阅 v1.27.0 更新日志。

6.1 PIX 转账至 CPF

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/out" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "accountId": "'${ACCOUNT_ID}'",
       "amount": 150.00,
       "currency": "BRL",
       "keyType": "CPF",
       "key": "12345678900",
       "description": "Service payment",
       "identifier": "order-456"
     }'

6.2 PIX 转账至邮箱

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/out" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "accountId": "'${ACCOUNT_ID}'",
       "amount": 75.50,
       "currency": "BRL",
       "keyType": "EMAIL",
       "key": "supplier@company.com",
       "description": "Pagamento NF 789"
     }'

6.3 PIX 转账至手机号

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/out" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "accountId": "'${ACCOUNT_ID}'",
       "amount": 200.00,
       "currency": "BRL",
       "keyType": "PHONE",
       "key": "+5511999999999",
       "description": "Transfer"
     }'

6.4 PIX 转账至随机密钥（EVP）

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/out" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "accountId": "'${ACCOUNT_ID}'",
       "amount": 500.00,
       "currency": "BRL",
       "keyType": "EVP",
       "key": "123e4567-e89b-12d3-a456-426614174000",
       "description": "Pagamento de fornecedor"
     }'

keyType 的可选值：

值	描述	格式
`CPF`	收款方的 CPF	11 位数字（仅数字）
`CNPJ`	收款方的 CNPJ	14 位数字（仅数字）
`EMAIL`	收款方的邮箱	有效邮箱地址
`PHONE`	收款方的手机号	+55 + 区号 + 号码
`EVP`	随机密钥	UUID v4

成功响应：

{
  "transactionId": "txn-abc123-def456",
  "status": "APPROVED",
  "endToEndId": "E12345678202401151234abcdefghijkl",
  "amount": 150.00,
  "currency": "BRL"
}

status 的可选值：

值	描述
`APPROVED`	转账已批准并完成
`PENDING`	等待银行确认
`PROCESSING`	处理中
`REJECTED`	已拒绝（请查看错误信息）

6.5 查询转账状态

使用 E2E ID 查询转账状态：

curl -X GET "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/transactions?endToEndId=E12345678202401151234abcdefghijkl" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}"

响应：

{
  "transactionId": "txn-abc123-def456",
  "endToEndId": "E12345678202401151234abcdefghijkl",
  "status": "COMPLETED",
  "type": "CASH_OUT",
  "amount": -150.00,
  "currency": "BRL",
  "description": "PIX - MARIA DA SILVA",
  "transactionDate": "2024-01-15T12:34:00Z",
  "counterparty": {
    "name": "MARIA DA SILVA",
    "document": "123***01",
    "bankCode": "001"
  },
  "balance": 14350.00
}

查询参数：

参数	描述
`accountId`	账户 ID（必填）
`endToEndId`	交易 E2E ID
`identifier`	收费或参考标识符

注意：endToEndId 或 identifier 参数至少需要提供一个。

7. 支付 QR Code（通过 EMV 进行 PIX Out）

使用 EMV 字符串（复制粘贴）支付 PIX QR Code。

7.1 支付动态 QR Code（预设金额）

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/out/qr-code" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "accountId": "'${ACCOUNT_ID}'",
       "emv": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000520400005303986540510.005802BR5913Loja Exemplo6008Sao Paulo62070503***6304ABCD",
       "description": "Pagamento de compra online"
     }'

7.2 支付静态 QR Code（指定金额）

对于未预设金额的静态 QR Code，amount 字段为必填：

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/out/qr-code" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "accountId": "'${ACCOUNT_ID}'",
       "emv": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000520400005303986540010.005802BR5913Loja Exemplo6008Sao Paulo62070503***6304EFGH",
       "amount": 150.00,
       "description": "Service payment"
     }'

成功响应：

{
  "transactionId": "txn-qr-abc123",
  "status": "APPROVED",
  "endToEndId": "E12345678202401151234mnopqrstuvwx",
  "amount": 150.00,
  "currency": "BRL"
}

8. 申请退款

对此前收到的 PIX 进行退款（全额或部分）。

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/out/refund" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "accountId": "'${ACCOUNT_ID}'",
       "originalEndToEnd": "E12345678202401101234abcdefghijkl",
       "amount": 150.00,
       "currency": "BRL",
       "reason": "Product not available in stock"
     }'

响应：

{
  "refundId": "ref-abc123-def456",
  "status": "PROCESSING",
  "amount": 150.00,
  "currency": "BRL"
}

退款 status 的可选值：

值	描述
`PROCESSING`	退款处理中
`COMPLETED`	退款已成功完成
`REJECTED`	退款被拒绝

9. 查询最近交易（对账单）

获取账户的最近交易记录。

curl -X GET "${API_URL}/v1/accounts/${ACCOUNT_ID}/statement?limit=10&order=desc" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}"

查询参数：

参数	类型	描述
`page`	integer	页码索引（从 0 开始）
`size`	integer	每页大小（最大 500）
`startDate`	datetime	起始日期过滤（ISO 8601）
`endDate`	datetime	结束日期过滤（ISO 8601）
`limit`	integer	总记录数限制（最大 1000）
`order`	string	排序方式：`asc` 或 `desc`

10. 管理 PIX 密钥

10.1 查询 PIX 密钥列表

curl -X GET "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/keys" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}"

10.2 注册新 PIX 密钥

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/keys" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "keyType": "email",
       "pixKey": "financeiro@minhaempresa.com.br"
     }'

注册时 keyType 的可选值：

值	描述
`cpf`	账户持有人的 CPF
`cnpj`	账户持有人的 CNPJ
`phone`	手机号（+5511999999999）
`email`	邮箱地址
`random`	随机密钥（EVP）- 由系统自动生成

10.3 注册随机密钥（EVP）

注册随机密钥时，省略 pixKey 字段：

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/keys" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "keyType": "random"
     }'

10.4 删除 PIX 密钥

curl -X DELETE "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/keys/contact%40mycompany.com" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}"

11. 查询 MED（特别退回机制）

查询通过 MED 发起的违规与争议。

curl -X GET "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/med?status=OPEN&limit=20" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}"

过滤参数：

参数	可选值	描述
`status`	`OPEN`、`IN_PROGRESS`、`CLOSED`、`CANCELED`	MED 状态
`responseStatus`	`PENDING`、`AGREED`、`DISAGREED`	响应状态
`minAmount`	number	最小金额
`maxAmount`	number	最大金额
`from`	datetime	起始日期
`to`	datetime	结束日期
`limit`	integer	结果数量限制
`cursor`	string	分页游标

11.1 响应 MED

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/med/med-12345/response" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Content-Type: application/json" \
     -d '{
       "answer": "DISCORDO",
       "message": "Legitimate transaction as per attached receipts",
       "evidences": [
         {
           "order": 1,
           "description": "Comprovante de entrega",
           "url": "https://storage.exemplo.com/evidencia1.pdf"
         }
       ]
     }'

answer 的可选值：

值	描述
`CONCORDO`	同意所请求的退款
`DISCORDO`	对退款请求提出异议

12. 内部转账

在同一银行内的账户之间转账（免费、即时）。

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/transfers/internal" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "branch": "0001",
       "account": "123456-7",
       "taxNumber": "12345678900",
       "value": 500.00,
       "message": "Transfer between accounts",
       "identifier": "transf-int-12345"
     }'

常见错误处理

余额不足

{
  "errorCode": "insufficient_balance",
  "message": "insufficient available balance: 50.00 (total: 100.00, locked: 50.00, requested: 150.00)"
}

无效的 PIX 密钥

{
  "errorCode": "invalid_payload",
  "message": "keyType must be one of: CPF, CNPJ, EMAIL, PHONE, EVP"
}

幂等性冲突

{
  "errorCode": "idempotency_conflict",
  "message": "Request with same Idempotency-Key but different payload"
}

最佳实践

始终使用 Idempotency-Key —— 在 POST/PUT/PATCH 操作中使用以避免重复
保存 endToEndId —— 用于交易跟踪和退款
实现指数退避重试 —— 针对 5xx 错误
提前验证余额 —— 在出账操作前验证以提升用户体验
配置 webhooks —— 以接收实时通知

更多关于各端点的详细信息，请参阅 API 参考文档或集成指南。

环境变量​

1. 认证​

2. 查询余额​

3. 生成动态 QR Code（收款）​

4. 生成静态 QR Code​

5. 查询 QR Code 状态​

6. PIX Out（通过密钥转账）​

6.1 PIX 转账至 CPF​

6.2 PIX 转账至邮箱​

6.3 PIX 转账至手机号​

6.4 PIX 转账至随机密钥（EVP）​

6.5 查询转账状态​

7. 支付 QR Code（通过 EMV 进行 PIX Out）​

7.1 支付动态 QR Code（预设金额）​

7.2 支付静态 QR Code（指定金额）​

8. 申请退款​

9. 查询最近交易（对账单）​

10. 管理 PIX 密钥​

10.1 查询 PIX 密钥列表​

10.2 注册新 PIX 密钥​

10.3 注册随机密钥（EVP）​

10.4 删除 PIX 密钥​

11. 查询 MED（特别退回机制）​

11.1 响应 MED​

12. 内部转账​

常见错误处理​

余额不足​

无效的 PIX 密钥​

幂等性冲突​

最佳实践​

环境变量

1. 认证

2. 查询余额

3. 生成动态 QR Code（收款）

4. 生成静态 QR Code

5. 查询 QR Code 状态

6. PIX Out（通过密钥转账）

6.1 PIX 转账至 CPF

6.2 PIX 转账至邮箱

6.3 PIX 转账至手机号

6.4 PIX 转账至随机密钥（EVP）

6.5 查询转账状态

7. 支付 QR Code（通过 EMV 进行 PIX Out）

7.1 支付动态 QR Code（预设金额）

7.2 支付静态 QR Code（指定金额）

8. 申请退款

9. 查询最近交易（对账单）

10. 管理 PIX 密钥

10.1 查询 PIX 密钥列表

10.2 注册新 PIX 密钥

10.3 注册随机密钥（EVP）

10.4 删除 PIX 密钥

11. 查询 MED（特别退回机制）

11.1 响应 MED

12. 内部转账

常见错误处理

余额不足

无效的 PIX 密钥

幂等性冲突

最佳实践