快速开始

本页用 DEEPayment SDK 跑通第一笔代收或代付订单。字段全集请到 API Reference 中按代收/代付、国家和支付方式查看。

最小接入闭环：生成密钥对，配置 SDK，创建订单，接收并验签 webhook，异常时用查询接口确认订单状态。Ed25519 签名、Content-Digest 和 X25519 body 加密都由 SDK 完成，不需要手工拼 Header。

接入前准备

API host

生产请求发送至 https://panama.deepayment.com/api/v1。SDK 只需要域名，不带 /api/v1。

Access Key

开户时分配的公开商户标识。

商户 Ed25519 密钥对

商户自己生成。公钥上传到商户后台，私钥只保存在自己的服务端。

平台公钥

从商户后台获取：X25519 body 公钥及其 keyId，以及 webhook Ed25519 公钥。

webhookUrl

接收 payment 或 payout 最终状态的公网 HTTPS 地址。

method 信息

根据国家、币种选择 paymentMethod 或 payoutMethod。

SDK 已开源，每个语言一个仓库。本页是跑通第一笔订单的最短路径；每个方法、配置项和错误的完整说明见 SDK 使用手册。SDK 实现的线路协议见鉴权机制。

安装 SDK

Go
JavaScript
Python
PHP
Java

go get github.com/deepayment/[email protected]

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

需要 Go 1.24 及以上。包页面：pkg.go.dev · 源码：github.com/deepayment/sdk-go

npm install @support-deepayment/sdk

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

需要 Node.js 18 及以上，ES module。包页面：npm · 源码：github.com/deepayment/sdk-js

pip install deepayment

from deepayment import Client

需要 Python 3.10 及以上。包页面：PyPI · 源码：github.com/deepayment/sdk-python

composer require deepayment/sdk

use Deepayment\Sdk\Client;

需要 PHP 8.2 及以上，并启用 sodium、json、curl 扩展。包页面：Packagist · 源码：github.com/deepayment/sdk-php

<dependency>
  <groupId>com.deepayment</groupId>
  <artifactId>sdk</artifactId>
  <version>0.1.0</version>
</dependency>

import com.deepayment.sdk.Client;

需要 JDK 17 及以上。包页面：Maven Central · 源码：github.com/deepayment/sdk-java

安装 Agent Skill

用 AI 编码助手写对接代码时，先装上这个 skill。它带着各币种的方式码、条件必填字段，以及请求失败后如何判断订单是否已经生成的规则。

npx skills add deepayment/skill

支持 Claude Code、Cursor、Codex 等 skills CLI 覆盖的 agent。助手先读入口文件，需要方式码表时再按需拉取。源码与手动安装说明：github.com/deepayment/skill。skill 与 SDK 出自同一源码树，随 SDK 一起更新。

通信规则

仅支持 HTTPS
最低 TLS 1.2
编码为 UTF-8
请求与响应主体使用 JSON；POST body 由 SDK 加密

生产环境 Base URL

https://panama.deepayment.com/api/v1

接入流程

生成密钥
生成 Ed25519 密钥对，在商户后台上传公钥，并复制 Access Key 和平台公钥。不同环境的密钥不要混用。
配置 SDK
传入 Base URL、Access Key、商户私钥、平台 body 公钥和平台 webhook 公钥。
创建订单
创建订单时传入 merchantOrderNo、currency、amount、paymentMethod 或 payoutMethod、webhookUrl。
处理结果
通过 SDK 解析 webhook，SDK 会先校验平台签名。回调延迟、重复或请求超时时，用查询接口确认状态。

配置 SDK

把占位值替换为商户后台中的实际配置。

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,        // 商户 Ed25519 私钥，base64
    PlatformBodyKeyID:           "body_20260827_01",
    PlatformBodyPublicKeyBase64: platformBodyPublicKey,     // 平台 X25519 公钥，base64
    PlatformWebhookPublicKeys: map[string]string{           // keyId -> 平台 Ed25519 公钥，base64
        "pwhk_20260827_01": platformWebhookPublicKey,
    },
})
if err != nil {
    return err
}

const client = new Client({
  baseUrl: 'https://panama.deepayment.com',
  accessKey: 'mak_live_xxx',
  merchantPrivateKeyBase64: merchantPrivateKey,        // 商户 Ed25519 私钥，base64
  platformBodyKeyId: 'body_20260827_01',
  platformBodyPublicKeyBase64: platformBodyPublicKey,  // 平台 X25519 公钥，base64
  platformWebhookPublicKeys: {                         // keyId -> 平台 Ed25519 公钥，base64
    pwhk_20260827_01: platformWebhookPublicKey,
  },
});

client = Client(
    base_url="https://panama.deepayment.com",
    access_key="mak_live_xxx",
    merchant_private_key_base64=merchant_private_key,        # 商户 Ed25519 私钥，base64
    platform_body_key_id="body_20260827_01",
    platform_body_public_key_base64=platform_body_public_key,  # 平台 X25519 公钥，base64
    platform_webhook_public_keys={                           # keyId -> 平台 Ed25519 公钥，base64
        "pwhk_20260827_01": platform_webhook_public_key,
    },
)

$client = new Client([
    'baseUrl' => 'https://panama.deepayment.com',
    'accessKey' => 'mak_live_xxx',
    'merchantPrivateKeyBase64' => $merchantPrivateKey,        // 商户 Ed25519 私钥，base64
    'platformBodyKeyId' => 'body_20260827_01',
    'platformBodyPublicKeyBase64' => $platformBodyPublicKey,  // 平台 X25519 公钥，base64
    'platformWebhookPublicKeys' => [                          // keyId -> 平台 Ed25519 公钥，base64
        'pwhk_20260827_01' => $platformWebhookPublicKey,
    ],
]);

Client client = Client.builder()
    .baseUrl("https://panama.deepayment.com")
    .accessKey("mak_live_xxx")
    .merchantPrivateKeyBase64(merchantPrivateKey)          // 商户 Ed25519 私钥，base64
    .platformBodyKeyId("body_20260827_01")
    .platformBodyPublicKeyBase64(platformBodyPublicKey)    // 平台 X25519 公钥，base64
    .platformWebhookPublicKeys(Map.of(                     // keyId -> 平台 Ed25519 公钥，base64
        "pwhk_20260827_01", platformWebhookPublicKey))
    .build();

选择接口

创建代收订单

用户向商户付款。进入代收目录后按国家和支付方式查看完整接口文档。

POST /payments

创建代付订单

商户向用户或合作方出款。进入代付目录后按国家和出款方式查看完整接口文档。

POST /payouts

创建代收

业务字段和 API Reference 中的请求体一致，加密和签名由 SDK 完成。

Go
JavaScript
Python
PHP
Java

order, err := c.CreatePayment(ctx, &deepayment.CreatePaymentReq{
    MerchantOrderNo: "M202605060001",
    Currency:        "BRL",
    Amount:          "250.00",
    Country:         "BR",
    PaymentMethod: deepayment.PaymentMethod{
        Code: "PIX",
        Pix: &deepayment.PaymentPixExtra{
            PayerCPF:  "12345678901",
            PayerName: "Joao Silva",
        },
    },
    ReturnUrl:  "https://merchant.example/return",
    WebhookUrl: "https://merchant.example/webhook/payment",
    Attach:     "user_123",
})

const order = await client.createPayment({
  merchantOrderNo: 'M202605060001',
  currency: 'BRL',
  amount: '250.00',
  country: 'BR',
  paymentMethod: {
    code: 'PIX',
    pix: { payerCPF: '12345678901', payerName: 'Joao Silva' },
  },
  returnUrl: 'https://merchant.example/return',
  webhookUrl: 'https://merchant.example/webhook/payment',
  attach: 'user_123',
});

order = client.create_payment(CreatePaymentReq(
    merchantOrderNo="M202605060001",
    currency="BRL",
    amount="250.00",
    country="BR",
    paymentMethod={
        "code": "PIX",
        "pix": {"payerCPF": "12345678901", "payerName": "Joao Silva"},
    },
    returnUrl="https://merchant.example/return",
    webhookUrl="https://merchant.example/webhook/payment",
    attach="user_123",
))

$order = $client->createPayment([
    'merchantOrderNo' => 'M202605060001',
    'currency' => 'BRL',
    'amount' => '250.00',
    'country' => 'BR',
    'paymentMethod' => [
        'code' => 'PIX',
        'pix' => ['payerCPF' => '12345678901', 'payerName' => 'Joao Silva'],
    ],
    'returnUrl' => 'https://merchant.example/return',
    'webhookUrl' => 'https://merchant.example/webhook/payment',
    'attach' => 'user_123',
]);

Map<String, Object> order = client.createPayment(Map.of(
    "merchantOrderNo", "M202605060001",
    "currency", "BRL",
    "amount", "250.00",
    "country", "BR",
    "paymentMethod", Map.of(
        "code", "PIX",
        "pix", Map.of("payerCPF", "12345678901", "payerName", "Joao Silva")),
    "returnUrl", "https://merchant.example/return",
    "webhookUrl", "https://merchant.example/webhook/payment",
    "attach", "user_123"));

创建代付使用 createPayout 和 payoutMethod 对象，方式相同。出款方式字段见 API Reference 代付目录。

查询订单

Go
JavaScript
Python
PHP
Java

order, err := c.QueryPaymentByMerchantOrderNo(ctx, "M202605060001")

const order = await client.queryPaymentByMerchantOrderNo('M202605060001');

order = client.query_payment_by_merchant_order_no("M202605060001")

$order = $client->queryPaymentByMerchantOrderNo('M202605060001');

Map<String, Object> order = client.queryPaymentByMerchantOrderNo("M202605060001");

接收 webhook

把原始 HTTP 请求交给 SDK。SDK 会校验 Content-Digest、Webhook-Event-Id 和平台 Ed25519 签名，通过后返回事件。事件落库后返回 HTTP 2xx。

Go
JavaScript
Python
PHP
Java

func handlePaymentWebhook(w http.ResponseWriter, r *http.Request) {
    wh, err := c.ParsePaymentWebhook(r)
    if err != nil {
        w.WriteHeader(http.StatusUnauthorized)
        return
    }
    // 按 wh.EventID 去重，再按 wh.Status 更新订单 wh.MerchantOrderNo
    w.WriteHeader(http.StatusOK)
}

// Express 风格处理函数，需要保留原始 body
const event = await client.parsePaymentWebhook({
  method: req.method,
  path: req.path,
  rawQuery: req.url.split('?')[1] ?? '',
  headers: req.headers,
  body: rawBody, // 实际收到的原始字节（Buffer 或 string）
});
// 按 event.eventId 去重，再按 event.status 处理
res.sendStatus(200);

event = client.parse_payment_webhook(
    method=request.method,
    path=request.path,
    raw_query=request.query_string.decode(),
    headers=dict(request.headers),
    body=request.get_data(),  # 实际收到的原始字节
)
# 按 event.eventId 去重，再按 event.status 处理
return "", 200

$event = $client->parsePaymentWebhook(
    $_SERVER['REQUEST_METHOD'],
    parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH),
    getallheaders(),
    file_get_contents('php://input'),
    $_SERVER['QUERY_STRING'] ?? ''
);
// 按 $event['eventId'] 去重，再按 $event['status'] 处理
http_response_code(200);

Map<String, Object> event = client.parsePaymentWebhook(
    request.getMethod(),
    request.getRequestURI(),
    headers,          // 请求 header 的 Map<String, String>
    rawBody);         // 实际收到的原始字节 byte[]
// 按 event.get("eventId") 去重，再按 event.get("status") 处理
response.setStatus(200);

成功响应

所有接口使用统一响应 envelope。SDK 返回其中的 data 对象，其余情况抛出错误。traceId 建议写入日志，便于排查。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "code": 200,
  "msg": "OK",
  "traceId": "7f3d2f0c9b4d4a1a",
  "data": {}
}

失败响应

失败响应使用对应 HTTP status，body 仍是同一 envelope。SDK 把它转换为业务错误，包含 code、msg、traceId 和 data.message。排查时同时记录这几项。

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "code": 12100007,
  "msg": "INVALID_FIELD",
  "traceId": "7f3d2f0c9b4d4a1a",
  "data": {
    "message": "paymentMethod.pse.bankCode is required"
  }
}

幂等和恢复

代收和代付创建都以 merchantOrderNo 作为商户侧幂等键。
同一商户下，payments 和 payouts 各自独立唯一。
同一 merchantOrderNo 重复提交同一请求，返回原订单。
同一 merchantOrderNo 改了字段再提交，返回的仍是原订单。平台不比对字段，改了金额或收款账号都不会生效。另一笔订单要用新单号。
SDK 不自动重试写请求。创建超时、5xx 或连接断开时，先查单再决定是否重试。重试之所以是同一笔创建，靠的是复用同一个 merchantOrderNo，与幂等键无关。

:::tip 对账建议 webhook 是事件通知，查询接口是状态确认入口。回调重复、延迟或乱序时，先按 eventId 幂等落库，再用查询接口确认最终状态。 :::

接入前准备​

API host

Access Key

商户 Ed25519 密钥对

平台公钥

webhookUrl

method 信息

安装 SDK​

安装 Agent Skill​

通信规则​

生产环境 Base URL​

接入流程​

配置 SDK​

选择接口​