> 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/codapay/recurring-payments/initiate-payment-account-binding.md).

# Initiate Payment (Account Binding)

Same Init contract as [Initiate a payment request](https://docs.coda.co/codapay/hosted-payment-page-integration/initiate-a-payment-request), plus saved-card and off-session-reuse fields.

Content-Type: `application/json`. Init authentication is the `apiKey` field in the JSON body (not Token Charge headers).

#### `initRequest` parameters <a href="#initrequest-parameters" id="initrequest-parameters"></a>

<table><thead><tr><th width="197.97021484375">Parameter</th><th width="117.4417724609375">Type</th><th width="107.1612548828125">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>country</code></td><td>number</td><td>yes</td><td>ISO 3166 numeric country code. See Country and Currency Codes.</td></tr><tr><td><code>payType</code></td><td>number</td><td>yes</td><td>Payment channel ID. Use your assigned <strong>card</strong> channel. <code>0</code> / <code>1</code> are channel-selection / DCB pages — not this flow.</td></tr><tr><td><code>apiKey</code></td><td>string</td><td>yes</td><td>API key from Coda (Getting started / Publisher Portal).</td></tr><tr><td><code>projectId</code></td><td>number</td><td>yes</td><td>v2.0 only. Project (title) ID from Coda.</td></tr><tr><td><code>orderId</code></td><td>string</td><td>yes</td><td>Your unique order id, 4–64 characters.</td></tr><tr><td><code>currency</code></td><td>number</td><td>yes</td><td>ISO 4217 numeric currency code.</td></tr><tr><td><code>isTaxInclusiveAmount</code></td><td>boolean</td><td>no</td><td>v2.0, US market when Coda is MoR. Whether <code>items[].price</code> already includes tax. Default <code>false</code>.</td></tr><tr><td><code>items</code></td><td>array</td><td>yes</td><td>Line items. US and Canada: one item.</td></tr><tr><td><code>items[].code</code></td><td>string</td><td>no</td><td>Your item code. Mandatory for some channels (e.g. Taiwan Line Pay).</td></tr><tr><td><code>items[].price</code></td><td>number</td><td>yes</td><td>Price in <code>currency</code>.</td></tr><tr><td><code>items[].name</code></td><td>string</td><td>yes</td><td>Item name. Latin characters.</td></tr><tr><td><code>items[].skuImageUrl</code></td><td>string</td><td>no</td><td>Public image URL for checkout.</td></tr><tr><td><code>profile</code></td><td>object</td><td>yes</td><td>Key/value profile.</td></tr><tr><td><code>profile.entry</code></td><td>array</td><td>yes</td><td>List of <code>{ key, value }</code>.</td></tr><tr><td><code>enableSavePaymentMethod</code></td><td>boolean</td><td><strong>yes for binding</strong></td><td>Show save-card and persist the instrument.</td></tr><tr><td><code>displaySavedPaymentMethodList</code></td><td>boolean</td><td>optional</td><td>Show previously saved cards on HPP. Typical first save: <code>true</code> or omit per your UX.</td></tr><tr><td><code>userInitiated</code></td><td>boolean</td><td><strong>yes for binding</strong></td><td>Must be <code>true</code> (customer present).</td></tr><tr><td><code>offSessionReuse</code></td><td>boolean</td><td><strong>yes for binding</strong></td><td>Must be <code>true</code> so the card can be reused later via Token Charge. Omit or <code>false</code> for a one-off CIT that must not be reused as MIT.</td></tr><tr><td><code>offSessionType</code></td><td>string</td><td><strong>yes for binding</strong></td><td><code>Unscheduled</code>,<code>Subscriptions</code>,<code>Installments</code></td></tr><tr><td><code>shopper</code></td><td>object</td><td><strong>yes for binding</strong></td><td>Shopper identity for vaulting. See table below.</td></tr></tbody></table>

#### `profile.entry` keys (Init) <a href="#profile-entry-keys-init" id="profile-entry-keys-init"></a>

<table><thead><tr><th width="180.1817626953125">Key</th><th width="121.860107421875">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>user_id</code></td><td>yes</td><td>Your user’s unique identifier.</td></tr><tr><td><code>in_frame_redirect</code></td><td>no</td><td><code>true</code> / <code>false</code> — iframe close behavior.</td></tr><tr><td><code>return_url</code></td><td>no</td><td>Dynamic return URL. Placeholders <code>{transactionId}</code>, <code>{orderId}</code>.</td></tr><tr><td><code>need_mno_id</code></td><td>no</td><td>Any non-null value if you need selected channel id back.</td></tr><tr><td><code>email</code></td><td>no</td><td>Receipt email if Coda has enabled receipts for your title.</td></tr><tr><td><code>client_ip</code></td><td>no</td><td>Shopper IPv4 if the channel requires it.</td></tr><tr><td><code>lang_code</code></td><td>no</td><td>HPP language, e.g. <code>en_US</code>.</td></tr></tbody></table>

#### `shopper.entry` keys (Init) <a href="#shopper-entry-keys-init" id="shopper-entry-keys-init"></a>

<table><thead><tr><th width="191.6839599609375">Key</th><th width="115.0880126953125">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>no</td><td>If <code>id</code> is present, Coda looks up that shopper. If not, Coda creates a shopper linked to <code>partnerShopperId</code>.</td></tr><tr><td><code>partnerShopperId</code></td><td>yes</td><td>Your stable user id (case-sensitive). Same value on every later Init. Token Charge does not send shopper ids; Coda resolves the shopper from <code>paymentMethodId</code>.</td></tr><tr><td><code>email</code></td><td>conditional</td><td>Often required to create a shopper.</td></tr><tr><td><code>phoneNumber</code></td><td>no</td><td></td></tr><tr><td><code>billingFirstName</code></td><td>conditional</td><td>Required in some markets / shopper creation.</td></tr><tr><td><code>billingLastName</code></td><td>conditional</td><td></td></tr><tr><td><code>billingDocumentType</code></td><td>conditional</td><td>e.g. CPF.</td></tr><tr><td><code>billingDocumentId</code></td><td>conditional</td><td>Paired with document type.</td></tr><tr><td><code>billingAddress</code></td><td>no</td><td></td></tr><tr><td><code>billingCity</code></td><td>no</td><td></td></tr><tr><td><code>billingRegion</code></td><td>no</td><td></td></tr><tr><td><code>billingCountry</code></td><td>no</td><td>ISO alpha-2, e.g. <code>US</code>.</td></tr><tr><td><code>billingZipCode</code></td><td>no</td><td></td></tr></tbody></table>

If `id` is present, Coda looks up that shopper. If not, Coda creates a shopper linked to `partnerShopperId`.

#### Init response (`initResult`) <a href="#init-response-initresult" id="init-response-initresult"></a>

<table><thead><tr><th width="150.2706298828125">Field</th><th width="109.424072265625">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>resultCode</code></td><td>integer</td><td><code>0</code> = Init succeeded. Other values: error catalog.</td></tr><tr><td><code>resultDesc</code></td><td>string</td><td>Present when <code>resultCode</code> is not <code>0</code>.</td></tr><tr><td><code>txnId</code></td><td>integer</td><td>Coda transaction id. <code>0</code> if Init failed.</td></tr><tr><td><code>redirectUrl</code></td><td>string</td><td>Hosted Payment Page URL. Send the customer here.</td></tr></tbody></table>

#### Sample — first save (CIT-for-MIT) <a href="#sample-first-save-cit-for-mit" id="sample-first-save-cit-for-mit"></a>

```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" }
      ]
    }
  }
}
```

#### Sample Init success <a href="#sample-init-success" id="sample-init-success"></a>

```json
{
  "initResult": {
    "resultCode": 0,
    "txnId": 7714940366302699999,
    "redirectUrl": "https://airtime.codapayments.com/airtime/begin?txn_id=7714940366302699999"
  }
}
```

***

### How you get `paymentMethod.id` <a href="#how-you-get-paymentmethod-id" id="how-you-get-paymentmethod-id"></a>

After a successful save, Coda sends a JSON webhook to your configured endpoint. Store `paymentMethod.id` — that is the `paymentMethodId` on Token Charge. Shopper identity is resolved by Coda from the payment method; you do not send `shopper` on Token Charge.

#### `PAYMENT_METHOD_ADDED` <a href="#payment-method-added" id="payment-method-added"></a>

```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"
    }
  }
}
```

| Field                                | Description                                           |
| ------------------------------------ | ----------------------------------------------------- |
| `eventType`                          | `PAYMENT_METHOD_ADDED`                                |
| `timestamp`                          | When the method was saved                             |
| `shopper.id`                         | Coda shopper id (keep for HPP returning-shopper Init) |
| `shopper.partner_shopper_id`         | Your `partnerShopperId`                               |
| `paymentMethod.id`                   | Saved card id — Token Charge `paymentMethodId`        |
| `paymentMethod.type`                 | e.g. `card`                                           |
| `paymentMethod.card.lastFour`        | Last four digits                                      |
| `paymentMethod.card.expirationMonth` | `MM`                                                  |
| `paymentMethod.card.expirationYear`  | `YYYY`                                                |

Respond with HTTP 2xx. Non-2xx is retried. Verify the notification checksum as documented for saved-card notifications.

Related `eventType` values you should handle: `PAYMENT_METHOD_ADDED`, `PAYMENT_METHOD_REMOVED`. See [Saving Card Details](https://docs.coda.co/codapay/hosted-payment-page-integration/saving-card-details).

### Payment Result Webhook Notifications&#x20;

Same callback contract as [Get notified of a transaction status change,](https://docs.coda.co/codapay/hosted-payment-page-integration/get-notified-of-a-transaction-status-change) plus `PaymentMethodId` field when it is a Account Binding process (Customer Initiated Transaction for future offSession payment)&#x20;

{% hint style="info" %}
`PaymentMethodId` will only applicable for Successful payments.&#x20;
{% endhint %}

{% tabs %}
{% tab title="v2.0 Notification" %}

<pre class="language-json5"><code class="lang-json5"><strong>// Sample for non-USD payments initiated
</strong>https://&#x3C;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 // Only applied to Recurring Binding (CIT for MIT)

// Sample for USD payments initiated
https://&#x3C;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 // Only applied to Recurring Binding (CIT for MIT)
</code></pre>

{% 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/codapay/recurring-payments/initiate-payment-account-binding.md?ask=<question>&goal=<user_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.