PIX Cash-Out（付款）

Authorization: Bearer {token}
Content-Type: application/json

{
  "value": 250.50,
  "details": {
    "key": "12345678901",
    "keyType": "DOCUMENT",
    "name": "Ana Costa",
    "document": "12345678901"
  },
  "externalId": "PAYMENT-987654-20240119",
  "description": "供应商付款"
}

curl -X POST https://api.fypay.me/api/pix/cash-out \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "value": 250.50,
    "details": {
      "key": "12345678901",
      "keyType": "DOCUMENT",
      "name": "Ana Costa",
      "document": "12345678901"
    },
    "externalId": "PAYMENT-987654-20240119",
    "description": "供应商付款"
  }'

{
  "transactionId": "9876",
  "externalId": "PAYMENT-987654-20240119",
  "status": "PENDING",
  "generateTime": "2024-01-19T15:45:00.000Z"
}

import axios from 'axios';

interface CashOutRequest {
  value: number;
  details: {
    key: string;
    keyType: 'DOCUMENT' | 'EMAIL' | 'PHONE' | 'RANDOM';
    name: string;
    document: string;
  };
  externalId: string;
  description?: string;
}

interface CashOutResponse {
  transactionId: string;
  externalId: string;
  status: 'PENDING' | 'CONFIRMED' | 'ERROR';
  generateTime: string;
}

async function sendPixPayment(
  token: string,
  recipientKey: string,
  recipientKeyType: 'DOCUMENT' | 'EMAIL' | 'PHONE' | 'RANDOM',
  recipientName: string,
  recipientDocument: string,
  amount: number,
  description?: string
): Promise<CashOutResponse> {
  const payload: CashOutRequest = {
    value: amount,
    details: {
      key: recipientKey,
      keyType: recipientKeyType,
      name: recipientName,
      document: recipientDocument
    },
    externalId: `PAY-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
    description: description || `PIX 付款 R$ ${amount.toFixed(2)}`
  };

  try {
    const response = await axios.post<CashOutResponse>(
      'https://api.fypay.me/api/pix/cash-out',
      payload,
      {
        headers: {
          'Authorization': `Bearer ${token}`,
          'Content-Type': 'application/json'
        }
      }
    );

    console.log('PIX 付款已成功发起！');
    console.log(`交易 ID：${response.data.transactionId}`);
    console.log(`状态：${response.data.status}`);
    console.log(`金额：R$ ${amount.toFixed(2)}`);
    console.log(`收款方：${recipientName}`);

    return response.data;
  } catch (error) {
    if (axios.isAxiosError(error)) {
      const errorData = error.response?.data;
      console.error('付款出错：', errorData);

      // 处理特定错误
      if (error.response?.status === 400) {
        if (errorData?.code === 'PIX_INSUFFICIENT_BALANCE') {
          throw new Error('余额不足，无法完成付款');
        }
        throw new Error('数据无效：' + errorData?.message);
      }

      if (error.response?.status === 422 || error.response?.status === 429) {
        // 密钥出金保护机制：参见 /zh/docs/guides/pix-cash-out-protections
        const retryAfter = error.response.headers['retry-after'];
        throw new Error(`${errorData?.code}：请在 ${retryAfter ?? '?'} 秒后重试`);
      }

      throw new Error(errorData?.message || 'PIX 付款出错');
    }
    throw error;
  }
}

// 用法 - 通过 CPF 付款
sendPixPayment(
  'your_token_here',
  '12345678901',
  'DOCUMENT',
  'Ana Costa',
  '12345678901',
  250.50,
  '供应商付款'
);

// 用法 - 通过邮箱付款
sendPixPayment(
  'your_token_here',
  'ana.costa@email.com',
  'EMAIL',
  'Ana Costa',
  '12345678901',
  100.00,
  '退款'
);

// 用法 - 通过电话付款（区号 + 号码，不含国家代码 +55）
sendPixPayment(
  'your_token_here',
  '11999999999',
  'PHONE',
  'Ana Costa',
  '12345678901',
  50.00
);

import requests
from datetime import datetime
from typing import Dict, Optional
import uuid

def send_pix_payment(
    token: str,
    recipient_key: str,
    recipient_key_type: str,
    recipient_name: str,
    recipient_document: str,
    amount: float,
    description: Optional[str] = None
) -> Dict:
    """
    发送 PIX 付款

    Args:
        token: 有效的 Bearer token
        recipient_key: 收款方的 PIX 密钥
        recipient_key_type: 密钥类型（DOCUMENT、EMAIL、PHONE、RANDOM）
        recipient_name: 收款方姓名
        recipient_document: 收款方的 CPF 或 CNPJ
        amount: 金额（雷亚尔）
        description: 付款描述（可选）

    Returns:
        已发起付款的数据
    """
    url = 'https://api.fypay.me/api/pix/cash-out'

    payload = {
        'value': round(amount, 2),
        'details': {
            'key': recipient_key,
            'keyType': recipient_key_type,
            'name': recipient_name,
            'document': recipient_document
        },
        'externalId': f'PAY-{int(datetime.now().timestamp())}-{uuid.uuid4().hex[:8]}',
        'description': description or f'PIX 付款 R$ {amount:.2f}'
    }

    headers = {
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    }

    try:
        response = requests.post(url, json=payload, headers=headers)
        response.raise_for_status()

        data = response.json()

        print('PIX 付款已成功发起！')
        print(f"交易 ID：{data['transactionId']}")
        print(f"状态：{data['status']}")
        print(f"金额：R$ {amount:.2f}")
        print(f"收款方：{recipient_name}")

        return data

    except requests.exceptions.HTTPError as e:
        error_data = e.response.json() if e.response else {}

        # 处理特定错误
        if e.response.status_code == 400:
            if error_data.get('code') == 'PIX_INSUFFICIENT_BALANCE':
                raise Exception('余额不足，无法完成付款')
            raise Exception(f"数据无效：{error_data.get('message')}")

        raise Exception(f"付款出错：{error_data.get('message', str(e))}")

# 用法
token = 'your_token_here'

# 通过 CPF 付款
payment = send_pix_payment(
    token=token,
    recipient_key='12345678901',
    recipient_key_type='DOCUMENT',
    recipient_name='Ana Costa',
    recipient_document='12345678901',
    amount=250.50,
    description='供应商付款'
)

<?php

function sendPixPayment(
    string $token,
    string $recipientKey,
    string $recipientKeyType,
    string $recipientName,
    string $recipientDocument,
    float $amount,
    ?string $description = null
): array {
    $url = 'https://api.fypay.me/api/pix/cash-out';

    $payload = [
        'value' => round($amount, 2),
        'details' => [
            'key' => $recipientKey,
            'keyType' => $recipientKeyType,
            'name' => $recipientName,
            'document' => $recipientDocument
        ],
        'externalId' => 'PAY-' . time() . '-' . bin2hex(random_bytes(4)),
        'description' => $description ?? "PIX 付款 R$ " . number_format($amount, 2, ',', '.')
    ];

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $token,
        'Content-Type: application/json'
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 201) {
        $errorData = json_decode($response, true);
        $errorMessage = $errorData['message'] ?? "HTTP $httpCode";

        if ($httpCode === 400 && ($errorData['code'] ?? '') === 'PIX_INSUFFICIENT_BALANCE') {
            throw new Exception('余额不足，无法完成付款');
        }

        throw new Exception("付款出错：$errorMessage");
    }

    $data = json_decode($response, true);

    echo "PIX 付款已成功发起！" . PHP_EOL;
    echo "交易 ID：{$data['transactionId']}" . PHP_EOL;
    echo "状态：{$data['status']}" . PHP_EOL;
    echo "金额：R$ " . number_format($amount, 2, ',', '.') . PHP_EOL;
    echo "收款方：$recipientName" . PHP_EOL;

    return $data;
}

// 用法
$token = 'your_token_here';
$payment = sendPixPayment(
    $token,
    '12345678901',
    'DOCUMENT',
    'Ana Costa',
    '12345678901',
    250.50,
    '供应商付款'
);

class PayrollProcessor {
  constructor(private token: string) {}

  async processPayroll(employees: Employee[]) {
    const results = {
      successful: [],
      failed: []
    };

    for (const employee of employees) {
      try {
        // 每笔付款前检查余额
        const balance = await getBalance(this.token);

        if (balance.netBalance < employee.salary) {
          throw new Error('余额不足');
        }

        // 执行付款
        const payment = await sendPixPayment(
          this.token,
          employee.pixKey,
          employee.pixKeyType,
          employee.fullName,
          employee.document,
          employee.salary,
          `工资 ${new Date().toLocaleDateString('pt-BR', { month: 'long', year: 'numeric' })}`
        );

        results.successful.push({
          employee: employee.fullName,
          amount: employee.salary,
          transactionId: payment.transactionId
        });

        // 每笔付款之间等待 1 秒
        await this.sleep(1000);

      } catch (error) {
        results.failed.push({
          employee: employee.fullName,
          error: error.message
        });
      }
    }

    return results;
  }

  private sleep(ms: number): Promise<void> {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
}

// 用法
interface Employee {
  fullName: string;
  document: string;
  pixKey: string;
  pixKeyType: 'DOCUMENT' | 'EMAIL' | 'PHONE' | 'RANDOM';
  salary: number;
}

const payroll = new PayrollProcessor('your_token_here');
const employees: Employee[] = [
  {
    fullName: 'Pedro Santos',
    document: '12345678901',
    pixKey: '12345678901',
    pixKeyType: 'DOCUMENT',
    salary: 3500.00
  },
  // ... 更多员工
];

const results = await payroll.processPayroll(employees);
console.log(`成功付款：${results.successful.length}`);
console.log(`失败付款：${results.failed.length}`);

class MarketplacePayouts:
    """处理电商平台向卖家的分账"""

    def __init__(self, token: str):
        self.token = token

    def process_seller_payouts(self, sales_data: list) -> dict:
        """根据销售额处理分账"""
        results = {'successful': [], 'failed': []}

        # 按卖家汇总销售额
        seller_totals = self.group_sales_by_seller(sales_data)

        for seller_id, total_amount in seller_totals.items():
            try:
                # 获取卖家数据
                seller = self.get_seller_data(seller_id)

                # 计算扣除佣金后的金额
                commission = total_amount * 0.10  # 10% 佣金
                payout_amount = total_amount - commission

                # 执行付款
                payment = send_pix_payment(
                    token=self.token,
                    recipient_key=seller['pix_key'],
                    recipient_key_type=seller['pix_key_type'],
                    recipient_name=seller['name'],
                    recipient_document=seller['document'],
                    amount=payout_amount,
                    description=f'销售分账 - {len(sales_data)} 笔交易'
                )

                results['successful'].append({
                    'seller': seller['name'],
                    'gross_amount': total_amount,
                    'commission': commission,
                    'net_amount': payout_amount,
                    'transaction_id': payment['transactionId']
                })

                # 在数据库中记录分账
                self.record_payout(seller_id, payment)

            except Exception as e:
                results['failed'].append({
                    'seller_id': seller_id,
                    'error': str(e)
                })

        return results

    def group_sales_by_seller(self, sales_data: list) -> dict:
        """按卖家汇总销售额"""
        totals = {}
        for sale in sales_data:
            seller_id = sale['seller_id']
            totals[seller_id] = totals.get(seller_id, 0) + sale['amount']
        return totals

class RefundSystem {
  constructor(token) {
    this.token = token;
  }

  async processRefund(orderId, refundReason) {
    // 获取订单数据
    const order = await this.getOrderData(orderId);

    // 验证是否允许退款
    if (!this.canRefund(order)) {
      throw new Error('该订单不允许退款');
    }

    // 将款项付回给客户
    const refund = await sendPixPayment(
      this.token,
      order.customer.pixKey,
      order.customer.pixKeyType,
      order.customer.name,
      order.customer.document,
      order.amount,
      `退款 - 订单 ${orderId} - ${refundReason}`
    );

    // 更新订单状态
    await this.updateOrderStatus(orderId, 'REFUNDED', refund.transactionId);

    // 向客户发送通知
    await this.notifyCustomer(order.customer.email, refund);

    return refund;
  }

  canRefund(order) {
    // 检查订单是否已付款且仍在期限内
    const daysSincePurchase = (Date.now() - new Date(order.paidAt)) / (1000 * 60 * 60 * 24);
    return order.status === 'PAID' && daysSincePurchase <= 7;
  }
}

function inferPixKeyType(key: string): 'DOCUMENT' | 'EMAIL' | 'PHONE' | 'RANDOM' | null {
  const trimmed = key.trim();

  // 1. UUID（随机密钥 / EVP）
  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
  if (uuidRegex.test(trimmed)) return 'RANDOM';

  // 2. 邮箱
  if (trimmed.includes('@')) return 'EMAIL';

  // 3. 仅数字 → DOCUMENT 或 PHONE
  const digits = trimmed.replace(/\D/g, '');

  // 14 位 → CNPJ
  if (digits.length === 14) return 'DOCUMENT';

  // 11 位 → CPF 或 PHONE
  // 通过校验 CPF 的校验位来区分
  if (digits.length === 11) {
    return isValidCpf(digits) ? 'DOCUMENT' : 'PHONE';
  }

  // 10 位 → 座机（区号 + 8 位）
  if (digits.length === 10) return 'PHONE';

  return null; // 无法识别的格式
}

// CPF 算法校验（校验位）
function isValidCpf(cpf: string): boolean {
  if (/^(\d)\1{10}$/.test(cpf)) return false; // 拒绝 11111111111 这类序列
  let sum = 0;
  for (let i = 0; i < 9; i++) sum += parseInt(cpf[i]) * (10 - i);
  let check = 11 - (sum % 11);
  if (check >= 10) check = 0;
  if (check !== parseInt(cpf[9])) return false;
  sum = 0;
  for (let i = 0; i < 10; i++) sum += parseInt(cpf[i]) * (11 - i);
  check = 11 - (sum % 11);
  if (check >= 10) check = 0;
  return check === parseInt(cpf[10]);
}

function validatePixKey(key: string, keyType: string): boolean {
  switch (keyType) {
    case 'DOCUMENT':
      // CPF：11 位或 CNPJ：14 位（仅数字）
      return /^\d{11}$/.test(key) || /^\d{14}$/.test(key);

    case 'EMAIL':
      // 带有效域名的邮箱（顶级域名至少 2 个字符）
      return /^[^\s@]+@[^\s@]+\.[^\s@]{2,}$/.test(key);

    case 'PHONE':
      // 区号 + 号码：10 位（座机）或 11 位（手机）
      // 不要包含国家代码（+55）— API 会自动添加
      return /^\d{10,11}$/.test(key);

    case 'RANDOM':
      // 带连字符的 UUID 或不带连字符的 32 位十六进制字符
      return /^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$/.test(key)
        || /^[a-fA-F0-9]{32}$/.test(key);

    default:
      return false;
  }
}

async function safePayment(
  token: string,
  amount: number,
  recipient: RecipientData
) {
  // 查询余额
  const balance = await getBalance(token);

  // 检查余额是否充足
  if (balance.netBalance < amount) {
    throw new Error(
      `余额不足。可用：R$ ${balance.netBalance.toFixed(2)} | ` +
      `所需：R$ ${amount.toFixed(2)}`
    );
  }

  // 继续付款
  return await sendPixPayment(token, ...recipient, amount);
}

async function monitorPaymentStatus(transactionId, timeout = 60000) {
  const startTime = Date.now();

  while (Date.now() - startTime < timeout) {
    const status = await checkTransactionStatus(transactionId);

    if (status === 'CONFIRMED') {
      console.log('付款已确认！');
      return true;
    }

    if (status === 'ERROR') {
      throw new Error('付款失败');
    }

    // 等待 2 秒后再次检查
    await new Promise(resolve => setTimeout(resolve, 2000));
  }

  throw new Error('超时：付款未在预期时间内确认');
}

POST /api/pix/cash-out
         │
         ▼
     ┌─────────┐
     │ PENDING  │  ← API 立即响应（201）
     └────┬─────┘
          │  （在清算银行处理）
          │
    ┌─────┴──────┐
    ▼            ▼
┌──────────┐ ┌───────┐
│CONFIRMED │ │ ERROR │  ← 通过 webhook 通知
└──────────┘ └───────┘

{
  "event": "CashOut",
  "status": "ERROR",
  "transactionId": "12345",
  "externalId": "PAYMENT-987654-20240119",
  "errorCode": "TAX_ID_MISMATCH",
  "errorMessage": "O CPF/CNPJ informado não corresponde ao titular da conta.",
  ...
}