接入指南

欢迎使用 Adopay OpenAPI。

本指南将帮助您完成接入模式确认、账户注册、KYB/KYC 认证、Sandbox 联调及生产环境上线。

接入流程总览

%%{init: {"flowchart": {"nodeSpacing": 30, "rankSpacing": 40, "wrappingWidth": 360}}}%%
flowchart LR
    START(["开始接入"]) --> MODE{"确认接入模式"}
    MODE -->|"商户直连接入"| SIGN1["与 Adopay 商务签约<br>运营侧后台开户"]
    MODE -->|"合作商接入"| SIGN2["与 Adopay 商务签约<br>确认 accessMode 与 subMerchantNo"]
    SIGN1 --> REG["注册控制台账户（管理员 + MFA）"]
    SIGN2 --> REG
    REG --> KYB["准备并提交 KYB / KYC 材料"]
    KYB --> AUDIT{"合规审核"}
    AUDIT -->|"需补件 / EDD"| FIX["按控制台或邮件通知补充材料"]
    FIX --> AUDIT
    AUDIT -->|"审核通过"| CONSOLE["访问控制台"]
    CONSOLE --> CREDS["获取 Sandbox 凭证<br>登记 P-256 公钥"]
    CREDS --> DEV1["实现签名、验签与幂等"]
    DEV1 --> DEV2["配置 Webhook 接收地址"]
    DEV2 --> TEST["Sandbox 跑通首笔收款与代付"]
    TEST --> PASS{"联调验收通过？"}
    PASS -->|"否，排查修复"| DEV1
    PASS -->|"是"| PROD["申请生产环境<br>完成上线检查清单"]
    PROD --> LIVE(["正式上线"])

1. 确认接入模式

开始接入前，请与 Adopay 商务或实施经理确认客户类型、账户模式及所需产品能力。

账户模式由客户主体、业务场景、开户材料及合规审核结果决定，不能仅通过 API 自行选择或变更。

客户可以根据合作方案申请账户、Pix 收付款、批量付款、FX 换汇、跨境结算、分账、退款与 MED、报表对账等能力。具体产品、币种及限额以实际开通结果为准。

两种接入模式

ADOPAY 采用一套公共能力平台 + 两种接入模式：

                       ADOPAY
                          │
             ┌────────────┴────────────┐
             │                         │
       商户直连接入               合作商接入
             │                         │
             │                    ┌────┼────┐
             │                    │    │    │
             │                   M-A  M-B  M-C
             │
        自有交易 / 自有资金

维度	商户直连接入	合作商接入
适用对象	处理自有交易的商户	平台、ISV、PSP、收单机构等管理多个下游商户的合作方
API Credential	商户自持	合作商自持
API 调用方	商户	合作商（代表下游商户）
交易归属	商户	下游商户（subMerchantNo）
Webhook 接收方	商户	合作商
资金 / 结算归属	商户	按合作模式配置
开户方式	线下商务签约，后台开户，无需 Create Merchant 接口	合作商凭证接入，下游商户以二级商户形式管理

如何选择：

• 只处理自己的交易与资金 → Merchant API
• 需要替多个下游商户统一接入、调用与接收回调 → Partner API

两种模式复用同一交易核心：收款 / 退款 / 代付的字段与能力模型保持一致，合作商侧仅增加二级商户维度（accessMode、subMerchantNo）。

确认开户与接入参数

1. 与商务完成签约；开户由 ADOPAY 运营侧完成，商户模式不存在线上开户接口。
2. 合作商模式请同时确认接入模式参数 accessMode（normal / saas_isv / acquirer / platform）与二级商户号 subMerchantNo 的分配方式。

2. 注册控制台账户

合作确认后，Adopay 将向客户管理员发送控制台邀请。

管理员需要完成：

1. 填写管理员姓名、工作邮箱及手机号码；
2. 验证邮箱和手机号码；
3. 设置登录密码；
4. 接受适用的服务协议；
5. 配置多因素身份验证（MFA）。

控制台注册成功不代表已经完成 KYB/KYC 或获得生产交易权限。

请勿多人共用管理员账户。客户可以为技术、财务、运营及风控人员创建独立用户，并根据职责配置角色权限。

3. 完成 KYB/KYC 认证

为满足巴西适用的金融、支付及反洗钱监管要求，客户必须完成相应的身份和业务审核。

企业 KYB

企业客户通常需要提交：

• 公司注册证明及最新公司章程；
• 税务登记和注册地址证明；
• 股东名册、股权结构及最终受益所有人信息；
• 法定代表人、UBO 及授权人的身份和地址证明；
• 官网、业务介绍或客户合同等经营证明；
• 同名结算账户证明；
• 业务模式、资金流及预计交易规模。

机构客户补充材料

支付机构、PSP、ISV 或平台客户还可能需要提供：

• 适用的金融、支付、MSB 或 VASP 牌照；
• AML、制裁及商户管理政策；
• 下游商户类型及主要行业；
• 代收、代付、换汇和结算资金流；
• 投诉、退款、MED 和 RFI 处理机制。

个人 KYC

法定代表人、UBO、授权签署人或其他关键人员通常需要提供：

• 法定姓名及税务识别号；
• 有效身份证件；
• 地址证明；
• 人脸识别或手持证件自拍；
• 手机号码及邮箱验证。

4. 审核与补件

提交申请后，Adopay 合规团队将进行审核。

审核状态与时效说明待补充。

如需补件，Adopay 将通过控制台或预留的工作邮箱通知客户。部分客户或业务场景可能需要进行强化尽职调查（EDD）。

请确保提交的材料真实、完整、清晰且在有效期内。完成基础 KYB/KYC 不代表所有产品能力均会自动开通。

5. 访问控制台

审核通过后，客户可以根据已授权的角色使用 Adopay 控制台，包括：

• 商户及账户管理；
• 余额和资金流水查询；
• Pix Key 及 Pix 交易管理；
• MED、RFI 及补件处理；
• 对账报表下载；
• API 凭证和 Webhook 配置；
• 用户、角色及安全设置。

实际功能以客户已开通的产品权限为准。

6. 获取 Sandbox 凭证

完成初步审核并确认技术方案后，Adopay 将开通 Sandbox 环境。

开通时 Adopay 分配商户号与密钥版本，并提供 Sandbox 环境地址及用于验签的平台公钥。P-256 密钥对由客户自行生成，公钥提交 Adopay 登记后生效：

• 商户号：Adopay 分配的商户标识，请求时通过 X-Merchant-Id 传递；Partner 模式使用一级商户号。
• 密钥版本：通过 Authorization 中的 keyId 标识，用于密钥轮换。
• P-256 私钥：客户自行生成并保管，用于生成 ES256 请求签名。
• P-256 公钥：提交 Adopay 登记，用于 Adopay 校验请求签名。
• 平台公钥：随开户材料提供，用于校验响应及 Webhook 通知的 ES256 签名。
• Sandbox 环境地址：开通时由 Adopay 提供。

Sandbox 与 Production 使用完全独立的凭证。密钥只能保存在服务端安全环境中，不得写入前端代码、移动端应用或公开代码仓库。

进入联调前，请先阅读公共规范：认证、请求签名（含验签）、响应格式 / 响应状态码、幂等、错误码、日期与时间 / 金额与币种、Webhook 规范。

7. 开始 API 联调

建议按照以下顺序完成接入。

第一步：实现签名和幂等

按照"认证与签名"章节生成请求签名。

所有创建订单、付款、退款、换汇及结算请求均须传递唯一幂等键：

Idempotency-Key: {unique-value}

发生网络超时后，应先查询原请求结果，不得直接更换幂等键重复提交。

第二步：配置 Webhook

POST /v4/webhook-endpoints

Webhook 接收地址必须使用 HTTPS，并能够：

• 验证 Webhook 签名；
• 根据 event_id 进行去重；
• 处理重复或乱序通知；
• 在规定时间内返回 2xx 状态码。

当前文档体系中，回调地址也可通过订单请求中的 notifyUrl 字段指定，或由商户后台 / 运营侧统一配置；投递、验签、重试与响应要求见 Webhook 规范。

第三步：完成 Sandbox 测试与首笔交易

先分别跑通一笔收款和一笔代付，再按测试重点逐项覆盖。

跑通首笔收款：

1. 调用收款下单接口创建 Pix 动态二维码订单：
   • Merchant：创建支付 / 二维码
   • Partner：收款下单
2. 将返回的 qrCodeUrl 渲染为二维码或复制给付款人。
3. 等待支付结果 Webhook；也可通过订单查询接口主动查询：
   • Merchant：按商户订单号查询支付
   • Partner：收款订单查询

跑通首笔代付：

1. 调用代付接口，提供收款人信息与 Pix Key：
   • Merchant：创建 PIX 代付
   • Partner：代付请求
2. 等待代付结果 Webhook；也可主动查询订单状态：
   • Merchant：查询 PIX 代付
   • Partner：代付订单查询

测试重点：

• 鉴权、签名及幂等；
• Webhook 验签、重试及去重；
• 商户、账户及 Pix Key；
• Pix 收款、付款、退款及异常状态；
• 付款凭证；
• FX 报价、锁价及执行；
• 交易、余额、费用及结算对账。

异步请求的最终结果，以资源查询接口或 Webhook 通知为准。

8. 申请生产环境

Sandbox 测试完成后，请向 Adopay 实施经理提交上线申请。

上线前，双方需要确认：

• KYB/KYC 及必要的 EDD 已经完成；
• 合同、报价及结算条款已经生效；
• 产品权限、账户模式、币种及限额已经确认；
• 同名及非同名交易规则已经确认；
• 生产 IP 白名单及 Webhook 已经配置；
• MED、RFI 及异常交易处理流程已经确认；
• Sandbox 测试及对账验收已经通过。

技术上线检查清单：

• 签名 / 验签在沙箱与生产均通过
• Webhook 地址可公网访问，3 秒内响应，且已做验签与去重
• 所有超时 / 未知异常场景都会回查订单状态，绝不直接判定终态
• 幂等处理：同一订单号重复通知不会重复入账
• 金额单位与币种处理正确（详见金额与币种）
• 合作商模式：accessMode 与 subMerchantNo 与运营侧确认一致

审核通过后，Adopay 将单独提供 Production Base URL 及生产环境凭证。

9. 实用提示

• 文件质量：上传材料应清晰完整，不得遮挡、反光或裁剪。
• 账户安全：请启用 MFA 并定期轮换 API 凭证。
• 状态判断：异步交易不能仅根据 HTTP 响应判断最终结果。
• 环境隔离：Sandbox 与 Production 的地址、凭证和数据相互独立。
• 技术支持：提交问题时，请提供环境、接口路径、请求时间、X-Request-Id 及相关资源 ID。
• 生产权限：Sandbox 测试通过不代表生产权限自动开通。