AdYen 支付对接

AdYen 是处于荷兰的支付公司, 具备有网上支付牌照和超低的手续费率等大量优点

对于国内出海来说, 只需要看超低手续费率就可以了(PayPal这种高额手续费不推荐), 但是需要注意以下问题

  • 信用卡支付体系: 海外性用卡拒付周期很长, 一旦申诉拒付失败会有相应罚金

  • 海外收款转国内: 无法直接人民币结算到中国大陆对公账户, 必须走 外币→境外账户→结汇回国

  • 黑五类等审核严格: 仿牌/黑五类/虚拟商品之类申请手续麻烦, 并且有很大封号风险

可以经由香港公司以服务费用转到国内进出口公司(需账务审计), 或者跨境PSP中转(万里汇)缴纳中转费用

这里主要将以技术方面出发来做海外第三方系统支付对接, 所以商户账号申请这部分可能没这么详细

开发文档: https://docs.adyen.com/get-started-with-adyen

初始化

首先就是向 AdYen 提交商户相关信息, 如果是公司/企业角色最好找专家处理专门对接事项

高周转金额最好找 AdYen 的商户经理做对接, 可以更快响应支付当中的问题(须英语交流)

AdYen 目前支持以下类别主体申请成为商户主体

  • 公司: 具备有海外的公司主体信息(支持香港), 涵盖法人代表和公司地址

  • 个人：具备有个人护照和境外开户银行账号(支持香港), 涵盖独立跨境服务站点等信息

  • 个体户: 个体户分为国内和海外个体户, 都需要各自所在地区的营业执照, 但 Adyen 不接受内地银行账户

中国的个人|个体户审核很难通过, 并具有年度最高额度限制(每年5w美元结汇额度), 不推荐申请该主体

保证商户审核通过获取账号密码, 就可以登陆 AdYen 商户后台: https://ca-live.adyen.com/ca/ca/overview

有 live 和 test 两个入口, 分别是正式上线和开发中的后台入口

一般可以现在测试后台开始做初期的对接需求, 也可以直接在正式环境配置完成跑小额支付

开发配置

在进入后台之后需要按照以下流程处理

1. 后台侧边栏选择支付配置(Developers -> API credentials)

在页面点击 创建新的凭证信息(Create new credential), 这里弹出创建菜单填写方式如下

  • 凭证类型(Credential type): 直接选择 Web服务(Web service user) 即可

  • 描述信息(Description): 这里只是作为后台补充的可见信息, 该项是作为可选填写

之后点击创建就会在页面新增类似 ws_123456@Company 凭证信息项, 后面需要再回来该页面配置

2. 后台侧边栏选择回调配置(Developers -> Webhook)

在页面点击 创建新WebHook(Create new webhook), 这里弹出创建菜单填写方式如下

  • 直接添加 标准 WebHook(Standard webhook) 即可(一般就是首个选项)

创建完成之后选择创建 WebHook 做详细设置(服务器配置(Server configuration)/安全(Security)/事件(Events)):

  • URL: 我们的服务端回调地址, 必须保证地址可以访问

  • Method: 回调响应的数据模式, 保持默认 JSON 即可, 可选有 JSON, HTTP POST, SOAP

  • Encryption protocol: 回调响应的协议, 保持默认即可, 可选有 TLSv1.2, TLSv1.3

  • HMAC Key: 服务器对接的 HMAC 密钥, 可以生成之后保存本地, 开发回调认证需要用到

  • Events 选项保持默认即可, 除非你需要监听所有的操作事件

主要的就是生成的 HMAC Key, 必须和商户名标识一起移交给服务端那边做支付开发

3. 后台侧边栏选择支付配置(Developers -> API credentials)

点击之前创建好的 凭证(credential) 用户名来进入配置详情页面:

  • 生成ApiKey(Server settings -> Authentication): 可以点击 生成API Key(Generate API key) 生成保存本地

  • 添加IP白名单(Add an allowed IP range):: 将涉及到和 AdYen 交互的服务器 IP 地址都填写上去

ApiKey 生成格式: 测试 KEY 为 test_xxx, 正式 KEY 为 live_yyy

保存完成之后, 目前就有以下信息可以提供支付对接

  • Merchant Account：商户标识, 一般在商户后台的最左上角选择商户账户有复制按纽, 可以直接点击复制

  • HMAC Key: 服务端用的回调和创建订单 KEY

  • API Key: 客户端请求 AdYen 的对接 KEY

之后就是按照自身业务的订单创建和页面渲染

4. 服务端创建订单

服务端对接文档: https://docs.adyen.com/marketplaces/checkout-components

AdYen 官方目前提供 Java/PHP/C#/NodeJS/Go/Python/Ruby 服务端对接方案, 按照项目编程语言来选择即可

主要服务端对接成功之后返回 id(字符串, 订单ID) 和 sessionData(对象组, 详细数据) 就是客户端需要支付窗口渲染信息

核心就是最后的支付完成返回 sessionData 对象, 用于提供给客户端和 AdYen 做渲染组件处理

5. 客户端渲染组件

客户端对接文档: https://docs.adyen.com/marketplaces/checkout-components#create-the-component

在服务端创建完成订单返回 session.id 和 session.sessionData 就可以引入对应 css/js 唤起前端组建:

1
2
3
4
<!-- 引入 AdYen 相关样式和库 -->
<!-- 这里版本库还是采用官方的 6.16.0, 可以自行选择最新版本  -->
<link rel="stylesheet" href="https://checkoutshopper-live.adyen.com/checkoutshopper/sdk/6.16.0/adyen.css">
<script src="https://checkoutshopper-live.adyen.com/checkoutshopper/sdk/6.16.0/adyen.js"></script>

如果采用原生页面集成(不含React等技术), AdYen 的 JS 类库需要在 window.AdyenWeb 引入:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
// 原生 HTML 从 window 之中提取组建库

// 1. 创建支付组件实例
const {AdyenCheckout, Dropin, Card, GooglePay, PayPal} = window.AdyenWeb;

// 2. 配置相关的支付参数
const configuration = {
    environment: "live", // 生产环境使用 "live", 测试环境用 test
    clientKey: 'live_abcd....', // 从 Adyen 后台配置的 API KEY
    analytics: {
        enabled: true
    },
    session: {
        id: 'CSD9CAC3...', // 服务端对接获取的 AdYen 订单ID 
        sessionData: 'Ab02b4c...', // 服务端对接获取的 AdYen 会话详情 
    },
    amount: {
        value: 1000, // 最小单位货币
        currency: 'EUR', // 单位货币代码
    },

    // 直接让 adyen 处理地区信息
    locale: locale,
    countryCode: countryCode,

    // 请求完成
    onPaymentCompleted: (result, component) => {
        // 用户完成支付之后的回调
        // 注意: 支付完成不等于支付成功, 这里可能会返回支付某些异常问题
        console.info(result, component);
    },

    // 支付异常
    onPaymentFailed: (result, component) => {
        // 用户支付异常返回的回调, 比如被支付过程被判定为异常
        console.info(result, component);
    },

    // 请求错误
    onError: (error, component) => {
        // 用户请求的通用错误回调, 比如被拉黑的用户或者意想不到的网络错误
        console.error(error.name, error.message, error.stack, component);
    }
};


// 3. 创建前端支付组件, 建议对 dropin 对象做全局管理避免被重复创建
const checkout = await AdyenCheckout(configuration);
const dropin = new Dropin(checkout, {
    paymentMethodsConfiguration: {
        card: {
            // Optional configuration.
            hasHolderName: true, // Show the cardholder name field.
            holderNameRequired: true, // Mark the cardholder name field as required.
        }
    }
});

6. 支付渠道配置

这部分实际上不属于开发来处理, 该配置需要在开发后台的自行开通支付渠道(比如万事达/Visa之类)

一般这部分需要等运营去配好海外香港支付账户信息, 否则可能会出现发起支付成功但是支付过程失败的问题

不过一般走到这里就代表支付系统已经调通, 剩下的就是支付完成回调状态和其他结汇和申诉相关方面