PHP项目数字巴哈马元与eBSD

wen PHP项目 2026-07-16 264

本文目录导读：

PHP项目数字巴哈马元与eBSD

核心架构设计（PHP）
与 Sand Dollar 支付网络对接
特殊注意事项（针对Sand Dollar）
项目关键PHP依赖
测试建议

针对你提到的“PHP项目”以及“数字巴哈马元 (Digital Bahamian Dollar / Sand Dollar)”和“eBSD”（通常指电子巴哈马元或Digital Bahamian Dollar的电子形态），我将从技术实现、API对接、合规性以及项目架构几个方面给出建议。

首先澄清概念：

数字巴哈马元 (Sand Dollar)：巴哈马中央银行发行的央行数字货币（CBDC）。
eBSD：通常是与数字巴哈马元相关的电子凭证或账户余额表示,可以将其视为数字巴哈马元在系统内的存储或交易单位。
你的项目可能是：一个需要处理Sand Dollar支付、兑换、余额管理的PHP应用（电商、钱包、金融系统等）。

核心架构设计（PHP）

1 数据模型

建议在数据库中将 eBSD 金额存储为 整数（以最小单位表示）,避免浮点数精度问题。

-- 示例：用户钱包表
CREATE TABLE user_wallets (
    id INT PRIMARY KEY AUTO_INCREMENT,
    user_id INT,
    ebsd_balance BIGINT NOT NULL DEFAULT 0 COMMENT '余额，单位：分（1 eBSD = 100 分）',
    version INT NOT NULL DEFAULT 1,       -- 乐观锁
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
-- 交易流水表
CREATE TABLE transactions (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    from_wallet_id INT,
    to_wallet_id INT,
    amount BIGINT NOT NULL,               -- 同样以最小单位存储
    tx_hash VARCHAR(128) UNIQUE,           -- 与链上或中央账本对应的唯一ID
    type ENUM('payment', 'transfer', 'topup', 'withdrawal'),
    status ENUM('pending', 'completed', 'failed', 'cancelled'),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

PHP 代码示例（金额转换与操作）：

class EBSDService {
    const SCALE = 2; // 2位小数
    const MIN_UNIT = 100; // 1 eBSD = 100分
    public static function toDisplay(int $amountInCents): float {
        return $amountInCents / self::MIN_UNIT;
    }
    public static function toMinUnit(float $displayAmount): int {
        return (int) round($displayAmount * self::MIN_UNIT);
    }
    // 安全转账（带乐观锁）
    public function transfer(int $fromWalletId, int $toWalletId, int $amountInCents): bool {
        $db = getDBConnection();
        $db->beginTransaction();
        try {
            // 扣减方
            $stmt = $db->prepare(
                "UPDATE user_wallets 
                 SET ebsd_balance = ebsd_balance - :amount, version = version + 1 
                 WHERE id = :id AND ebsd_balance >= :amount AND version = :version"
            );
            $stmt->execute([
                ':amount' => $amountInCents,
                ':id' => $fromWalletId,
                ':version' => $this->getCurrentVersion($fromWalletId)
            ]);
            if ($stmt->rowCount() === 0) throw new \Exception('余额不足或并发冲突');
            // 增加方
            $stmt = $db->prepare(
                "UPDATE user_wallets 
                 SET ebsd_balance = ebsd_balance + :amount, version = version + 1 
                 WHERE id = :id AND version = :version"
            );
            // ... 类似操作
            $db->commit();
            return true;
        } catch (\Exception $e) {
            $db->rollBack();
            logError($e->getMessage());
            return false;
        }
    }
}

与 Sand Dollar 支付网络对接

Sand Dollar 目前主要通过 巴哈马央行的授权支付服务商 提供API,你需要从巴哈马央行或持牌服务商获取以下信息：

1 核心API接口（假设参考国际标准）

// 伪代码：Sand Dollar API Client
class SandDollarClient {
    private $baseUrl;
    private $apiKey;
    private $merchantId;
    public function __construct($baseUrl, $apiKey, $merchantId) {
        $this->baseUrl = $baseUrl;
        $this->apiKey = $apiKey;
        $this->merchantId = $merchantId;
    }
    // 发起付款
    public function createPayment(array $params): array {
        $endpoint = '/v1/payments';
        $payload = [
            'merchant_id' => $this->merchantId,
            'amount' => $params['amount'],       // 单位最小单位
            'currency' => 'BSD',
            'payer_reference' => $params['order_id'],
            'callback_url' => $this->baseUrl . '/sanddollar/callback'
        ];
        return $this->post($endpoint, $payload);
    }
    // 验证支付回调签名
    public function verifyCallbackSignature(string $payload, string $signature): bool {
        $computed = hash_hmac('sha256', $payload, $this->apiKey);
        return hash_equals($computed, $signature);
    }
    private function post($endpoint, $data): array {
        $ch = curl_init($this->baseUrl . $endpoint);
        curl_setopt_array($ch, [
            CURLOPT_POST => true,
            CURLOPT_HTTPHEADER => [
                'Authorization: Bearer ' . $this->apiKey,
                'Content-Type: application/json'
            ],
            CURLOPT_POSTFIELDS => json_encode($data),
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT => 30
        ]);
        $result = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        if ($httpCode !== 200) {
            throw new \Exception('Sand Dollar API error: ' . $result);
        }
        return json_decode($result, true);
    }
}

2 回调处理（Webhook）

设置一个公开的PHP端点接收支付确认：

// sanddollar-callback.php
$client = new SandDollarClient($config['base_url'], $config['api_key'], $config['merchant_id']);
$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
if (!$client->verifyCallbackSignature($rawBody, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}
$data = json_decode($rawBody, true);
// 处理交易状态更新
$txId = $data['transaction_id'];
$status = $data['status']; // 'completed', 'failed'
$amount = $data['amount'];
// 更新本地数据库状态

特殊注意事项（针对Sand Dollar）

1 合规要求

KYC/AML：任何涉及 Sand Dollar 的账户必须通过巴哈马反洗钱验证，你的PHP系统需要集成合规检查（可调用外部身份验证服务）。
日限额：Sand Dollar 钱包通常有每日/每笔交易限额,需在你的系统中计算并强制。
离线支付：Sand Dollar 支持 NFC 离线支付，如果要支持,你的PHP后端需要设计批量对账逻辑。

2 官方资源

巴哈马央行 Sand Dollar 开发者文档：https://www.centralbankbahamas.com/sand-dollar
推荐联系 Sand Dollar 授权代理商（如 Kanoo Payments、ZEN 等）获取测试环境。

项目关键PHP依赖

{
  "require": {
    "php": ">=8.1",
    "guzzlehttp/guzzle": "^7.0",      // HTTP客户端
    "ramsey/uuid": "^4.0",            // 生成交易ID
    "vlucas/phpdotenv": "^5.0",       // 环境变量配置
    "monolog/monolog": "^3.0"         // 日志记录（审计追踪）
  }
}