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 for more details to ensure you have selected the right version to integrate with.

Reference

Sandbox

Version	Base URL
v2.0	https://sandbox.codapayments.com/airtime/api/restful/v2.0/Payment/Component

Production

Version	Base URL
v2.0	https://airtime.codapayments.com/airtime/api/restful/v2.0/Payment/Component

Endpoint

POST {Base URL}/init.json

Codapay's APIs support REST web services. By default, the endpoints displayed are RESTful.

Request Parameters

Parameter	Type	Description
initRequest	Object	Mandatory Must be a valid JSON object
initRequest.country	String	Mandatory ISO 3166 country code - refer to Country and Currency Codes Note: United States, Canada, and Taiwan is not supported currently
initRequest.payType	String	Mandatory The ID of the payment channel you want to use - refer to the full list available here. 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 here.
initRequest.apiKey	String	Mandatory API key provided by Coda - Refer to Getting started to find out how to get it.
initRequest.projectId	String	Mandatory Project ID provided by Coda, unique for each title product - Refer to Getting started to find out how to get it.
initRequest.isTaxInclusiveAmount	Boolean	*Supported for the U.S. market only Optional Whether the summed items[].price Already includes tax. Applies only when Coda is MoR in a supported tax market (currently the US). When true, the item total is treated as tax-inclusive and charged as-is; when false (or omitted), it is treated as tax-exclusive and tax is added on top. Defaults to false if omitted, preserving existing behavior. Ignored when Coda is not MoR. → See [Check Status - Tax handling] for how this affects the response and tax breakdown.
initRequest.orderId	String	Mandatory Your unique identifier for the transaction
initRequest.currency	String	Mandatory ISO 4217 currency code - refer to Country and Currency Codes
initRequest.items	Array	Mandatory List of items being purchased by the users
initRequest.items[].code	String	Optional Code associated with the item on your side
initRequest.items[].price	Number	Mandatory Price of the item inclusive of any taxes in the currency specified in the request.
initRequest.items[].name	String	Mandatory Name of the item being purchased. Only supports latin characters.
initRequest.profile	Object	Mandatory User profile information of the user making the purchase
initRequest.profile.entry	Array	Mandatory List of key-value pairs for profile information. Specific key-values that can be used to process currently are listed below.
initRequest.profile.entry[].key	String	Key for the profile entry
initRequest.profile.entry[].value	String	Key for the profile entry

Profile

Key	Expected value	Description
user_id	String	Mandatory Your user's unique identifier

Response Parameters

Parameter	Type	Description
initResult	Object	Contains the result of the initiation request
initResult.resultCode	Integer	Result code for the initiation request. resultCode = 0 if the request is successful. Otherwise, the resultCode value is an error. Full list of error Codes is available here.
initResult.resultDesc	String	Description of the error, resultCode is not 0.
initResult.txnId	Integer	Transaction ID for the initiated request. If the transaction initiation failed this value will be 0.
initResult.clientSecret	String	This is only returned for hosted component integrations. The client secret authorizes the SDK to load the card fields for this specific transaction.

Samples

Request

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

Successful Response

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

Failed Response

{
    "initResult": {
        "resultCode": 103,
        "resultDesc": "This transaction has been cancelled. No charges were made. (error:103)",
        "txnId": 0
    }
}

Profile Sample

Request

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