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