MakePay PHP SDK

概述

MakePay PHP SDK 是一个轻量 Composer 库，用于服务器端 MakePay 集成。它封装 API key 认证、支付链接操作、MakePay 设置和签名 Webhook 验证。

公开源码仓库：

https://github.com/makecryptoio/makepay-php-sdk

安装

通过公开 Git 仓库使用 Composer 安装：

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/makecryptoio/makepay-php-sdk"
    }
  ],
  "require": {
    "makepay/makepay-php": "^0.1"
  }
}

然后运行：

composer update makepay/makepay-php

身份验证

从 MakeCrypto 商户开发者区域创建 MakePay API 密钥，并只把 secret 保存在服务器端环境变量中。

use MakePay\Client;

$makepay = new Client([
    'keyId' => getenv('MAKEPAY_KEY_ID'),
    'keySecret' => getenv('MAKEPAY_KEY_SECRET'),
    'checkoutBaseUrl' => 'https://makepay.io',
]);

SDK 会向 MakePay 合作伙伴 API 发送 X-MakeCrypto-Key-Id 和 X-MakeCrypto-Key-Secret 请求头。

创建支付链接

$response = $makepay->createPaymentLink([
    'title' => 'Order #1042',
    'description' => 'Checkout for order #1042',
    'amount' => '129.99',
    'currency' => 'USDT',
    'orderId' => 'order_1042',
    'customerEmail' => 'buyer@example.com',
    'returnUrl' => 'https://merchant.example/orders/1042',
    'successUrl' => 'https://merchant.example/orders/1042/success',
    'failureUrl' => 'https://merchant.example/orders/1042/pay',
    'expirationTime' => '12h',
]);

header('Location: ' . $response['paymentLink']['publicUrl']);

如果希望 MakePay 在创建时向客户发送邮件，请传入 sendPaymentRequestEmail。

嵌入式结账

PHP 后端可以在创建支付链接后生成托管链接、嵌入式 iframe URL 和 HTML 片段。常用方法包括 hostedCheckoutUrl、embeddedCheckoutUrl、embedButtonHtml 和 iframeHtml。

读取和更新链接

使用 SDK 列出支付链接、读取单个链接、暂停或重新激活链接，并发送支付请求邮件。

$makepay->listPaymentLinks();
$makepay->getPaymentLink('PAYMENT_LINK_UID');
$makepay->updatePaymentLink('PAYMENT_LINK_UID', ['status' => 'paused']);
$makepay->sendPaymentRequestEmail('PAYMENT_LINK_UID', 'buyer@example.com');

设置

$makepay->getSettings();
$makepay->updateSettings([
    'callbackUrl' => 'https://merchant.example/webhooks/makepay',
]);

Webhook 验证

在解析 JSON 前读取原始请求体，并使用 SDK 的 Webhook 解析/验证工具验证 x-makepay-signature。

错误处理

API 调用失败时会抛出 MakePay 异常，其中包含 HTTP 状态和解码后的响应体。请在后端记录这些信息，并把面向客户的错误文案保持简洁。

源码结构

规范源码位于 apps/plugins/php-sdk。发布包应从该源码生成 Composer 可安装版本。

发布说明

包名为 makepay/makepay-php。发布应使用 MakeCrypto 控制的 Composer/GitHub 凭据，并遵循仓库发布流程。