跨境多支付渠道集成开发：海外本地化支付接入的难点与解决方案

<?php

interface PaymentGatewayInterface
{
    /**
     * 创建支付订单，返回前端调起收银台所需参数
     */
    public function createOrder(array $orderData, array $userData): array;

    /**
     * 处理异步回调通知，验证签名并更新订单状态
     */
    public function handleCallback(array $callbackData): array;

    /**
     * 发起退款
     */
    public function refund(string $transactionId, float $amount, string $reason = ''): bool;

    /**
     * 查询订单状态（可选，用于主动对账）
     */
    public function queryOrder(string $transactionId): array;

    /**
     * 获取该渠道支持的币种列表
     */
    public function getSupportedCurrencies(): array;

    /**
     * 获取该渠道的手续费率（百分比或固定值）
     */
    public function getFeeRate(): float;
}

<?php

class WisePayment implements PaymentGatewayInterface
{
    private $apiBaseUrl;
    private $apiKey;
    private $webhookSecret;

    public function __construct(array $config)
    {
        $this->apiBaseUrl = $config['api_base_url'];
        $this->apiKey = $config['api_key'];
        $this->webhookSecret = $config['webhook_secret'];
    }

    public function createOrder(array $orderData, array $userData): array
    {
        // 调用 Wise 创建转账订单
        $payload = [
            'amount' => $orderData['amount'],
            'currency' => $orderData['currency'],
            'recipient' => $userData['email'],
            'reference' => $orderData['order_id'],
        ];
        // 发送 HTTP 请求...
        // 返回前端需要的 checkout_url 或 token
        return ['checkout_url' => 'https://wise.com/pay/...'];
    }

    public function handleCallback(array $callbackData): array
    {
        // 验签（具体见下文）
        if (!$this->verifySignature($callbackData)) {
            throw new \Exception('Invalid signature');
        }
        // 解析支付结果
        $status = $callbackData['status'] === 'completed' ? 'paid' : 'failed';
        return [
            'order_id' => $callbackData['reference'],
            'transaction_id' => $callbackData['transfer_id'],
            'status' => $status,
            'raw_data' => $callbackData,
        ];
    }

    // ... 其他方法实现
}

<?php

class PaymentFactory
{
    public static function getGateway(string $channelCode): PaymentGatewayInterface
    {
        $config = self::loadChannelConfig($channelCode);
        switch ($channelCode) {
            case 'wise':
                return new WisePayment($config);
            case 'dcpay':
                return new DcpayPayment($config);
            case 'fedaPay':
                return new FedaPayPayment($config);
            // ... 更多渠道
            default:
                throw new \Exception('Unsupported payment channel');
        }
    }
}

<?php

class CurrencyConverter
{
    private $exchangeRates; // 从外部汇率 API 获取的实时汇率

    public function lockExchangeRate(string $fromCurrency, string $toCurrency, float $amount, string $orderId): array
    {
        // 获取最新汇率
        $rate = $this->fetchCurrentRate($fromCurrency, $toCurrency);
        $convertedAmount = $amount * $rate;

        // 将汇率和转换后的金额保存到订单表，后续所有财务计算都基于此锁定数据
        $order = Order::find($orderId);
        $order->locked_rate = $rate;
        $order->target_currency = $toCurrency;
        $order->target_amount = $convertedAmount;
        $order->save();

        return [
            'rate' => $rate,
            'converted_amount' => $convertedAmount,
        ];
    }

    private function fetchCurrentRate(string $from, string $to): float
    {
        // 调用第三方汇率接口（如 fixer.io），并做缓存（避免每次请求）
        // 实现省略...
        return 0.14; // 示例
    }
}

<?php

class FedaPayPayment implements PaymentGatewayInterface
{
    private $publicKey;

    public function verifySignature(array $callbackData): bool
    {
        // 假设回调数据包含 signature 字段和原始 payload
        $signature = $callbackData['signature'];
        unset($callbackData['signature']); // 移除签名本身

        // 按字典序排序参数，拼接成字符串（不同渠道规则不同）
        ksort($callbackData);
        $stringToSign = http_build_query($callbackData, '', '&');

        // 使用 RSA 公钥验签
        $publicKeyId = openssl_pkey_get_public($this->publicKey);
        $result = openssl_verify($stringToSign, base64_decode($signature), $publicKeyId, OPENSSL_ALGO_SHA256);

        return $result === 1;
    }

    public function handleCallback(array $callbackData): array
    {
        if (!$this->verifySignature($callbackData)) {
            // 记录攻击日志并抛出异常
            throw new \Exception('Signature verification failed');
        }

        // 验签通过后，再验证订单号是否存在、金额是否匹配
        $order = Order::find($callbackData['order_id']);
        if (!$order || $order->amount != $callbackData['amount']) {
            throw new \Exception('Order mismatch');
        }

        // 最后更新订单状态
        $order->status = 'paid';
        $order->transaction_id = $callbackData['transaction_id'];
        $order->save();

        return ['status' => 'success'];
    }
}

<?php

class OrderTimeoutService
{
    public function cancelExpiredOrders(): void
    {
        $expiredOrders = Order::where('status', 'pending')
            ->where('created_at', '<', now()->subMinutes(30))
            ->get();

        foreach ($expiredOrders as $order) {
            // 如果该订单已调用支付渠道但未回调，可尝试主动查询渠道状态
            if ($order->payment_channel && $order->transaction_id) {
                $gateway = PaymentFactory::getGateway($order->payment_channel);
                $status = $gateway->queryOrder($order->transaction_id);
                if ($status['status'] === 'paid') {
                    // 主动同步状态，避免误取消
                    continue;
                }
            }
            // 否则取消订单并释放库存
            $order->status = 'cancelled';
            $order->save();
            // 释放库存逻辑...
        }
    }
}

<?php

class RiskControl
{
    public function checkOrder(Order $order): bool
    {
        // 同 IP 1 小时内订单数超过 10 笔
        $count = Order::where('ip', $order->ip)
            ->where('created_at', '>', now()->subHour())
            ->count();
        if ($count > 10) {
            return false;
        }

        // 单笔金额超过 5000 美元，触发人工审核
        if ($order->amount > 5000) {
            $order->need_manual_review = true;
            $order->save();
        }

        return true;
    }
}

// 根据用户国家获取推荐支付列表
getRecommendedChannels(country) {
    const map = {
        'US': ['balance', 'wise', 'paypal'],
        'SA': ['dcpay', 'qpay', 'wise'],  // 沙特
        'TJ': ['dcpay', 'wise'],          // 塔吉克斯坦
    };
    return map[country] || ['wise', 'paypal'];
}