发起支付请求

用于发起支付请求并获取Coda订单交易 ID

前置条件

接入 Codapay API 前，请确保满足以下要求：

• 使用 HTTPS 协议。

• 支持 TLS 1.2 或更高版本。

Codapay API 提供两个版本，请查阅 Codapay API 版本概览 ，确保选择适合的版本进行接入。

详情

沙盒环境

版本	接口 URL
v2.0	https://sandbox.codapayments.com/airtime/api/restful/v2.0/Payment
v1.0	https://sandbox.codapayments.com/airtime/api/restful/v1.0/Payment

正式环境

版本	接口 URL
v2.0	https://airtime.codapayments.com/airtime/api/restful/v2.0/Payment
v1.0	https://airtime.codapayments.com/airtime/api/restful/v1.0/Payment

接口地址

POST {Base URL}/init.json

Codapay 的 API 支持 REST 接口服务，默认情况下，提供的端点均为 RESTful。

请求参数

参数	类型	描述
initRequest	Object	必填 必须是有效的JSON对象
initRequest.country	String	必填 ISO 3166 国家代码 - 请参阅 国家和货币代码
initRequest.payType	String	必填 您想使用的支付渠道ID - 请参阅 支付页面 API 。 支付渠道选择页面，可以设置为0； 运营商支付，可以设置为1 详情请参考支付渠道接入方式
initRequest.apiKey	String	必填 Coda提供的API密钥 - 请参考 Codapay 入门指南 了解如何获取。
initRequest.projectId	String	*此字段仅适用于v2.0 API 必填 Coda提供的Project ID，专于每个标题产品。 请参考 Codapay 入门指南 了解如何获取。
initRequest.isTaxInclusiveAmount	Boolean	*此字段仅适用于v2.0 API. 仅支持美国市场 此参数影响items[].price 的总金额是否包含税费。此参数仅适用于 Coda 作为 MoR（Merchant of Record） 且支持税务的市场（目前仅支持美国）。 当设置为 true 时，商品总金额将视为含税价格，并按该金额直接收费。 当设置为 false（或未提供该参数）时，商品总金额将视为未含税价格，系统会在此基础上额外加收税费。 若未提供此参数，默认值为 false并保存原有配置 当 Coda 不是 MoR 时，此参数将被忽略。 → 有关此参数如何影响响应结果及税费明细，请参阅 【查询订单-税务处理】。
initRequest.orderId	String	必填 您在支付请求发起时传递的订单ID。长度必须在4到64个字符之间
initRequest.currency	String	必填 ISO 4217 货币代码 - 请参阅 国家和货币代码 仅支持本地货币或美元请求
initRequest.items	Array	必填 用户购买的商品列表。美国和加拿大仅支持单个商品
initRequest.items[].code	String	可选 商户商品关联的代码
initRequest.items[].price	Number	必填 商品价格，包括请求中指定货币的所有税费。
initRequest.items[].name	String	必填 购买的商品名称。仅支持拉丁字符（即英文）。
initRequest.profile	Object	必填 用户的个人资料信息（Profile）
initRequest.profile.entry	Array	必填 个人资料信息的键值对列表。目前可以用于处理的特定键值如下所示。
initRequest.profile.entry[].key	String	个人资料信息
initRequest.profile.entry[].value	String	个人资料信息

Profile

参数	类型	描述
user_id	String	必填 您用户的独有标识的 ID
in_frame_redirect	True or False	可选 如果您在网站的iframe中使用支付页面，您可以使用此参数控制支付流程完成后的行为。 True - 当用户尝试关闭Codapay窗口时，用户将被重定向到iframe中的重定向地址。 False - 当用户尝试关闭Codapay窗口时，用户将被重定向到新标签页中重定向到已配置的重定向地址。
return_url	String	可选 这允许您动态传递支付完成后用户将被重定向到的返回网址。此URL可以包含以下查询字符串占位符 {transactionId} 即Coda订单ID {orderId} 即商家订单ID 如果未使用此键值对，Codapay将使用商户在Coda后台中配置的重定向地址。
need_mno_id	Any value or null	如果您使用payType = 0 / 1 或运营商支付发起了支付，并且希望知道用户选择了哪个支付渠道，可以在此字段中传递任意非空值。

响应参数

参数	类型	描述
initResult	Object	包含发起请求的结果
initResult.resultCode	Integer	请求成功将返回 resultCode = 0。 其余 resultCode值为错误代码。 错误代码的完整列表，请参阅 常见错误代码
initResult.resultDesc	String	错误描述
initResult.txnId	Integer	发起请求的订单ID。如果订单发起失败，此值将为0。

示例

v2.0 请求

{
    "initRequest": {
        "country": 158,
        "payType": 82,
        "apiKey": "e944d44f065eade8157737385a094a",
        "projectId": 21 //此字段仅适用于 v2.0 API
        "orderId": "12321312321314",
        "currency": 901,
        "items": [
            {
                "code": "1",
                "price": 1000.00,
                "name": "Test Item"
            }
        ],
        "profile": {
            "entry": [
                {
                    "key": "user_id",
                    "value": "105"
                }
            ]
        }
    }
}

v1.0 请求

{
    "initRequest": {
        "country": 158,
        "payType": 82,
        "apiKey": "e944d44f065eade8157737385a094a",
        "orderId": "12321312321314",
        "currency": 901,
        "items": [
            {
                "code": "1",
                "price": 1000.00,
                "name": "Test Item"
            }
        ],
        "profile": {
            "entry": [
                {
                    "key": "user_id",
                    "value": "105"
                }
            ]
        }
    }
}

成功响应

{
    "initResult": {
        "resultCode": 0,
        "txnId": 7177415887085060516
    }
}

失败响应

{
    "initResult": {
        "resultCode": 103,
        "resultDesc": "This transaction has been cancelled. No charges were made. (error:103)",
        "txnId": 0
    }
}

Profile 示例

请求

"profile": {
            "entry": [
                {
                    "key": "user_id",
                    "value": "test105"
                },
                {
                    "key": "in_frame_redirect",
                    "value": "true"
                },
                {
                    "key": "return_url",
                    "value": "https://www.example.com/{transactionId}/{orderId}/return"
                },
                {
                    "key": "need_mno_id",
                    "value": "YES"
                }
            ]
        }