> 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/integration-guides/codapay-api-versions.md).

# Codapay API Versions

Codapay offers two versions of its API: v1.0 and v2.0.

While both versions are fully supported, **v2.0 is the recommended version for all new integrations**. It provides several improvements designed to simplify integration, improve maintainability, and enable access to newer features such as card saving.

#### Why v2.0?

**v2.0** introduces the concept of a **Global API Key**, replacing the need for multiple API keys across countries and titles. This reduces complexity and streamlines integration and credential management. Additionally, a **Project ID** field has been added to help distinguish different products or titles, enabling better transaction segmentation and reporting.

Some advanced features, including **saved card functionality**, are only available when using v2.0 API keys.

#### Key Differences: v1.0 vs v2.0

| Feature                  | v1.0                                  | v2.0                            |
| ------------------------ | ------------------------------------- | ------------------------------- |
| API Key                  | One key per title-country combination | One global API key per merchant |
| Project ID               | Not required                          | **Mandatory** for all requests  |
| Saved Card Support       | Not supported                         | Supported                       |
| Endpoint URL             | `/v1.0/Payment`                       | `/v2.0/Payment`                 |
| Request Payload Contract | No `projectId`                        | `projectId` is required         |

### Migrating from v1.0 to v2.0

If you are already integrated with **Codapay API v1.0**, we recommend upgrading to **v2.0** to benefit from a simplified integration and new features. The upgrade process is lightweight and compatible with your existing transaction logic.

#### Migration Steps

1. **Request a v2.0 API Key:** Contact your Codapay integration support to obtain your global API key and project ID(s).
2. **Update API Endpoint:** Switch your base URLs from `/v1.0/` to `/v2.0/` for both sandbox and production environments:
   * **Sandbox:** `https://sandbox.codapayments.com/airtime/api/restful/v2.0/Payment`
   * **Production:** `https://airtime.codapayments.com/airtime/api/restful/v2.0/Payment`
3. **Add the** `projectId` **Field:** Update your `initRequest` payload to include the `projectId`, which is **mandatory** in v2.0.

   ```json
   "initRequest": {
     "projectId": "YOUR_PROJECT_ID",
     ...
   }
   ```
4. **Retain Existing Fields:** All other request fields and flow remain unchanged. You can continue using the same logic for `country`, `payType`, `currency`, `items`, and `profile`.
5. **Test and Go Live:** Validate your integration against the v2.0 sandbox environment. Once verified, switch to the production endpoint and begin using the updated flow.

#### Sample Comparison

**v1.0 Sample**

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

```

**v2.0 Sample**

```json
{
    "initRequest": {
        "country": 158,
        "payType": 82,
        "apiKey": "e944d44f065eade8157737385a094a",
        "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"
                }
            ]
        }
    }
}
```


---

# 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/integration-guides/codapay-api-versions.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.