Integration



80%

Marketplace

I am developing a Marketplace. How to integrate Marketplace ?

This document specifies the workflow and basic functionalities used by marketplaces to process payments with 's API. For specific needs, please contact our team at .
INTRODUCTION
is a payment solution which enables marketplaces to easily process third-party payments.
INTEGRATION
1. Register Marketplace as a Merchant under
Your first step is to register into our platform and create a test account. Registration can be done using APIs or using Merchant Interface.
Click here for more information.
API Integration URL:
  • Test: merchantServices/api/v1/merchantSignup
  • Live: merchantServices/api/v1/merchantSignup
Merchant needs to set authentication token in header for each request. To generate authentication token, please refer Auth token API.

Sample Request

Sample Response


In our API Specifications you can find a full list of parameters that can be sent in the request.
2. Get Marketplace/Partner credentials from
will create a Partner for you. This Partner credentials will be needed for registering your vendors.
At the end of Step 2 , you will receive below details from :
  • partnerId for Marketplace (This is used to register the vendors from API/UI)
  • partner key for Marketplace (This is used to register the vendors from API)
  • partnerName/MarketplaceName assigned to Marketplace (This is used to register the vendors from UI)
  • Partner Username/Password to access Partner Interface for managing marketplace.
3. Register Vendor as a Sub Merchant in Marketplace using your partnerid
The vendor is also registered as a merchant in the system.A new member id is generated for each registration. Registration can be done using APIs or using Merchant Interface.
a. Vendor Registration API
You can post following parameters with their values:
  • authentication.partnerId - Partner ID for the marketplace, under which the vendor will be registered.
  • authentication.checksum - Checksum
  • merchant.username - Username of the vendor of sub merchant
  • merchant.password - Password of the vendor of sub merchant
  • merchant.conPassword - Confirm Password
  • merchant.companyName - Organisation Name
  • merchant.country - Country
  • merchant.email - Contact Email Address
  • merchant.contactName - Contact Person's Name
  • merchant.telcc - Contact Telephone Number CC
  • merchant.phone - Contact Telephone Number
  • merchant.website - Merchant Website or Site URL
Once you fill these details and submit, you will get registered with Marketplace
Merchant needs to set authentication token in header for each request. To generate authentication token, please refer Auth token API, and make sure that you are passing the partnerid for Marketplace here.

Sample Request

Sample Response


In our API Specifications you can find a full list of parameters that can be sent in the request.

How to generate Checksum?

A checksum has to be calculated with following combination and need to be send along with the authentication parameters in each server-to-server request. Vendor sign up for Marketplace:
<username>|<partner's secureKey provided to Marketplace>|<password>|<partnerId>

Sample Code

Here partnerId, and partner's secureKey, are the Partner ID and secureKey for the marketplace, which will be provided to you by as a part of Step 2.
b. Vendor Registration using UI
You can directly go on merchant's login page with merchant/signup.jsp?partnerid="partneridForMarketPlace"&fromtype="MarketplaceName"
After clicking on "Create an account" button you can find the sign up form with below fields:
  • Username
  • Password
  • Confirm Password
  • Organisation Name
  • Site URL
  • Country
  • Support Number
  • Contact Email Address
  • Contact Person's Name
  • Contact Telephone Number
3. Merchant On-boarding

Merchant/Vendor Onboarding will be done in two steps:

Step 1. Generate AuthToken

Generate auth token using sub merchant details. For each vendor you need to generate the auth token in order to show the on boarding form. Refer Get Merchant AuthToken for more information.
Below is the sample request and response for generating auth token.
Parameter description:

  • authentication.partnerId - partnerId assigned to the Marketplace.
  • merchant.username - Will be login name of the sub merchant (vendor).
  • authentication.sKey - Will be the secure key of the sub merchant (vendor)
In our API Specifications you can find a full list of parameters along with their description.

Sample Request

Sample Response


Step 2. Onboarding API

Use Onboarding API, to access the Merchant/Vendor Application Form, which can be opened using iFrame, and the Merchant/Vendors can fill that up, upload their KYCs and Submit their Form.
You can view the merchant submitted form in the parnter backoffice

Append the authtoken generated from STEP 1 in the url mentioned below and open it in the iframe or redirect it. Sameple URL :
  • Test: merchant/servlet/PopulateApplication?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjb25tZXJjaGFudDEiLCJyb2xlIjoibWVyY2hhbnQiLCJpc3MiOiJQWiIsImV4cCI6MTUwMTE0NjY0MX0.TFmGGKDUgkktmZQvrUTeox1buH1J6lgBVE3Mcy8OVjA
  • Live: merchant/servlet/PopulateApplication?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjb25tZXJjaGFudDEiLCJyb2xlIjoibWVyY2hhbnQiLCJpc3MiOiJQWiIsImV4cCI6MTUwMTE0NjY0MX0.TFmGGKDUgkktmZQvrUTeox1buH1J6lgBVE3Mcy8OVjA
4. Transaction
Merchants and Vendors have now been registered within our API. The next step is to send funds to the merchant’s account. You can submit your transactions from Standard Checkout.
Below you can find the sample Request for the same,

In our API Specifications you can find a full list of parameters that can be sent in the initial request.

Sample Request

The account holder will be redirected to hosted page, where the account holder can fill the card/account details.
Once the payment has been processed, the customer will be redirected to your merchantRedirectUrl along with a POST parameters.

Sample Response


Along with the response parameters, you will receive the Master_Trackingid (trackingid), and child_Trackingid for each vendor
5. Standard Notification/Callback
After the transaction has reached a conclusive status, "" will send a notification on the MerchantNotificationURL. Here, Master_Trackingid (paymentId), transaction status, and marketPlaceDetails are returned in the notification.
marketPlaceDetails is an array of below information:
  1. child_Trackingid,
  2. amount against the child transaction, and
  3. orderid against the child transaction.

Sample Notification

{
   "paymentId":"6579092",
   "status":"capturesuccess",
   "paymentBrand":"VISA",
   "paymentMode":"CC",
   "firstName":"s",
   "lastName":"p",
   "amount":"11.00",
   "currency":"USD",
   "descriptor":" Test",
   "result":{
      "code":"00001",
      "description":"Transaction succeeded"
   },
   "card":{
      "bin":"411111",
      "lastFourDigits":"1111",
      "last4Digits":"1111",
      "expiryMonth":"12",
      "expiryYear":"2030"
   },
   "customer":{
      "email":"john.doe@test.com",
      "id":"12596"
   },
   "timestamp":"2021-01-18 13:34:13",
   "merchantTransactionId":"Test172",
   "remark":"Transaction authorised.",
   "transactionStatus":"Y",
   "tmpl_amount":"11.00",
   "tmpl_currency":"USD",
   "eci":"",
   "checksum":"253d493476364a95558ed4df8f875b71",
   "marketPlaceDetails":[
      {
         "trackingid":"6579093",
         "amount":"1.00",
         "orderid":"Order-12256-172"
      },
      {
         "trackingid":"6579094",
         "amount":"10.00",
         "orderid":"Order-12258-172"
      }
   ]
}

Checksum in the Notification can be calculated with the following combination.
<paymentId> | <merchantTransactionId> | <amount> | <transactionStatus> | <secret key for Master Merchant>
Example : 6579092|Test172|11.00|Y| <merchant secret key>
6. Refund
For a transaction that has been successfully paid, the customer can request the merchant/vendors for refunding as long as the refunding period is still valid.
In order to refund your transaction, POST your request to endpoint: /transactionServices/REST/v1/payments/Master_Trackingid and pass the trackingids and refund amount for each vendor.

Sample Request 

{
   "authentication":{
      "memberId":"12251",
      "checksum":"96b0ebc2ea14e1e01f062eb04b968fb8"
   },
   "amount":"0.02",
   "paymentType":"RF",
   "marketplace":[
    {
        "trackingid":"100222",
        "amount":"0.01"
    },
    {
        "trackingid":"100223",
        "amount":"0.01"
    }
    ]
}

Sample Response 

{
    "paymentId": "100221",
    "result": {
        "code": "00005",
        "description": "Transaction refunded successfully"
    },
    "timestamp": "2019-05-07 15:16:06"
}

Hashing Rule for Refund

is supporting MD5 Cryptographic Hash for the authenticity of payment request send to the server.

Below is the description of fields used for generating checksum:
  • memberId - Merchant ID as shared by
  • secureKey - Secure Key that can be generated through 's dashboard
  • paymentId - TrackingId of the successfull transaction to be refunded
  • amount - Amount of transaction

How to generate Checksum?

Checksum has to be calculated with following combination & needs to be send along with the authentication parameters in each server-to-server request:
<memberId>|<secureKey>|<paymentId>|<amount>

Sample Code

GLOSSARY

MARKETPLACE Online platform where products and services are exchanged by third parties. Transactions are processed by the platform. (You)
MERCHANT User with multiple vendors selling products under merchant's name.
VENDOR User selling a product or a service.
CUSTOMER User buying a product or a service.
REFUND Reimbursement to a user.
MASTER TRACKING ID Tracking id received in the response of the purchase transaction for master merchant.