> 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/hosted-payment-page-integration/initiate-a-payment-request.md).

# Initiate a payment request

### Pre-requisite

When integrating with Codapay APIs, ensure you adhere to the following standards:

1. Use HTTPS protocol.
2. TLS 1.2 or higher

<table><thead><tr><th width="165">Environment</th><th>BaseURL</th></tr></thead><tbody><tr><td>Sandbox</td><td><a href="https://sandbox.codapayments.com/airtime/api/restful/v1.0/Payment">https://sandbox.codapayments.com/airtime/api/restful/v1.0/Payment</a></td></tr><tr><td>Production</td><td><a href="https://airtime.codapayments.com/airtime/api/restful/v1.0/Payment/init">https://airtime.codapayments.com/airtime/api/restful/v1.0/Payment</a></td></tr></tbody></table>

Note that Codapay APIs have two versions, please refer to [Codapay API Versions](/codapay/integration-guides/codapay-api-versions.md) for more details to ensure you have selected the right version to integrate with.

### Reference

#### Sandbox <a href="#sandbox-web-services-service-information" id="sandbox-web-services-service-information"></a>

<table><thead><tr><th width="107">Version</th><th>Base URL</th></tr></thead><tbody><tr><td>v2.0</td><td>https://sandbox.codapayments.com/airtime/api/restful/v2.0/Payment</td></tr><tr><td>v1.0</td><td>https://sandbox.codapayments.com/airtime/api/restful/v1.0/Payment</td></tr></tbody></table>

#### Production <a href="#production-web-services-service-information" id="production-web-services-service-information"></a>

<table><thead><tr><th width="107">Version</th><th>Base URL</th></tr></thead><tbody><tr><td>v2.0</td><td>https://airtime.codapayments.com/airtime/api/restful/v2.0/Payment</td></tr><tr><td>v1.0</td><td>https://airtime.codapayments.com/airtime/api/restful/v1.0/Payment</td></tr></tbody></table>

#### Endpoint

<mark style="color:green;">**POST**</mark>**&#x20;{Base URL}/init.json**

{% hint style="info" %}
Codapay's APIs support REST web services. By default, the endpoints displayed are RESTful.&#x20;
{% endhint %}

### Request Parameters

<table><thead><tr><th width="282">Parameter</th><th width="93">Type</th><th>Description</th></tr></thead><tbody><tr><td>initRequest</td><td>Object</td><td><strong>Mandatory</strong><br>Must be a valid JSON object</td></tr><tr><td>initRequest.country</td><td>String</td><td><strong>Mandatory</strong><br>ISO 3166 country code - refer to <a href="/pages/7B3qZnefeSwkSs84sKuB">Country and Currency Codes</a></td></tr><tr><td>initRequest.payType</td><td>String</td><td><strong>Mandatory</strong><br>The ID of the payment channel you want to use - refer to the full list available <a href="/pages/rdoVc0oxwR2mZFGuuyDe">here</a>. <br>Can be set to 0 if you want to use the channel selection page or 1 if you want to use the DCB page - More details <a href="/pages/6noelPac6O8nyEfCRV8d">here</a>.</td></tr><tr><td>initRequest.apiKey</td><td>String</td><td><strong>Mandatory</strong><br>API key provided by Coda - Refer to <a href="/pages/3LZq8zaG4X5CpSs54V8k">Getting started</a> to find out how to get it.</td></tr><tr><td>initRequest.projectId</td><td>String</td><td><p>*<strong>This field is only needed for v2.0 API</strong></p><p><strong>Mandatory</strong><br>Project ID provided by Coda, unique for each title product - Refer to <a href="/pages/3LZq8zaG4X5CpSs54V8k">Getting started</a> to find out how to get it.</p></td></tr><tr><td>initRequest.isTaxInclusiveAmount</td><td>Boolean</td><td><p>*<strong>This field is only applicable to the v2.0 API. *Supported for the U.S. market only.</strong></p><p>Whether the summed <code>items[].price</code> Already includes tax. Applies only when Coda is MoR in a supported tax market (currently the US). </p><p></p><p>When <code>true</code>, the item total is treated as tax-inclusive and charged as-is; </p><p></p><p>when <code>false</code> (or omitted), it is treated as tax-exclusive and tax is added on top. </p><p></p><p><strong>Defaults to <code>false</code></strong> if omitted, preserving existing behavior. Ignored when Coda is not MoR. </p><p></p><p>→ <em>See</em> <a href="/pages/bp4Qc1kdIwn1UE8ZzYXN#tax-handling-applicable-in-the-us-market-only"><em>[Check Status - Tax handling]</em> </a><em>for how this affects the response and tax breakdown.</em></p></td></tr><tr><td>initRequest.orderId</td><td>String</td><td><strong>Mandatory</strong><br>Your unique identifier for the transaction. Must be between 4 to 64 characters. </td></tr><tr><td>initRequest.currency</td><td>String</td><td><strong>Mandatory</strong><br>ISO 4217 currency code - refer to <a href="/pages/7B3qZnefeSwkSs84sKuB">Country and Currency Codes</a></td></tr><tr><td>initRequest.items</td><td>Array</td><td><p><strong>Mandatory</strong><br>List of items being purchased by the users</p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>US and Canada supports one item only. Multiple items support is WIP. </p></div></td></tr><tr><td>initRequest.items[].code</td><td>String</td><td><p><strong>Optional</strong><br>Code associated with the item on your side</p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>This field is mandatory for Taiwan Line Pay integration</p></div></td></tr><tr><td>initRequest.items[].price</td><td>Number</td><td><strong>Mandatory</strong><br>Price of the item inclusive of any taxes in the currency specified in the request.</td></tr><tr><td>initRequest.items[].name</td><td>String</td><td><strong>Mandatory</strong><br>Name of the item being purchased. Only supports latin characters.</td></tr><tr><td>initRequest.items[].skuImageUrl</td><td>String</td><td><p><strong>Optional</strong><br>Publicly accessible URL for your SKU Image asset. Codapay will display this image on the checkout page for optimal checkout context &#x26; conversion-friendliness.</p><div><figure><img src="/files/XcrIE97gd3nKs5QLflxn" alt="Sample checkout page with SKU Image" width="188"><figcaption></figcaption></figure></div><div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p>NOTE: Some payment channels that are using an older version of our client will not display the SKU Image. We aim to ensure all payment channels are upgrade to new client version by end of 2026.</p><p><img src="/files/3EV20GIK8wZAr5lh3aZk" alt=""></p></div></td></tr><tr><td>initRequest.profile</td><td>Object</td><td><strong>Mandatory</strong><br>User profile information of the user making the purchase</td></tr><tr><td>initRequest.profile.entry</td><td>Array</td><td><strong>Mandatory</strong><br>List of key-value pairs for profile information. Specific key-values that can be used to process currently are listed below.</td></tr><tr><td>initRequest.profile.entry[].key</td><td>String</td><td>Key for the profile entry</td></tr><tr><td>initRequest.profile.entry[].value</td><td>String</td><td>Key for the profile entry</td></tr></tbody></table>

#### Profile

<table><thead><tr><th width="178">Key</th><th width="155">Expected value</th><th>Description</th></tr></thead><tbody><tr><td>user_id</td><td>String</td><td><strong>Mandatory</strong><br>Your user's unique identifier</td></tr><tr><td>in_frame_redirect</td><td>True or False</td><td><strong>Optional</strong><br>If you're using the hosted payment page within an iframe on your website, you can use this parameter to control the behavior after the payment flow is completed. <br><br>If True - when the user tries to close the Codapay window, the user will be redirected to the landing URL within the iframe<br><br>If False - when the user tries to close the Codapay window, the user will be redirected to the landing URL on a new tab</td></tr><tr><td>return_url</td><td>String</td><td><p><strong>Optional</strong><br>This allows you to pass dynamically the return url the user will be redirected to after the payment is complete. This URL may contain the following query strings placeholders which will be replaced by actual values:</p><ul><li><code>{transactionId}</code> which will be replaced by Codapay Transaction Id</li><li><code>{orderId}</code> which will be replaced by “orderId“ parameter value</li></ul><p>This is optional, if this key-value is not used, Codapay will use the return url configured on publisher portal.</p></td></tr><tr><td>need_mno_id</td><td>Any value or null</td><td>If you initiated the payment with payType = 0 / 1 or carrier billing channels and wish to know which payment channel has been selected by your user, you can pass any non-null value in this field.</td></tr><tr><td>email</td><td>String</td><td><p><strong>Optional</strong></p><p>The email address where the successful transaction receipt will be sent. Upon a successful payment, Coda will automatically deliver a digital receipt to this address.<br><br><em>This feature is not enabled by default. To activate automated receipt delivery for your titles, please contact the payment enablement team at</em> <a href="mailto:codapay_integration@coda.co"><em>codapay_integration@coda.co</em></a><em>.</em> </p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><em>Receipt example:</em> <br><img src="/files/Qc0A59imkhpH80srHbs7" alt=""></p></div></td></tr><tr><td>client_ip</td><td>String</td><td><strong>Optional</strong><br>This parameter (client_ip) is used to identify the user’s location and is only required if the payment channel specifically requests it. Must be in IPV4 format. </td></tr><tr><td>lang_code</td><td>String</td><td><strong>Optional</strong><br>This parameter is used to select a language to use for the hosted payment page. The list of languages available for each country can be found <a href="/pages/TvHQKPp0fObDQU1DJ2rn">here</a>.<br><br>e.g. en_US</td></tr></tbody></table>

### Response Parameters

<table><thead><tr><th width="220">Parameter</th><th width="91">Type</th><th>Description</th></tr></thead><tbody><tr><td>initResult</td><td>Object</td><td>Contains the result of the initiation request</td></tr><tr><td>initResult.resultCode</td><td>Integer</td><td><p>Result code for the initiation request.</p><p></p><p><code>resultCode = 0</code> if the request is successful. Otherwise, the resultCode value is an error. Full list of error Codes is available <a href="/pages/Ijfanb3Eb2mtXRsbF81n">here</a>.</p></td></tr><tr><td>initResult.resultDesc</td><td>String</td><td>Description of the error, resultCode is not 0.</td></tr><tr><td>initResult.txnId</td><td>Integer</td><td>Transaction ID for the initiated request. If the transaction initiation failed this value will be 0.</td></tr><tr><td><strong>initResult.redirectUrl</strong><br><mark style="color:yellow;"><strong>NEW</strong></mark></td><td>String</td><td>The URL to the checkout session. Applies to both Codapay Hosted Payment Page integration &#x26; Coda Links. Redirect the customers to this URL to proceed with checkout &#x26; payment.<br><br>For example: <a href="https://airtime.codapayments.com/airtime/begin?txn_id=7144594637002072212&#x26;browser_type=mobile-web"><code>https://airtime.codapayments.com/airtime/begin?txn_id=714459463700207221</code></a></td></tr></tbody></table>

### Samples

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

```json
{
    "initRequest": {
        "country": 158,
        "payType": 82,
        "apiKey": "live_****************************",
        "projectId": 21 //This field is only needed for v2.0 API
        "orderId": "12321312321314",
        "currency": 901,
        "items": [
            {
                "code": "1",
                "price": 1000.00,
                "name": "Test Item"
            }
        ],
        "profile": {
            "entry": [
                {
                    "key": "user_id",
                    "value": "105"
                }
            ]
        }
    }
}
```

{% endtab %}

{% tab title="v1.0 Request " %}

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

```

{% endtab %}

{% tab title="Successful Response" %}

```json
{
    "initResult": {
        "resultCode": 0,
        "txnId": 7714940366302672840,
        "redirectUrl": "https://airtime.codapayments.com/airtime/begin?txn_id=7144594637002072212&browser_type=mobile-web&utm_source=facebook”
    }
}
```

{% endtab %}

{% tab title="Failed Response" %}

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

{% endtab %}
{% endtabs %}

### Profile Sample

{% tabs %}
{% tab title="Request" %}

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

{% 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.coda.co/codapay/hosted-payment-page-integration/initiate-a-payment-request.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.