接入指南

接入流程

从注册到上线，5步快速完成接入

注册商户账号

在线提交商户资料，完成企业认证。审核通常1-3个工作日完成，支持加急审核通道。

在线提交资料
企业实名认证
加急审核通道

获取API密钥

审核通过后，在商户后台获取API Key和Secret。支持沙箱环境密钥和正式环境密钥分离管理。

沙箱/正式密钥
密钥权限管理
IP白名单配置

集成开发

使用官方SDK或直接调用RESTful API进行集成开发。提供多语言SDK和详细文档，降低开发难度。

多语言SDK
示例代码
详细API文档

沙箱测试

在沙箱环境中完成全流程测试，验证支付、回调、退款等核心功能。测试通过后方可申请上线。

全流程模拟
测试数据生成
回调调试工具

正式上线

切换至正式环境密钥，开始接收真实交易。专属技术顾问全程护航，确保平稳上线。

一键切换环境
上线健康检查
专属技术顾问

API 能力概览

覆盖支付全链路的完整API接口

支付接口

核心

支持收单支付、订阅扣款、代扣等多种支付模式，覆盖全球200+国家地区

POST /v1/payments 创建支付
GET /v1/payments/{id} 查询支付
POST /v1/payments/{id}/cancel 取消支付

退款接口

核心

支持全额退款和部分退款，退款状态实时回调通知

POST /v1/refunds 创建退款
GET /v1/refunds/{id} 查询退款

订阅接口

创建和管理订阅计划，支持灵活的计费策略和周期管理

POST /v1/subscriptions 创建订阅
PUT /v1/subscriptions/{id} 更新订阅
DELETE /v1/subscriptions/{id} 取消订阅

汇兑接口

汇兑

实时汇率查询、货币兑换、锁汇等汇兑相关API

GET /v1/rates 查询汇率
POST /v1/exchanges 创建兑换
POST /v1/locks 创建锁汇

回调通知

通知

支付状态变更、退款完成、订阅扣款等事件实时Webhook通知

payment.completed 支付完成
refund.succeeded 退款成功
subscription.renewed 订阅续费

数据查询

数据

交易数据、对账文件、结算报表等数据查询与导出

GET /v1/transactions 交易查询
GET /v1/settlements 结算查询
GET /v1/balance 余额查询

SDK 多语言支持

覆盖主流开发语言，开箱即用

Java

Maven / Gradle

v3.2.1

Python

pip install

v2.8.0

Node.js

npm / yarn

v4.1.0

Go

go mod

v2.5.3

PHP

Composer

v3.0.2

Rust

cargo

v1.2.0

iOS

Swift SDK

v2.0.1

Android

Kotlin SDK

v2.1.0

快速上手

几行代码，快速发起一笔支付

import ysf

client = ysf.Client(
    api_key="your_api_key",
    api_secret="your_api_secret"
)

# 创建一笔支付
payment = client.payments.create(
    amount=1000,          # 金额（分）
    currency="USD",       # 币种
    method="card",        # 支付方式
    order_id="ORD_20260101",
    description="测试订单",
    return_url="https://your-site.com/return",
    webhook_url="https://your-site.com/webhook"
)

print(f"支付链接: {payment.payment_url}")
print(f"支付ID: {payment.id}")

import com.ysf.sdk.Client;
import com.ysf.sdk.model.Payment;

Client client = new Client("your_api_key", "your_api_secret");

// 创建一笔支付
Payment payment = client.payments()
    .create(Payment.builder()
        .amount(1000L)                    // 金额（分）
        .currency("USD")                  // 币种
        .method("card")                   // 支付方式
        .orderId("ORD_20260101")
        .description("测试订单")
        .returnUrl("https://your-site.com/return")
        .webhookUrl("https://your-site.com/webhook")
        .build());

System.out.println("支付链接: " + payment.getPaymentUrl());
System.out.println("支付ID: " + payment.getId());

const Ysf = require('ysf-sdk');

const client = new Ysf({
    apiKey: 'your_api_key',
    apiSecret: 'your_api_secret'
});

// 创建一笔支付
const payment = await client.payments.create({
    amount: 1000,           // 金额（分）
    currency: 'USD',        // 币种
    method: 'card',         // 支付方式
    order_id: 'ORD_20260101',
    description: '测试订单',
    return_url: 'https://your-site.com/return',
    webhook_url: 'https://your-site.com/webhook'
});

console.log(`支付链接: ${payment.payment_url}`);
console.log(`支付ID: ${payment.id}`);

curl -X POST https://api.ysf.cc/v1/payments \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "USD",
    "method": "card",
    "order_id": "ORD_20260101",
    "description": "测试订单",
    "return_url": "https://your-site.com/return",
    "webhook_url": "https://your-site.com/webhook"
  }'

# Response
{
  "id": "pay_xxxxxxxxxxxx",
  "status": "pending",
  "payment_url": "https://pay.ysf.cc/checkout/xxxxxxxxxxxx"
}

安全接入规范

多重安全机制，保障交易和数据安全

HTTPS 加密传输

所有API请求强制使用TLS 1.2+加密传输，确保数据在传输过程中不被窃取或篡改

请求签名验证

每个API请求使用HMAC-SHA256签名，服务端验证签名确保请求来源可信、数据完整

IP 白名单

商户可配置服务器IP白名单，仅允许指定IP发起API请求，有效防止未授权访问

密钥分级管理

API Key与Secret分离存储，支持密钥轮换，沙箱与生产环境密钥完全隔离

PCI-DSS 合规

通过PCI-DSS Level 1认证，商户无需自行处理卡号等敏感信息，大幅降低合规成本

3D Secure 验证

支持3DS 2.0验证流程，在保障安全的同时优化用户体验，提升交易成功率

沙箱测试环境

零风险模拟全流程，确保接入质量

完整交易模拟

支持支付、退款、争议、订阅等全类型交易模拟，覆盖所有业务场景

测试卡号

提供多种测试卡号，模拟不同支付结果：成功、失败、3DS验证等场景

回调调试

支持自定义回调URL，实时查看回调请求和响应，快速定位集成问题

性能测试

提供压测工具和并发模拟，帮助评估系统承载能力，保障上线稳定

沙箱环境说明

沙箱环境数据与生产环境完全隔离，不会产生真实交易
沙箱API地址：https://sandbox-api.ysf.cc
沙箱密钥可在商户后台「开发设置」中获取
沙箱测试不收取任何费用

常见问题

接入过程中常见的疑问解答

接入需要多长时间？

标准接入周期为3-5个工作日。包含商户审核（1-3个工作日）和技术集成（1-2个工作日）。如需加急，可联系客户经理开通绿色通道。

是否支持测试环境？

支持。我们提供完整的沙箱测试环境，包含测试API、测试卡号、回调调试工具等。沙箱环境与生产环境功能一致，但不产生真实交易。

回调通知失败怎么办？

系统会自动重试回调通知，最多重试5次（间隔1/5/15/60/300分钟）。您也可以通过API主动查询交易状态作为兜底方案。建议实现幂等处理避免重复通知。

如何处理多币种支付？

创建支付时指定目标币种即可，系统自动处理汇率转换。您也可以通过汇兑API提前锁定汇率，或设置自动结汇规则，资金到达后自动兑换为指定币种。

是否提供技术支持？

提供7×24小时技术支持。接入阶段安排专属技术顾问一对一协助，上线后可通过工单系统、技术支持热线、开发者社区获取帮助。

API有调用频率限制吗？

默认每分钟1000次请求。如需更高频率，可在商户后台申请提额，或联系客户经理根据业务量定制配额。批量操作建议使用批量API减少请求次数。