The main transaction request API is used to process all payments, regardless if they are through either your own payment pages, the managed form, or if you are using the hosted payment pages.

All requests are made using server-to-server calls, with JSON format data. The transaction request API must not be used from a browser.



In this article you will be going to know about:



This article is about the common structure between the own payment pages, the managed form, and the hosted payment page endpoints. All the mandatory fields for each one will be mentioned on its own solution article



API Endpoints


An API endpoint is a point at which an API -- the code that allows your system and ClickPay one to communicate with each other -- connects with the software program. APIs work by sending requests for information from ClickPay servers and receiving a response.


The API endpoint that can be used with your account is differentiating from one region (country) to another which is available at Merchant Dashboard > Developers > Getting Started > Transaction  API




This is a must step, not using the proper endpoint domain will lead to authentication errors in your responses


Postman Collection

For the purposes of this article, you will need to use the following postman collection for testing and integrating, for proceeding with this please click here.

Request Authentication


You will need your profile_id and server_key in order to make any of the API requests in this collection. This is not the same as the client key that is used within the managed payment pages. 

Authentication is done by including your server_key in the ‘Authorization:’ header for the request.

For more details about where to find the profile_id and server_key check here.


(Authorization Type: API key)




The Request Payload (Body)

All requests must be sent using HTTP POST to the ClickPay transaction API endpoint ({{ClickPay API Endoint}}/payment/request)


The main details needed in the request payload are:


  1. Merchant profile ID (profile_id)
  2. Item cost (cart_amount)
  3. Currency (cart_currency) Must be 3 Character ISO currency code 
  4. Description (cart_description)
  5. Unique order reference (cart_id)
  6. Either the callback URL (callback) or the return URL (return) for your store (these URLs will only be used if the transaction required any form of browser redirection)
  7. Transaction Type (tran_type)
    ValueDescription
    salePurchase Transaction
    authTransaction in auth and capture mode
    captureCapturing authorized transaction
    voidVoiding authorized transaction
    refundRefund Transaction of fully captured transaction

  8. Transaction Class (tran_class)
    Value
    Description
    ecomECommerce Online Transaction
    motoMail Order Telephonic Order Transaction
    recurring

    Recurring token-based transaction



The Response Payload (Body)

The response from the transaction API can be grouped into 3 main categories:




1. Transaction Processing Result

If the transaction can be processed without requiring any additional details, then the response from the API will be the final transaction results.


2. Redirection

If for any reason additional information is needed from the customer, then the system will trigger a browser redirect. You must navigate the customer to the URL provided, using the method indicated.

This can happen if (as an example) the customers' card issuer requires 3DSecure authentication or in the case of hosted payment page integration.


Once the customer has completed the steps required by the redirection, the ClickPay gateway will process the transaction, and only once that has been completed, the actions will be taken depending on whether you supplied a callback URL or a return URL in the original request payload.



If you supplied a callback URL, then  ClickPay gateway will send the transaction results to that URL using a HTTP POST. This will be a purely server-to-server request, the customers browser will not be involved.

Your systems should provide HTTP response with response codes 200 or 201.


3. Errors

ClickPay uses conventional HTTP response codes to indicate the success or failure of an API request. In general:


Codes in the 2xx range indicate success.

Codes in the 4xx range indicate an error if the system is unable to process the request due to (for example) any errors within the request details.

Codes in the 5xx range indicate an error with ClickPay’s servers (these are rare cases, don't worry).


The response body will include app error code (that could be handled programmatically) and error message