做跨境电商、独立站、软件服务、会员订阅或数字产品时，商家通常希望在现有网站中增加 Visa、Mastercard 等银行卡收款，同时兼顾 Apple Pay、Google Pay 和多币种结算。对于已经通过 Sokin Payment Acceptance 审核的企业，可以通过 Sokin Checkout API，把 Sokin 官方托管收银台接入易支付，再由易支付统一管理订单、回调和退款。
本文将从 Sokin Checkout 的用途、申请前准备、X API Key 和域名白名单，一直讲到易支付插件安装、支付方式、支付通道、Webhook、金额换算、测试付款和常见故障。无论你是自己运营独立站，还是为客户搭建支付系统，都可以按照本文完成基础部署。
重要说明：本文介绍的是面向真实企业、真实网站和合规业务的技术对接流程。安装插件不等于获得 Sokin 收款资格，也不能绕过 KYC、KYB、行业审核、地区限制或风控要求。实际费率、结算币种和付款方式，以商户与 Sokin推荐开户赚100美元 的协议及后台获批能力为准。
一、Sokin Checkout 是什么
Sokin Checkout 是 Sokin 面向企业提供的在线支付接收方案。商户完成 Payment Acceptance 开通后，可以通过托管收银台、API 或相应电商插件接收客户付款。客户选择 Sokin 后，会进入由 Sokin 承载的安全支付页面完成银行卡或其他可用方式付款。
根据 Sokin 官方介绍，Checkout 可用于在线接收多币种付款，并将款项结算到相应币种账户。官方列出的支付能力包括银行卡、数字钱包、银行支付和部分本地支付方式，但并不是每个商户、每个国家和每个币种都会显示全部方式。最终可用能力取决于企业注册地、客户地区、行业、结算币种和 Sokin 审核结果。
官方介绍：Sokin Checkout；官方帮助中心：Sokin Checkout Support。
二、哪些商家适合接入
这套 Sokin 对接易支付方案比较适合以下用户：
- 已经拥有真实注册、持续经营的企业主体；
- 已经通过 Sokin 企业账户及 Payment Acceptance 审核；
- 运营跨境电商、外贸、SaaS、在线服务或其他合规网站；
- 希望在网站增加 Visa、Mastercard 等银行卡收款入口；
- 希望把 Sokin 与支付宝、微信、PayPal 或其他支付通道统一放进易支付管理；
- 需要通过 API 创建订单、自动回调、主动核单和退款；
- 需要将 Sokin 作为独立支付方式进行订单统计和通道路由。
如果还没有取得 Payment Acceptance 权限，应先完成官方申请。插件只能完成技术连接，不能帮助商户绕过资格审核，也不能保证银行卡、Apple Pay、Google Pay 或某个本地支付方式一定获批。
三、申请前应准备什么
Sokin 会根据企业主体、实际业务和网站内容开展审核。为了提高资料一致性，申请前建议准备：
- 有效的公司注册文件、董事及最终受益人资料；
- 真实的经营地址、联系方式和企业邮箱；
- 能够正常访问并使用 HTTPS 的业务网站；
- 清晰的商品或服务介绍以及真实价格；
- 服务条款、隐私政策、退款政策和交付说明；
- 预计月交易额、平均客单价、主要客户国家和收款币种；
- 必要时提供合同、发票、历史收款记录或供应链证明；
- 清楚说明客户从下单、付款到获得商品或服务的完整流程。
网站、公司、商品和申请表中的业务描述应保持一致。不要使用虚假业务、虚假地址、复制别人的网站或隐藏真实商品。支付机构可能在开户后持续复核商户，因此“先通过再更换成其他业务”的做法同样存在账户限制和资金风险。
四、开通 Sokin Payment Acceptance
登录 Sokin 企业后台后，找到 Checkout、Payment Acceptance 或在线收款相关入口，根据页面要求提交申请。如果后台没有入口，可以联系你的 Sokin 客户经理或官方支持团队，确认公司所在地区及行业是否可以申请。
审核中可能会要求补充网站所有权、商品说明、公司资料、交易规模、履约周期、退款处理方式和客户服务流程。审核通过后，后台才会开放 Checkout 配置和 API 凭据。
是否批准、审核时间、交易费率、保证金、结算周期和具体付款方式均由 Sokin 决定。不要向客户承诺“百分之百开户”或固定到账时间。
五、取得 X API Key
Payment Acceptance 获批后，在 Sokin Customer Portal 中进入：
Settings → Sokin Checkout API Configuration 或 Settings → Checkout configuration
找到或生成 X API Key。该密钥用于服务器调用 Sokin API 创建订单、查询订单和发起退款。Sokin 官方帮助中心列出的正式环境地址为：
API URL：https://payment-gateway.sokin.com/api/services/v1 Checkout URL：https://pay.sokin.com/sokinpay/customerPay
官方配置参考：Integrating the Payment Acceptance Plugin。
密钥安全：X API Key 只能保存在服务器和易支付支付通道配置中。不要把完整密钥放进文章、视频、截图、聊天群或公开代码仓库。
六、Sokin 易支付插件介绍
为了让已经通过 Sokin Payment Acceptance 审核的商户快速接入网站，我们开发了 Sokin Checkout 对接易支付插件。
客户在网站选择 Sokin 后，易支付先显示付款人姓名和邮箱页面，然后使用服务器端 X API Key 创建 Sokin Order，最后跳转至 Sokin 官方托管收银台。付款完成后，插件通过 Webhook 和订单查询接口核验交易，再更新易支付订单状态。
本插件属于第三方易支付扩展，并非 Sokin 官方开发、销售或背书。使用前必须自行获得 Sokin 的相应商户权限。
七、插件主要功能
- 对接 Sokin Checkout Orders API；
- 支持正式环境和 UAT/Sandbox 环境切换；
- 跳转 Sokin 官方 Hosted Checkout 托管收银台；
- 使用独立的 sokin 支付方式，便于统计和通道路由；
- 支持 EUR、GBP、USD、AED、AUD、CAD、CHF、HKD、JPY、SGD 等配置项；
- 支持同币种直接收款和手动金额换算系数；
- 收集 Sokin 创建订单所需的付款人姓名和电子邮箱；
- Webhook 到达后主动查询 Sokin 订单，不直接相信回调内容；
- 复核订单状态、金额、币种、Sokin Order ID 和商户订单号；
- 保存成功付款返回的 paymentId；
- 支持全额或部分退款请求，实际能力以账户权限为准；
- 同一易支付订单加锁，避免并发重复创建多个 Sokin Order；
- 校验 Checkout 跳转域名，防止异常地址被当作官方收银台。
这里列出的币种是插件可配置币种，并不代表你的 Sokin 商户已经全部获批。请只选择 Sokin 后台实际允许收款和结算的币种。
八、安装插件与图标
下载插件后，保持文件夹名称为 sokin，上传至易支付根目录：
/易支付根目录/plugins/sokin/
目录结构如下：
plugins/sokin/
├── sokin_plugin.php
├── README.md
└── inc/
└── SokinPayClient.php
将支付图标上传到：
/易支付根目录/assets/icon/sokin.ico
上传完成后进入易支付后台：
支付插件 → 刷新插件列表
如果列表没有立即出现，可以检查 PHP 文件权限、插件目录名和入口文件名，并清理 PHP OPcache 或站点缓存。不要把目录上传成 sokin/sokin/ 两层结构。
九、新增独立 Sokin 支付方式
进入：
易支付后台 → 支付方式 → 新增
| 配置项 | 建议填写 |
|---|---|
| 调用值 | sokin |
| 显示名称 | Sokin Checkout 或银行卡支付 |
| 支持设备 | PC + Mobile |
| 状态 | 开启 |
调用值必须使用小写 sokin。单独建立支付方式后，Sokin 订单不会与系统原来的 bank 类型混在一起，后期统计、通道路由和故障排查会更清楚。
十、新增 Sokin 支付通道
进入：
易支付后台 → 支付通道 → 新增通道
| 配置项 | 填写内容 |
|---|---|
| 显示名称 | Sokin Checkout |
| 支付方式 | Sokin Checkout |
| 支付插件 | Sokin Checkout |
| X API Key | Sokin 后台取得的完整密钥 |
| 运行环境 | 正式收款选正式；测试选沙箱 |
| 收款货币 | 选择账户实际获批币种 |
| 金额换算系数 | 同币种填 1 |
| 状态 | 测试无误后开启 |
保存后记下该通道的数字 ID，例如 12。Webhook 地址中的最后一段就是这个通道 ID。正式密钥与沙箱环境不能混用，否则通常会出现 401、403 或找不到订单。
十一、币种与金额换算系数
插件中的金额计算方式是：
Sokin 收款金额 = 易支付订单实付金额 × 金额换算系数
如果网站商品本身使用 EUR 计价，Sokin 通道也使用 EUR 收款，换算系数填写：
1
如果易支付使用人民币计价，Sokin 使用欧元收款，假设商户根据当时汇率和自身定价策略设置：
1 CNY = 0.12 EUR 金额换算系数 = 0.12 100 CNY × 0.12 = 12.00 EUR
不要把汇率方向填反。当前版本采用手动系数，跨币种经营的商户需要定期检查汇率，并考虑支付手续费、退款成本和价格波动。插件会将大多数币种保留两位小数，JPY 等零小数币种按整数金额处理；换算后的 Sokin 金额不能低于接口要求的最小值。
十二、域名白名单与回调域名
Sokin 可能要求商户提交用于 Checkout 或 Webhook 的网站域名并进行审核。建议提交真正承载易支付和回调接口的固定域名，例如：
pay.example.com
一般不需要把包含订单号、通道 ID 或长查询参数的每个完整链接都当成新域名提交。域名审核关注的是主机名，实际 Webhook 可以继续使用该域名下面的固定路径。
如果前端商城和支付网关使用不同域名，例如：
商城：www.example.com 支付网关：pay.example.com
应当向 Sokin 说明真正创建订单、接收回调并跳转 Checkout 的是 pay.example.com。不要频繁更换支付域名，HTTPS 证书、DNS、防火墙和 CDN 都要保持稳定。
十三、Webhook 应该怎么填写
假设易支付域名为：
https://pay.example.com
Sokin 通道 ID 为：
12
Webhook 地址就是：
https://pay.example.com/pay/webhook/12/
在 Sokin 后台的 Webhook Configuration 中，可按下面方式配置：
| Sokin 配置项 | 填写内容 |
|---|---|
| Order and Payment Status | https://pay.example.com/pay/webhook/12/ |
| Refund Status | https://pay.example.com/pay/webhook/12/ |
两个项目可以使用同一个已审核域名下的回调地址，不需要在地址后添加 API Key、Token 或随机长串参数。通道 ID 必须替换为你自己后台的真实 ID。插件的付款入账依赖支付状态通知后主动核单；退款请求由后台调用退款 API 发起，退款最终状态仍建议同时以 Sokin 后台记录为准。
十四、完整支付流程
接入完成后，一笔订单会经过以下流程：
- 客户在商城或业务网站创建订单；
- 网站通过易支付接口提交订单，并选择 type=sokin；
- 易支付验证商户签名并生成本地支付订单；
- 插件显示付款人姓名和电子邮箱表单；
- 客户点击“前往安全付款”；
- 易支付服务器使用 X API Key 调用 Sokin Orders API；
- Sokin 返回 orderId 和 corporateId；
- 浏览器跳转到 pay.sokin.com 官方托管收银台；
- 客户通过账户可用的银行卡或其他方式完成付款；
- Sokin 向易支付发送状态 Webhook；
- 插件再次查询 Sokin 订单并核对状态、金额、币种和订单号；
- 全部一致后，易支付订单更新为已支付并通知上游网站。
客户从 Sokin 页面跳回商户网站，只代表浏览器完成了回跳，不应单独作为付款成功依据。真正入账应以服务器端核验结果为准。
十五、上线前测试清单
建议先完成一笔可控的小额测试，不要在未验证回调前直接开放大额交易。
- 确认 Sokin 已批准 Payment Acceptance 和对应收款币种；
- 确认服务器 PHP 已启用 cURL、JSON 和 OpenSSL；
- 确认服务器可以访问 payment-gateway.sokin.com；
- 确认支付域名已加入 Sokin 白名单；
- 确认易支付通道填入正确环境的 X API Key；
- 新建一笔订单并选择 Sokin；
- 填写测试客户姓名和可以接收通知的邮箱；
- 确认最终跳转域名确实是 pay.sokin.com 或官方 UAT 域名；
- 完成付款后检查 Sokin 后台是否出现交易；
- 检查易支付订单是否自动更新为已支付；
- 检查易支付接口订单号是否保存 Sokin paymentId；
- 检查上游商城是否收到易支付异步通知；
- 选择符合条件的订单测试小额退款；
- 确认退款状态和金额在 Sokin 后台一致。
十六、插件如何保护支付回调
Sokin Checkout 的当前公开资料没有向插件提供一个可直接照搬的 Webhook 签名密钥配置项，因此插件不会仅凭一段外部 POST 内容就把订单改成已支付。
收到状态通知后，插件会：
- 解析 Webhook 中的商户订单号和 Sokin Order ID；
- 查询本地易支付订单是否存在；
- 检查订单实际使用的支付通道是否与 Webhook URL 中的通道一致；
- 读取本地保存的 Sokin Order ID；
- 使用服务器端 X API Key 主动调用 Sokin 查询接口；
- 确认远程订单状态已经处理成功；
- 核对订单金额、币种、Sokin Order ID 和 referenceNo；
- 从有效付款记录取得 paymentId；
- 全部一致后才调用易支付入账流程。
即使有人知道公开的 Webhook 地址，也不能只伪造一个“success”字段完成订单，因为插件还会通过 Sokin API 读取真实订单状态。
十七、退款功能说明
插件使用原成功付款记录中的 paymentId 调用 Sokin Refunds API，可发起全额或部分退款。操作前应确认：
- 原订单已经成功支付；
- 易支付订单中已经保存 paymentId；
- 退款币种与原收款币种一致；
- 退款金额没有超过可退余额；
- Sokin 账户具有退款权限和足够可用余额；
- 该付款方式仍在允许退款的时间和规则范围内。
API 接受退款请求不一定代表客户银行已经即时入账。实际退款速度取决于付款方式、卡组织、客户银行和 Sokin 的处理状态。
十八、对接上游网站或另一套易支付
部分运营者会使用两层结构：
商城或上游易支付
↓ epayn 标准接口
支付网关易支付
↓ Sokin Checkout API
Sokin 官方收银台
这种架构可以让多个网站统一使用一个已经配置好的 Sokin 网关。上游 epayn 插件需要允许 sokin 类型，并将目标网关的商户 PID、平台公钥、商户私钥和接口地址配置正确。
需要特别注意，Sokin 插件的付款人资料表单应固定提交到当前订单的本地支付地址：
https://pay.example.com/pay/submit/易支付订单号/
不能把姓名邮箱再次提交到 /api/pay/submit，否则第二次请求没有 epayn 的 pid 和签名参数，会出现“你还未配置支付接口商户”的提示。最新版插件已经处理这一流程。
十九、常见问题
1. Sokin 企业账户开通后，是否自动拥有网站收款功能？
不一定。企业账户、转账能力与 Payment Acceptance/Checkout 属于不同能力。必须确认后台已经批准在线收款，并且能够取得 Checkout 使用的 X API Key。
2. X API Key 应该填在哪里？
填写在易支付后台对应 Sokin 支付通道的 X API Key 配置项中。不要填入易支付商户 PID、签名密钥或其他 Sokin 登录密码。
3. 为什么能跳转，但 Sokin 页面没有银行卡或 Apple Pay？
付款方式由商户获批能力、客户设备、浏览器、地区、币种和风控共同决定。插件只能跳转到官方 Checkout，不能强制显示尚未批准或当前环境不支持的付款方式。
4. 为什么点击“前往安全付款”提示未配置支付接口商户？
这通常出现在上游 epayn 对接场景：付款资料表单错误地再次提交到了 /api/pay/submit。请升级插件，确保表单 action 指向 /pay/submit/当前订单号/，并使用新订单重新测试。
5. 为什么提示 X API Key 未配置或 API 返回 401/403？
检查密钥是否完整、是否带有多余空格、正式密钥是否误选沙箱环境、Sokin 是否已启用当前域名，以及商户的 Payment Acceptance 权限是否仍然有效。
6. 为什么 API 返回 422？
通常与姓名、邮箱、币种、金额或描述字段格式有关。新版插件会限制订单描述中的特殊字符，并检查邮箱、金额和三位币种代码。如果仍报错，应查看服务器错误日志中的 Sokin API 错误详情，但公开求助时不要贴出 API Key。
7. 为什么付款成功后易支付没有自动更新？
重点检查 Webhook URL 的通道 ID、域名白名单、HTTPS 证书、防火墙/CDN、服务器出站网络和 Sokin 订单查询结果。还要确认该笔订单实际选中的通道，就是 Webhook 地址中的通道。
8. Webhook 后面要不要加一长串 Token？
不需要。插件使用固定路径和通道 ID，并在收到通知后主动查询 Sokin 订单。示例格式为 https://pay.example.com/pay/webhook/12/。
9. 为什么支付金额不对？
检查“金额换算系数”方向。同币种填写 1；人民币转欧元应填写“1 人民币等于多少欧元”，而不是“1 欧元等于多少人民币”。
10. 是否支持退款？
插件已经接入退款接口并使用成功付款返回的 paymentId。实际能否退款、可退金额和处理时间，以 Sokin 账户权限及原付款方式规则为准。
11. 插件是否会保存客户银行卡资料？
不会。客户的银行卡及官方 Checkout 支付信息由 Sokin 收银台处理。插件只收集创建订单所需的姓名和邮箱，并保存支付订单关联信息。商户仍需在隐私政策中说明自己如何处理客户个人资料。
12. 可以直接用于高风险或违规业务吗？
不可以。商户只能经营 Sokin 已审核并允许的真实业务。插件不会规避地区、行业、制裁、反洗钱、卡组织或 Sokin 风控限制。
二十、插件咨询与获取
如果你已经通过 Sokin Payment Acceptance 审核，并希望把 Sokin Checkout 接入彩虹易支付、独立站或现有聚合支付系统，可以联系我们了解插件安装、通道配置、Webhook 联调和上游网站对接服务。
咨询前建议准备以下非敏感信息：
- 易支付系统版本和 PHP 版本；
- Sokin Payment Acceptance 是否已经获批；
- 需要使用的收款币种；
- 是否需要对接上游商城或另一套易支付；
- 报错文字和已遮挡敏感信息的截图。
请不要通过聊天发送完整 X API Key、服务器密码、数据库密码或客户银行卡资料。
总结
完整接入流程可以概括为：
准备真实企业和完整业务网站 → 申请并通过 Sokin Payment Acceptance → 在 Checkout Configuration 取得 X API Key → 安装 Sokin 易支付插件和图标 → 新增 sokin 支付方式及支付通道 → 设置币种和金额换算系数 → 提交支付域名白名单 → 配置 Order/Payment 与 Refund Webhook → 完成小额支付、自动回调和退款测试 → 正式上线并持续做好风控与对账
对于已经拥有合规业务和 Sokin Checkout 权限的商户，这套插件可以把 Sokin 官方托管收银台接入易支付，帮助多个网站统一管理 Sokin 订单、回调和退款。最终可用币种、付款方式、费率和结算安排，仍以 Sokin 后台显示及双方协议为准。
