Initiate a payment request
Allows you to initiate a payment request and collect your payment transaction ID.
Pre-requisite
When integrating with Codapay APIs, ensure you adhere to the following standards:
Use HTTPS protocol.
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
v2.0
https://sandbox.codapayments.com/airtime/api/restful/v2.0/Payment
v1.0
https://sandbox.codapayments.com/airtime/api/restful/v1.0/Payment
Production
v2.0
https://airtime.codapayments.com/airtime/api/restful/v2.0/Payment
v1.0
https://airtime.codapayments.com/airtime/api/restful/v1.0/Payment
Endpoint
POST {Base URL}/init.json
Request Parameters
initRequest
Object
Mandatory Must be a valid JSON object
initRequest.payType
String
initRequest.apiKey
String
Mandatory API key provided by Coda - Refer to Getting started to find out how to get it.
initRequest.projectId
String
*This field is only needed for v2.0 API
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
*This field is only applicable to the v2.0 API. *Supported for the U.S. market only.
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. Must be between 4 to 64 characters.
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.items[].skuImageUrl
String
Optional Publicly accessible URL for your SKU Image asset. Codapay will display this image on the checkout page for optimal checkout context & conversion-friendliness.
NOTE: Some payment channels that are using an older version of our client will not display the SKU Image. We aim to ensure all payment channels are upgrade to new client version by end of 2026.
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
user_id
String
Mandatory Your user's unique identifier
in_frame_redirect
True or False
Optional If you're using the hosted payment page within an iframe on your website, you can use this parameter to control the behavior after the payment flow is completed. If True - when the user tries to close the Codapay window, the user will be redirected to the landing URL within the iframe If False - when the user tries to close the Codapay window, the user will be redirected to the landing URL on a new tab
return_url
String
Optional This allows you to pass dynamically the return url the user will be redirected to after the payment is complete. This URL may contain the following query strings placeholders which will be replaced by actual values:
{transactionId}which will be replaced by Codapay Transaction Id{orderId}which will be replaced by βorderIdβ parameter value
This is optional, if this key-value is not used, Codapay will use the return url configured on publisher portal.
need_mno_id
Any value or null
If you initiated the payment with payType = 0 / 1 or carrier billing channels and wish to know which payment channel has been selected by your user, you can pass any non-null value in this field.
String
Optional
The email address where the successful transaction receipt will be sent. Upon a successful payment, Coda will automatically deliver a digital receipt to this address. This feature is not enabled by default. To activate automated receipt delivery for your titles, please contact the payment enablement team at codapay_integration@coda.co.
Receipt example:
client_ip
String
Optional This parameter (client_ip) is used to identify the userβs location and is only required if the payment channel specifically requests it. Must be in IPV4 format.
lang_code
String
Optional This parameter is used to select a language to use for the hosted payment page. The list of languages available for each country can be found here. e.g. en_US
Response Parameters
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.redirectUrl NEW
String
The URL to the checkout session. Applies to both Codapay Hosted Payment Page integration & Coda Links. Redirect the customers to this URL to proceed with checkout & payment.
For example: https://airtime.codapayments.com/airtime/begin?txn_id=714459463700207221
Samples
Profile Sample
Last updated
Was this helpful?