Introduction

ABC payment gateway facilitates payments between end users and merchants. We provide users and merchants to transfer Crypto. With a simple configuration/toggle capability, it can serve different options for different merchants based on their business needs, operating country/local region laws, compliances, etc.

Our payment gateway provides merchants with two types of integration options:

  1. Web-SDK Integration
  2. API Integration

These integration methods offer flexibility and convenience for merchants to seamlessly integrate our payment gateway into their applications, catering to their specific needs and preferences. Whether you prefer a ready-to-use user interface or want to build a custom solution, we have you covered.

Web-SDK Integration

Web-SDK Integration provides a user-friendly and streamlined approach for merchants to incorporate our payment gateway functionality into their web-based applications.

Upon integrating our web-SDK-based solution, you can launch the CPGModal, a user-friendly interface that empowers users to perform transactions quickly and efficiently. The CPGModal provides a seamless and intuitive experience, ensuring a user-friendly interface for users to complete their transactions securely.

Using the CPGModal, merchants can seamlessly allow their users to initiate Crypto deposits.

Deposit Flow

Merchants can call our backend API to obtain a transferReferenceId and then launch the CPGModal using that id. This method provides additional control and security feature for merchants to manage transactions and integrate with their backend systems.

This section will guide you through the steps required to launch the CPGModal with transferReferenceId.

Step 1: Add the SDK File

Start by including the CPGModal SDK file in the `<head>` tag of your HTML page. Make sure to specify the correct file path.

<script src="${SDK_URL}"></script>

Step 2: Create an Instance of the CPGModal

Next, create an instance of the CPGModal by passing a config object. The config object should contain the mandatory parameter applicationId, which represents the ID of the application created in the merchant site.

Parameter Type Mandatory Description
applicationId STRING Yes Id of the application created in the merchant site

To create an instance of the CPGModal, you have two options: either include the code in a separate JavaScript file or directly within a `<script>` tag of your HTML file.

Option 1: Separate JavaScript file

Create a new JavaScript file (e.g., `cpgmodal.js`) and add the following code:


  // cpgmodal.js

  // Create an instance of CPGModal
  const config = {
    applicationId: "your_application_id",
  };
  const cpgInstance = new cpg.Instance(config); 
                  

Then in your HTML file, include the JavaScript file using a `<script>` tag:

Option 2: Inline within HTML file

Alternatively, you can directly include the code within a `<script>` tag of your HTML file:


  <head>
    <script>
      // Create an instance of CPGModal
      const config = {
        applicationId: "your_application_id",
      };
      const cpgInstance = new cpg.Instance(config); 
    </script>
  </head>
                  

Remember to replace 'your_application_id' with the actual ID of the application you created on the merchant site.

Step 3: Implement a Response Callback Function

Implement a response callback function that will handle the transaction response. This function will be called when the transaction is completed, failed, or canceled.

As step 2, Add the following code to implement the response callback function in the same JavaScript file `cpgmodal.js`.


  // cpgmodal.js

  // ...previous code here

  // Implement the response callback function
  const callback = (response) => {
    switch(response.status) {
      case "USER_CLOSE":
          // user closed the session
        break;
      case "ERROR":
        // error in the sdk/application
        break;
      case "SUCCESS":
        // transaction success
        break;
      case "PENDING":
        // transaction pending (Transaction Id submitted) 
        break;
      case "FAILURE":
        // transaction got rejected
        break;
    }
  }
                  

Or, You can directly include the code within a `<script>` tag of your HTML file:


  <head>
    <script>
    // ...previous code here

    // Implement the response callback function
    const callback = (response) => {
      switch(response.status) {
        case "USER_CLOSE":
            // user closed the session
          break;
        case "ERROR":
          // error in the sdk/application
          break;
        case "SUCCESS":
          // transaction success
          break;
        case "PENDING":
          // transaction pending (Transaction Id submitted) 
          break;
        case "FAILURE":
          // transaction got rejected
          break;
      }
    }
    </script>
  </head>
                  

Make sure to handle all the cases for a better user experience.

Step 4: Generate transferReferenceId from Backend

The transferReferenceId, required to initiate the deposit transaction, can be generated by calling our Initiate Crypto Deposit API from your backend with the necessary parameters. Once the transferReferenceId is generated, it should be sent to your front end for launching the CPGModal.

Warning

It is recommended to call the Initiate Crypto Deposit API from the backend rather than directly from the front end to ensure the security of sensitive information. By performing the API call from the backend, such as a server-side script or application, you prevent the exposure of private keys or authentication credentials to the client-side environment. This helps maintain the integrity of your application and protects sensitive data from unauthorized access or misuse.

Step 5: Launch the CPGModal with the transferReferenceId

Upon receiving the transferReferenceId from the backend, From the frontend, you can launch the CPGModal using the transferReferenceId.

Similar to step2, step3, Add the following code to launch the CPGModal with options in the same JavaScript file `cpgmodal.js`.


  // cpgmodal.js

  // ...previous code here

  // Retrieve the transferReferenceId from the backend
  const transferReferenceId = 'your_transfer_reference_id';

  // Launch the CPGModal using the callback function and transferReferenceId
  cpgInstance.launch(callback, transferReferenceId); 
                  

Or, You can directly include the code within a `<script>` tag of your HTML file:


  <head>
    <script>
      // ...previous code here

      // Retrieve the transferReferenceId from the backend
      const transferReferenceId = 'your_transfer_reference_id';
    
      // Launch the CPGModal using the callback function and transferReferenceId
      cpgInstance.launch(callback, transferReferenceId);
    </script>
  </head>
                  

Congratulations! You have now successfully integrated the deposit flow in your application, adding an extra layer of security.

API Integration

In addition to web-SDK integration, we also offer REST API-based integration, allowing merchants to build their own custom user interface (UI) while leveraging our API endpoints for seamless transaction processing. With REST API integration, merchants can design and tailor their UI to their specific branding and user experience requirements.

By utilizing our REST API, merchants can access a comprehensive set of endpoints that enable them to perform various transaction-related operations, including initiating deposits, processing withdrawals, and retrieving transaction history. These APIs offer secure and reliable communication channels for transmitting transaction data between the merchant's application and our payment gateway.

Crypto Currencies

The Crypto Currencies API allows merchant to retrieve the list of crypto currencies available. By utilizing this API, we can obtain the list of crypto currencies.

Method: POST

Endpoint: ${BASE_URL}/api/v0/crypto/currencies

Request body:

The API request requires merchants to include specific data in the request body. This data consists of the following parameters.

Parameter Type Description Format Example Mandatory
application_id STRING Application ID auto-generated when the application is created on the merchant site, length should be less than 36 characters. uuid 41be906b-0a84-44b2-92e2-26b06c2ce103 Yes
timestamp STRING Time in UTC format Date-Time 2024-05-03T05:32:49.154Z Yes
Example request body:

                    {
                      "application_id": "41be906b-0a84-44b2-92e2-26b06c2ce103",
                      "timestamp": "2024-05-03T05:32:49.154Z"
                  }
                    
Request headers:

To ensure the security and integrity of the request, merchants need to generate a signature for the request body. This signature serves as a unique identifier for the request and helps prevent unauthorized tampering with the data. The generated signature should be included in the request header for authentication purposes.

Parameter Type Mandatory Description
signature STRING Yes Hashed data of the requested body
Example request headers:

  headers: {
    signature: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiI2Y2RhMzk5Ni03"
  }
                  

Note

For steps on how to generate the signature, please refer to the Signaturesection of the documentation. It provides detailed instructions and guidelines on generating the required signature for authentication purposes.

Response Handling:

Once our payment gateway processes the request, a response will be returned to the merchant's application.

Response type: SUCCESS

Status code: 200

Example response data:

                      {
                        "error": false,
                        "currencies_list": [
                            {
                                "crypto_currency": "MATIC",
                                "blockchain": "POLYGON",
                                "network_id": "80002",
                                "token_type": null,
                                "token_address": ""
                            },
                            {
                                "crypto_currency": "USDT",
                                "blockchain": "TRON",
                                "network_id": "1001",
                                "token_type": "TRC-20",
                                "token_address": "TXLAQ63Xg1NAzckPwKHvzw7CSEmLMEqcdj"
                            },
                            {
                                "crypto_currency": "ETH",
                                "blockchain": "ETHEREUM",
                                "network_id": "11155111",
                                "token_type": null,
                                "token_address": ""
                            },
                            {
                                "crypto_currency": "USDT",
                                "blockchain": "ETHEREUM",
                                "network_id": "11155111",
                                "token_type": "ERC-20",
                                "token_address": "0x314e45db3f0c019adfae55232c195ca3101ac4ab"
                            },
                            {
                                "crypto_currency": "SOL",
                                "blockchain": "SOLANA",
                                "network_id": "901",
                                "token_type": null,
                                "token_address": ""
                            },
                            {
                                "crypto_currency": "BNB",
                                "blockchain": "BSC",
                                "network_id": "97",
                                "token_type": null,
                                "token_address": ""
                            },
                            {
                                "crypto_currency": "USDT",
                                "blockchain": "BSC",
                                "network_id": "56",
                                "token_type": "BEP-20",
                                "token_address": "0x55d398326f99059fF775485246999027B3197955"
                            }
                        ]
                    }
                      

Response type: BAD REQUEST

Status code: 400

Example response data:

                      { 
                        "error": true, 
                        "message": "Something went wrong" 
                      }
                    

Response type: FORBIDDEN

Status code: 403

Example response data:

                      { 
                        "error": true, 
                        "message": "Invalid Signature" 
                      }
                    

Initiate Crypto Deposit

The Initiate Crypto Deposit API allows merchants to initiate Crypto deposit transactions through our payment gateway. By requesting this API, merchants can securely and conveniently initiate the deposit process for their users.

Method: POST

Endpoint: ${BASE_URL}/api/v0/deposits/crypto/initiate

Request body:

The API request requires merchants to include specific data in the request body. This data consists of the following parameters.

Parameter Type Description Format Example Mandatory
mobile_number STRING Mobile number of the user - 9xxxxxxx83 Yes
application_id STRING Application ID auto-generated when the application is created on the merchant site, and the length should be less than 36 characters. uuid 3a7292cc-64b2-46ea-bcd3-e5ea844e93e1 Yes
timestamp STRING Timestamp in UTC format Date-Time 2016-08-29T09:12:33.001Z Yes
currency STRING Native currency selected while creating the application (INR) - INR Yes
email STRING User email address - [email protected] No
amount NUMBER Transaction amount with respect to native currency - 100 Yes
reference_id STRING Unique referenceid - 42cdsf546bwug Yes
username STRING username of the user - Saba@123 No
crypto_currency STRING crypto currency (required only when you want to accept specific crypto from user) - USDT/MATIC/ETH/XRP No
network_id STRING network_id or chain_id for the blockchain String 1 No
Example request body:

  {
    "amount": 100,
    "application_id": "41be906b-0a84-44b2-92e2-26b06c2ce103",
    "crypto_currency": "USDT",
    "currency": "INR",
    "email": "[email protected]",
    "mobile_number": "9876543211",
    "network_id": "11155111",
    "reference_id": "aa910def-9ff9-4751-a787-b50aaf466283",
    "timestamp": "2024-04-18T06:01:36.015Z"
  }
                  
Request headers:

To ensure the security and integrity of the request, merchants need to generate a signature for the request body. This signature serves as a unique identifier for the request and helps prevent unauthorized tampering with the data. The generated signature should be included in the request header for authentication purposes.

Parameter Type Mandatory Description
signature STRING Yes Hashed data of the requested body
Example request headers:

  headers: {
    signature: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiI2Y2RhMzk5Ni03"
  }
                  

Note

For steps on how to generate the signature, please refer to the Signature section of the documentation. It provides detailed instructions and guidelines on generating the required signature for authentication purposes.

Response Handling:

Once our payment gateway processes the request, a response will be returned to the merchant's application. The response contains relevant information regarding the initiated deposit transaction, such as a deposit referenceId or any additional details required for further processing.

Response type: SUCCESS

Status code: 200

Example response data for Crypto currency:

 {
  "transfer_reference_id": "ea753286-e4a3-4843-879a-b840fdc711f7",
  "amount": 1.1756915142761004,
  "payment_options": [
    {
      "payment_method": "CRYPTO_TRANSFER",
      "payment_method_details": {
        "blockchain": "ETHEREUM",
        "network_id": "11155111",
        "currency_name": "USDT"
      }
    }
  ]
}
                    

Response type: BAD REQUEST

Status code: 400

Example response data:

  { 
    "error": true, 
    "message": "Something went wrong" 
  }
                    

Response type: FORBIDDEN

Status code: 403

Example response data:

  { 
    "error": true, 
    "message": "Invalid Signature" 
  }
                    

CRYPTO DEPOSIT WALLET ADDRESS

Provides the wallet address of appropriate blockchain to which user has to transfer the funds.

Method: POST

Endpoint: ${BASE_URL}/api/v0/deposits/crypto/wallet-address

Request body:

The API request requires merchants to include specific data in the request body. This data consist of the following parameters.

Parameter Type Description Format Example Mandatory
application_id STRING Application ID auto-generated when the application is created on the merchant site, and length should be less than 36 characters. uuid 3a7292cc-64b2-46ea-bcd3-e5ea844e93e1 Yes
timestamp STRING Timestamp in UTC format Date-Time 2016-08-29T09:12:33.001Z Yes
transfer_reference_id STRING transferReferenceId generated after initiating the deposit transaction uuid 3a7292cc-64b2-46ea-bcd3-e5ea844e93e1 Yes
crypto_currency STRING Name of the crypto currency. - 123456789012 Conditional
network_id STRING network_id or chain_id for the blockchain String 1 Yes
Example request body:

  {
    "application_id":"41be906b-0a84-44b2-92e2-26b06c2ce103",
    "crypto_currency":"USDT",
    "network_id":"11155111",
    "timestamp":"2024-04-30T12:11:37.145Z",
    "transfer_reference_id":"63ad16c7-abf8-4350-99c3-24e7fb8897fd"
  }                    
                  

Note

Request headers:

To ensure the security and integrity of the request, merchants need to generate a signature for the request body. This signature serves as a unique identifier for the request and helps prevent unauthorized tampering with the data. The generated signature should be included in the request header for authentication purposes.

Parameter Type Mandatory Description
signature STRING Yes Hashed data of the requested body
Example request headers:

  headers: {
    signature: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiI2Y2RhMzk5Ni03"
  }
                  

Note

For steps on how to generate the signature, please refer to the Signature section of the documentation. It provides detailed instructions and guidelines on generating the required signature for authentication purposes.

Response Handling:

Once our payment gateway processes the request, a response will be returned to the merchant's application.

Response type: SUCCESS

Status code: 200

Example response data:

  {
    "error": false,
    "data": {
      "wallet_address": "0xeC8aeaEA56D61b38A7c2ec91168793CcE9270e19",
      "amount": 11.515037,
      "network_id": "11155111",
      "blockchain": "ETHEREUM",
      "token_address": "0x314e45db3f0c019adfae55232c195ca3101ac4ab",
      "crypto_currency": "USDT"
  }
  }
                    

Response type: BAD REQUEST

Status code: 400

Example response data:

  { 
    "error": true, 
    "message": "Something went wrong" 
  }
                    

Response type: FORBIDDEN

Status code: 403

Example response data:

  { 
    "error": true, 
    "message": "Invalid Signature" 
  }
                    

CRYPTO DEPOSIT SUBMIT TRANSACTION

The Crypto Deposit Submit Transaction API empowers merchants to securely and conveniently submit the crypto transaction details for the initiated transaction. Leveraging this API, merchants can expedite the verification process for user transactions while ensuring the highest standards of security throughout the entire verification process

Method: POST

Endpoint: ${BASE_URL}/api/v0/deposits/crypto/submit-transaction

Request body:

The API request requires merchants to include specific data in the request body. This data consist of the following parameters.

Parameter Type Description Format Example Mandatory
application_id STRING Application ID auto-generated when the application is created on the merchant site, and length should be less than 36 characters. uuid 3a7292cc-64b2-46ea-bcd3-e5ea844e93e1 Yes
timestamp STRING Timestamp in UTC format Date-Time 2016-08-29T09:12:33.001Z Yes
transfer_reference_id STRING transferReferenceId generated after initiating the deposit transaction uuid 3a7292cc-64b2-46ea-bcd3-e5ea844e93e1 Yes
transaction_hash STRING A unique transaction hash number is generated by when a transaction is completed. String 0x48ef4a9839f30c01ebd498a8ffbe961a5104d30fbebc39766c47aa4fb6d1c0cf Conditional
block_number STRING Block number in which the transaction got included in the blockchain String 5806845 Yes
Example request body:

                    {
                    "application_id": "41be906b-0a84-44b2-92e2-26b06c2ce103",
                    "timestamp": "2024-04-17T10:02:12.106Z",
                    "transaction_hash": "0x500ac979a252a67e94b7d5a46829d5d060cb8111ac3ac66ab14f5d67794b9d8a",
                    "transfer_reference_id": "a3f1a93b-7822-47c2-aa7a-572b240e9b21"
                }                  
                  

Note

Request headers:

To ensure the security and integrity of the request, merchants need to generate a signature for the request body. This signature serves as a unique identifier for the request and helps prevent unauthorized tampering with the data. The generated signature should be included in the request header for authentication purposes.

Parameter Type Mandatory Description
signature STRING Yes Hashed data of the requested body
Example request headers:

  headers: {
    signature: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiI2Y2RhMzk5Ni03"
  }
                  

Note

For steps on how to generate the signature, please refer to the Signature section of the documentation. It provides detailed instructions and guidelines on generating the required signature for authentication purposes.

Response Handling:

Once our payment gateway processes the request, a response will be returned to the merchant's application.

Response type: SUCCESS

Status code: 200

Example response data:

  {
    "error": false,
    "message": "Transaction details submitted successfully."
  }
                    

Response type: BAD REQUEST

Status code: 400

Example response data:

  { 
    "error": true, 
    "message": "Something went wrong" 
  }
                    

Response type: FORBIDDEN

Status code: 403

Example response data:

  { 
    "error": true, 
    "message": "Invalid Signature" 
  }
                    

Transaction Status

The Deposit Transaction Status API allows merchants to retrieve the status of deposit transactions. By utilizing this API, merchants can obtain real-time information on the status of deposit transactions performed by the users.

Method: POST

Endpoint: ${BASE_URL}/api/v0/deposits/crypto/status

Request body:

The API request requires merchants to include specific data in the request body. This data consists of the following parameters.

Parameter Type Description Format Example Mandatory
application_id STRING Application ID auto-generated when the application is created on the merchant site, length should be less than 36 characters. uuid 3a7292cc-64b2-46ea-bcd3-e5ea844e93e1 Yes
timestamp STRING Time in UTC format Date-Time 2016-08-29T09:12:33.001Z Yes
transfer_reference_id STRING transferReferenceId generated after initiating the deposit transaction. uuid 3a7292cc-64b2-46ea-bcd3-e5ea844e93e1 Yes
Example request body:

  {
    "application_id": "3a7292cc-64b2-46ea-bcd3-e5ea844e93e1",
    "timestamp": "2016-08-29T09:12:33.001Z",
    "transfer_reference_id": "3a7292cc-64b2-46ea-bcd3-e5ea844e93e1",
  }                    
                  
Request headers:

To ensure the security and integrity of the request, merchants need to generate a signature for the request body. This signature serves as a unique identifier for the request and helps prevent unauthorized tampering with the data. The generated signature should be included in the request header for authentication purposes.

Parameter Type Mandatory Description
signature STRING Yes Hashed data of the requested body
Example request headers:

  headers: {
    signature: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiI2Y2RhMzk5Ni03"
  }
                  

Note

For steps on how to generate the signature, please refer to the Signaturesection of the documentation. It provides detailed instructions and guidelines on generating the required signature for authentication purposes.

Response Handling:

Once our payment gateway processes the request, a response will be returned to the merchant's application.

Response type: SUCCESS

Status code: 200

Example response data:

  {
    "error": false,
    "message": "Transaction details fetchched successfully.",
    "data": {
        "amount": "1000",
        "crypto_amount": 21.254487,
        "currency": "INR",
        "transfer_reference_id": "9670d5eb-a4f4-4152-9f5e-7adbde96b732",
        "status": "PENDING",
        "application_id": "41be906b-0a84-44b2-92e2-26b06c2ce103",
        "mobile_number": "9398538738",
        "crypto_currency": "USDT",
        "network_id": "11155111",
        "transaction_hash": "0xdddf5c48f5e0c36eae565c96b476aac0d03e21356eea28b34ab91c8ef5a320cc"
    }
}
                    

Response type: BAD REQUEST

Status code: 400

Example response data:

  { 
    "error": true, 
    "message": "Something went wrong" 
  }
                    

Response type: FORBIDDEN

Status code: 403

Example response data:

  { 
    "error": true, 
    "message": "Invalid Signature" 
  }
                    

Web-Redirection Integration

For merchants seeking a seamless payment solution without the need for modal pop-ups on their website, the web-redirection method offers an ideal alternative. With this integration, merchants have the flexibility to direct users to our dedicated payment interface via a simple URL. Upon completing the transaction, they will receive transaction notifications through callbacks from our server, ensuring a smooth and integrated payment experience.

Deposit Flow

The following section will provide a step-by-step guide on integrating the deposit flow into your application through web redirection.

Step 1: Call the Initiate Crypto Deposit API

Initiate the deposit process in your application by making a call to the Initiate Crypto Deposit API. This call typically includes parameters like the user's information, transaction details, and any other required data. Upon a successful API request, you will receive a transferReferenceId, which is a unique identifier. It can be used for further tracking of the request.

Warning

It is recommended to call the Initiate Crypto Deposit API from the backend rather than directly from the front end to ensure the security of sensitive information. By performing the API call from the backend, such as a server-side script or application, you prevent the exposure of private keys or authentication credentials to the client-side environment. This helps maintain the integrity of your application and protects sensitive data from unauthorized access or misuse.

Step 2: Generate the Redirection URL

After obtaining the transferReferenceId, you can construct the redirection URL. This URL directs users to the payment interface, facilitating transaction completion. To achieve this, add the transferReferenceId as a query parameter to the predetermined URL. This process ensures a smooth transition to the payment interface

URL: ${FRONTEND_URL}/redirection/index.html

Example endpoint with query parameters:

${FRONTEND_URL}/redirection/index.html?transferReferenceId=2fd68246-58ef-4efc-8637-249e1af3c610
                

Step 3: Redirect Users

Once the redirection URL is generated you can redirect users to it. When users are redirected to the URL, they can conveniently complete the transaction. You can initiate the redirection through a button or a link in your website or application.

Example:

<!-- Add a button that opens the payment interface in a new window/tab -->
<button id="payNowButton">Pay Now</button>

<script>
  // JavaScript function to handle the button click event
  document.getElementById("payNowButton").addEventListener("click", function() {
      // Get the transferReferenceId (replace with the actual value)
      var transferReferenceId = "2fd68246-58ef-4efc-8637-249e1af3c610";

      // Replace 'FRONTEND_URL' with your actual URL
      var FRONTEND_URL = "https://frontend-url.com"; 

      // Construct the redirection URL with the transferReferenceId
      var redirectionURL = FRONTEND_URL + "/redirection/index.html?transferReferenceId=" + transferReferenceId;

      // Open the payment interface in a new browser window/tab
      window.open(redirectionURL, "_blank");
  });
</script>                  

Note

When the redirection url is opened using `window.open`, it will automatically close upon reaching the final step of the transaction process. This behavior ensures a streamlined and user-friendly experience, eliminating the need for manual tab closure by the user.

Callback API Integration

The Callback API allows you to receive real-time notifications about the status of transactions. Integrating our Callback API into your system lets you stay informed about transaction updates and take appropriate actions accordingly.

Callback URLs

To receive deposit and withdraw transaction status notifications, you need to provide us with the following callback URLs:

  • Deposit Callback URL:

    The Deposit Callback URL is a designated endpoint where our payment gateway sends callback requests upon completion of deposit transactions.

During the application creation process on the merchant site, it is essential to provide these URLs - Deposit Callback URL and Withdraw Callback URL. These URLs enable the seamless communication between our payment gateway and your application, ensuring timely transaction notifications.

Furthermore, for enhanced control and convenience, merchants have the flexibility to update these URLs later within the application settings, allowing for easy adjustments to accommodate any changes in callback endpoint requirements.

Additionally, in case of transaction failures, our system provides the option to enable callbacks for failure transactions within your application settings.

Note

Please be aware that by default callback requests are triggered exclusively in the event of successful deposit or withdrawal transactions.

Note

Only after enabling the "Callback for Failure Transactions" option within your application settings, our system will include an additional field, "status," in the callback API requests for both successful and failed transactions. This enhancement provides comprehensive transaction status information, ensuring that you are well-informed about the outcome of each transaction, whether it succeeds or encounters an issue.

Note

It's important to note that transactions for which no user action is taken will be automatically cancelled after a specific timeout period. You have the flexibility to configure and set this timeout period according to your preferences within the application settings.

Request body:

In the callback URL request, the data is sent as parameters that are first stringified and then assigned to a variable named "data". This "data" variable is then sent as the JSON body of the request.

By using this method, the parameters are securely transmitted to the callback URL in a structured JSON format, ensuring that the necessary information is effectively communicated and processed.

The following are the fields that are sent in the "data" variable

Parameter Type Description
amount NUMBER Transaction amount
application_id STRING Application ID auto-generated when the application is created on the merchant site.
currency STRING Native currency alias name (which is set in merchant portal application settings)
crypto_amount STRING Amount paid by user in crypto
network_id STRING network_id or chain_id for the blockchain
crypto_currency STRING Name of the crypto currency
transaction_hash STRING A unique transaction hash number is generated by when a transaction is completed
reference_id STRING Reference Id provided by merchant at the time of transaction initiation.
timestamp STRING Time in UTC format
transfer_reference_id STRING transferReferenceId generated by our system after initiating the transaction.
user_mobile_number STRING Mobile number of the user
status STRING State of the transaction SUCCESS/CANCELLED (**Will be sent only when Callback for failure transactions is enabled**)
Example request body (default case):

{
"data": "{\"amount\":200,\"application_id\":\"41be906b-0a84-44b2-92e2-26b06c2ce103\",\"currency\":\"INR\",\"reference_id\":\"75551ff9-cc4e-47c7-84b5-984e1afa539b\",\"status\":\"SUCCESS\",\"timestamp\":\"2024-04-17T10:02:25.219Z\",\"transfer_reference_id\":\"a3f1a93b-7822-47c2-aa7a-572b240e9b21\",\"user_mobile_number\":\"9398538738\"}"
}
                  
Example request body (failure callback enabled):

{
  "data": "{\"amount\":1000,\"application_id\":\"41be906b-0a84-44b2-92e2-26b06c2ce103\",\"currency\":\"INR\",\"reference_id\":\"3b6e1820-bca7-4924-8439-81a7f3d34f7f\",\"status\":\"CANCELLED\",\"timestamp\":\"2024-04-17T11:11:02.014Z\",\"transfer_reference_id\":\"a2acaa9a-4674-40f5-a5e4-df7cbfd19491\",\"user_mobile_number\":\"9398538738\"}"
}                   
                  
Example request body (transaction_hash is included):

{
  "data": "{\"amount\":60,\"application_id\":\"41be906b-0a84-44b2-92e2-26b06c2ce103\",\"crypto_amount\":0.00370106064737,\"crypto_currency\":\"ETH\",\"currency\":\"INR\",\"network_id\":\"11155111\",\"reference_id\":\"6c8faaaa-f704-49f9-9b8a-fbc7bed232f1\",\"status\":\"SUCCESS\",\"timestamp\":\"2024-05-07T17:45:21.856Z\",\"transaction_hash\":\"0xedf55e76393b3c98a3bdba036f0514c55ad5f3fb5962cbc373c17516a4e91b4f\",\"transfer_reference_id\":\"832b5656-01b0-4aab-872b-0c980bd4f404\",\"user_mobile_number\":\"9398538738\"}"
}                    
                  

Note

If the callback retry option is enabled in the application settings, our system will make three additional callback attempts in case of a request failure. However, if the callback retry option is not enabled, our system will attempt to send the callback request only once.

Note

Merchants have the option to manually trigger callbacks from the transactions tab within the merchant portal if needed. This feature allows merchants to initiate callback requests on demand.

Signature

To ensure secure communication between your system and our backend APIs, you must generate a Signature for each API request. The Signature is used to verify the authenticity and integrity of the request.

Steps to Generate Signature

  1. Add Current Timestamp: Include the current timestamp in the request body. The timestamp should accurately represent the time of the request.
  2. Sort Request Body: Sort the key-value pairs in the request body in ascending order based on the keys. This ensures consistent ordering of the data for generating the hash.
  3. Generate Hash with HMAC Algorithm: Use the HMAC (Hash-based Message Authentication Code) algorithm to generate the hash. Encode the secret key using hex encoding before passing it to the HMAC algorithm. Ensure that the data is serialized to JSON with UTF-8 encoding before updating the hash. Convert the resulting hash to bytes.
  4. Convert Hash to Hex Signature: Convert the hash, which is now in bytes, to a hexadecimal signature. This is the final format in which the signature will be included in the request headers.
  5. Include Signature in Request Headers: Add the generated Signature to the request headers as a field (e.g., "signature"). This allows our backend APIs to verify the integrity of the request.

Note

During signature generation, careful consideration should be given to string encoding. As our APIs consume JSON bodies, it's essential to note that the default character set for serialized JSON is UTF-8, a widely supported encoding in most libraries.

Note

For accurate and secure signature generation for your API requests, please carefully follow the steps outlined above. Accurate implementation of each step is crucial to maintain request integrity and authenticity. If you encounter difficulties or have questions, refer to this documentation or contact our support team for assistance.

Example (Node.js):

const crypto = require('crypto');

// Step 1: Add current timestamp to the request body
const timestamp = new Date();

// Step 2: Sort the request body based on keys
const requestBody = {
  timestamp,
  // ...other request parameters
};
const sortedBody = Object.keys(requestBody)
  .sort()
  .reduce((sorted, key) => {
    sorted[key] = requestBody[key];
    return sorted;
  }, {});

// Step 3: Generate the hash using HMAC algorithm
const secret = 'YOUR_SECRET_KEY';
const keyBytes = Buffer.from(secret, 'hex'); // Key encoded as hex encoded binary bytes
const hmac = crypto
  .createHmac('sha256', keyBytes)
  .update(JSON.stringify(sortedBody)) // Encode the sorted body using UTF-8
  .digest('hex'); // Convert the hash to a hexadecimal string

// Step 4: Include the Signature in the request headers
const headers = {
  'signature': hmac,
  // ...other headers
};
                
Example (using `CryptoJS` library):

  <script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.0.0/crypto-js.min.js"></script>
  <script>
    // Step 1: Add a current timestamp to the request body
    const timestamp = new Date();

    // Step 2: Sort the request body based on keys
    const requestBody = {
      timestamp,
      // ...other request parameters
    };
    const sortedBody = Object.keys(requestBody)
      .sort()
      .reduce((sorted, key) => {
        sorted[key] = requestBody[key];
        return sorted;
      }, {});

    // Step 3: Generate the hash using HMAC algorithm
    const secret = "YOUR_SECRET_KEY";
    // Create an HMAC instance with CryptoJS using the secret key (key encoding: hex)
    const keyBytes = CryptoJS.enc.Hex.parse(secret); // Key encoded as hex binary bytes
    const hmac = CryptoJS.HmacSHA256(JSON.stringify(sortedBody), keyBytes);
    // Convert the hash to a hexadecimal string (data/body encoding: utf-8)
    const hash = hmac.toString(CryptoJS.enc.Hex);

    // Step 4: Include the Signature in the request headers
    const headers = {
      signature: hash,
      // ...other headers
    };
  </script>
                
Example (JAVA Spring Boot Framework):

package com.abcmoney.signature.sample.controller;

import java.util.TreeMap;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import com.abcmoney.signature.sample.dto.SignatureDto;
import com.abcmoney.signature.sample.service.SignerService;

@RestController
@RequestMapping("/sign")
public class SignerController {
    
    @Autowired
    SignerService signerService;

    String key = "27d1b6e12fa9c48da476f29cc92fd7c57270058f89a8a357ff0afa68c01b5d24f2d540ed94a39d0d679fcb3ab3d7c4b137797ac82ab8e5c5290dea4e1e5650cd";
    
    @GetMapping("/generate")
    public SignatureDto generate() {
        TreeMap<String, String> requestObject = new TreeMap<String, String>();
        requestObject.put("amount", "100");
        requestObject.put("application_id", "6980E5F4-EB4F-4DC0-84E7-53C897115D9D");
        requestObject.put("currency", "INR");
        requestObject.put("email", "[email protected]");
        requestObject.put("mobile_number", "9988776655");
        requestObject.put("reference_id", "6E430071-F173-4F49-A499-BA30D252B007");
        requestObject.put("timestamp", "2023-08-08T08:08:08.808Z");
        requestObject.put("username", "abcustomer");
        return signerService.getSignature(key, requestObject);
    }

    @GetMapping("/verify")
    public SignatureDto verify() {
        String hash = "7e4a33aca6bb49b3b6ab9e52066f87e5666543bba43eb280f321ccb94f3763b";
        // The request json can be in any order the `TreeMap` will sort the data and creates the hash for it
        String jsonData = "{\"currency\":\"INR\",\"email\":\"[email protected]\"," + 
                        "\"amount\":\"100\",\"reference_id\":\"6E430071-F173-4F49-A499-BA30D252B007\"," + 
                        "\"mobile_number\":\"9988776655\",\"timestamp\":\"2023-08-08T08:08:08.808Z\"," + 
                        "\"application_id\":\"6980E5F4-EB4F-4DC0-84E7-53C897115D9D\",\"username\":\"abcustomer\"}";
        System.out.println(jsonData);
        return signerService.verifySignature(key, jsonData, hash);        
    }
}
                

package com.abcmoney.signature.sample.service;


import com.abcmoney.signature.sample.dto.SignatureDto;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;

import lombok.extern.log4j.Log4j2;

import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.HexFormat;
import java.util.TreeMap;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Log4j2
@Service
public class SignerService {    

    @Autowired
    ObjectMapper objectMapper;

  /**
   * Gets signature hash.
   *
   * @param key secret key
   * @param obj value to be encrypted
   * @return SignatureDto
   */
  public SignatureDto getSignature(String key, TreeMap<String, String> obj) {
    try {
      String requestString = objectMapper.writeValueAsString(obj);
      log.info("Request body for signature generation : {} key : {}", requestString, key);
      
      Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
      SecretKeySpec secret_key = new SecretKeySpec(key.getBytes(), "HmacSHA256");
      sha256_HMAC.init(secret_key);
      String signature = new String(HexFormat.of().formatHex(sha256_HMAC.doFinal(requestString.getBytes())));
      
      SignatureDto signResponse = new SignatureDto();
      signResponse.setJsonData(requestString);
      signResponse.setSignature(signature);
      signResponse.setOperation("CREATE");
      
      return signResponse;
    } catch (NoSuchAlgorithmException ex) {
      throw new RuntimeException("No such algorithm exception.", ex);
    } catch (InvalidKeyException e) {
      throw new RuntimeException("Invalid secret key.", e);
    } catch (JsonProcessingException e) {
      throw new RuntimeException("Unable to parse json.", e);
    }
  }

  public SignatureDto verifySignature(String key, String data, String hash) {
      TreeMap<String, String> requestObject;
      SignatureDto signResponse;
      try {
        requestObject = (TreeMap<String, String>)objectMapper.readValue(data, TreeMap.class);
        signResponse = getSignature(key, requestObject);
        if (!signResponse.getSignature().equals(hash)) {
          // Signature Verification failed
          throw new RuntimeException("Hash mismatch " + signResponse.getSignature() + " != " + hash);
        }
      } catch (JsonProcessingException e) {
        e.printStackTrace();
        throw new RuntimeException(e);
      }
      signResponse.setOperation("VERIFY");
      return signResponse;
  }

}

                

package com.abcmoney.signature.sample.dto;

import lombok.Data;

@Data
public class SignatureDto {
    public String jsonData;
    public String signature;
    public String operation;
}
                

Secret Key

The secret key required for generating the Signature can be found in the application details we provided. It is essential to keep this secret key confidential and securely store it in your system.

Signature Generator

This is a sample signature genrator which ca be used to test and verify signatures.

Frequently Asked Questions (FAQ)

Welcome to our Frequently Asked Questions (FAQ) section, where we provide answers to common queries and concerns about our payment gateway integration. Whether you're seeking information about API endpoints, SDK usage, callback handling, or other integration-related topics, you'll find comprehensive answers here. These FAQs are designed to streamline your integration process and ensure a seamless experience while using our services. If you can't find the answer you're looking for, please don't hesitate to reach out to our support team for further assistance.

Where can we find Application ID and Application Secret?

You can locate the Application ID and Application Secret within the application settings of your merchant account.

What is the API Base URL?

The API Base URL is the primary endpoint for accessing our API services. You can obtain this URL from our support team.

Where can I find the SDK Source URL?

You can obtain the SDK Source URL by reaching out to our support team.

How can I launch the SDK with the reference ID?

You can launch the SDK with the reference ID by calling our backend API to generate the reference ID and then initiating the SDK with this ID.

Is there a PHP Library available for integration?

No, at present, we do not offer a PHP library for integration.

Is there an NPM package available for the SDK?

No, currently, we do not provide an NPM package for the SDK.

Is there a way to skip the OTP during integration testing on stage?

Yes, you have the flexibility to skip OTP verification for both stage and live environments by disabling the OTP verification option in the application settings.

What is the purpose of the 'abcmoney.umd.js' file?

'abcmoney.umd.js' is a JavaScript file designed for integrating the CPGModal into your application, enabling the initiation of deposit and withdrawal transactions. When integrated, it opens an iframe within your web application, facilitating seamless payment processing.

Can I use dummy bank account details for integration testing on the stage environment?

Yes, you can utilize dummy account details for integration testing on the stage environment, allowing you to simulate transactions without providing actual bank accounts. Additionally, you have the capability to manually approve or reject these transactions from the merchant portal for testing purposes.

What kind of signature errors might occur during integration?

Signature errors can occur due to various reasons, including:

  1. Incorrect Parameter Sorting: If the parameters in your API requests are not sorted correctly, it can result in signature errors.
  2. Encoding Mismatch: The encoded string must match our encoding format (UTF-8). Any mismatch can lead to signature verification issues.
  3. Expired Timestamp: If the timestamp in your request expires before processing, it can trigger signature errors. Ensure that the timestamp is current and within the acceptable time frame i.e 5 min.
How can I address a 'Forbidden' error in API requests?

A 'Forbidden' error typically occurs due to a signature mismatch. To resolve this, you can verify the signature by generating a signature using the same request body with our signature generator. Ensure that the generated signature matches the one sent in the request headers to rectify the 'Forbidden' error.

Do I need to request access from specific IPs for API access?

In the stage environment, there is no need for IP whitelisting. However, for the live environment, it is mandatory to whitelist specific IPs to ensure secure API access.

Regarding the mobile number in API requests, should I include the country code?

No, you should provide the ten-digit mobile number without the country code in all API requests. Please note that currently, we only support Indian mobile numbers for OTP purposes.

What are the types of callbacks available?

There are two types of callbacks available: one for deposit transactions and the other for withdrawal transactions.

What happens if a transaction times out?

If a user doesn't take any action after initiating the transaction, the transaction will be automatically cancelled upon the completion of the timeout period. This timeout period can be configured from the merchant portal for your convenience.

What data is included in a status callback?

For complete information on the data included in a status callback, please refer to our callback section for detailed documentation.

Can you provide a list of dummy phone numbers for testing purposes?

Here is a list of dummy phone numbers for testing purposes, including '9999999999' and '9999988888,' with a default OTP of '123456.'