Initiate a payment request

Allows you to initiate a payment request and collect your payment transaction ID.

Pre-requisite

When integrating with Codapay's API, ensure you adhere to the following standards:

1. Use HTTPS protocol.

2. TLS 1.2 or higher

Request Parameters

POST {Base URL}/init.json

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
initRequest.payType	String	Mandatory The ID of the payment channel you want to use. 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 the Getting started section to find out how to get it.
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
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 or 1 and wish to know which payment channel has been selected by your user, you can pass any non-null value in this field.

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.

Samples

Request

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

Successful Response

{
    "initResult": {
        "resultCode": 0,
        "txnId": 7177415887085060516
    }
}

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"
                },
                {
                    "key": "in_frame_redirect",
                    "value": "true"
                },
                {
                    "key": "return_url",
                    "value": "https://www.example.com/{transactionId}/{orderId}/return"
                },
                {
                    "key": "need_mno_id",
                    "value": "YES"
                }
            ]
        }