配置

客户端用六项值构造一次，进程生命周期内复用。可以在线程或请求之间共享。

必填项

项	来源	说明
Base URL	`https://panama.deepayment.com/api/v1`	只要协议和域名，必须 https。带 path、query 或 fragment 会被拒绝；`/api/v1/...` 由 SDK 自己拼。
Access Key	商户后台	公开标识。放在 `Merchant-Access-Key` 里，平台用它找你登记的公钥。
商户私钥	你自己生成	Ed25519，base64。libsodium 和 OpenSSL 产出的 32 字节 seed，以及 64 字节 seed 加公钥的形式都接受。永远不离开你的服务器。生成方法见密钥配置。
平台 body key id	商户后台	指明加密你 `POST` body 的平台 X25519 密钥。它随 envelope 传输，网关据此知道用哪把私钥解。
平台 body 公钥	商户后台	X25519，base64，32 字节。必须是 key id 所指的那把。
平台 webhook 公钥	商户后台	`keyId` 到 Ed25519 公钥的映射，base64，每把 32 字节。即使不消费 webhook 也必填。

密钥按环境隔离，生产密钥不要在测试环境使用。

webhook 密钥轮换

webhook 带着签名所用的 keyid，SDK 在你配置的映射里按它查公钥。轮换期间平台会先公布新密钥再用它签名；把新密钥加进映射让两把都在，等平台停用旧密钥后再移除。用映射里没有的密钥签的 webhook 验签失败。

构造客户端

Go
JavaScript
Python
PHP
Java

import deepayment "github.com/deepayment/sdk-go"

c, err := deepayment.NewClient(deepayment.Config{
    BaseURL:                     "https://panama.deepayment.com",
    AccessKey:                   "mak_live_xxx",
    MerchantPrivateKeyBase64:    merchantPrivateKey,
    PlatformBodyKeyID:           "body_20260827_01",
    PlatformBodyPublicKeyBase64: platformBodyPublicKey,
    PlatformWebhookPublicKeys: map[string]string{
        "pwhk_20260827_01": platformWebhookPublicKey,
    },
    // 可选
    Timeout:          30 * time.Second,  // 设置了 HTTPClient 时忽略
    HTTPClient:       nil,               // 自定义 *http.Client，如走代理
    UserAgent:        "",                // 默认 merchant-sdk-go
    AcceptLanguage:   "",                // 默认 en-US；错误文案的语言
    MaxResponseBytes: 0,                 // 默认 8 MiB
})

任一项缺失或格式不对时 NewClient 返回错误而不是客户端，错误里写明是哪一项。

import { Client } from '@support-deepayment/sdk';

const client = new Client({
  baseUrl: 'https://panama.deepayment.com',
  accessKey: 'mak_live_xxx',
  merchantPrivateKeyBase64: merchantPrivateKey,
  platformBodyKeyId: 'body_20260827_01',
  platformBodyPublicKeyBase64: platformBodyPublicKey,
  platformWebhookPublicKeys: { pwhk_20260827_01: platformWebhookPublicKey },
  // 可选
  timeoutMs: 30000,
  userAgent: 'merchant-sdk-js',
  acceptLanguage: 'en-US',
  maxResponseBytes: 8 * 1024 * 1024,
  fetchImpl: globalThis.fetch,   // 注入自己的 fetch，如带代理 agent
});

任一项缺失或格式不对时构造函数抛 ConfigError。

from deepayment import Client

client = Client(
    base_url="https://panama.deepayment.com",
    access_key="mak_live_xxx",
    merchant_private_key_base64=merchant_private_key,
    platform_body_key_id="body_20260827_01",
    platform_body_public_key_base64=platform_body_public_key,
    platform_webhook_public_keys={"pwhk_20260827_01": platform_webhook_public_key},
    # 可选
    timeout=30.0,
    user_agent="merchant-sdk-python",
    accept_language="en-US",
    max_response_bytes=8 * 1024 * 1024,
)

参数全部为关键字参数。任一项缺失或格式不对时抛 ConfigError。

use Deepayment\Sdk\Client;

$client = new Client([
    'baseUrl' => 'https://panama.deepayment.com',
    'accessKey' => 'mak_live_xxx',
    'merchantPrivateKeyBase64' => $merchantPrivateKey,
    'platformBodyKeyId' => 'body_20260827_01',
    'platformBodyPublicKeyBase64' => $platformBodyPublicKey,
    'platformWebhookPublicKeys' => ['pwhk_20260827_01' => $platformWebhookPublicKey],
    // 可选
    'timeout' => 30,                       // 秒
    'userAgent' => 'merchant-sdk-php',
    'acceptLanguage' => 'en-US',
    'maxResponseBytes' => 8 * 1024 * 1024,
    'transport' => null,                   // callable(url, method, headers, body): [status, rawBody]
]);

任一项缺失或格式不对时抛 ConfigException。

import com.deepayment.sdk.Client;
import java.time.Duration;
import java.util.Map;

Client client = Client.builder()
    .baseUrl("https://panama.deepayment.com")
    .accessKey("mak_live_xxx")
    .merchantPrivateKeyBase64(merchantPrivateKey)
    .platformBodyKeyId("body_20260827_01")
    .platformBodyPublicKeyBase64(platformBodyPublicKey)
    .platformWebhookPublicKeys(Map.of("pwhk_20260827_01", platformWebhookPublicKey))
    // 可选
    .timeout(Duration.ofSeconds(30))
    .userAgent("merchant-sdk-java")
    .acceptLanguage("en-US")
    .maxResponseBytes(8 * 1024 * 1024)
    .transport(null)                       // 自定义 HTTP 栈用 Client.Transport
    .build();

任一项缺失或格式不对时 build() 抛 DeepaymentException.Config。请求和响应都是 Map<String, Object>，键名与 API Reference 一致。

可选设置

设置	默认	作用
超时	30 秒	整个请求，从连接到读完最后一个字节。超时时 SDK 返回传输错误，结果未知，见错误。
User-Agent	`merchant-sdk-<lang>`	每个请求都带。可以追加你的产品名，便于在平台日志里识别。
Accept-Language	`en-US`	错误响应里人类可读 `message` 的语言。
最大响应字节数	8 MiB	超过的响应被丢弃并报响应过大错误。
HTTP client / transport / fetch	内置	需要代理、自定义 TLS 或连接池时注入自己的实现。Go 设置了 `HTTPClient` 时忽略 `Timeout`，请在自己的 client 上配超时。

时钟

签名带 created 和 expires 时间戳，相差不超过 300 秒，平台拒绝窗口外的签名。用 NTP 保持服务器时间准确；偏差超过几分钟，每个请求都会报 UNAUTHORIZED。

必填项​

webhook 密钥轮换​

构造客户端​

可选设置​

时钟​

必填项

webhook 密钥轮换

构造客户端

可选设置

时钟