• 新平台

本文对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 | 错误代码 |