Getting Started with PayKun Payment Gateway

Welcome to PayKun Developer Documentation section. Here you will find comprehensive guides and documentation to start working with PayKun.

Introduction:

With our API, you can authorize, capture, settle and refund all your payments on single click. Moreover, you can access all references of previous payments.

Getting Started:

If you want to start accepting payments with PayKun, you need to go through following:

  1. API Key (Generated from PayKun Dashboard)
  2. Integrated Checkout Form (for Website/App)
  3. Backend payment capturing process

To integrate the Checkout Form in your website, read the section below for Web Integration details. For mobile devices, read the section for Mobile Integration in Android and iOS device details.

General Payment Flow:

The payment flow will take place in following way:

  1. Order Creation

    Order is created whenever the customer fills up the checkout form and submits the information to the PayKun API. Still there is no processing has been done on the actual payment at this stage.

  2. Authorization and Capture

    An authorization is done when the payment details are processed and authenticated by the bank. At this time, money is just deducted from the customer’s bank, but not yet transferred to the merchant’s account until it is captured by the merchant.

    After successful authorization, for the next step merchant needs to capture the payment. Capture verifies that purchase as complete by the merchant. After capture, money is transferred to the merchant’s bank account within T+3 days (Can take longer depending on payout cycle), where T indicates day on which payment is captured by the merchant.

    At PayKun Payment Gateway, we don't have separate capturing process, once bank has authorised the customer’s payment, it will be auto captured and then no any further action is needed from merchant side.

  3. Refund

    Once the payment is captured successfully, it can only be refunded by the merchant.

Authentication

To perform any task using PayKun API you will need to provide credentials, below is the details of which type of credentials you will need based on your platform:

WEB:

PayKun provides unique Access Token and API Secret Key to every merchant. [See “How to Get Access Token & API Secret KEY (For Web)”]

For all other server-side requests like transaction initialization, transaction detail retrieval, refund details, settlement details, etc. it must be authenticated using the similar unique Access Token and API Secret Key.

Mobile:

PayKun provides unique Access Token and API Secret Key to every merchant. [See “How to Get Access Token & API Secret KEY (For Device)”]

For all other server-side requests like transaction initialization, transaction detail retrieval, refund details, settlement details, etc. it must be authenticated using the similar unique Access Token and API Secret Key.

Types of Integration:

PayKun Checkout offers three different types of Integrations:

  1. Web-Hosted Checkout
  2. JS Checkout (Coming Soon)
  3. Seamless Checkout (PCI required)
Web-Hosted Checkout

It is the simplest and easy way of checkout. On merchant website, when customer clicks on the “Pay Now” button, they will be redirected to the PayKun Payment Gateway. Here, customers can choose payment modes and have to fill payment details as well.

JS Checkout

In this type of payment mode, clicking on “Pay Now” will only display a Pop Up, where customer must fill all personal and necessary information and it will be sent to payment gateway server.

Seamless Checkout (PCI required)

Seamless Checkout offers true branding, where merchants can create and customize their own Checkout pages and all payment details will be sent to their servers. Hence customer will be able to complete payment without leaving merchant website. (Customer may be redirected to banks authorization page)

** For Seamless Checkout option, merchant must need to be compliant with PCI DSS.

Parameter Details

Parameter Name Constraints Required in web Required in device Description Sample Value
merchant_id Alphanumeric Yes Yes Your Merchant Id, you can get it from your merchant dashboard under My account -> profile section 357851063624213
access_token Alphanumeric Yes Yes Your access token, you have to generate your token from merchant dashboard under settings -> security (For android and ios device you have to generate device api key) 297E1CBBD172DA76325163469CB8D1EA
IsLive Boolean No Yes Set it to true for live transaction and false for test transaction True
order_no Alphanumeric, length should be between 10 To 30 Yes Yes Unique order id, if order id is already paid then Invalid Request error will be shown ORD20180910
product_name Alphanumeric Yes Yes Any product name that this transaction is for, it will be displayed at checkout page DVD
amount Double, Up to two decimals Yes Yes Transaction Amount, only up to two decimals is supported 20.00
success_url* Valid URL Yes No Any valid URL, if transaction is success then customer will be redirected back to this URL and you will get payment_id as query string https://example.com/success
failure_url* Valid URL Yes No Any valid URL, if transaction is failed then customer will be redirected back to this URL and you will get payment_id as query string https://example.com/failed
customer_name Alphanumeric Optional Optional Your customer name, if you provide this then it will be auto filled at checkout page Customer Name
customer_email Valid email address Optional Optional Your customer email, if you provide this then it will be auto filled at checkout page [email protected]
customer_phone Numeric, can include special characters Optional Optional Your customer phone number, if you provide this then it will be auto filled at checkout page 1234567890
shipping_address Alphanumeric, can include special characters Optional No Your customer shipping address, if you provide this then it will be auto filled at checkout page 100, Flat, city - 000000
shipping_city Alphanumeric Optional No Your customer shipping city, if you provide this then it will be auto filled at checkout page City
shipping_state Alphanumeric Optional No Your customer shipping state, if you provide this then it will be auto filled at checkout page State
shipping_country Alphanumeric Optional No Your customer shipping country, if you provide this then it will be auto filled at checkout page Country
shipping_zip Numeric Optional No Your customer shipping zip, if you provide this then it will be auto filled at checkout page Your customer name, if you provide this then it will be auto filled at checkout page 000000
billing_address Alphanumeric, can include special characters Optional No Your customer billing address, if you provide this then it will be auto filled at checkout page 100, Flat, city - 000000
billing_city Alphanumeric Optional No Your customer billing city, if you provide this then it will be auto filled at checkout page City
billing_state Alphanumeric Optional No Your customer billing state, if you provide this then it will be auto filled at checkout page State
billing_country Alphanumeric Optional No Your customer billing country, if you provide this then it will be auto filled at checkout page Country
billing_zip Numeric Optional No Your customer billing zip, if you provide this then it will be auto filled at checkout page 000000
udf_1 Alphanumeric, can include special characters Optional No User defined field, you can send any value that you want to associate with transaction for future processing Test_value_1
udf_2 Alphanumeric, can include special characters Optional No User defined field, you can send any value that you want to associate with transaction for future processing Test_value_2
udf_3 Alphanumeric, can include special characters Optional No User defined field, you can send any value that you want to associate with transaction for future processing Test_value_3
udf_4 Alphanumeric, can include special characters Optional No User defined field, you can send any value that you want to associate with transaction for future processing Test_value_4
udf_5 Alphanumeric, can include special characters Optional No User defined field, you can send any value that you want to associate with transaction for future processing Test_value_5

WEB INTEGRATION

How to Generate Access Token & API Secret KEY (For WEB)

You can generate/regenerate Access token and API KEY from your PayKun Admin panel.

Go to: Settings => Security => API KEY

Here you will find generate button, if you have not generated any API KEY before.

If you have ever generated any API KEY, you will see the creation date of it. You won’t be able to retrieve any old API KEY (Due to security concerns), that’s why we have provided regenerate option.

You can also regenerate API KEY in case you lost the older one.

Note:
Once you regenerate API KEY, your old API KEY will immediately stop working. So be double sure and cautious before regenerating API KEY
Web Integration - Encryption

All server to server data should be encrypted using AES-256-CBC with HMAC. Pseudo Code for encryption is explained below:

                    Input: plain_text
Input: api_secret
iv = generated random 16 byte
enc_text = Encrypt plain_text Using AES-256-CBC, api_secret & iv
b_iv = Base64 Encode iv
concat_string = b_iv + enc_text [Concat string]
mac = Generate SHA256 Hash of concat_string using api_secret [HMAC]
data_array = array of iv, enc_text, mac
json_string = Convert data_array into Json String
final_encrypted_text = Base64 Encode json_string
                
PHP Example:
                    function encrypt ($text, $key) {
      $iv = random_bytes(16);
      $value = openssl_encrypt(serialize($text), 'AES-256-CBC', $key, 0, $iv);
      $bIv = base64_encode($iv);
      $mac = hash_hmac('sha256', $bIv.$value, $key);
      $c_arr = ['iv'=>$bIv,'value'=>$value,'mac'=>$mac];
      $json = json_encode($c_arr);
      $crypted = base64_encode($json);
      return $crypted;
 }
                

Encryption should be done using API Secret Key.

Do not transfer or send this API Secret Key in any request.

Web Integration - Request:

Transaction can be initiated using form POST Request at following gateway URL:

For Live Transaction: https://checkout.paykun.com/payment

For Test Transaction: https://sandbox.paykun.com/payment

Form should contain three inputs to make this input as hidden to prevent exposure:

  • merchant_id
  • access_token
  • encrypted_request

Here, encrypted_request is encrypted “||” separated data string, all parameters should first concat using “||” in following format:

param_1: value_1 || param_2: value_2 || param_3: value_3 || ...

Example :

amount::20;billing_address::billing_address;billing_city::billing_city;billing_country::billing_country;billing_state::billing_state;billing_zip::billing_zip;customer_email::customer_email;customer_name::customer_name;customer_phone::customer_phone;failure_url::failure_url;order_no::order_no;product_name::product_name;shipping_address::shipping_address;shipping_city::shipping_city;shipping_country::shipping_country;shipping_state::shipping_state;shipping_zip::shipping_zip;success_url::success_url;udf_1::any_extra_param_you_want

And then it should be encrypted using the encryption algorithm shown in the following example of form that can be used:

Example :

encrypt("amount::20;billing_address::billing_address;billing_city::billing_city;billing_country::billing_country;billing_state::billing_state;billing_zip::billing_zip;customer_email::customer_email;customer_name::customer_name;customer_phone::customer_phone;failure_url::failure_url;order_no::order_no;product_name::product_name;shipping_address::shipping_address;shipping_city::shipping_city;shipping_country::shipping_country;shipping_state::shipping_state;shipping_zip::shipping_zip;success_url::success_url;udf_1::any_extra_param_you_want", api_secret)

                    <html lang="en">
  <head>
  <title>Processing Payment...</title>
  <meta http-equiv="content-type" content="text/html;charset=utf-8">
  </head>
  <body>
    <div>
      Processing your payment, please wait...
    </div>
    <form action="{gateway_url}" method="post" name="server_request" target="_top" >
      <table width="80%" align="center" border="0" cellpadding="0" cellspacing="0">
        <tr>
          <td>
            <input type="hidden" name="encrypted_request" id="encrypted_request" value="{encrypted_request}" />
          </td>
        </tr>
        <tr>
          <td>
            <input type="hidden" name="merchant_id" id="merchant_id" value="{merchant_id}" />
          </td>
        </tr>
        <tr>
          <td>
            <input type="hidden" name="access_token" id="access_token" value="{access_token}">
          </td>
        </tr>
      </table>
    </form>
    <script type="text/javascript">
      document.server_request.submit();
    </script>
  </body>
</html>

                
Test Environment:

Test mode is a tool which allows you to simulate the actual payment process as if you were using it real in live payment gateway. Please note that test mode is only for the development and testing purpose do not use it on a production site.

Test Environment Activation:

To activate test mode just login to your PayKun account and click on your account icon (upper right corner) >> Select Test Mode.

Then, you will see a pop up asking to generate sandbox account (by default it is inactive).

Fill user credentials like username and password for your sandbox account and click on the sandbox login.

If you have already active sandbox account and you have forget the password then, you can change your password by clicking on update password button.

Web Integration - Response:

Once transaction is completed, user will be redirected to given request URL. If transaction is successful, user will be redirected automatically to given success_url, if transaction gets fail, user will be redirected to provided failure_url.

In both cases, payment_id will be provided as query parameter; hence you can use this payment_id as transaction_id to retrieve transaction details and status information from the given API.

More details about API is explained in API reference section.

Error Codes - WEB:

Sandbox:

INVALID_REFERREL: When request is initiated from unauthorized/invalid website, try initiating request from authorized website only.

INVALID_MERCHANT: Merchant ID is not found, or Merchant is not active to perform the transaction.

INVALID_TOKEN: Provided access token is invalid.

PRIMARY_VALIDATION_FAIL: Primary data validation is failed, might be due to the following reason:

  • Duplicate Order ID
  • Invalid Amount
  • Invalid Order ID
  • Empty Transaction Limit
Production:

In Production mode/phase, no error code will be displayed. For any other cases, one of the following general message will be displayed:

Invalid Request:

This error will be shown in the following conditions:

  • Invalid Merchant ID/Token
  • Merchant is inactive for live transaction
  • Duplicate/Invalid Order ID
  • Invalid Amount
  • Empty Transaction Limit
Unauthorized Request:

This error will be shown only if there is an error with Access Token or API Secret or when request is initiated from unauthorized website.

Internal Server Error:

This error will be displayed when something went wrong in server.

Generally it is a temporary error. But if you are facing this error continuously, report it to [email protected]

Mobile Integration

How to Get Access Token (For Device)

Device access token is bounded with the application package name; hence one Access Token per Application will be granted.

You can generate/regenerate Access token and API KEY by logging into your PayKun Admin panel.

Go to: Settings => Security => Device API KEY Here you will find generate button, if you have not generated any Device Access Token before.

You must provide the package name of your application to generate the access token.

If you have ever generated any Access Token, you will see Package Name with Creation date of it. You won’t be able to retrieve any old Access Token (Due to security concerns), that’s why we have provided regenerate option.

Note:
Once you regenerate API KEY, your old API KEY will immediately stop working. So be double sure and cautious before regenerating API KEY.
Mobile SDK

You can find integration doc and SDK at following URLs:

Libraries & SDKs

We have multiple plugins available as per your requirements.

Please check out this page to download the relevant one https://github.com/paykun-code

You can get in touch with us at https://paykun.com/contact for any integration related queries.

Webhook (Coming Soon) :

Webhooks helps you get notified about events that happens over PayKun.

For example, when a buyer makes payment, PayKun can send an HTTP POST request to merchant server. This avoids keep polling over PayKun servers for updates.

It is simply a communication channel between PayKun servers and merchant servers.

Webhooks allow you to build or set up integrations which subscribe to certain events on PayKun API.

Functional use cases of Webhook are:

  • Sending customized emails to merchant at the end of every transaction.
  • Registration of a new user account on server.