Introduction

ABC payment gateway facilitates payments between end users and merchants. We provide users and merchants with payment methods: UPI, Bank Transfer, INR to crypto, and Crypto to 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 deposits or withdraw requests.

Deposit Flow

To provide flexibility and customization, our Web-SDK-based solution enables merchants to launch the CPGModal in two different ways. Merchants can choose the method that best suits their requirements and integration preferences.

  1. Launch CPGModal with Options:

    Merchants can directly launch the CPGModal with all the desired options and configurations. This method allows for a quick and straightforward integration process. By specifying the necessary parameters and options, merchants can customize the behavior and appearance of the modal to align with their application's design and user experience.

  2. Launch CPGModal with Reference ID (Backend API):

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

Launch CPGModal with Options

The Launch CPGModal with Options feature allows merchants to initiate the CPGModal directly with specific customization options and configurations. By leveraging this functionality, you can provide a tailored payment experience for your users within your application.

With the direct launch approach, you can specify various options such as payment amount, currency, reference id, and additional transaction details. This enables you to pre-fill specific fields, set default values, or customize the behavior of the CPGModal according to your particular requirements.

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

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>
                  

Choose the option that suits your project structure and preferences.

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 step2, 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 (UTR/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 (UTR/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: Launching the CPGModal

Launch the CPGModal by calling the `launch()` method on the CPGModal instance. Pass the callback function and the desired options as parameters to customize the modal behavior.

Available options are:

Parameter Type Mandatory Description
phoneNumber STRING Yes Mobile number of the user
referenceId STRING Yes Id generated by Merchant for merchant reference.
amount NUMBER Optional Transaction amount
currency STRING Yes Type of currency INR/BDT
emailId STRING Optional Email address of the User
username STRING Optional Username of the User.

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

  // Launch the CPGModal with options
  const options = {
    referenceId,
    amount,
    currency,
    phoneNumber,
  };
  cpgInstance.launch(callback, options); 
                  

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


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

      // Launch the CPGModal with options
      const options = {
        referenceId,
        amount,
        currency,
        phoneNumber,
      };
      cpgInstance.launch(callback, options); 
    </script>
  </head>
                  

That's it. You have successfully integrated deposit flow into your application.

Launch CPGModal with Reference ID (Backend API):

Launching the CPGModal with a Reference ID allows merchants to retrieve the reference ID from our backend API and use it to initiate the payment transaction. This method provides flexibility and control over the transaction process.

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

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>
                  

Choose the option that suits your project structure and preferences.

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 (UTR/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 (UTR/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 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 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.

Withdrawal Flow

You can leverage the same CPGModal for integrating the withdrawal flow into your application. By utilizing CPGModal, you can provide a seamless and user-friendly interface for users to perform withdrawal transactions securely. The withdrawal flow integration follows a similar process as the deposit flow, ensuring consistency and familiarity for users.

You can effectively track and manage withdrawal requests by leveraging the unique referenceId generated by our backend API for each withdrawal transaction. This referenceId serves as a vital identifier, allowing you to maintain secure and transparent withdrawals for your users.

The following section will guide you through the steps required to integrate withdrawal flow into your application using the CPGModal.

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>

Note

If you have already integrated the Deposit Flow using the CPGModal and added the SDK file to your application, you can skip this step for adding the SDK file and next step, creating an instance of the CPGModal.

Note

The SDK file and the instance of the CPGModal are required for initializing the payment gateway and launching the modal. However, if you have already completed this step during the integration of the deposit flow, there is no need to repeat it for the withdrawal integration. Proceed with the remaining steps specific to the withdrawal flow integration.

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>
                  

Choose the option that suits your project structure and preferences.

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 step2, 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 (UTR/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 (UTR/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 referenceId from Backend

The unique referenceId, which is required to initiate the withdrawal transaction, can be generated by calling our Initiate Withdrawal API from the your backend with necessary parameters. Once the referenceId is generated, it should be sent to your frontend for launching the CPGModal.

Warning

It is recommended to call the Initiate Withdrawal 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 referenceId

Upon receiving the referenceId from the backend, From the frontend, you can launch the CPGModal using the referenceId and the callback function.

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 referenceId = 'your_transfer_reference_id';

  // Launch the CPGModal using the callback function and referenceId
  cpgInstance.withdraw(callback, referenceId); 
                  

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 withdrawal flow in your application, with 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.

Initiate Deposit

The Initiate Deposit API allows merchants to initiate 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/initiate

Query parameters:

Query parameters are essential for obtaining additional information in the response. By including specific query parameters, you can request and receive more detailed information in the response, enhancing the value and relevance of the data provided.

Parameter Type Description Format Mandatory
upi_qr BOOLEAN When the upi_qr parameter is set to 'true' in the API request, a QR image will be included within the UPI payment options in the response. - No
upi_intent BOOLEAN If the upi_intent parameter is set to 'true' in the API request, an UPI intent will be included in the UPI payment options of the response. - No
Example endpoint with query parameters:

  ${BASE_URL}/api/v0/deposits/initiate?upi_intent=true&upi_qr=true
                  
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 Name of the currency (INR/BDT) - INR Yes
email string User email address - [email protected] No
amount NUMBER Transaction amount - 100 Yes
reference_id STRING referenceid - 42cdsf546bwug Yes
username STRING username of the user - Saba@123 No
Example request body:

  {
    "mobile_number": "9xxxxxxx83",
    "application_id": "3a7292cc-64b2-46ea-bcd3-e5ea844e93e1",
    "timestamp": "2016-08-29T09:12:33.001Z",
    "currency": "INR",
    "email": "[email protected]",
    "amount": 100,
    "reference_id": "e5ea844e-46ea-64b2-3a7292cc93e1",
    "username": "def123"
  }
                  
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 INR currency:

{
  "reference_id": "3a7292cc-64b2-46ea-bcd3-e5ea844e93e1",
  "amount": 1.1517679137897339,
  "payment_options": [
    {
      "payment_method": "UPI",
      "payment_method_details": {
        "upi_id": "9988998899@ybl",
        "bank_id": "5e137848-e16d-4d0c-b755-85f1e3adf61d",
        "bank_account_holder": "Chirantan"
      }
    },
    {
      "payment_method": "BANK_TRANSFER",
      "payment_method_details": {
        "bank_account_number": "1234567890543",
        "bank_account_holder": "SURE PAY",
        "ifs_code": "TEST0001234",
        "bank_name": "SURE PAY",
        "bank_id": "e5897873-01f1-464d-b334-ff02202ec5f5"
      }
    }
  ]
}

                    
Example response data(upi_qr and upi_intent options are true):

{
  "reference_id": "17aa4e20-5ea8-42d2-b8df-cdfc783974a7",              
  "amount": 10,
  "payment_options": [
    {
      "payment_method": "UPI",
      "payment_method_details": {
      "upi_id": "9876543211@ybl",
      "bank_id": "3f3588f4-7992-4335-9002-a6248c9a4d2c",
      "bank_account_holder": "Eswar Mekala",
      "upi_qr": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAALQAAAC0CAYAAAA9zQYyAAAAAklEQVR4AewaftIAAAeKSURBVO3BQY4cy5LAQDLQ978yR0tfJZCoaun9GDezP1jrEoe1LnJY6yKHtS5yWOsih7UucljrIoe1LnJY6yKHtS5yWOsih7UucljrIoe1LnJY6yKHtS7yw4dU/qaKJypTxaQyVbyh8qRiUnlSMalMFZPKVPGGylTxROVvqvjEYa2LHNa6yGGti/zwZRXfpPJGxZOKJypvVEwqU8WkMqlMFZPKVDGpTBWTylTxiYpvUvmmw1oXOax1kcNaF/nhl6m8UfGGylTxROVJxaQyVTypmFTeUJkqJpU3KiaVJxVvqLxR8ZsOa13ksNZFDmtd5IfLqHxTxaTypOJJxaQyVTyp+KaKmxzWushhrYsc1rrID5epmFSmiknlicpU8UbFpPJEZap4ojJV/H92WOsih7UucljrIj/8soq/SeWJylQxqUwVk8pUMalMFVPFpDJVTCpPKp6oTBWTylTxRsV/yWGtixzWushhrYv88GUq/1LFpDJVTCpTxaQyVUwqU8WkMlV8omJSmSp+k8p/2WGtixzWushhrYv88KGK/xKVJypTxW+qmFSeqDxRmSo+UfGk4n/JYa2LHNa6yGGti/zwIZWpYlL5poqp4onKN6lMFZPKVDFVPFF5UjGpTBVvqEwVk8o3Vfymw1oXOax1kcNaF7E/+EUqU8Wk8qRiUpkqvkllqphUnlS8ofKkYlKZKt5QmSreUJkqJpWp4m86rHWRw1oXOax1kR9+WcWkMlU8UZkqJpVPVDxRmSqeqEwVb1RMKk9UporfVDGpPFF5o+ITh7UucljrIoe1LvLDh1SmiknlExVPKiaVJxVPKiaVJypTxTdVTCpTxaQyVUwVk8obFVPFJ1S+6bDWRQ5rXeSw1kV++FDFpPKk4onKGxVvqDypmCreUHlS8UTlScWkMlU8UZkqnqhMKp+o+E2HtS5yWOsih7UuYn/wi1Smikllqnii8qTiDZU3Kt5QeVIxqUwVT1Smik+oTBWTylQxqXyi4hOHtS5yWOsih7UuYn/wAZUnFZPKN1U8UZkqnqhMFW+oTBVPVKaKSWWqeKLyRsWk8kbFJ1Smik8c1rrIYa2LHNa6yA+/TGWqeKIyVTxR+ZdU3lB5o2JS+Zsq3lCZKp5UfNNhrYsc1rrIYa2L2B98QGWqmFTeqJhUflPFE5UnFU9Upoo3VKaKJypTxaQyVUwqTyreUHmj4hOHtS5yWOsih7Uu8sMvq5hU3qiYVKaKJypvqEwVk8pvUpkqJpWp4o2KSWWqmFQ+UTGpTBXfdFjrIoe1LnJY6yI/fJnKVDFVTCpPVKaKJypTxROVb1J5ojJVTBVPKr6pYlKZKiaVb1KZKj5xWOsih7UucljrIj98qGJSmVSmiqliUpkqJpVPqPymikllqphUnlR8QmWqmFTeqHiiMlVMKr/psNZFDmtd5LDWRX74ZRWTypOKSeWNir9JZaqYKt6omFSmikllqphUJpU3VKaKSWWq+JcOa13ksNZFDmtdxP7gP0Rlqnii8qRiUnlSMam8UfGGypOKb1KZKiaVqWJSmSomlScVk8pU8YnDWhc5rHWRw1oXsT/4IpU3Kp6ovFExqUwVk8onKiaVqeJvUvlNFU9U3qj4psNaFzmsdZHDWhexP/iAylQxqUwVk8qTiicqTyreUHlSMam8UTGpTBWTyhsVk8onKt5QmSr+psNaFzmsdZHDWhf54ctUpoonFZPKpDJV/EsqU8Wk8gmVJxWTyqTypOINlScVT1TeqPjEYa2LHNa6yGGti/zwy1TeqHij4hMqU8WkMlVMKlPFGxWTyicqJpVPVLxR8URlqvimw1oXOax1kcNaF/nhyyq+SeWbKr6pYlJ5UvGkYlJ5UjGpTBVPVKaKSeU3qUwVnzisdZHDWhc5rHWRH/5jVKaKSeVJxROVJypvqEwVT1R+U8Wk8k0Vb6j8TYe1LnJY6yKHtS5if/ABlaniDZWpYlKZKiaVb6p4ovKJiknlScUnVP6miicqU8U3Hda6yGGtixzWusgPH6r4RMWTijcqJpVPqLxRMan8SxVPVKaKN1SeqDxRmSo+cVjrIoe1LnJY6yI/fEjlb6qYKiaVqeKJyhsVb1RMKm+oTBWTyhsVb6hMFZ+omFS+6bDWRQ5rXeSw1kV++LKKb1J5ojJVfELlicqTijcqnqhMKp9QeaPiDZWp4knFNx3WushhrYsc1rrID79M5Y2KT6g8qZgqJpVvUpkq3qj4JpUnKt+k8kbFJw5rXeSw1kUOa13kh8tUPFF5UjGpTBWTyhsqb1RMKk8qnlQ8Ufmmiicq33RY6yKHtS5yWOsiP1xGZaqYKiaVSeWJyhOVNyqeqLyhMlVMKlPFVPFEZap4ojJV/KbDWhc5rHWRw1oX+eGXVfymiicqTyqeqLxR8URlUpkqpopJZaqYVCaVqeINlScqU8W/dFjrIoe1LnJY6yI/fJnK36TyCZWp4o2KJypTxRsqU8Wk8gmVJxWTyhsVk8pvOqx1kcNaFzmsdRH7g7UucVjrIoe1LnJY6yKHtS5yWOsih7UucljrIoe1LnJY6yKHtS5yWOsih7UucljrIoe1LnJY6yL/B+Xf6YlYW9wdAAAAAElFTkSuQmCC",
      "upi_intent": "upi://pay?pa=9876543211%40ybl&pn=Eswar%20Mekala&am=10&tr=ZnaHTzwxkPWn&tn=ZnaHTzwxkPWn",
      "utr_required": false
      }
    },
    {
      "payment_method": "BANK_TRANSFER",
      "payment_method_details": {
      "bank_account_number": "23432254543",
      "bank_account_holder": "Eswar Mekala",
      "ifs_code": "SBIN0001234",
      "bank_name": "State Bank of India",
      "bank_id": "3f3588f4-7992-4335-9002-a6248c9a4d2c",
      "utr_required": true
      }
    }
                    
  ]
}
                    
Example response data for BDT currency:

 {
  "reference_id": "c1403426-8bd9-4b33-bfb8-f76bdd163277",
  "amount":100,
  "payment_options": [
      {
          "payment_method": "NAGAD",
          "payment_method_details": {
              "account_number": "10751599599",
              "phoneNumber": "1751599599",
              "accountName": "NagadTest",
              "takaAccountId": "fdaf9f71-3400-48f6-b7fb-8967cf15701s"
          }
      },
      {
        "payment_method": "BKASH",
        "payment_method_details": {
            "account_number": "10751599592",
            "phoneNumber": "1751599599",
            "accountName": "BKASHTest",
            "takaAccountId": "fdaf9f71-3400-48f6-b7fb-8967cf15700a"
        }
    },
    {
      "payment_method": "ROCKET",
      "payment_method_details": {
          "account_number": "10751599591",
          "phoneNumber": "1751599599",
          "accountName": "ROCKETTest",
          "takaAccountId": "fdaf9f71-3400-48f6-b7fb-8967cf15702d"
       }
    }
  ]
 }
                    

Note

When either the upi_qr or upi_intent query parameter is passed in the API request, an additional field named utr_required will be included in the response with a value of 'true' or 'false'. The presence and value of this utr_required field will determine whether the utr_number field in the request body of UPI transfer API becomes mandatory or optional.

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

UPI Transfer

The UPI Transfer API enables merchants to securely and conveniently submit deposit transactions using UPI (Unified Payments Interface). By leveraging this API, merchants can quickly initiate the verification process for user transactions and ensure the utmost security throughout the verification process.

Method: POST

Endpoint: ${BASE_URL}/api/v0/deposits/upi

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
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 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
reference_id STRING transferReferenceId generated after initiating the deposit transaction uuid 3a7292cc-64b2-46ea-bcd3-e5ea844e93e1 Yes
utr_number STRING A unique transaction reference number is generated by bank when a transaction is completed. This field is not required only when the utr_required field in the Initiate Deposit API is set to 'false'. - 123456789012 Conditional
bank_id STRING bank_id sent after initiating the transaction. uuid 5e137848-e16d-4d0c-b755-85f1e3adf61d Yes
Example request body:

  {
    "mobile_number": "9xxxxxxx83",
    "application_id": "3a7292cc-64b2-46ea-bcd3-e5ea844e93e1",
    "timestamp": "2016-08-29T09:12:33.001Z",
    "reference_id": "3a7292cc-64b2-46ea-bcd3-e5ea844e93e1",
    "utr_number": "123456789012",
    "bank_id": "5e137848-e16d-4d0c-b755-85f1e3adf61d"
  }                    
                  

Note

The requirement for the utr_number field is contingent on the UPI Options provided within the response from the Initiate API. When the utr_required field is 'false,' the utr_number is optional. In all other cases, including scenarios where the utr_required field might not be sent in the response, the utr_number is mandatory.

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": " UPI transfer request created 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" 
  }
                    

Bank Transfer

The Bank Transfer API enables merchants to securely and conveniently submit deposit transactions using NEFT/IMPS/RTGS. By leveraging this API, merchants can quickly initiate the verification process for user transactions and ensure the utmost security throughout the verification process.

Method: POST

Endpoint: ${BASE_URL}/api/v0/deposits/bank_transfer

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 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
reference_id STRING transferReferenceId generated after initiating the deposit transaction. uuid 3a7292cc-64b2-46ea-bcd3-e5ea844e93e1 Yes
utr_number STRING unique transaction reference number generated when transaction is done. - 123456789012 Yes
bank_id STRING bank_id sent after initiating the transaction. uuid 5e137848-e16d-4d0c-b755-85f1e3adf61d Yes
Example request body:

  {
    "mobile_number": "9xxxxxxx83",
    "application_id": "3a7292cc-64b2-46ea-bcd3-e5ea844e93e1",
    "timestamp": "2016-08-29T09:12:33.001Z",
    "reference_id": "3a7292cc-64b2-46ea-bcd3-e5ea844e93e1",
    "utr_number": "123456789012",
    "bank_id": "5e137848-e16d-4d0c-b755-85f1e3adf61d"
  }                    
                  
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": "Bank transfer request created 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" 
  }
                    

Taka Transfer

The Taka Transfer API enables merchants to securely and conveniently submit deposit transactions using NAGAD/BKASH/ROCKET. By leveraging this API, merchants can quickly initiate the verification process for user transactions and ensure the utmost security throughout the verification process.

Method: POST

Endpoint: ${BASE_URL}/api/v0/deposits/taka

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 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
reference_id STRING transferReferenceId generated after initiating the deposit transaction. uuid 3a7292cc-64b2-46ea-bcd3-e5ea844e93e1 Yes
utr_number STRING unique transaction reference number generated when transaction is done. - 123456789012 Yes
bank_id STRING accountId sent after initiating the transaction. uuid 5e137848-e16d-4d0c-b755-85f1e3adf61d Yes
Example request body:

  {
    "mobile_number": "9xxxxxxx83",
    "application_id": "3a7292cc-64b2-46ea-bcd3-e5ea844e93e1",
    "timestamp": "2016-08-29T09:12:33.001Z",
    "reference_id": "3a7292cc-64b2-46ea-bcd3-e5ea844e93e1",
    "utr_number": "123456789012",
    "bank_id": "5e137848-e16d-4d0c-b755-85f1e3adf61d"
  }                    
                  
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": "Taka transfer request created 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" 
  }
                    

Deposit 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/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
reference_id STRING transferReferenceId generated after initiating the deposit transaction. uuid 3a7292cc-64b2-46ea-bcd3-e5ea844e93e1 Yes
utr_number STRING Unique transaction reference no generated when transaction is done. - 123456789012 No
Example request body:

  {
    "application_id": "3a7292cc-64b2-46ea-bcd3-e5ea844e93e1",
    "timestamp": "2016-08-29T09:12:33.001Z",
    "reference_id": "3a7292cc-64b2-46ea-bcd3-e5ea844e93e1",
    "utr_number": "123456789012"
  }                    
                  
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,
    "data": [
      {
        "amount": 5000,
        "transfer_reference_id": "f11b5f84-975f-44f7-bc0d-ee3de37ff2e3",
        "status": "CANCELLED",
        "application_id": "bc799075-faf8-4705-95c1-cef63018216e",
        "transaction_type": "UPI_TRANSFER",
        "user_id": "4a3e2d03-1db7-49ee-bd13-1c4d7520b589",
        "mobile_number": "9000760789",
        "utr": "308611119999"
      }
    ]
  }
                    

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 Withdrawal

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

Method: POST

Endpoint: ${BASE_URL}/api/v0/withdrawal/request

Request body:

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

Parameter Type Mandatory Description
mobile_number STRING Yes Mobile number of the user
application_id STRING Yes Application ID auto-generated when the application is created in the merchant site. The length should be less than 36 characters.
timestamp STRING Yes Time in UTC format by merchant
reference_id STRING Yes Id generated by Merchant for reference.
currency STRING Yes Type of currency INR/BDT
email STRING No Email address of the User
username STRING No Username of the User.
amount NUMBER Yes Amount to be transferred
account_details OBJECT No The account details of the user should be given based on currency along with the type of the account. (For INR currency, bank account details should be provided with type as 'BANK'. For BDT currency, wallet details should be provided with type as 'TAKA')
Example request body (BANK):

{
  "account_details": {
    "account": {
      "account_holder_name": "TEST name",
      "account_number": "1234567890",
      "bank_name": "TEST",
      "ifsc": "TEST0001234"
    },
    "type": "BANK"
  },
  "amount": 1000,
  "application_id": "3a7292cc-64b2-46ea-bcd3-e5ea844e93e1",
  "currency": "INR",
  "email": "[email protected]",
  "mobile_number": "9xxxxxxx83",
  "reference_id": "y23521hkj9927",
  "timestamp": "2024-01-18T15:02:58.640Z",
  "username": "user123"
}

                  
Example request body (BDT):

  {
    "mobile_number": "9xxxxxxx83",
    "application_id": "3a7292cc-64b2-46ea-bcd3-e5ea844e93e1",
    "timestamp": "2016-08-29T09:12:33.001Z",
    "currency": "BDT",
    "email": "[email protected]",
    "amount": 100,
    "reference_id": "y23521hkj9927",
    "username": "def123",
    "account_details": {
      "type": "TAKA",
      "account": {
        "phoneNumber": "1212121212",
        "takaAccountType": "NAGAD"
      }
    }
  }
                  
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 withdrawal transaction, such as a withdrawal referenceId or any additional details required for further processing.

Response type: SUCCESS

Status code: 200

Example response data:

  {
    "reference_id": "sdt62r6323t",
    "message": "Withdrawal request submitted succesfully",
    "error": "false"
  }
                    

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

Process Withdrawal

The Process Withdrawal API is designed to be called after the Initiate Withdrawal API. Once the Initiate Withdrawal API is invoked and the necessary withdrawal details are provided, the Process Withdrawal API is called to move the withdrawal request into the processing stage.

Method: POST

Endpoint: ${BASE_URL}/api/v0/withdrawal/process

Request body:

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

Parameter Type Mandatory Description
application_id STRING Yes Application ID auto-generated when the application is created in the merchant site. The length should be less than 36 characters.
timestamp STRING Yes Time in UTC format by merchant
reference_id STRING Yes transferReferenceId generated after initiating the withdrawal transaction.
Example request body:

  {
    "application_id": "3a7292cc-64b2-46ea-bcd3-e5ea844e93e1",
    "reference_id": "4be11db9-c3c7-47ae-9b69-509f7ab4979f",
    "timestamp": "2016-08-29T09:12:33.001Z",
  }
                  
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 this API request, a response will be returned to the merchant's application.

Response type: SUCCESS

Status code: 200

Example response data:

  {
    "message": "Withdraw Request Moved For Process Successfully",
    "error": "false"
  }
                    

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

Withdrawal Transaction Status

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

Method: POST

Endpoint: ${BASE_URL}/api/v0/withdrawal/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 withdrawal transaction. uuid 3a7292cc-64b2-46ea-bcd3-e5ea844e93e1 Yes
Example request body:

{
    "application_id": "945df189-4d5f-4d2e-baca-9793bb35ff2d",
    "timestamp": "2023-09-04T10:01:41.866Z",
    "transfer_reference_id": "2fd68246-58ef-4efc-8637-249e1af3c610"
}                   
                  
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:

{
    "transfer_reference_id": "2fd68246-58ef-4efc-8637-249e1af3c610",
    "mobile_number": "9467446126",
    "amount": 707.123,
    "status": "PENDING",
    "withdraw_request_type": "BANK"
}
                    

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

Fetch Deposits List

Fetch Deposits List API allows you to retrieve all the deposit transactions. . By utilizing this API, merchants can obtain list of deposit transactions performed by the users in their application.

Method: POST

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

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
reference_id STRING reference id provided by the merchant while initiating the transfer request. uuid 607d633d-4c34-4ab6-a215-2e5dcf8ae14c No
transfer_reference_id STRING reference id of the transaction generated when transfer request is initiated. uuid a07d633d-4c34-4ab6-a215-2e5dcf8ae141 No
utr STRING Search based on the UTR number STRING 420816273973 No
timestamp STRING Time in UTC format Date-Time 2016-08-29T09:12:33.001Z Yes
limit number The "limit" parameter specifies the maximum number of records to return in a response (default and maximum value for limit is 100) number 100 No
offset number The "offset" parameter indicates the starting point in the collection of data from which to begin returning records. number 0 No
start_date STRING Time in UTC format Date-Time 2024-07-29T09:12:33.001Z No
end_date STRING Time in UTC format Date-Time 2024-08-30T09:12:33.001Z No
status STRING status of transaction(SUCCESS, PENDING, INITIATED, CANCELLED, ABANDONED) STRING SUCCESS No
Example request body:

{
 "application_id":"945df189-4d5f-4d2e-baca-9793bb35ff2d",
 "timestamp":"2024-06-17T09:07:45.479Z",
 "limit":25,
 "offset":0,
 "startDate": "2024-05-16T18:30:00Z",
 "endDate": "2024-06-17T18:29:59Z",
 "status":"ABANDONED",
}                   
                  
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,
    "data": {
        "transactions": [
            {
                "application_name": "App0320",
                "application_id": "b030c293-d0f7-4b8c-975b-0fa1b533de96",
                "amount": 2267.6430031252885,
                "created_at": "2024-03-19T14:08:40.936Z",
                "currency": "INR",
                "fee": 22.67573696145125,
                "initiated_amount": 2267.573696145125,
                "reference_id": "52150139-85ed-4150-a00f-3f3bdd3d70a1",
                "status": "ABANDONED",
                "transfer_reference_id": "2f6b7038-a750-4741-8a89-bb8280658556",
                "updated_at": "2024-04-06T04:38:23.000Z",
                "utr": null,
                "user_id": "e7e17548-6860-42e6-9f6f-96d8843e4472",
                "user_name": " ",
                "user_mobile_number": "9988998899",
                "user_email": "[email protected]"
            },
            {
                "application_name": "App0320",
                "application_id": "b030c293-d0f7-4b8c-975b-0fa1b533de96",
                "amount": 2267.6430031252885,
                "created_at": "2024-03-19T14:11:55.522Z",
                "currency": "INR",
                "fee": 22.67573696145125,
                "initiated_amount": 2267.573696145125,
                "reference_id": "5e112b55-b8f4-43ff-ad75-f2630359b836",
                "status": "ABANDONED",
                "transfer_reference_id": "0f2bb57c-a376-488d-baa8-e3d4ccdb831c",
                "updated_at": "2024-04-06T04:38:23.000Z",
                "utr": null,
                "user_id": "e7e17548-6860-42e6-9f6f-96d8843e4472",
                "user_name": " ",
                "user_mobile_number": "9988998899",
                "user_email": "[email protected]"
            }
        ],
        "count": 2
    }
}                    

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

Fetch Withdrawals List

Fetch Withdrawals List API allows you to retrieve all the Withdrawals transactions. . By utilizing this API, merchants can obtain list of deposit transactions performed by the users in their application.

Method: POST

Endpoint: ${BASE_URL}/api/v0/withdrawal

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
reference_id STRING reference id provided by the merchant while initiating the transfer request. uuid 607d633d-4c34-4ab6-a215-2e5dcf8ae14c No
transfer_reference_id STRING reference id of the transaction generated when transfer request is initiated. uuid a07d633d-4c34-4ab6-a215-2e5dcf8ae141 No
utr STRING Search based on the UTR number STRING 420816273973 No
timestamp STRING Time in UTC format Date-Time 2016-08-29T09:12:33.001Z Yes
limit number The "limit" parameter specifies the maximum number of records to return in a response (default and maximum value for limit is 100) number 100 No
offset number The "offset" parameter indicates the starting point in the collection of data from which to begin returning records. number 0 No
start_date STRING Time in UTC format Date-Time 2024-07-29T09:12:33.001Z No
end_date STRING Time in UTC format Date-Time 2024-08-30T09:12:33.001Z No
status STRING status of transaction(SUCCESS, PENDING, INITIATED, CANCELLED) STRING SUCCESS No
Example request body:

{
 "application_id":"945df189-4d5f-4d2e-baca-9793bb35ff2d",
 "timestamp":"2024-06-17T09:07:45.479Z",
 "limit":25,
 "offset":0,
 "startDate": "2024-05-16T18:30:00Z",
 "endDate": "2024-06-17T18:29:59Z",
 "status":"CANCELLED",
}                                       
                  
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,
    "data": {
        "transactions": [
            {
                "application_name": "App",
                "amount": 13.12,
                "created_at": "2023-07-03T08:02:39.814Z",
                "currency": "INR",
                "reference_id": "1234",
                "status": "CANCELLED",
                "transfer_reference_id": "89437638-f128-4791-b103-cc3adf58c916",
                "updated_at": "2023-07-03T08:02:39.814Z",
                "utr": null,
                "user_name": " ",
                "user_mobile_number": "9988998899",
                "user_email": "[email protected]"
            }
        ],
        "count": 1
    }
}
                    

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

Fetch Chargebacks List

Fetch Chargebacks List API allows you to retrieve all the Chargebacks. . By utilizing this API, merchants can obtain list of Chargebacks performed by the users in their application.

Method: POST

Endpoint: ${BASE_URL}/api/v0/deposits/chargebacks

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
reference_id STRING reference id provided by the merchant while initiating the transfer request. uuid 607d633d-4c34-4ab6-a215-2e5dcf8ae14c No
transfer_reference_id STRING reference id of the transaction generated when transfer request is initiated. uuid a07d633d-4c34-4ab6-a215-2e5dcf8ae141 No
utr STRING Search based on the UTR number STRING 420816273973 No
timestamp STRING Time in UTC format Date-Time 2016-08-29T09:12:33.001Z Yes
limit number The "limit" parameter specifies the maximum number of records to return in a response (default and maximum value for limit is 100) number 100 No
offset number The "offset" parameter indicates the starting point in the collection of data from which to begin returning records. number 0 No
start_date STRING Time in UTC format Date-Time 2024-07-29T09:12:33.001Z No
end_date STRING Time in UTC format Date-Time 2024-08-30T09:12:33.001Z No
status STRING status of transaction(CHARGEBACK_INITIATED, SETTLED_TO_USER, SETTLED_TO_MERCHANT, CHARGEBACK_SUCCESS, CHARGEBACK_REJECTED) STRING CHARGEBACK_SUCCESS No
Example request body:

{
 "application_id":"945df189-4d5f-4d2e-baca-9793bb35ff2d",
 "timestamp":"2024-06-17T09:07:45.479Z",
 "limit":25,
 "offset":0,
 "startDate": "2024-05-16T18:30:00Z",
 "endDate": "2024-06-17T18:29:59Z",
 "status":"CHARGEBACK_SUCCESS",
}   
                  
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,
  "data": {
      "chargebacks": [
          {
              "application_name": "DMS",
              "chargeback_amount": 2000,
              "chargeback_created_at": "2024-03-25T12:18:03.756Z",
              "chargeback_raised_time": "2024-02-02T00:00:00.000Z",
              "chargeback_success_time": "2024-03-25T12:18:04.000Z",
              "reference_id": "1e837303-6c3e-4ac1-a010-ba32c205f1e1",
              "status": "CHARGEBACK_SUCCESS",
              "transfer_reference_id": "23fa6a4d-5c90-4350-a01f-82677e0a1ff4",
              "transaction_amount": 400,
              "utr": "890123456789",
              "user_id": "e19ccfc0-ae49-4fcd-9106-b1154c707c94",
              "user_name": " ",
              "user_mobile_number": "6302960165",
              "user_email": "[email protected]"

          }
      ],
      "count": 1
  }
}
                    

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 Deposit API

Initiate the deposit process in your application by making a call to the Initiate 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 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.

  • Withdrawal Callback URL:

    The Withdrawal Callback URL is a predefined endpoint where our payment gateway sends callback requests after the completion of withdrawal 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.

Moreover, for INR transactions, we offer the option to enable the inclusion of the UTR (Unique Transaction Reference) field in callback requests. Enabling this feature allows you to receive the UTR information in your callback notifications, providing enhanced visibility and tracking capabilities for INR transactions.

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)
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
utr STRING/NULL unique transaction reference number generated when transaction is done from bank (**Will be sent only when send utr in callback is enabled and only in case of INR**)
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\":17856,\"application_id\":\"3afa4bd1-9425-4bf6-9508-fc7fa2d62a40\",\"currency\":\"points\",\"reference_id\":\"e202b2ff2fd7e25230878216d88d710050830bce\",\"timestamp\":\"2023-08-02T09:45:20.433Z\",\"transfer_reference_id\":\"b6901c94-8485-4c58-8453-46d832b021e8\",\"user_mobile_number\":\"1234567890\"}"
}                    
                  
Example request body (failure callback enabled):

{
  "data": "{\"amount\":840.123,\"application_id\":\"945df189-4d5f-4d2e-baca-9793bb35ff2d\",\"currency\":\"POINTS\",\"reference_id\":\"12345\",\"status\":\"CANCELLED\",\"timestamp\":\"2023-08-31T11:49:38.772Z\",\"transfer_reference_id\":\"bc4808e5-90cc-4a57-a271-e6efc5520719\",\"user_mobile_number\":\"9729017298\"}"
}                   
                  
Example request body (utr is included):

{
  "data": "{\"amount\":491.123,\"application_id\":\"945df189-4d5f-4d2e-baca-9793bb35ff2d\",\"currency\":\"INR\",\"reference_id\":\"12345\",\"status\":\"SUCCESS\",\"timestamp\":\"2023-09-04T09:48:39.422Z\",\"transfer_reference_id\":\"2db5f08c-3e99-4d08-b0b5-2e03ab6827fe\",\"user_mobile_number\":\"9556410229\",\"utr\":\"20157482725076\"}"
}                    
                  

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.'

What is the maximum UTR length supported?

The maximum UTR (Unique Transaction Reference) length can vary based on the transfer type, ranging from 12 to 22 alphanumeric characters.