> For the complete documentation index, see [llms.txt](https://docs.coda.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coda.co/https-coda-payments.gitbook.io-zhong-wen-coda-private-technical-documentation/codapay/xun-huan-fu-kuan-ji-jiang-tui-chu/fa-qi-fu-kuan-zhang-hu-bang-ding.md). # 发起付款（账户绑定） [与发起支付请求](https://docs.coda.co/codapay/hosted-payment-page-integration/initiate-a-payment-request)相同的 Init 合约，外加 saved-card 和 off-session-reuse 字段。 Content-Type: `application/json`. 初始化身份验证是`apiKey`JSON 正文中的字段（不是 Token Charge 标头）。 ### `initRequest`参数 | 参数 | 类型 | 是否必须 | 介绍 | | ------------------------------- | ------- | ---------- | ----------------------------------------------------------------------------------------- | | `country` | number | 是 | ISO 3166 数字国家代码。参见国家和货币代码。 | | `payType` | number | 是 |

支付渠道 ID。请使用您分配的卡渠道。0/1渠道选择 / DCB 页面 — 不属于此流程。

| | `apiKey` | string | 是 | 来自 Coda 的 API 密钥（入门指南/发布商门户）。 | | `projectId` | number | 是 | 仅限 v2.0 版本。项目（标题）ID 来自 Coda。 | | `orderId` | string | 是 | 您的唯一订单 ID，4-64 个字符。 | | `currency` | number | 是 | ISO 4217 数字货币代码。 | | `isTaxInclusiveAmount` | boolean | 不是 | v2.0，美国市场，Coda 为 MoR 时适用。是否`items[].price`已包含税费。默认值`false`。 | | `items` | array | 是 | 分项列出。美国和加拿大：一项。 | | `items[].code` | string | 不是 | 您的商品代码。部分渠道（例如台湾Line Pay）必须填写。 | | `items[].price` | number | 是 | 价格单位为`currency` | | `items[].name` | string | 是 | 物品名称。拉丁字母。 | | `items[].skuImageUrl` | string | 不是 | 用于结账的公开图片 URL。 | | `profile` | object | 是 | 键值对配置文件。 | | `profile.entry` | array | 是 | 列表`{ key, value }`。 | | `enableSavePaymentMethod` | boolean | **是，用于绑定** | 显示保存卡并持久化仪器。 | | `displaySavedPaymentMethodList` | boolean | 可选 | 在 HPP 上显示之前保存的卡片。通常首次保存时会显示：`true`或者根据您的用户体验要求省略。 | | `userInitiated` | boolean | **是，用于绑定** | 必须`true`（顾客在场）。 | | `offSessionReuse` | boolean | **是，用于绑定** | 必须允许`true`该卡稍后通过令牌充值方式重复使用。省略或`false`用于一次性 CIT，该 CIT 不得作为 MIT 重复使用。 | | `offSessionType` | string | **是，用于绑定** | `Unscheduled`,`Subscriptions`,`Installments` | | `shopper` | object | **是，用于绑定** | 用于存储商品的购物者身份信息。请参见下表。 | ### `profile.entry`键（初始化） | 参数 | 是否必须 | 介绍 | | ------------------- | ---- | ------------------------------------------ | | `user_id` | 是 | 您的用户唯一标识符。 | | `in_frame_redirect` | 不是 | `true`/ `false`— iframe 关闭行为 | | `return_url` | 不是 | 动态返回 URL。占位符`{transactionId}`，`{orderId}`。 | | `need_mno_id` | 不是 | 如果您需要返回所选频道 ID，请提供任何非空值。 | | `email` | 不是 | 如果 Coda 已为您的项目启用收据功能，您将收到收据电子邮件。 | | `client_ip` | 不是 | 如果频道需要，则提供购物者 IPv4 地址。 | | `lang_code` | 不是 | 语言，例如`en_US`。参照集成指南 | #### `shopper.entry` 键（初始化）
参数是否必须介绍
id不是如果id存在，Coda 会查找该购物者。如果不存在，Coda 会创建一个与该购物者关联的购物者partnerShopperId。
partnerShopperId是您的稳定用户 ID（区分大小写）。每次初始化时都使用相同的值。Token Charge 不会发送购物者 ID；Coda 会从中解析购物者paymentMethodId。
email有条件通常需要创建购物者。
phoneNumber不
billingFirstName有条件某些市场/购物者创建需要。
billingLastName有条件
billingDocumentType有条件例如 CPF。
billingDocumentId有条件与文档类型配对。
billingAddress不
billingCity不
billingRegion不
billingCountry不ISO alpha-2，例如US。
billingZipCode不
如果`id`存在，Coda 会查找该购物者。如果不存在，Coda 会创建一个与该购物者关联的购物者`partnerShopperId`。 ### **初始化响应( `initResult`)** | 值 | 类型 | 介绍 | | ------------- | ------- | ----------------------- | | `resultCode` | integer | `0`初始化成功。其他值：错误目录。 | | `resultDesc` | string | 当`resultCode`不存在时出现`0`。 | | `txnId` | integer | Coda 交易 ID。`0`如果初始化失败。 | | `redirectUrl` | string | 托管支付页面 URL。请将客户引导至此页面。 | #### **示例 — 首次保存 (CIT-for-MIT)** ```json { "initRequest": { "country": 702, "payType": 1005, "apiKey": "your_v2_api_key", "projectId": 1, "orderId": "order-cit-001", "currency": 702, "items": [ { "code": "ITEM_1", "price": 9.99, "name": "First payment" } ], "profile": { "entry": [ { "key": "user_id", "value": "user-105" } ] }, "enableSavePaymentMethod": true, "displaySavedPaymentMethodList": true, "userInitiated": true, "offSessionReuse": true, "shopper": { "entry": [ { "key": "partnerShopperId", "value": "user-105" }, { "key": "email", "value": "user-105@example.com" } ] } } } ``` #### **示例初始化成功** ```json { "initResult": { "resultCode": 0, "txnId": 7714940366302699999, "redirectUrl": "https://airtime.codapayments.com/airtime/begin?txn_id=7714940366302699999" } } ``` *** ### 你如何获得`paymentMethod.id` 保存成功后，Coda 会向您配置的端点发送一个 JSON Webhook。保存`paymentMethod.id`——即`paymentMethodId`令牌支付。购物者身份由 Coda 根据支付方式解析；您无需在令牌收费上发送`shopper`。 #### `PAYMENT_METHOD_ADDED` ```json { "eventType": "PAYMENT_METHOD_ADDED", "timestamp": "2025-06-19T02:48:39.568907Z", "shopper": { "id": "shp_sg197861636b99999", "partner_shopper_id": "partner-shopper-101", "email": "shopper@example.com" }, "paymentMethod": { "id": "pmt_sg1a9999ac56ae00000", "type": "card", "card": { "lastFour": "1234", "expirationMonth": "04", "expirationYear": "2027" } } } ``` | 值 | 介绍 | | ------------------------------------ | ------------------------------ | | `eventType` | `PAYMENT_METHOD_ADDED` | | `timestamp` | 方法保存时 | | `shopper.id` | Coda 购物者 ID（保留用于 HPP 返回购物者初始化） | | `shopper.partner_shopper_id` | Your `partnerShopperId你的` | | `paymentMethod.id` | 已保存的卡号 — 令牌收费`paymentMethodId` | | `paymentMethod.type` | 例如 `card` | | `paymentMethod.card.lastFour` | 最后四位数字 | | `paymentMethod.card.expirationMonth` | `MM` | | `paymentMethod.card.expirationYear` | `YYYY` | 返回 HTTP 2xx 响应。非 2xx 响应将重试。请按照已保存卡片通知的文档说明验证通知校验和。 `eventType`您应该处理的相关值： `PAYMENT_METHOD_ADDED`，`PAYMENT_METHOD_REMOVED`。请参阅[“保存卡片详细信息”](https://docs.coda.co/codapay/hosted-payment-page-integration/saving-card-details)。 ## 回调通知 回调协议与 [回调通知详情](https://coda-payments.gitbook.io/coda-public-technical-documentation/coda-ji-shu-wen-dang/codapay/zhi-fu-ye-mian-api-ji-cheng/hui-tiao-tong-zhi-xiang-qing) 相同。当属于账户绑定流程（用于未来离线支付的用户发起交易/CIT）时，将额外包含 `PaymentMethodId` 字段。 ``` PaymentMethodId 仅适用于支付成功的场景。 ``` {% tabs %} {% tab title="v2.0 Notification" %} 
// Sample for non-USD payments initiated
https://<your_webhook_url>?
  TxnId=7715121708032676249
  OrderId=365f5Z619951c1a4b8
  TotalPrice=1.00
  PaymentType=237
  ResultCode=0
  Checksum=6b6c5e0f835f9f1442726bed3aedc3c9
  PayTaxRate=8.00
  PayCurrency=MYR
  PayAmount=1.00
  OriginAmount=1.00
  OriginCurrency=MYR
  SubTotalPrice=0.93
  PaymentMethodId=pmt_9281361551672933 // 仅适用于账户绑定 (CIT for MIT)

// Sample for USD payments initiated
https://<your_webhook_url>?
  TxnId=7715122576202672831
  OrderId=365f5Z619951c1a4b8
  TotalPrice=1.17
  PaymentType=237
  ResultCode=0
  Checksum=10741fa6be7e6f2b189f029b3f8a0963
+ USDPrice=0.30
  PayTaxRate=8.00
  PayCurrency=MYR 
  PayAmount=1.17 
  OriginAmount=0.30
  OriginCurrency=USD 
  SubTotalPrice=1.08 
  PaymentMethodId=pmt_9281361551672933 // 仅适用于账户绑定 (CIT for MIT)
{% endtab %} {% endtabs %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.coda.co/https-coda-payments.gitbook.io-zhong-wen-coda-private-technical-documentation/codapay/xun-huan-fu-kuan-ji-jiang-tui-chu/fa-qi-fu-kuan-zhang-hu-bang-ding.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.