• 新平台

本文就Hosted Payment Page集成方式进行了具体介绍，包括系统交互流程，请求示例，Postman参考以及特殊使用场景。
官方文档地址：https://www.checkout.com/docs/four/integrate/hosted-payments-page

交互流程

Step1，用户在商户前端提交支付请求
Step2，商户前端系统发送请求至后端系统
Step3，商户后端系统通过API请求Checkout.com系统，Checkout.com系统返回重定向URL
Step4，商户将用户重定向至Checkout.com的托管支付页面
Step5，用户在Checkout.com托管支付页面内完成支付信息的输入并完成支付
Step6，用户在支付完成后重定向至商户定义的URL
Step7，商户通过主动查询Get Payment Detail获取支付结果，或者等待Checkout.com Webhook 异步通知确认支付结果（至少必须实现Webhook异步通知机制）
image.png

商户创建了一个Hosted Payment Page后，其有效期为30分钟。

开通Hosted Payment Page功能

在集成Hosted Payment Page开始前，请先联系负责贵司的工程师进行功能开通。若Hosted Payment Page未开通则会返回以下报错信息：

  1. {
  2.     "request_id": "136bbf870299513d72f317af46c38966",
  3.     "error_type": "request_forbidden",
  4.     "error_codes": [
  5.         "merchant_not_onboarded"
  6.     ]
  7. }

请求示例

请求示例：

  1. {
  2.   "amount": 1000,
  3.   "currency": "GBP",
  4.   "reference": "ORD-123A",
  5.   "billing": {
  6.     "address": {
  7.       "country": "GB"
  8.     }
  9.   },
  10.   "customer": {
  11.     "name": "Bruce Wayne",
  12.     "email": "brucewayne@gmail.com"
  13.   },
  14.   "success_url": "https://example.com/payments/success",
  15.   "failure_url": "https://example.com/payments/failure",
  16.   "cancel_url": "https://example.com/payments/checkout"
  17. }

返回示例：

  1.  {
  2.   "id": "hpp_xGQBg0AXl3cM",
  3.   "reference": "ORD-123A",
  4.    "_links": {
  5.     "self": {
  6.       "href": "https://api.checkout.com/hosted-payments/hpp_xGQBg0AXl3cM"
  7.     },
  8.      "redirect": {
  9.        "href": "https://pay.checkout.com/page/hpp_xGQBg0AXl3cM"
  10.      }
  11.    }
  12.  }

支付方式选择

Hosted Payment Page通过国家+币种组合，及一些渠道个性化参数来决定可以展示的支付方式。当满足条件时，如果对应支付方式已经在您的账户上开通，则会展示给用户使用。
不同支付方式要求的字段如下，其中如果customer.name为必填项，则需要输入 First name + 空格 + Last Name的格式，如 Bruce Wayne。

支付方式 字段要求
Bancontact
- billing.address.country: BE
- currency: EUR
- customer.name 必填
EPS
- billing.address.country: AT
- currency: EUR
Giropay
- billing.address.country: DE
- currency: EUR
iDEAL
- currency: EUR
- billing.address.country: NL
Klarna（仅老平台）
- Austria: AT - EUR - en-AT
- Denmark: DK - DKK - en-DK
- Finland: FI - EUR - en-FI
- Germany: DE - EUR - en-DE or de-DE
- Netherlands: NL - EUR - en-NL or nl-NL
- Norway: NO - NOK - en-NO
- Sweden: SE - SEK - en-SE
- Switzerland: CH - CHF - de-CH, fr-CH, it-CH or en-CH
- United Kingdom: GB - GBP - en-GB

以下字段为必填项：
- customer.name
- customer.email
- billing.address.address_line1
- billing.address.city
- billing.address.zip
- products (object)
| | KNET |
- billing.address.country: KW
- currency: KWD.
| | Mada |
- billing.address.country: SA
- currency: SAR.
| | Multibanco |
- billing.address.country: PT
- currency: EUR.
- customer.name 为必填项
| | PayPal（仅老平台） |
- reference 为必填项
- billing.address.country 和 currency 为必填项
| | Przelewey24 |
- billing.address.country: PL
- currency: EUR 或者 PLN.
- customer.name 为必填项
- customer.email 为必填项
| | SEPA Direct Debit（仅老平台） |
- currency: EUR.
- billing.address.country 为必填项
- customer.name 为必填项
| | Sofort |
- currency EUR.
- billing.address.country 为必填项，且为以下的某一个国家：
- Belgium：BE
- Germany：DE
- Italy：IT
- The Netherlands：NL
- Austria：AT
- Spain：ES
|

后端Postman参考

可通过以下链接获取Postman的参考:
Postman Link:
密码请咨询负责贵司的工程师。

导入以上Postman collection后，替换Header中的Authorization值为您沙箱环境的secret key后即可开始测试。
其中，新平台密钥值格式为：Bearer {{API_secret_key}}，如：Bearer sk_sbox_71234oqw3k1234cdkf3sjpe1234
老平台密钥值格式为：{{API_secret_key}}，如：sk_test_90db1234-f9ff-4901-b366-94a508ee1234
image.png

特殊使用场景

启用3DS

若商户自身没有完善的风控工具和体系，为了减少欺诈和拒付问题，可以添加请求参数来发起一笔3DS的卡支付，支付过程中用户会从Checkout.com的支付页面跳转至发卡行的页面并完成身份验证。
由于这一逻辑由Checkout.com处理，商户无需做额外的前端业务流程处理，仅在用户回调到商户页面时，查询接口的参数名有区别，具体可以参考通用接口中的 《Get payment detail 接口介绍》

涉及的参数为 3ds.enabled

请求示例：

  1. {
  2.     "amount": 5000,
  3.     "currency": "EUR",
  4.     "billing": {
  5.         "address": {
  6.             "country": "PL"
  7.         }
  8.     },
  9.     "customer":{
  10.         "name":"Asuaka L",
  11.         "email":"abc@yeah.net"
  12.     },
  13.     "reference":"abc-123",
  14.     "3ds": {
  15.         "enabled": true,
  16.     },
  17.     "success_url": "http://127.0.0.1:3000/result",
  18.     "failure_url": "http://127.0.0.1:3000/result",
  19.     "cancel_url": "http://127.0.0.1:3000/result"
  20. }

指定支付方式

Hosted Payment Page的默认展示逻辑是将所有可用的支付方式都进行展示，如以下请求中的币种+国家组合，决定了可以支持的支付方式有：iDeal，Sofort，Paypal和Card：

  1. {
  2.     "amount": 5000,
  3.     "currency": "EUR",
  4.     "billing": {
  5.         "address": {
  6.             "country": "PL"
  7.         }
  8.     },
  9.     "customer":{
  10.         "name":"Asuaka L",
  11.         "email":"abc@yeah.net"
  12.     },
  13.     "reference":"abc-123",
  14.     "3ds": {
  15.         "enabled": true,
  16.     },
  17.     "success_url": "http://127.0.0.1:3000/result",
  18.     "failure_url": "http://127.0.0.1:3000/result",
  19.     "cancel_url": "http://127.0.0.1:3000/result"
  20. }

用户打开的支付页面：

image.png

若商户出于业务的考虑，希望能够指定某一特定的支付方式，则可以通过新增参数：allow_payment_methods来进行控制。
如修改上述请求示例为：

  1. {
  2.     "amount": 5000,
  3.     "currency": "EUR",
  4.     "billing": {
  5.         "address": {
  6.             "country": "NL"
  7.         }
  8.     },
  9.     "customer":{
  10.         "name":"Asuaka L",
  11.         "email":"abc@yeah.net"
  12.     },
  13.     "reference":"abc-123",
  14.     "3ds": {
  15.         "enabled": true
  16.     },
  17.     "allow_payment_methods":["ideal"],
  18.     "success_url": "http://127.0.0.1:3000/result",
  19.     "failure_url": "http://127.0.0.1:3000/result",
  20.     "cancel_url": "http://127.0.0.1:3000/result"
  21. }

则页面上将仅展示iDeal一种支付方式：
image.png也可以使用同一个方法指定其他支付方式。