docs

发起 PIX 付款（Cash-Out）

POST /api/pix/cash-out

POST https://api.fypay.me/api/pix/cash-out

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

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

认证

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

请求体

字段类型必填描述
valuenumber是金额（巴西雷亚尔，最多 2 位小数）。最小值：0.01
externalIdstring是每个账户唯一的外部标识符（最多 50 个字符）
descriptionstring否交易描述（最多 140 个字符）
detailsobject是目标 PIX 密钥信息
details.keystring是目标 PIX 密钥（格式见下表）
details.keyTypestring是密钥类型：DOCUMENT、EMAIL、PHONE、RANDOM。必填，因为 API 不会查询 DICT
details.namestring否密钥持有人姓名（最多 100 个字符）。部分清算机构要求提供：建议始终发送
details.documentstring否密钥持有人的有效 CPF（11 位数字）或 CNPJ（14 位数字），仅数字。部分清算机构要求提供：建议始终发送。API 仅校验格式；参见按清算机构划分的持有人核验
details.checkPixKeyWithDocumentboolean否为 true 时，要求核验密钥是否属于 details.document 中的 CPF/CNPJ，不一致则拒绝付款。必须同时提供 details.document（否则 API 返回 400）。仅在支持该核验的清算机构上生效。默认：false

details.key 的格式要求

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

付款始终按 PIX 密钥（details.key）寻址。 FyPay API 会校验 details.document 的格式，但在发送前不会将其与 details.key 比对，也不会查询 DICT。与密钥真实持有人的比对取决于您账户的清算机构（部分清算机构还取决于 details.checkPixKeyWithDocument）。未进行该核验时，不一致的 details.document 不会拦截付款：资金将进入密钥持有人账户。参见按清算机构划分的持有人核验。

请求示例

通过 CPF 付款 -- 最常见的场景。details.key 和 details.document 必须相同（都是 CPF）。API 不会核验二者是否相同：请在发送前在您这一侧确保一致。

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

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

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

通过电子邮件密钥付款。请注意，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": "11122233396"
  }
}

通过随机密钥（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": "55666777000181"
  }
}

按清算机构划分的持有人核验

FyPay API 仅校验 details.document 的格式（11 或 14 位数字及校验位），并按 keyType 校验 details.key 的格式。API 不会将 details.document 与 details.key 比对，不会查询 DICT，两者不一致时也不会拦截操作。 付款始终按 PIX 密钥寻址。

如需将证件号与密钥真实持有人比对，该核验由您账户配置的清算机构执行：

  • 部分清算机构只要收到该字段就会核验 details.document。不一致时，交易以 ERROR 结束，不扣款，webhook 会携带清算机构的消息。
  • 部分清算机构仅在您发送 details.checkPixKeyWithDocument: true 时才核验。
  • 其余清算机构接受该字段但不核验：付款将进入密钥持有人账户。

如何了解我的账户的行为？ 清算机构按账户配置。如有疑问，请咨询您的集成经理。如果您的业务要求证件号不一致时必须拦截付款，请在发送前自行核验持有人：对于 keyType: DOCUMENT，确保 details.document 与 details.key 相同。

代码示例

cURL
curl -X POST "https://api.fypay.me/api/pix/cash-out" \
  -H "Authorization: Bearer $FYPAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "value": 150.00,
  "externalId": "PAG-2024-0001",
  "description": "Pagamento freelancer - Janeiro/2024",
  "details": {
    "key": "12345678909",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678909"
  }
}'
const axios = require('axios');

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

response = requests.post(
    'https://api.fypay.me/api/pix/cash-out',
    headers={
        'Authorization': f'Bearer {os.environ["FYPAY_TOKEN"]}',
        'Content-Type': 'application/json',
    },
    json={
  "value": 150.00,
  "externalId": "PAG-2024-0001",
  "description": "Pagamento freelancer - Janeiro/2024",
  "details": {
    "key": "12345678909",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678909"
  }
},
)
print(response.json())
$ch = curl_init('https://api.fypay.me/api/pix/cash-out');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('FYPAY_TOKEN'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{
  "value": 150.00,
  "externalId": "PAG-2024-0001",
  "description": "Pagamento freelancer - Janeiro/2024",
  "details": {
    "key": "12345678909",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678909"
  }
}',
]);
$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": "12345678909",
        "keyType": "DOCUMENT",
        "name": "Ana Costa",
        "document": "12345678909"
      }
    }
    """;
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.fypay.me/api/pix/cash-out"))
    .header("Authorization", "Bearer " + System.getenv("FYPAY_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生成的交易内部标识符（数字字符串）
externalIdstring请求中提供的外部标识符
statusstring初始状态：PENDING。通过 webhook 确认：CONFIRMED 或 ERROR
generateTimestring交易生成日期/时间（ISO 8601 UTC）
{
  "transactionId": "466208",
  "externalId": "PAG-2024-0001",
  "status": "PENDING",
  "generateTime": "2024-01-15T10:30:00.000Z"
}

错误

当请求体未通过验证时返回。顶层字段（value、externalId、description、details 或未知字段）的错误返回 code: PUB_REQUEST_BODY_INVALID，出错字段列在 details.violations 中，如示例所示。details.* 字段的错误以列表形式返回在 message 中，每个字段一条消息。

{
  "statusCode": 400,
  "timestamp": "2026-04-10T15:30:34.560Z",
  "path": "/api/pix/cash-out",
  "method": "POST",
  "code": "PUB_REQUEST_BODY_INVALID",
  "message": "Request body validation failed: value: value must not be less than 0.01",
  "userMessage": "Request body is invalid.",
  "errorId": "a1b2c3d4e5f6789012345678abcdef01",
  "details": {
    "violations": {
      "value": "value must not be less than 0.01"
    }
  }
}

常见原因：

  • value 小于 0.01 或超过 2 位小数
  • details.keyType 值无效
  • details.key 与 keyType 的格式不匹配
  • details.document 的 CPF/CNPJ 无效
  • externalId 超过 50 个字符或 description 超过 140 个字符
  • details.checkPixKeyWithDocument: true 但未提供 details.document

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

{
  "statusCode": 400,
  "timestamp": "2026-04-10T15:30:34.560Z",
  "path": "/api/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": "/api/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 字段可用于查找原始交易。

当响应来自被拒密钥的记录时，API 返回 422，不创建任何交易，并包含 Retry-After 响应头。只有响应来自该记录时才会出现 details.cached: true。没有该字段时，PIX_KEY_NOT_FOUND 来自提供商在本次调用中的响应。参见 Pix 密钥出金保护机制。

{
  "statusCode": 422,
  "timestamp": "2026-04-10T15:30:34.560Z",
  "path": "/api/pix/cash-out",
  "method": "POST",
  "code": "PIX_KEY_NOT_FOUND",
  "message": "Chave Pix não encontrada",
  "userMessage": "Chave Pix não encontrada",
  "errorId": "d4e5f6a7b8c9012345678909abcdef03",
  "errorCode": "PIX_KEY_NOT_FOUND",
  "details": {
    "retryAfterSeconds": 900,
    "source": "provider-guard",
    "cached": true
  }
}

提供商正在封锁查询。API 返回 429，不创建任何交易，并包含 Retry-After 响应头。请等待指定的时间后重新发送。参见 Pix 密钥出金保护机制。

{
  "statusCode": 429,
  "timestamp": "2026-04-10T15:30:34.560Z",
  "path": "/api/pix/cash-out",
  "method": "POST",
  "code": "TOO_MANY_PIX_KEYS_NOT_FOUND",
  "message": "Muitas tentativas com chaves Pix inexistentes. Saque por chave bloqueado temporariamente; tente novamente em instantes.",
  "userMessage": "Muitas tentativas com chaves Pix inexistentes. Saque por chave bloqueado temporariamente; tente novamente em instantes.",
  "errorId": "e5f6a7b8c9d0123456789092abcdef04",
  "errorCode": "TOO_MANY_PIX_KEYS_NOT_FOUND",
  "details": {
    "retryAfterSeconds": 60,
    "source": "provider-guard"
  }
}

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

errorCode描述可重试？
TAX_ID_MISMATCHdetails.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": "12345678909",
  "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": "12345678909",
    "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-In）

生成 PIX 收款以接收付款。

通过二维码发送 PIX 付款（Cash-Out QR Code）

通过读取二维码发送 PIX 付款。

本页目录

POST /api/pix/cash-out认证请求体details.key 的格式要求请求示例按清算机构划分的持有人核验代码示例响应 (201 Created)错误