> 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/getting-started/test-hosted-payment-page-api.md).

# Test Hosted Payment Page API

{% hint style="info" %}
This tutorial only shows how to test for a specific payment method. If you are interested in our Payment Selection Page, [you can follow this guide](/codapay/hosted-payment-page-integration/payment-channel-integration-options.md).
{% endhint %}

<figure><img src="/files/D9IyeljJ2biJp4Lso3d8" alt=""><figcaption></figcaption></figure>

## What you'll learn

* Initiating a payment request.
* What your customer will experience upon payment request.
* What your customer will experience upon a successful payment notification.

This tutorial assumes you have a developer set up and tools to make API calls (Postman, ...). If that is not the case, you can also test the flow through our Coda Portal ["Sandbox Testing"](https://portal.codapayments.com/integration/codapay/sandbox-testing) section.

***

## Step 1: Initiate the payment request

1. Initiate the payment request by calling the <mark style="color:red;">`/init`</mark> endpoint to collect your **payment transaction ID**. Use the curl below and populate it with:

<table><thead><tr><th width="145">Parameter</th><th width="304">Placeholder text</th><th>Description</th></tr></thead><tbody><tr><td>country</td><td><pre><code>[SELECTED_COUNTRY]
</code></pre></td><td>The country that you want to test. <a href="/pages/7B3qZnefeSwkSs84sKuB">See the full list here</a>.</td></tr><tr><td>currency</td><td><pre><code>[SELECTED_CURRENCY]
</code></pre></td><td>The currency code that you want to use. <a href="https://coda-payments.gitbook.io/coda-private-technical-documentation/references/country-and-currency-codes">See the full list here</a>.</td></tr><tr><td>payType</td><td><pre><code>[SELECTED_PAYMENT_CHANNEL_ID]
</code></pre></td><td>The payment method that you want to use. <a href="https://coda-payments.gitbook.io/coda-private-technical-documentation/codapay/payment-page-api/supported-payment-channels">See the full list here</a>.</td></tr><tr><td>apiKey</td><td><pre><code>[API_KEY]
</code></pre></td><td>Get your APIKey from <a href="/pages/3LZq8zaG4X5CpSs54V8k">Coda Portal</a>.</td></tr><tr><td>projectId</td><td><pre><code>[PROJECT_ID]
</code></pre></td><td><p>*This field is only needed for v2.0 API</p><p>Get the projectId for each title from <a href="/pages/3LZq8zaG4X5CpSs54V8k">Coda Portal</a>.</p></td></tr></tbody></table>

{% hint style="warning" %}
Make sure that the price is within transaction limits for the payment channel you’ve selected by [checking transaction limits here](/codapay/integration-guides/price-limits.md).
{% endhint %}

{% hint style="info" %}
Other parameters have been populated with dummy data for testing purposes below. They can be changed and populated properly as part of your integration. More details on the parameters of the <mark style="color:red;">`/init`</mark> endpoint [can be found here](/codapay/hosted-payment-page-integration.md).\
\
Codapay offers two API versions - v1.0 and v2.0, with v2.0 being an upgraded version. **If you are a new merchant, please use v2.0.** More details [can be found here](/codapay/integration-guides/codapay-api-versions.md).
{% endhint %}

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

<pre class="language-json"><code class="lang-json"><strong>curl --location 'https://sandbox.codapayments.com/airtime/api/restful/v2.0/Payment/init.json' \
</strong>--header 'Content-Type: application/json' \
--data '{
    "initRequest": {
        "country": [SELECTED_COUNTRY],
        "payType": [SELECTED_PAYMENT_CHANNEL_ID],
        "apiKey": [API_KEY],
        "projectId": [PROJECT_ID] //This field is only needed for v2.0 API
        "orderId": "12321312321314",
        "currency": [SELECTED_CURRENCY],
        "items": [
            {
                "code": "1",
                "price": 50.00,
                "name": "Test Item"
            }
        ],
        "profile": {
            "entry": [
                {
                    "key": "user_id",
                    "value": "105"
                }
            ]
        }
    }
}
</code></pre>

{% endtab %}

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

```json
curl --location 'https://sandbox.codapayments.com/airtime/api/restful/v1.0/Payment/init.json' \
--header 'Content-Type: application/json' \
--data '{
    "initRequest": {
        "country": [SELECTED_COUNTRY],
        "payType": [SELECTED_PAYMENT_CHANNEL_ID],
        "apiKey": [COUNTRY_API_KEY],
        "orderId": "12321312321314",
        "currency": [SELECTED_CURRENCY],
        "items": [
            {
                "code": "1",
                "price": 50.00,
                "name": "Test Item"
            }
        ],
        "profile": {
            "entry": [
                {
                    "key": "user_id",
                    "value": "105"
                }
            ]
        }
    }
}
```

{% endtab %}
{% endtabs %}

Below is an example using a dummy sandbox API Key for **Singapore**, with **Singapore Dollar (SGD)** as a currency and **Card Payments** as a payment method.

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

<pre class="language-json"><code class="lang-json"><strong>curl --location 'https://sandbox.codapayments.com/airtime/api/restful/v2.0/Payment/init.json' \
</strong>--header 'Content-Type: application/json' \
--data '{
    "initRequest": {
        "country": 702,
        "payType": 427,
        "apiKey": "test_32774abe1cd7d8bae650ea48265e",
        "projectId": 21 //This field is only needed for v2.0 API
        "orderId": "12321312321314",
        "currency": 702,
        "items": [
            {
                "code": "1",
                "price": 50.00,
                "name": "Test Item"
            }
        ],
        "profile": {
            "entry": [
                {
                    "key": "user_id",
                    "value": "105"
                }
            ]
        }
    }
}'
</code></pre>

{% endtab %}

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

```json
curl --location 'https://sandbox.codapayments.com/airtime/api/restful/v1.0/Payment/init.json' \
--header 'Content-Type: application/json' \
--data '{
    "initRequest": {
        "country": 702,
        "payType": 427,
        "apiKey": "32774abe1cd7d8bae650ea48265e",
        "orderId": "12321312321314",
        "currency": 702,
        "items": [
            {
                "code": "1",
                "price": 50.00,
                "name": "Test Item"
            }
        ],
        "profile": {
            "entry": [
                {
                    "key": "user_id",
                    "value": "105"
                }
            ]
        }
    }
}'
```

{% endtab %}

{% tab title="Response" %}

```json
{
   "initResult": {
       "resultCode": 0,
       "txnId": 7122167282516076304
   }
}
```

{% endtab %}
{% endtabs %}

***

## Step 2: Redirect your user to the payment page to complete payment

1. Use the received <mark style="color:red;">`txnId`</mark> from **Step 1** to redirect your user to the following URL:

{% hint style="info" %}
[Click here to see all the available parameters to pass in the URL.](/codapay/hosted-payment-page-integration/display-the-hosted-payment-page.md)
{% endhint %}

{% tabs %}
{% tab title="🖥️  Desktop" %}

<pre data-overflow="wrap"><code>https://sandbox.codapayments.com/airtime/begin?type=3&#x26;txn_id=<a data-footnote-ref href="#user-content-fn-1">[txnId]</a>
</code></pre>

{% endtab %}

{% tab title="📱 Mobile" %}

<pre data-overflow="wrap"><code>https://sandbox.codapayments.com/airtime/begin?type=3&#x26;txn_id=<a data-footnote-ref href="#user-content-fn-1">[txnId]</a>&#x26;browser_type=mobile-web
</code></pre>

{% endtab %}
{% endtabs %}

Below is an example of what it would look like for the transaction initiated above for **Card Payments** in **Singapore**:

{% tabs %}
{% tab title="🖥️  Desktop" %}

<figure><img src="/files/IUdRo6qKiAq5XZ0U76j4" alt=""><figcaption><p>https://sandbox.codapayments.com/airtime/begin?type=3&#x26;txn_id=7122167282516076304</p></figcaption></figure>
{% endtab %}

{% tab title="📱 Mobile" %}

<figure><img src="/files/vPeRdBixqLkH1XKMifqX" alt="" width="187"><figcaption><p>https://sandbox.codapayments.com/airtime/begin?type=3&#x26;txn_id=7122167282516076304&#x26;browser_type=mobile-web</p></figcaption></figure>
{% endtab %}
{% endtabs %}

2. In the sandbox environment, you can follow the testing instructions [provided here to complete the payment](broken://spaces/YHHTIo7U3NRvUwPKNG0G/pages/jaFqkOEJv6NkI7vKsHzd).

{% hint style="info" %}
Complete a test transaction with **Card Payments** in **Singapore** and use the following test card below.
{% endhint %}

<table><thead><tr><th width="321">Card number</th><th>Expiry date</th><th>CVC</th></tr></thead><tbody><tr><td><pre><code>4242 4242 4242 4242
</code></pre></td><td><pre data-full-width="false"><code>01/35
</code></pre></td><td><pre><code>123
</code></pre></td></tr></tbody></table>

{% hint style="warning" %}
**Note:** On the sandbox environment, the payment might take a few minutes to complete.
{% endhint %}

***

## Step 3: Receive the successful payment notification

1. You will receive a notification on the Complete Notification URL, including the following fields as query parameters:

<table><thead><tr><th width="170">Parameters</th><th>Description</th></tr></thead><tbody><tr><td>TxnId</td><td>Coda transaction ID</td></tr><tr><td>OrderId</td><td>OrderId passed by you in the init request</td></tr><tr><td>ResultCode</td><td>Payment status (e.g. success = 0)</td></tr><tr><td>TotalPrice</td><td>Total price paid by the user for the transaction</td></tr><tr><td>PaymentType</td><td>Payment Channel ID chosen by the user</td></tr><tr><td>Checksum</td><td>A checksum to verify that messages have not been altered</td></tr></tbody></table>

2. Respond to this notification with a success message <mark style="color:red;">`ResultCode=0`</mark> or a failure message (including an appropriate error code).

{% hint style="info" %}
If you want to try receiving an error response, simply replace the error code digit with any of the available error codes, [which you can access here.](/codapay/error-codes.md)
{% endhint %}

***

## Step 4: Check the status of a successful payment using the InquiryPaymentResult API call

Use the InquiryPaymentResult API call below to inquire about the payment status of your transaction.

{% hint style="info" %}
[Click here to see all the available parameters.](/codapay/hosted-payment-page-integration/check-a-transaction-status.md)
{% endhint %}

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

```json
curl --location 'https://sandbox.codapayments.com/airtime/api/restful/v2.0/Payment/inquiryPaymentResult.json' \
--header 'Content-Type: application/json' \
--data '{
    "inquiryPaymentRequest":
    {
        "apiKey" : "test_32774abe1cd7d8bae650ea48265e",
        "country": 702 //This field is only needed for v2.0 API
        "projectId" : 21 //This field is only needed for v2.0 API
        "txnId" : "7144594637002072212",
        "needStatusFinal": "true"
    }
}'
```

{% endtab %}

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

```json
curl --location 'https://sandbox.codapayments.com/airtime/api/restful/v1.0/Payment/inquiryPaymentResult.json' \
--header 'Content-Type: application/json' \
--data '{
    "inquiryPaymentRequest":
    {
        "apiKey" : "32774abe1cd7d8bae650ea48265e",
        "txnId" : "7144594637002072212",
        "needStatusFinal": "true"
    }
}'
```

{% endtab %}

{% tab title="Response" %}

```json
{
    "paymentResult": {
        "orderId": 12321312321314,
        "profile": {
            "entry": [
                {
                    "key": "PaymentType",
                    "value": 427
                },
                {
                    "key": "isStatusFinal",
                    "value": true
                },
                {
                    "key": "status",
                    "value": "success"
                }
            ]
        },
        "resultCode": 0,
        "resultDesc": "",
        "totalPrice": 50,
        "txnId": 7144594637002072212
    }
}
```

{% endtab %}
{% endtabs %}

## Next steps

* Dive deeper into Payment Page API to understand more about the [Hosted Payment Page](/codapay/hosted-payment-page-integration.md) and [Payment Channel Selection Page](/codapay/hosted-payment-page-integration/payment-channel-integration-options.md) offering.
* Dive deeper into our [Backend API](/codapay/direct-api-integration.md) offering.

[^1]: Replace the txnId response and copy then paste the complete URL.


---

# 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/getting-started/test-hosted-payment-page-api.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.