> 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-component-integration/cards/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

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/Component</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/Component</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><br><strong>Note: Taiwan is not supported currently</strong></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><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.</td></tr><tr><td>initRequest.isTaxInclusiveAmount</td><td>Boolean</td><td><p><strong>*Supported for the U.S. market only</strong></p><p><strong>Optional</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/qmDr2wr2jTZbmLuUnwbB"><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</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><strong>Mandatory</strong><br>List of items being purchased by the users</td></tr><tr><td>initRequest.items[].code</td><td>String</td><td><strong>Optional</strong><br>Code associated with the item on your side</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.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></tbody></table>

### Response Parameters

<table><thead><tr><th width="250">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>initResult.clientSecret</td><td>String</td><td>This is only returned for hosted component integrations. The client secret authorizes the SDK to load the card fields for this specific transaction.</td></tr></tbody></table>

### Samples

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

```json
{
  "initRequest": {
    "country": 840,
    "payType": 1006,
    "apiKey": "live_CVcqKHR12es0UHRvSsdHnTOizCIq",
    "projectId": 102,
    "orderId": "12321312321314",
    "currency": 840,
    "items": [
      {
        "code": "1",
        "price": 3,
        "name": "Item Name"
      }
    ],
    "profile": {
      "entry": [
        {
          "key": "user_id",
          "value": "105"
        }
      ]
    }
  }
}
```

{% endtab %}

{% tab title="Successful Response" %}

```json
{
    "initResult": {
        "resultCode": 0,
        "txnId": 7726919418568084576,
        "clientSecret": "eyJhbGciIU4zI1NiIsI8nR5cCI6IkpXVCJ9.eyJpYXQiOjE3NzI2OTE5NDMsImV4cCI6MTc3MjY5MzE0MywiaXNzIjoiaHR0cHM6Ly9hcGktdGMtY2FyZC5jb2RhcGF5bWVudHMuY29tLyIsInBhcnRuZXJfaWQiOiJwYXJfc2cxOTJhZDE4MGY2MDAwMDEiLCJkYXRhIjoiQ2dFeEVnbEpkR1Z0SUU1aGJXVWFBek11TUNJRFZWTkVLZzR4TWpNeU1UTXhNak15TVRNeE5Eb0NWVk5DRXpjM01qWTVNVGswTVRnMU5qZ3dPRFExTnpaS2ZIc2liV1Z5WTJoaGJuUmZjMlYwZEd4bGJXVnVkRjlwWkNJNk5URXlPU3dpYldWeVkyaGhiblJmYm1GdFpTSTZJbFZ1YVhSNUlGUmxjM1FpTENKdFpYSmphR0Z1ZEY5cFpDSTZNalkzTkRZc0luQmpjRjlwWkNJNk5ESXNJbTF1YjE5cFpDSTZNVEF3Tml3aWJXVnlZMmhoYm5SZmRIbHdaU0k2TVgxYUFIQUIifQ.3UqtMwDZQx8gfyNPFNd3gA7BqiNBRc-z33fEfz4L8cU"
    }
}
```

{% 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 ](#profile)Sample

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

```json
"profile": {
            "entry": [
                {
                    "key": "user_id",
                    "value": "test105"
                }
            ]
        }
```

{% 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-component-integration/cards/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.