快速开始

服务端 SDK

快速开始

安装 J-Pay Server SDK、初始化 API Client，并开始调用支付、代付与代理 API。

Language

jpay-api/php-sdk

J-Pay API 快速开始

简介

J-Pay 支付网关 PHP Server SDK

安装

使用 Composer

composer require jpay-api/php-sdk

{
  "require": {
    "jpay-api/php-sdk": "~1.0"
  }
}

初始化 API Client

说明： 客户端详细配置见 API Client。

API Client 支持以下可配置参数：

参数	类型	Description
apiKey	string	Merchant API key for automatic MD5 request signing on Payments API calls.
environment	Environment	The API environment. <br> Default: Environment.SANDBOX
timeout	int	Timeout for API calls in seconds.<br>Default: 30
enableRetries	bool	Whether to enable retries and backoff feature.<br>Default: false
numberOfRetries	int	The number of retries to make.<br>Default: 0
retryInterval	float	The retry time interval between the endpoint calls.<br>Default: 1
backOffFactor	float	Exponential backoff factor to increase interval between retries.<br>Default: 2
maximumRetryWaitTime	int	The maximum wait time in seconds for overall retrying requests.<br>Default: 0
retryOnTimeout	bool	Whether to retry on request timeout.<br>Default: true
httpStatusCodesToRetry	array	Http status codes to retry against.<br>Default: 408, 413, 429, 500, 502, 503, 504, 521, 522, 524, 408, 413, 429, 500, 502, 503, 504, 521, 522, 524
httpMethodsToRetry	array	Http methods to retry against.<br>Default: 'GET', 'PUT', 'GET', 'PUT'
loggingConfiguration	LoggingConfigurationBuilder	Represents the logging configurations for API calls
proxyConfiguration	ProxyConfigurationBuilder	Represents the proxy configurations for API calls
verifyPeer	bool	Whether to verify SSL certificates.<br>Default: true
verifyHost	bool	Whether to verify SSL host names.<br>Default: true

可按如下方式初始化 API Client：

use JPayApiLib\Logging\LoggingConfigurationBuilder;
use JPayApiLib\Logging\RequestLoggingConfigurationBuilder;
use JPayApiLib\Logging\ResponseLoggingConfigurationBuilder;
use Psr\Log\LogLevel;
use JPayApiLib\Environment;
use JPayApiLib\JPayApiClientBuilder;

$client = JPayApiClientBuilder::init()
    ->apiKey('your-merchant-api-key')
    ->environment(Environment::SANDBOX)
    ->loggingConfiguration(
        LoggingConfigurationBuilder::init()
            ->level(LogLevel::INFO)
            ->requestConfiguration(RequestLoggingConfigurationBuilder::init()->body(true))
            ->responseConfiguration(ResponseLoggingConfigurationBuilder::init()->headers(true))
    )
    ->build();

环境

SDK 支持切换 API 环境，可选值如下：

字段

名称	说明
SANDBOX	Sandbox (Default)
PRODUCTION	Production

请求模型与 Builder

各 API 端点提供与 OpenAPI 规范一致的强类型请求模型与链式 Builder，参数类型与 API 定义一致（均为 string）。

use JPayApiLib\Models\Requests\Builders\CreatePayoutRequestBuilder;

$request = CreatePayoutRequestBuilder::init()
    ->orderType('BANK')
    ->memberid('10153')
    ->outTradeNo('PO20260101001')
    ->amount('100.00')
    ->currency('USD')
    ->notifyurl('https://example.com/payout/notify')
    ->remark('Salary payout')
    ->firstname('John')
    ->payeeCountry('US')
    ->payeeaccount('1234567890')
    ->bankcode('001')
    ->bankname('Test Bank')
    ->build();

$response = $client->getPayoutsApi()->createFromRequest($request);
/** @var \JPayApiLib\Models\ApiV1PaymentCreateOrderResponse $result */
$result = $response->getResult();

响应模型会自动反序列化（如 PayTradeQueryResponse、PaymentResponse）。

自动请求签名

配置 apiKey 后，PaymentsApi 会在发起出站请求前自动生成 MD5 签名（pay_md5sign），通常无需手动设置 payMd5Sign，除非需要覆盖计算值。

签名规则见 J-Pay 签名算法：参与签名的非空字段按名称排序，拼接为 key=value&...，末尾追加 &key={apiKey} 后做 MD5 并转大写。

卡支付下单（POST /pay_index）参与签名的字段：pay_memberid、pay_orderid、pay_applydate、pay_bankcode、pay_notifyurl、pay_callbackurl、pay_amount。

API 列表

• 支付 API
• Link Payment
• 代理 API
• 文件 API
• 代付 API

SDK 基础设施

配置

• ProxyConfigurationBuilder
• LoggingConfigurationBuilder
• RequestLoggingConfigurationBuilder
• ResponseLoggingConfigurationBuilder

HTTP

• HttpRequest

Utilities

• FileWrapper
• ApiResponse