• 新平台

本文对Webhook异步通知的配置进行了简单介绍。包括如何配置Webhook，常见的Webhook使用类型及示例，安全性相关：IP白名单，Header中Auth验证，验签方式及代码示例。
官网文档地址：https://www.checkout.com/docs/reporting-and-insights/webhooks

如何配置Webhook

商户可以在Hub后台直接进行Webhook的配置，具体操作流程如下：
Step 1，登录Hub后台
image.png
Step 2，打开Settings->Channels
右下角点击 “New Webhook” 进行添加
image.png

Step 3，输入贵司接受Webhook异步通知的网关地址，选择API版本v2.0，并根据业务需要勾选Webhook类型。
image.png

Step 4，完成配置，点击可以查看配置及Private shared key，这个key将出现在每一笔Webhook请求的HTTP Header中，可以用于安全校验
image.png
image.png

常见Webhook类型

建议添加的Webhook类型如下，尤其是绿色标注部分：

Webhook 类型 描述
Payment approved 授权成功，待请款
Payment captured 请款成功（扣款成功）
Payment declined 支付失败
Payment refunded 退款成功
Payment refund declined 退款失败
Payment chargeback 发生拒付

具体示例：
HTTP Header：

authorization 9b715918-466e-421f-b9f0-b03a6fbe4d60
cko-signature bf213e71463459a4d3dff58374e58e5f33ef15117f592873b96b3e67ea8b21e4

其中authorization对应的Value即Hub配置信息中的Private shared key
cko-signature是对报文体加签得到的签名，亦可以用作安全验证

Body：

  1. {
  2.   "id": "evt_vha2gih6tl5u5ebrpajhm727fe",
  3.   "type": "payment_approved",
  4.   "created_on": "2019-06-07T08:25:21Z",
  5.   "data": {
  6.     "action_id": "act_waji5li3mqtetnaor77xmow4bq",
  7.     "payment_type": "REGULAR",
  8.     "auth_code": "007895",
  9.     "response_code": "10000",
  10.     "response_summary": "Approved",
  11.     "scheme_id": "638284745624527",
  12.     "source": {
  13.       "id": "src_isu5yyegxg4e5l5yadnpu6y744",
  14.       "type": "card",
  15.       "billing_address": {},
  16.       "expiry_month": 12,
  17.       "expiry_year": 2025,
  18.       "scheme": "VISA",
  19.       "last_4": "4242",
  20.       "fingerprint": "71580b426f1d190d29087ff265d8f48df1ad34ede41c27cbff9d23c1a14d1776",
  21.       "bin": "424242",
  22.       "card_type": "Credit",
  23.       "card_category": "Consumer",
  24.       "issuer": "JPMORGAN CHASE BANK NA",
  25.       "issuer_country": "US",
  26.       "product_id": "A",
  27.       "product_type": "Visa Traditional",
  28.       "avs_check": "S",
  29.       "cvv_check": ""
  30.     },
  31.     "customer": {
  32.       "id": "cus_gs47qn23bqmefhkmlpokm7vzxm"
  33.     },
  34.     "processing": {
  35.       "acquirer_transaction_id": "8137549556",
  36.       "retrieval_reference_number": "000007895269"
  37.     },
  38.     "amount": 10000,
  39.     "metadata": {},
  40.     "risk": {
  41.       "flagged": false
  42.     },
  43.     "id": "pay_waji5li3mqtetnaor77xmow4bq",
  44.     "currency": "EUR",
  45.     "processed_on": "2019-06-07T08:25:21Z",
  46.     "reference": "ORD-5023-4E89"
  47.     },
  48.   "_links": {
  49.     "self": {
  50.       "href": "https://api.sandbox.checkout.com/events/evt_vha2gih6tl5u5ebrpajhm727fe"
  51.     },
  52.     "payment": {
  53.       "href": "https://api.sandbox.checkout.com/payments/pay_waji5li3mqtetnaor77xmow4bq"
  54.     }
  55.   }
  56. }
  1. {
  2.   "id": "evt_h3wfa5symn3ehof6fbgilpu5fm",
  3.   "type": "payment_declined",
  4.   "created_on": "2019-06-07T08:27:26Z",
  5.   "data": {
  6.     "action_id": "act_pfyq4sdkrvoexn737g2e26c3xm",
  7.     "payment_type": "REGULAR",
  8.     "auth_code": "000000",
  9.     "response_code": "20005",
  10.     "response_summary": "Declined - Do Not Honour",
  11.     "scheme_id": "638284745624527",
  12.     "amount": 5,
  13.     "source": {
  14.       "id": "src_isu5yyegxg4e5l5yadnpu6y744",
  15.       "type": "card",
  16.       "expiry_month": 12,
  17.       "expiry_year": 2025,
  18.       "scheme": "VISA",
  19.       "last_4": "4242",
  20.       "fingerprint": "71580b426f1d190d29087ff265d8f48df1ad34ede41c27cbff9d23c1a14d1776",
  21.       "bin": "424242",
  22.       "card_type": "Credit",
  23.       "card_category": "Consumer",
  24.       "issuer": "JPMORGAN CHASE BANK NA",
  25.       "issuer_country": "US",
  26.       "product_id": "A",
  27.       "product_type": "Visa Traditional",
  28.       "avs_check": "S",
  29.       "cvv_check": ""
  30.     },
  31.     "customer": {
  32.       "id": "cus_gs47qn23bqmefhkmlpokm7vzxm"
  33.     },
  34.     "processing": {
  35.       "acquirer_transaction_id": "8137549596",
  36.       "retrieval_reference_number": "000896481776"
  37.     },
  38.     "id": "pay_pfyq4sdkrvoexn737g2e26c3xm",
  39.     "currency": "EUR",
  40.     "processed_on": "2019-06-07T08:27:26Z",
  41.     "reference": "ORD-5023-4E89"
  42.   },
  43.   "_links": {
  44.     "self": {
  45.       "href": "https://api.sandbox.checkout.com/events/evt_h3wfa5symn3ehof6fbgilpu5fm"
  46.     },
  47.     "payment": {
  48.       "href": "https://api.sandbox.checkout.com/payments/pay_pfyq4sdkrvoexn737g2e26c3xm"
  49.     }
  50.   }
  51. }
  1. {
  2.   "id": "evt_6aznipgxbuaure3qen5qbzyswy",
  3.   "type": "payment_captured",
  4.   "created_on": "2019-06-07T08:25:22Z",
  5.   "data": {
  6.     "action_id": "act_gse7gcrhleuedmzhq25n3mhweq",
  7.     "response_code": "10000",
  8.     "response_summary": "Approved",
  9.     "amount": 10000,
  10.     "processing": {
  11.       "acquirer_transaction_id": "8137549557",
  12.       "acquirer_reference_number": "000220552364"
  13.     },
  14.     "id": "pay_waji5li3mqtetnaor77xmow4bq",
  15.     "currency": "EUR",
  16.     "processed_on": "2019-06-07T08:25:22Z",
  17.     "reference": "ORD-5023-4E89"
  18.   },
  19.   "_links": {
  20.     "self": {
  21.       "href": "https://api.sandbox.checkout.com/events/evt_6aznipgxbuaure3qen5qbzyswy"
  22.     },
  23.     "payment": {
  24.       "href": "https://api.sandbox.checkout.com/payments/pay_waji5li3mqtetnaor77xmow4bq"
  25.     }
  26.   }
  27. }
  1. {
  2.   "id": "evt_rmbwhvwacc7u5iczmz2tdcogum",
  3.   "type": "payment_refunded",
  4.   "created_on": "2020-02-03T11:35:03Z",
  5.   "data": {
  6.     "action_id": "act_7fmebms4rtmuja2poigylogjk4",
  7.     "response_code": "10000",
  8.     "response_summary": "Approved",
  9.     "reference": "ORD-5023-4E89",
  10.     "amount": 200,
  11.     "processing": {
  12.       "acquirer_transaction_id": "7026208384",
  13.       "acquirer_reference_number": "773993129364"
  14.     },
  15.     "id": "pay_pswr5qaqzzferh2puzfyrefzuy",
  16.     "currency": "GBP",
  17.     "processed_on": "2020-02-03T11:35:03Z",
  18.     "metadata": {
  19.       "coupon_code": "NY2018",
  20.       "partner_id": 123989
  21.     }
  22.   },
  23.   "_links": {
  24.     "self": {
  25.       "href": "https://api.checkout.com/events/evt_rmbwhvwacc7u5iczmz2tdcogum"
  26.     },
  27.     "payment": {
  28.       "href": "https://api.checkout.com/payments/pay_pswr5qaqzzferh2puzfyrefzuy"
  29.     }
  30.   }
  31. }
  1. {
  2.   "id": "evt_z5w4pkadoi3u5hu5lmlklwrxla",
  3.   "type": "payment_refund_declined",
  4.   "created_on": "2018-04-10T08:12:14Z",
  5.   "data": {
  6.     "id": "pay_y3oqhf46pyzuxjbcn2giaqnb44",
  7.     "action_id": "act_y3oqhf46pyzuxjbcn2giaqnb44",
  8.     "amount": 6540,
  9.     "currency": "USD",
  10.     "response_code": "20120",
  11.     "response_summary": "Invalid Customer/User",
  12.       "reference": "ORD-5023-4E89",
  13.       "metadata": {
  14.         "coupon_code": "NY2018",
  15.         "partner_id": 123989
  16.       },
  17.     "processed_on": "2018-04-19T15:56:59Z"
  18.   },
  19.   "_links": {
  20.     "self": {
  21.       "href": "https://api.checkout.com/events/evt_z5w4pkadoi3u5hu5lmlklwrxla"
  22.     },
  23.     "payment": {
  24.       "href": "https://api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
  25.     }
  26.   }
  27. }
  1. {
  2.   "id": "evt_hiefbhf5x2ye3f2qcyxfvye2ja",
  3.   "type": "payment_chargeback",
  4.   "created_on": "2018-05-10T10:41:35Z",
  5.   "data": {
  6.     "id": "pay_zlrug3xvfbsulovtpu2hhi33tq",
  7.     "action_id": "act_7B15779D173D0W45700D",
  8.     "processed_on": "2018-05-10T10:40:35Z",
  9.     "scheme": "Visa",
  10.     "currency": "GBP",
  11.     "amount": 500,
  12.     "payment_date": "2018-05-10T10:40:31Z",
  13.     "indicator": "ADJM",
  14.     "chargeback_code": "10.4",
  15.     "reference": "TRK12345",
  16.     "acquirer_reference_number": "3435301780034812032057",
  17.     "customer_id": "cus_5au3sqiyr2yuvoa3g2gv2h7aku"
  18.   },
  19.   "_links": {
  20.     "self": {
  21.       "href": "https://api.checkout.com/events/evt_hiefbhf5x2ye3f2qcyxfvye2ja"
  22.     },
  23.     "payment": {
  24.       "href": "https://api.checkout.com/payments/pay_zlrug3xvfbsulovtpu2hhi33tq"
  25.     }
  26.   }
  27. }

其他Webhook可参考Chcekout.com官方文档：https://www.checkout.com/docs/reporting-and-insights/webhooks/webhook-examples

安全机制

Webhook当前采用3个安全手段来保证其安全性。

1. Private shared key

即HTTP Header中的Authroization固定值，在收到Webhook通知时，可以与Hub后台系统生成的Privated shared key进行比对，若二者相同则验证成功，若二者不同则存在Webhook伪造的可能性。

2. Signature 签名

通过签名机制可以防止报文内容被篡改，当前Checkout.com产生签名的算法是 HMAC-SHA256，在计算签名值时，使用整个报文体，并将商户的secret key作为Hash key。若商户自己计算得到的签名值和HTTP Header中cko-signatrue中的值相同，则说明签名验证成功。

以下为简单的代码示例：

  1. //Name of the file : sha256-hmac.js
  2. //Loading the crypto module in node.js
  3. var crypto = require('crypto');
  4. //creating hmac object 
  5. var hmac = crypto.createHmac('sha256', '{{sk_XXXXX}}');//输入商户的secret key
  6. //passing the data to be hashed
  7. data = hmac.update('{"id":"{{webhook body}}");//输入收到的Webhook请求的Body
  8. //Creating the hmac in the required format
  9. gen_hmac= data.digest('hex');
  10. //Printing the output on the console
  11. console.log("hmac : " + gen_hmac);

3. IP 白名单

商户还可以对Checkout.com服务器对外的公网IP地址进行白名单处理：

IP地址 环境
52.31.105.56 生产环境
52.210.98.185 生产环境
52.210.86.142 生产环境
52.56.73.133 测试环境
52.56.70.215 测试环境
3.9.108.151 测试环境

如何处理Webhook

当商户收到来自Checkout.com的Webhook异步通知时，如果处理正常则需要在10秒返回一个HTTP = 2XX，表示接收成功。若未收到这一返回，Checkout.com的系统会进行自动重试：

每次重试和上一次的时间间隔如下：

重试次数 生产环境 测试环境
第一次重试 5分钟 5分钟
第二次重试 10分钟 10分钟
第三次重试 15分钟 15分钟
第四次重试 30分钟 30分钟
第五次重试 60分钟 60分钟
第六次重试 240分钟 N/A
第七次重试 720分钟 N/A