Dhpay极简支付商户接入文档

版本:V1.0

密级:公开

Last: 2018/12/20

1.集成步骤

1.登陆https://www.dhpay.com 商家后台账户安全-概要菜单获取tokenizationKey。

2.申请开通nonce支付,运营审核配置接口权限;

3.技术开发初始化客户端JS,在客户端令牌化支付卡信息,获取nonce;

4.商户服务端获取accesstoken,提交支付,完成支付过程。

2.接口文档

1)商户端开发

  1. 客户端开发

    在付款页面嵌入dhpay-client.js

    <html>
    <body>
    <div id="insert-card"></div>
    <button id="submit-button">提交</button>
    </body>
    <script type="text/javascript" src="https://www.dhpay.com/frontend/js/jquery-3.2.1.min.js" ></script>
    <script type="text/javascript" src="https://www.dhpay.com/frontend/js/dhpayclient-1.0.0.min.js" ></script>
    <script type="text/javascript">
        console.log(DhpayNonce)
        var card = DhpayNonce.default.init('#insert-card', 'prod_BGHYlImaWy_200000000109510')
        card.on('success', function(payload){
            console.log(payload);
            console.log(payload.data.nonce);
            alert("付款金额:"+$('#amount').val()+" USD.");
            $.ajax({
                type: 'POST',
                url: '/rest/rest/noncepay/checkout',
                dataType:'json',
                data: {'paymentMethodNonce': payload.data.nonce,'paymentAmount':$('#amount').val(),'payload':JSON.stringify(payload) }
            }).done( function(result) {
                console.log(result);
                if (result.success) {
                    $('#submit-button').remove();
                    if(result.form3D){
                        $('#checkout-message').html(result.form3D);
                    }else
                        $('#checkout-message').html('<h1>Success</h1><p>Your Drop-in UI is working! Check your test transactions.</p><p>Refresh to try another transaction.</p>');
                } else {
                    $('#checkout-message').html('<h1>Error</h1><p>Check your console.</p>');
                }
            });
    
        })
        card.on('fail', function(error){
            alert(error);
            console.log(error)
        })
        $('button').on('click', function(){
            card.submit()
        })
    </script>
    </html>
    

    初始化成功唤起客户端付款界面(供参考);

    1544600562827

  2. 服务端开发

    参考对应语言demo程序集成付款接口,完成以下付款接口开发和相应付款逻辑处理;

    前端错误码:

错误码 错误消息 说明
E08 cardnum parity check false. 卡奇偶校验
E09 black cardbin check false. 卡黑名单检查
E10 card expire check false. 卡有效期校验
E11 cvv check failure. CVV校验
E05 params miss. 缺少参数

服务器端错误码请参考官网。或者使用dhpay-error.js对照;

2.)Nonce支付

商家服务端获取到NONCE后发起支付

状态含义: status=[00:处理中 | 01:成功 | 02:失败]

1)获取token

请求地址:

POST https://www.dhpay.com/api/oauth2/token

HTTP请求header参数
参数名 必须 说明 示例
Accept Y 参数提交类型 application/json
Client-Id Y 商户号 50517365
Secret Y 商户秘钥 WWdxJxwpwelij098723klhj089KSLi
请求失败:

{"status":"02","error_code":"E0002"}

请求成功:
{
"status": "01",
"data": {
"expires_in": 28800,
"token_type": "Bearer",
"access_token": "6817F5DEB3B0FB690FD8C0289F811F97"
}
}

2)支付提交

请求地址:

POST https://www.dhpay.com/api/payments/nonce/v1

HTTP请求header参数
参数名 必须 说明 示例
Content-Type Y 参数提交类型 application/json
Authorization Y auth请求获得 Bearer 5448780132C1E8DEA0F45E00DAB5866B
version Y API版本 v1
BODY参数:
参数名 是否必须 长度 说明 示例
tokenInfo 32 令牌化NONCE sandbox_tcc_877924e3442847afb3c234829b93ddd7
merchant_id 30 商户号 200000000167187
invoice_id 50 商户平台唯一交易ID TraderId20180101346
order_no 50 商户平台交易号 Order20180101346
currency 3 币种 USD
amount 20,2 金额 19.88
country 2 Billing 国家代码 US
product_name 200 商品名称 该字段需要 上报外管局 结汇时需要, 请按真实产 品名称传递 IPHONE1000
hash 150 签名
product_price 20,2 商品单价 19.88
product_quantity 10 商品数量 10
buyer_ip 100 买家IP 192.168.1.2
buyer_email 30 买家邮箱 test@dhgate.com
state 50 Billing 州省 alabama
city 50 Billing 城市 newyork
first_name 50 Billing 名 Jordan
last_name 50 Billing 姓 Steven
address_line 500 Billing 地址 Bboolltem st.02
phone 2-50 账单电话 13666655554
zipcode 4-10 Billing 邮编 1005523
shipping_country 2 货运国家 US
shipping_first_name 50 shipping 名 Jordan
shipping_last_name 50 shipping 姓 Steven
shipping_address_line 500 shipping 地址 Bboolltem st.02
shipping_city 50 shipping 城市 newyork
shipping_state 50 shipping 州省 alabama
shipping_zipcode 4-10 shipping 邮编 1005523
shipping_email 30 shipping email test@dhgate.com
shipping_phone 2-50 shipping 电话 02056874321
return_url 500 支付完成返 回地址,如果 不填则以商 户设置为准 http://www.dhpay.com/callback
remark 1000 备注 备注
notify_url 500 异步通知地址(建议上送) http://www.dhpay.com/notify
buyer_id 40 用户在商户平台的唯一标识 2455611

请求示例:

{  
   "requestParam":{  
      "phone":"",
      "shipping_state":"",
      "remark":"",
      "product_name":"20180806092337115293 -- 1519",
      "product_quantity":"1",
      "state":"",
      "shipping_address_line":"",
      "record_website":"dhpay.com",
      "order_no":"A2018231251232",
      "invoice_id":"A2018231251232",
      "currency":"USD",
      "city":"",
      "shipping_zipcode":"",
      "amount":"12.30",
      "first_name":"",
      "buyer_email":"",
      "shipping_phone":"",
      "shipping_last_name":"",
      "merchant_id":"200000000109510",
      "buyer_id":"",
      "shipping_country":"",
      "product_price":"12.30",
      "shipping_first_name":"",
      "zipcode":"",
      "shipping_city":"",
      "notify_url":"",
      "shipping_email":"",
      "address_line":"",
      "country":"US",
      "product_prices":"",
      "return_url":"",
      "buyer_ip":"108.95.144.100",
      "last_name":""

   },
   "cardParam":{  
        "tokenInfo":"sandbox_tcc_877924e3442847afb3c234829b93ddd7"
   }
}
返回值
  • API请求失败
{"status":"02","error_code":"E0002"}
  • API请求成功(NO3D返回),status=01,

  • 返回data为交易结果,data.status=01 成功, 交易完成;

    返回data为交易结果, data.status=02失败,需要进一步检查失败原因。

{
    "status": "01",
    "data": {
        "currency": "USD",
        "amount": "0.01",
        "status": "02",
        "merchant_id": "200000000167187",
        "invoice_id": "123123123123123123",
        "order_no": "11223344",
        "ref_no": "20171222094007_051464",
        "failure_reason": "M0092",
        "trans_date": "20171222",
        "trans_time": "094008"
    }
}
  • API请求成功(3D返回),status=01,返回data为交易结果

  • data.status=00处理中,需要进一步3D验证

    关于3D支付返回,商户需要在前端页面跳转到redirect_url,以便用户输入3D验证码。用户输入3D验证码并提交后,DHPAY会通过回调接口即时通知支付结果。请参考Web回调参数文档

跳转方式

将MD、TermUrl、paReq、orderId、transactionId、sessionToken字段POST到redirect_url页面

注意参数的键区分大小写

3D FORM Demo:

<from action="https://pit.3dsecure.net/VbVTestSuiteService/pit1/acsService" method="POST">
    <input type="hidden" name="MD" value = "20180807104133_055653"/>
    <input type="hidden" name="paReq" value = "eJxVUdtuwjAM/ZWK95ELBTrkRioDbWgqQxsS7DExxxxx======"/>
    <input type="hidden" name="TermUrl" value = "https://www.dhpay.com/merchant/bank/notify/mscskCallback"/>
    <input type="hidden" name="orderId" value = "232571063"/>
    <input type="hidden" name="transactionId" value = "1513061066"/>
    <input type="hidden" name="sessionToken" value = "123dfde9-509a-4877-a856-08c608c53fc6"/>
</from>
{
    "status": "01",
    "data": {
        "invoice_id": "A201823125",
        "merchant_id": "200000000109510",
        "order_no": "A201823125",
        "currency": "USD",
        "amount": "122.80",
        "trans_date": "20180807",
        "trans_time": "104146",
        "ref_no": "20180807104133_055653",
        "status": "00",
        "failure_reason": "",
        "redirect_url": "https://pit.3dsecure.net/VbVTestSuiteService/pit1/acsService",
        "paReq": "eJxVUdtuwjAM/ZWK95ELBTrkRioDbWgqQxsS7DExxxxx======",
        "TermUrl": "https://www.dhpay.com/merchant/bank/notify/mscskCallback",
        "MD": "20180807104133_055653",
        "orderId": "232571063",
        "transactionId": "1513061066",
        "sessionToken": "123dfde9-509a-4877-a856-08c608c53fc6"
    }
}
返回参数说明
参数 长度 示例 说明
currency 3 USD 交易币种
amount 20,2 101.02 交易金额
status 2 01 交易状态; 00 处理中 01 成功 02 失败
merchant_id 50 2000000187 交易商户号
invoice_id 30 MaTest346 商户平台交易流水号
order_no 30 MaTest346 商户平台交易流水号
failure_reason 10 M0023 失败原因错误码;成功时为空
ref_no 50 20180102151521_051768 DHPAY交易参考号
redirect_url 500 https://0eafstag.cardmerce.com/EAF 3D交易跳转地址
paReq 500 VUdtuwjAM/ZWK95ELBTrkRioDbWgqQxsS7DExxxxx== 3D跳转提交参数
TermUrl 500 dhpay回调地址 3D回调地址
MD 21 20180807104133_055653 3D跳转提交参数
orderId 30 232571063 3D跳转提交参数
transactionId 30 1513061066 3D跳转提交参数
sessionToken 50 123dfde9-509a-4877-a856-08c608c53fc6 3D跳转提交参数
trans_date 8 20180722 交易日期
trans_time 6 182201 交易时间

3.API通信错误码

E0001=resource is not exsits
E0002=token is not exsits
E0003=module not exists or disabled
E0004=api not exists or disabled
E0005=module not exists or disabled
E0006=api not exists or disabled
E0007=IP black list
E0008=unknown error
E0009=DomainName black list
E0010=not found Client-Id, token may be out of date
E0011=Account black list
E0012=not found Api-Id, resource not found
E0013=do not have this Api-Authority
E0014=Accept is empty
E0015=Client-Id is empty
E0016=Secret-Id is empty
E0017=Client-Id or Secret is not correct
E0018=Route failure, Please contact DHpay
E0404=404
E0405=405
E0505=505

results matching ""

    No results matching ""