> 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/direct-api-integration/direct-api-integration-for-alternative-payment-methods/initiate-usd-transactions.md).

# Initiate USD Transactions

{% hint style="warning" %}
Please take note that Backend API USD transactions require some specification on the currency code.
{% endhint %}

## Request Message

<table><thead><tr><th width="148">Parameters</th><th width="95">Type</th><th width="116">Length</th><th>Description</th></tr></thead><tbody><tr><td>api_key</td><td>String</td><td>256</td><td><strong>Mandatory</strong><br>API key provided by Coda. Refer to <a data-mention href="/pages/SJ2KtFdcmUYgMDiplZT1">/pages/SJ2KtFdcmUYgMDiplZT1</a> to find out how to get it.</td></tr><tr><td>project_id</td><td>String</td><td>10</td><td><p>*<strong>This field is only needed for v2.0 API</strong></p><p><strong>Mandatory</strong> </p><p>Project ID provided by Coda, unique for each title product. Refer to <a data-mention href="/pages/SJ2KtFdcmUYgMDiplZT1">/pages/SJ2KtFdcmUYgMDiplZT1</a> to find out how to get it.</p></td></tr><tr><td>order_id</td><td>String</td><td>64</td><td><p><strong>Mandatory</strong> </p><p>Your unique identifier for the transaction</p></td></tr><tr><td>country</td><td>Number</td><td>N/A</td><td><strong>Mandatory</strong><br>ISO 3166 based country code. Can refer to <a data-mention href="/pages/7B3qZnefeSwkSs84sKuB">/pages/7B3qZnefeSwkSs84sKuB</a></td></tr><tr><td>lang</td><td>String</td><td>2</td><td><p><strong>Mandatory</strong></p><p>2-character language code. See <a data-mention href="/pages/lumiE4ZV7er3NqdusLTc">/pages/lumiE4ZV7er3NqdusLTc</a>for options.</p></td></tr><tr><td>type</td><td>Number</td><td>1</td><td>1: Digital content,<br>2: Non-digital content</td></tr><tr><td>pay_type</td><td>Number</td><td>1</td><td><p><strong>Mandatory</strong></p><p>Carrier Billing use pay_type = 1<br><br>For Carrier billings, if customers enter MSISDN of different carrier billings than the carrier billings in request message, the transaction will be failed with error 240. </p><p></p><p>Refer <a data-mention href="/pages/H5smNhrW5H8UuJgvQJ6Y">/pages/H5smNhrW5H8UuJgvQJ6Y</a> for more details</p></td></tr><tr><td>mno_code</td><td>Number</td><td>N/A</td><td><p><strong>Mandatory</strong></p><p>Mobile Network Code. If empty, Coda selects available MNO.</p></td></tr><tr><td>msisdn</td><td>Number</td><td>15</td><td><p><strong>Optional</strong></p><p>MSISDN (non-formatted; without country code).<br><br>Only include this if MSISDN is required and not email.</p></td></tr><tr><td>items</td><td>ItemInfo</td><td>N/A</td><td><p><strong>Mandatory</strong></p><p>List of items being purchased by the users</p></td></tr><tr><td>items[].code</td><td>String</td><td>128</td><td><p><strong>Mandatory</strong></p><p>Code associated with the item on your side</p></td></tr><tr><td>items[].name</td><td>String</td><td>128</td><td><strong>Mandatory</strong> Name of the item being purchased. Only supports latin characters.</td></tr><tr><td>items[].price</td><td>Number</td><td>N/A</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>profile</td><td>Map</td><td>N/A</td><td><strong>Mandatory</strong><br>Refer Profile Info below for more details</td></tr></tbody></table>

### Profile Info

{% hint style="warning" %}
USD transactions require profile info params with **`"currency_code": "840"`**
{% endhint %}

<table><thead><tr><th width="160">Parameters</th><th width="95">Type</th><th width="83">Length</th><th>Description</th></tr></thead><tbody><tr><td>user_id</td><td>String</td><td>N/A</td><td><p><strong>Mandatory</strong> </p><p>Your user's unique identifier</p></td></tr><tr><td>currency_code</td><td>Number</td><td>3</td><td><p><strong>Mandatory</strong></p><p>Set USD with <code>"currency_code": "840"</code></p></td></tr></tbody></table>

## Response Message

<table><thead><tr><th width="143">Parameter</th><th width="111">Type</th><th width="88">Length</th><th>Description</th></tr></thead><tbody><tr><td>txn_id</td><td>Number</td><td>N/A</td><td>Unique payment transaction identifier.</td></tr><tr><td>txn_timeout</td><td>Number</td><td>N/A</td><td>Transaction Timeout in Minutes.</td></tr><tr><td>result_code</td><td>Number</td><td>N/A</td><td>Success Resultcode is Success = 0.<br><br>Error Code list please refer to [<a href="/pages/Ijfanb3Eb2mtXRsbF81n">Error Codes</a>]</td></tr><tr><td>total_price</td><td>Number</td><td>N/A</td><td>The total amount the user has paid for the transaction. This will always be in local currency</td></tr><tr><td>pay_instructions</td><td>String</td><td>15</td><td>If this value is populated, publisher should display the instructions provided on screen to the customer.</td></tr><tr><td>profile</td><td>Map</td><td>N/A</td><td>Refer the Profile info below for more details</td></tr></tbody></table>

### Profile Info

<table><thead><tr><th width="205">Parameter</th><th width="95">Type</th><th width="91">Length</th><th>Description</th></tr></thead><tbody><tr><td>extInfoByte</td><td>Number</td><td>N/A</td><td>This is for Coda internal reference , please ignore this field.</td></tr><tr><td>foreign_currency_code</td><td>Number</td><td>3</td><td>Currency is used for the actual payment charged to the user.</td></tr><tr><td>exchange_rate</td><td>Number</td><td>N/A</td><td>Coda's USD exchange rate updates daily.</td></tr><tr><td>foreign_currency_amt</td><td>Number</td><td>N/A</td><td>The original amount provided in the initiation request</td></tr><tr><td>local_currency_code</td><td>Number</td><td>3</td><td>Local currency of the respective regions.<br><br>To know more about each currency code please refer to <a href="/pages/7B3qZnefeSwkSs84sKuB"><strong>Country and Currency Codes</strong></a></td></tr><tr><td>currency_code</td><td>Number</td><td>3</td><td>Initiate order with USD will be returned "currency_code":"840".</td></tr><tr><td>local_currency_amt</td><td>Number</td><td>N/A</td><td>The total amount the user has paid for the transaction. This will always be in local currency.</td></tr></tbody></table>

## Samples

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

```json
{
    "api_key": "test_e944d44f065eade8157737385a09",
    "order_id": "123456",
    "project_id": "1",//This field is only needed for v2.0 API
    "lang": "en",
    "merchant_name": "Codapay",
    "pay_type": "5",
    "pay_channel": -76,
    "pay_at": "4",
    "type": "1",
    "country": "702",
    "items": [
        {
            "code": "456789",
            "name": "Test Item",
            "price": 100
        }
    ],
    "profile": {
        "user_id": "12345"
    }
}
```

{% endtab %}

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

```json
{
    "api_key": "e944d44f065eade8157737385a094a",
    "order_id": "123456",
    "lang": "en",
    "merchant_name": "Amazon",
    "pay_type": "5",
    "pay_channel": -76,
    "pay_at": "4",
    "type": "1",
    "items": [
        {
            "code": "456789",
            "name": "GameCredit",
            "price": 100
        }
    ],
    "profile": {
        "user_id": "12345",
        "currency_code": "840"
    }
}
```

{% endtab %}

{% tab title="Successful Response" %}

```json
{
"txn_id": 7395063022892074013,
    "txn_timeout": 19,
    "result_code": 0,
    "result_desc": null,
    "total_price": 135.33,
    "pay_instructions": "",
    "profile": {
        "extInfoByte": "0",
        "foreign_currency_code": "840",
        "exchange_rate": "1.3533",
        "foreign_currency_amt": "100.0",
        "local_currency_code": "702",
        "currency_code": "840",
        "local_currency_amt": "135.33",
        "user_id": "12345",
        "projectId": "1",
        "merchantType": "Codapay",
        "redirect_url": "https://partner-api.stg-myteksi.com/grabid/v1/oauth2/authorize?acr_values=consent_ctx%3AcountryCode%3DSG,currency%3DSGD&client_id=8488e516acc54f88bad99c435cc18fdd&redirect_uri=https%3A%2F%2Fmidas.codapayments.com%2Fepcgw%2Fgrab%2Fredirect&request=eyJhbGciOiAibm9uZSJ9.eyJjbGFpbXMiOnsidHJhbnNhY3Rpb24iOnsidHhJRCI6ImFkNzI5ZjA1NzQ0MzQyMTA4ODQ5ZDQyMzcyZTFlYWZiIn19fQ.&response_type=code&code_challenge=csKQlGqOEs5LVHsLEFRQemfNIu4inReam4wfysr8zZY&code_challenge_method=S256&scope=payment.one_time_charge&state=7395063022892074846&nonce=0r2bt4lD0oRHxh9B",
        "payment_code": ""
    }
}
```

{% endtab %}

{% tab title="Failed Response" %}

```json
{
    "txn_id": 0,
    "txn_timeout": 0,
    "result_code": 103,
    "result_desc": "This transaction has been cancelled. No charges were made. (error:103)",
    "total_price": 0.0,
    "pay_instructions": null,
    "profile": null
}
```

{% 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/direct-api-integration/direct-api-integration-for-alternative-payment-methods/initiate-usd-transactions.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.