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.

   "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

{
    "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

{
    "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"
                }
            ]
        }
    }
}