docs
接口端点

PIX 转账

概述

POST /api/dict/pix 端点向指定密钥发起 PIX 转账。密钥可以是 CPF、CNPJ、电子邮件、电话或 EVP（随机密钥）。

同步响应仅确认转账已被接受处理。最终结果（LIQUIDATED 或 ERROR）通过 TRANSFER Webhook 送达。

端点

POST https://api.fypay.me/api/dict/pix

请求头

stringobrigatorio

通过 POST https://api.fypay.me/api/auth/token 获取的 Bearer 令牌。此路由不使用客户端证书。

stringobrigatorio

由您的系统生成的转账唯一标识符。最多 50 个字符，且在账户内唯一（UUID 是不错的选择）。它会成为交易的外部标识符，并在响应的 endToEndId 字段和 TRANSFER Webhook 的 idempotencyKey 字段中返回。

示例：550e8400-e29b-41d4-a716-446655440000

请求体

stringobrigatorio

目标 PIX 密钥。类型根据格式识别：

  • 电子邮件：包含 @
  • EVP：UUID（随机密钥）
  • 电话：带国家代码，格式为 +55DDDNUMERO（例如 +5511999999999）
  • CPF：11 位数字
  • CNPJ：14 位数字
string

收款人的 CPF 或 CNPJ。会转发给结算提供商，部分提供商要求提供该证件号。省略时，API 使用密钥本身中的数字。

string

随 PIX 转账附带的信息。会在 TRANSFER Webhook 的 data.remittanceInformation 中返回。

objectobrigatorio

付款数据。

string

HIGH 或 NORM。为兼容而接受并校验，但不影响处理。

string

为兼容而接受，没有效果。

number

介于 1 和 10800 之间。为兼容而接受并校验，但不影响处理。

array

字符串列表。为兼容而接受，没有效果：API 不会按 ISPB 屏蔽机构。

请求

curl -X POST https://api.fypay.me/api/dict/pix \
  -H "Authorization: Bearer <token>" \
  -H "x-idempotency-key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "pixKey": "destino@email.com",
    "creditorDocument": "12345678909",
    "description": "Pagamento referente a NF 12345",
    "payment": {
      "currency": "BRL",
      "amount": 100.50
    }
  }'
const idempotencyKey = crypto.randomUUID();

const response = await fetch('https://api.fypay.me/api/dict/pix', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'x-idempotency-key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    pixKey: 'destino@email.com',
    creditorDocument: '12345678909',
    description: 'Pagamento referente a NF 12345',
    payment: {
      currency: 'BRL',
      amount: 100.50,
    },
  }),
});

const transfer = await response.json();
import requests
import uuid

idempotency_key = str(uuid.uuid4())

response = requests.post(
    'https://api.fypay.me/api/dict/pix',
    headers={
        'Authorization': f'Bearer {token}',
        'x-idempotency-key': idempotency_key,
        'Content-Type': 'application/json',
    },
    json={
        'pixKey': 'destino@email.com',
        'creditorDocument': '12345678909',
        'description': 'Pagamento referente a NF 12345',
        'payment': {
            'currency': 'BRL',
            'amount': 100.50,
        },
    }
)

transfer = response.json()

响应

{
  "endToEndId": "550e8400-e29b-41d4-a716-446655440000",
  "eventDate": "2024-01-15T10:30:00.000Z",
  "id": 12345,
  "payment": {
    "amount": 100.5
  },
  "type": "PENDING"
}
{
  "statusCode": 400,
  "code": "PIX_INSUFFICIENT_BALANCE",
  "userMessage": "Saldo insuficiente para realizar esta operação.",
  "details": {
    "availableReais": "50.00",
    "requiredReais": "100.50"
  },
  "errorId": "c0a8012e-7b1f-4c55-9d1e-2f9a8c3b4d5e"
}
{
  "statusCode": 422,
  "code": "PIX_KEY_NOT_FOUND",
  "details": {
    "cached": true,
    "retryAfterSeconds": 300
  },
  "errorId": "c0a8012e-7b1f-4c55-9d1e-2f9a8c3b4d5e"
}

响应字段

endToEndIdstring

这不是 PIX 的 End to End ID。 此字段返回的是 x-idempotency-key 请求头的值。真正的 End to End ID 会在 TRANSFER Webhook 的 data.endToEndId 中返回。

eventDatestring

转账创建的日期和时间（ISO 8601）。

idnumber

FyPay 中的交易 ID。与 TRANSFER Webhook 中的 data.id 值相同。

paymentobject

typestring

响应时的交易状态：

  • PENDING：转账处理中（正常情况）
  • CONFIRMED：转账已确认
  • ERROR：转账失败

幂等性

x-idempotency-key 是必填项，且必须在账户内唯一。它可防止重复发送：如果您重复使用已用过的密钥，不会创建新的转账，API 返回 400，错误码为 PIX_DUPLICATE_EXTERNAL_ID。details.existingTransactionId 字段包含原始转账的 ID。

const key = '550e8400-e29b-41d4-a716-446655440000';

const res1 = await createTransfer(key, { amount: 100 });

const res2 = await createTransfer(key, { amount: 100 });

第一次调用创建转账（201，type: "PENDING"）。第二次被以 400 PIX_DUPLICATE_EXTERNAL_ID 拒绝，不会扣款。要跟踪第一次的结果，请等待 TRANSFER Webhook，或使用数字 id 或该密钥本身查询 GET https://api.fypay.me/api/pix/transaction/{id}。

出现 5xx 错误或超时后，不要更换密钥重试：付款可能已经发出。请等待 TRANSFER Webhook，并通过 data.idempotencyKey 进行关联。参见 TRANSFER。

转账 Webhook

转账处理完成后，在 cash_out 事件下以 PIX BACEN 格式登记的 URL 会收到 TRANSFER 类型的 Webhook（节选）：

{
  "data": {
    "id": 12345,
    "txId": "550e8400-e29b-41d4-a716-446655440000",
    "pixKey": "destino@email.com",
    "status": "LIQUIDATED",
    "payment": {
      "amount": "100.5",
      "currency": "BRL"
    },
    "endToEndId": "E12345678202401151030abcdefghijk",
    "creditDebitType": "DEBIT",
    "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
    "creditorAccount": {
      "ispb": "12345678",
      "name": "João Silva",
      "bankName": "Banco Exemplo S.A.",
      "issuer": "000",
      "number": "123456",
      "document": "12345678909",
      "accountType": null
    },
    "remittanceInformation": "Pagamento referente a NF 12345"
  },
  "type": "TRANSFER"
}

TRANSFER Webhook

查看 TRANSFER Webhook 的完整文档

常见错误

HTTP 状态码code原因处理方式
400PUB_REQUEST_BODY_INVALID请求体无效（amount 缺失或小于 0.01、priority 不是 HIGH/NORM 等）查看 details.violations
400PIX_DUPLICATE_EXTERNAL_ID该账户已使用过此 x-idempotency-key未创建任何转账；查看 details.existingTransactionId
400PIX_INSUFFICIENT_BALANCE余额不足查询余额后使用新的密钥重试
401令牌缺失、无效或已过期生成新令牌
422PIX_KEY_NOT_FOUND密钥在 DICT 中不存在与收款人确认密钥。若 details.cached: true，请等待 details.retryAfterSeconds。参见密钥不存在
429TOO_MANY_PIX_KEYS_NOT_FOUND按密钥提款时不存在的密钥过多等待 Retry-After 请求头指定的时间。参见提供商正在封锁查询

下一步

查询余额

查看可用余额

TRANSFER Webhook

处理转账通知

申请退款

按照巴西央行 Pix API 格式申请退还已收到的 PIX

查询余额

以 BACEN 格式查询已认证账户的余额

本页目录

概述端点请求头请求体请求响应响应字段幂等性转账 Webhook常见错误下一步