• 新平台

本文对iFrame所使用到的后端 Payment 接口进行介绍。
本接口也适用于Full Card Detail集成方式(需要修改部分参数,具体请与负责贵司的工程师联系)。

#API# Payment

官方说明地址:https://api-reference.checkout.com/#operation/requestAPaymentOrPayout
HTTP调用方式为POST
sandbox地址:https://api.sandbox.checkout.com/payments
生产地址:https://api.checkout.com/payments

主要请求参数

其中蓝色标注的是重点关注参数:

Body 参数名 是否必填 说明
source.type
- [x]

| 支付资金来源,对于iFrame卡支付填写“token” | | source.token |
- [x]

| iFrame前端获取的token值 | | source.billing_address.address_line1 |
- [ ]

| | | source.billing_address.address_line2 |
- [ ]

| | | source.billing_address.city |
- [ ]

| | | source.billing_address.state |
- [ ]

| | | source.billing_address.zip |
- [ ]

| | | source.billing_address.country |
- [ ]

| 国家代码可参考 | | source.phone.number |
- [ ]

| 若billing.phone出现,则为必填。 | | source.phone.country_code |
- [ ]

| 呼叫国家代码可参考 | | amount |
- [ ]

| 支付金额,为最小金额单位。如币种为美金USD时,amount = 1 表示1美分。具体可以参考文档《币种计算规则》 | | currency |
- [x]

| 支付金额,标准的ISO 3位币种,如USD。具体可参考 | | reference |
- [ ]

| 商户订单号 | | customer.email |
- [ ]

| 用户邮箱,用来唯一对应Checkout.com内部一个用户 | | customer.name |
- [ ]

| 用户名,格式为 First name + 空格 + last name,如“Bruce Wayne” | | shipping.address.address_line1 |
- [ ]

| | | shipping.address.address_line2 |
- [ ]

| | | shipping.address.city |
- [ ]

| | | shipping.address.state |
- [ ]

| | | shipping.address.zip |
- [ ]

| | | shipping.address.country |
- [ ]

| 若shipping出现,则为必填项。国家代码可参考 | | shipping.phone.number |
- [ ]

| 若shipping.phone出现,则为必填。 | | shipping.phone.country_code |
- [ ]

| 呼叫国家代码可参考 | | success_url |
- [x] (3DS支付)
- [ ] (非3DS支付)
| 用户支付成功后回调的商户页面,对于3DS支付场景必填 | | failure_url |
- [x] (3DS支付)
- [ ] (非3DS支付)
| 用户支付失败后回调的商户页面,对于3DS支付场景必填 | | 3ds.enabled |
- [ ]

| 是否启用3DS |

主要返回参数

3DS支付返回

  • 成功返回,HTTP Code = 202 | 参数名 | 说明 | | —- | —- | | id | 该支付单的唯一payment id | | status | 当前交易状态,固定值“pending” | | reference | 请求中发送的商户侧Id | | 3ds.downgraded | 3DS支付是否降级为非3DS | | 3ds.enrolled | 该卡是否支持3DS:
    Y:支付
    N:不支持
    U:未知 | | _links.self.href | 查询该Hosted Payment Page的Url | | _links.redirect.href | 用于重定向用户至发卡行3DS验证页面 |

非3DS支付返回

  • 成功返回,HTTP Code = 201 | 参数名 | 说明 | | —- | —- | | id | 该支付单的唯一payment id | | action_id | 一笔支付单对应一次业务操作的唯一ID,如authorization(授权)对应一个action_id,capture(请款)对应另外一个action_id,但是都归属于同一个payment_id | | amount | 支付金额 | | currency | 支付币种 | | approved | 授权或者请款是否成功 | | status | 当前交易状态。对于卡支付来说枚举值:
    “Authorized” “Pending” “Card Verified” “Captured” “Declined” | | response_code | Checkout.com返回码信息,详情请参考文档:
    https://www.checkout.com/docs/resources/codes/response-codes | | source.type | 返回实际处理的资金来源,对于卡支付固定值card | | source.id | Checkout.com内部对于该卡的id,可用于后续的支付发起,长期有效(相当于实际卡信息的长期token,在卡信息变更(如有限期修改)前,一直可用 | | source.expiry_month | 卡有效期-月份 | | source.expiry_year | 卡有效期-年份 | | source.scheme | 卡组织名称 | | source.last4 | 卡号后4位 | | source.fingerprint | 卡指纹信息,同一个卡号及有效期则保持一致,可以用来检查卡的唯一性 | | source.bin | 卡BIN,卡号前6/8位 | | source.card_type | 卡类型,枚举值:
    Credit” “Debit” “Prepaid” “Charge” “Deferred Debit” | | source.card_category | 卡种类,枚举值:
    “Consumer” “Commercial” | | source.issuer | 发卡行名称 | | source.issuer_country | 发卡行国家 | | avs_check | AVS检查结果,详情可参考:https://www.checkout.com/docs/resources/codes/avs-codes
    主要适用于US,CA和UK三个国家,且当上送了billing address信息 | | cvv_check | CVV检查结果,详情可参考:
    https://www.checkout.com/docs/resources/codes/cvv-response-codes
    可以用于风控判断 | | processing.retrieval_reference_number | RRN,授权交易时发送给发卡行的参考好 | | processing.acquirer_transaction_id | ARN,收单行产生的交易唯一单号,可以用于与发卡行沟通交易状态,如查询退款状态 | | processing.recommendation_code | 卡组织定义的后续处理建议代码,可参考文档:
    https://www.checkout.com/docs/resources/codes/recommendation-codes |
  • 失败返回,HTTP = 401,密钥使用错误
  • 失败返回,HTTP = 422,输入参数错误 | 参数名 | 说明 | | —- | —- | | request_id | Checkout.com内部Id | | error_type | 错误类型 | | error_codes | 错误代码 |