Getting Started

CashFree uses API keys to allow access to the API. Once you have signed up at our merchant site, you will be able to retreive your AppId and SecretKey (API keys).

Endpoints

URL Environment
https://ces-gamma.cashfree.com TEST
https://ces-api.cashfree.com PRODUCTION

PG Integration

This Section explains how to connect the Cashfree Payment Gateway (PG) to your Cashfree Marketplace Settlement account for a seamless settlement experience right from accepting payments from your customers to paying your vendors.

How this works

  1. Receive payments using Cashfree PG - Initiate payment request for an order and provide a list of vendors(who will eventually receive commission for that order payment) during the request along with rest of the order details.
  2. After we receive customer’s payment on your order, we will automatically transfer this transaction to your Marketplace account.
  3. Next as part of the configured settlement cycle of your Marketplace account the share of the vendors will be credited to their bank accounts.

Note:

  1. Marketplace settlements do not support the split on transactions completed using Paytm and PayPal. In this case, the settlement is moved to the merchant’s Paytm or PayPal account.
  2. IP Whitelisting is not a mandatory step when using Marketplace settlements.

Generating vendorSplit

  • Ensure that the PG Integration is done on your website and its working Properly.
  • While creating order an extra parameter, vendorSplit, needs to be passed. The parameter vendorSplit is base64 JSON array of vendor Ids and their corresponding commission. To generate vendorSplit first generate the JSON array of vendors as follows:
[
  {
    "vendorId":"<vendor_id_1>",
    "commission":<commission_value_as_percent>
  }, 
  {
    "vendorId":"<vendor_id_2>",
    "commissionAmount":<commission_value_in_ruppees>
  }
]
  • commission should be a number between 0 and 100 that represents the corresponding vendors commission as a percent. Instead of expressing commission as a percent, commissionAmount can also be used to express it in absolute amount. vendorId is the id of a vendor that you have already added to your Marketplace account. Please go to your dashboard to view the VendorId for all your vendors.

  • In case you are using commission please ensure that the sum of commission across all vendors is not more than 100. In case you are using commissionAmount please ensure the sum of commissionAmounts is not more than orderAmount.

  • Once the json array is generated, encode it using the base64 encoding. The resulting value is the vendorSplit to be attached during order creation. You can also provide multiple such vendor commissions to associate multiple vendors with a single order. For example to associate VENDOR1 and VENDOR2 with an order with commission of 30% and 40% respectively, the JSON array will look like this:

[
  {
    "vendorId":"VENDOR1",
    "commission":30
  },
  {
    "vendorId":"VENDOR2",
    "commission":40
  }
]
  • Once its base64 encoded its value will be: W3sidmVuZG9ySWQiOiJWRU5ET1IxIiwiY29tbWlzc2lvbiI6MzB9LCB7InZlbmRvcklkIjoiVkVORE9SMiIsImNvbW1pc3Npb24iOjQwfV0=

  • Vendor Split value needs to be correctly included in PG order creation depending on your integration type. Please see the relevant examples below:

Sending extra values with vendorSplit

For some features there is a need to send extra parameters. This can be done by generating vendorSplit as follows:

{
  "vendors" : [
    {
      "vendorId":"<vendor_id_1>",
      "commission":<commission_value_as_percent>
    }, 
    {
      "vendorId":"<vendor_id_2>",
      "commissionAmount":<commission_value_in_ruppees>
    }
  ],
  "<extra_param_name>":"<extra_param_value>" 
}

An example for the same is described here:

{
  "vendors":[
    {
      "vendorId":"VENDOR1", 
      "commission":50
    },
    {
      "vendorId":"VENDOR2", 
      "commission":50
    }
  ], 
  "overrideAmount":110
}

Once its base64 encoded the vendorSplit value will be: ewogICJ2ZW5kb3JzIjpbCiAgICB7CiAgICAgICJ2ZW5kb3JJZCI6IlZFTkRPUjEiLCAKICAgICAgImNvbW1pc3Npb24iOjUwCiAgICB9LAogICAgewogICAgICAidmVuZG9ySWQiOiJWRU5ET1IyIiwgCiAgICAgICJjb21taXNzaW9uIjo1MAogICAgfQogIF0sIAogICJhY3R1YWxBbW91bnQiOjExMAp9

Integrating vendorSplit

The vendorSplit value generated in last section needs to be sent during the PG order creation. The exact steps for this varies depending on your integration type.

Checkout & Seamless Pro

Include an extra field in the form you generate:

<input type="hidden" name="vendorSplit" value="<vendor_split_value>"/>


Embedded & Seamless Basic

Include an extra parameter in the data object you send to makePayment (or paySeamless) method as follows:

data.vendorSplit = "<vendor_split_value>";


REST API

Include an extra parameter in the request body of /api/v1/order/create call:

vendorSplit = "<vendor_split_value>";


ANDROID

While using the CFPaymentService.doPayment() pass along an extra value in the params hashmap as follows

params.put(PARAM_VENDOR_SPLIT, "<vendor_split_value>");



Self Payouts

By default the portion of order value that is not sent to the vendor is retained as part of marketplace account balance which can easily be withdrawn from our Dashboard here. However, many times part of requirement is that the merchant be able to easily receive their portion of intended sum instantly via automated payout to their business account. To support this merchants need to add an extra parameter in their vendor split.

To ensure that your share of the transaction is automatically sent to your business account registered with Cashfree you will need to use a special vendorId “SELF” in the vendorSplit that you generate for the order. Lets say you want to send 5% of order amount to your account and 95% to the account of a vendor identified by vendorId “VENDOR1”. This is what the vendorSplit will look like before base64 encoding:

[
  {
    "vendorId":"SELF",
    "commission":5
  },
  {
    "vendorId":"VENDOR1",
    "commission":95
  }
]

SELF is a special vendorId that identifies your business account in the vendor split. This vendor id is created and attached to your account when marketplace account is activated. Transfers to SELF vendor are exempted of all charges from our end.


Marketplace Refunds

To ensure correct settlements to your vendors you need to take PG refunds into account. To do this, we need you to use our Adjust Vendor Balance API .

This API can be used in addition to the refunds API to do a Marketplace refund. You must first refund the customer with the balance in your PG account using the Payment Gateway Refunds API and then debit the appropriate amount from the vendor using Adjust Vendor Balance API. This API can be used to make one-off debits and credits.

For example, let us consider a transaction worth Rs. 300 which consists of 3 items worth Rs. 100 each from 3 different vendors. Now, there is a refund request for a full refund of Rs. 100 for the item sold by Vendor_A and a partial refund of Rs. 50 from Vendor_B. Here is how you need to process the refund request:

First, initiate a refund of Rs. 150 using our Refunds API. This amount gets debited from the balance in your PG account. Ensure that you have the required amount before you process the refund.

Then, call the Adjust Vendor Balance API twice, i.e., once for Rs. 100 from Vendor_A and again for Rs. 50 from Vendor_B. Ensure you set the ‘type’ field in this call to DEBIT since it defaults to CREDIT if not mentioned. You can also pass the refundId in ‘remarks’ for future reference.


API Reference

This section lists all the API available for Cashfree Marketplace Settlements.

Authenticate

Authenticate the user with the Cashfree system and obtain the Authorization Bearer token. All other API calls must have this token as Authorization header in the format ‘Bearer <token>’ (without quotes) for them to be processed.

Caution : Do not store the token in an insecure manner. Regenerating new token does not invalidate the already generated token.But we do have a check where token generated from one IP address cannot be used from a different IP.

In case you are getting an ‘IP not whitelisted’ error, do the following:

  1. Login to merchant dashboard, select Marketplace Settlements
  2. Go to Access Control -> IP Whitelist
  3. Enter Ipv4 address from where you are making API requests and submit

Endpoint

Method URL
POST /ces/v1/authorize

Request Parameters

Type Params Values
HEAD X-Client-Id string
HEAD X-Client-Secret string

Response

Status Response
200 {"status":"SUCCESS", "message":"Token generated", "subCode":"200", "data": { "token":"4k9JC...2xyPBe", "expiry":1497637144}}
401 {"status":"ERROR","message":"Invalid clientId and clientSecret combination","subCode":"401"}

Verify Token

Verify the authentication token generated. Response will be ‘Token is not valid’ if token doesnot exist,invalid or has expired. Regenerate token incase of token expiry for making API calls ( use /ces/v1/authorize for this)

Endpoint

Method URL
POST /ces/v1/verifyToken

Request Parameters

Type Params Values
HEAD Authorization String (Format: Bearer <token>)

Response

Status Response
200 {"status":"SUCCESS", "message":"Token is valid", "subCode":"200"}
403 {"status":"ERROR", "subCode":"403", "message":"Token is not valid"}

Add Vendor

This operations allows you to enter the details of vendor to add it to your Marketplace accounts. You can settle money to a vendor only after you have added the vendor to your account.

Endpoint

Method URL
POST /ces/v1/addVendor

Request Parameters

Type Params Values
HEAD Authorization String (Format: Bearer <token>)
HEAD Content-Type application/json
POST vendorId* String. Alphanumeric. No Spaces. Unique Identifier for the Vendor. This identifier is used by other Marketplace API method to identify the vendor. Ex: VEN343
POST name* String. Alphanumeric. The name of the vendor.
POST phone* Number. Vendor’s phone number.
POST email* String (Ex: johndoe_1@cashfree.com)
POST bankAccount* Alphanumeric. The Bank Account of the Vendor. This is the account that we will settle to.
POST accountHolder* Alphanumeric. The name of the account holder for the bank account.
POST ifsc* Alphanumeric. The IFSC code for the bank account.
POST panNo Alphanumeric. The PAN number for the vendor. Ex: AAAPL1234C.
POST aadharNo Number. No spaces, hyphens etc allowed. The Aadhar Number for the vendor. Ex: 499118665246.
POST gstin Alphanumeric. No spaces, hyphens etc allowed. The GSTIN for the vendor. Ex: 22AAAAA0000A1Z5.
POST address1* Alphanumeric. First line of address of the vendor.
POST address2* Alphanumeric. Second line of address of the vendor.
POST city* Alphanumeric. Name of the city for the vendor.
POST state* Alphanumeric. Name of the state for the vendor.
POST pincode* Number. Valid Pincode.

Response

Status Request/Response
200 Request {"vendorId" : "VEN343", "name" : "343 Industries", "phone" : 9900034300, "email" : "three43@gmail.com", "commission" : 34.3, "bankAccount" : 30004343400003, "accountHolder" : "TFT", "ifsc" : "HDFC0000343", "address1" : "Diamond District", "address2" : "Indranagar", "city" : "Bengaluru", "state" : "Karnataka", "panNo" : "AAAPL1234C", "aadharNo" : "499118665246", "gstin" : "22AAAAA0000A1Z5", "pincode" : 560071}
Response {"status":"SUCCESS", "subCode":"200", "message":"Vendor added successfully"}

Edit Vendor

This operations allows you to edit the details of vendor added to your Marketplace accounts. Please note bank account related details are not updateable.

Endpoint

Method URL
POST /ces/v1/editVendor/<vendorId>

Request Parameters

Type Params Values
HEAD Authorization String (Format: Bearer <token>)
HEAD Content-Type application/json
POST name String. Alphanumeric. The name of the vendor.
POST phone Number. Vendor’s phone number.
POST email String (Ex: johndoe_1@cashfree.com)
POST panNo Alphanumeric. The PAN number for the vendor. Ex: AAAPL1234C.
POST aadharNo Number. No spaces, hyphens etc allowed. The Aadhar Number for the vendor. Ex: 499118665246.
POST gstin Alphanumeric. No spaces, hyphens etc allowed. The GSTIN for the vendor. Ex: 22AAAAA0000A1Z5.
POST address1 Alphanumeric. First line of address of the vendor.
POST address2 Alphanumeric. Second line of address of the vendor.
POST city Alphanumeric. Name of the city for the vendor.
POST state Alphanumeric. Name of the state for the vendor.
POST pincode Number. Valid Pincode.

Response

Status Request/Response
200 Request {"name" : "343 Industries", "phone" : 9900034300, "email" : "three43@gmail.com", "commission" : 34.3, "address1" : "Diamond District", "address2" : "Indranagar", "city" : "Bengaluru", "state" : "Karnataka", "panNo" : "AAAPL1234C", "aadharNo" : "499118665246", "gstin" : "22AAAAA0000A1Z5", "pincode" : 560071}
Response {"status":"SUCCESS", "subCode":"200", "message":"Vendor Updated"}

Get Vendors

Get all the vendors associated with your Cashfree Marketplace Settlements account.

Endpoint

Method URL
GET /ces/v1/getVendors

Request Parameters

Type Params Values
HEAD Authorization String (Format: Bearer <token>)
URL maxReturn [optional] Number (0 < maxReturn <= 200, default maxReturn = 20). For pagination support. Details the maximum number of records that should be returned from this query
URL lastReturnId [optional] Number. For pagination support. Every payments endpoint response has a lastReturnId param. Set this value in lastReturnId to get the next page.

Example URL : /ces/v1/getVendors?maxReturn=2&lastReturnId=75

Response

Status Response
200 {"status": "SUCCESS", "subCode": "200", "message": "Vendor Details", "data":[{ "vendorId": "VEN125", "name": "125 Industries", "commission": "10.00", "balance": "0.00", "email": "ven125@gmail.com", "phone": "9900012345", "accountHolder": "125 Indus", "bankAccount": "30004343400125", "ifsc": "HDFC0001748", "status": "PENDING"},{ "vendorId": "VEN124", "name": "124 Industries", "commission": "10.00", "balance": "0.00", "email": "ven124@gmail.com", "phone": "9900012345", "accountHolder": "124 Indus", "bankAccount": "30004343400124", "ifsc": "HDFC0001748", "status": "PENDING"}],"lastReturnId":73}

Get Vendor

Get details of a vendor associated with your Marketplace account.

Endpoint

Method URL
GET /ces/v1/getVendor/<vendorId>

Request Parameters

Type Params Values
HEAD Authorization String (Format: Bearer <token>)

Response

Status Request/Response
200 Request GET /ces/v1/getVendor/VEN343
Response {"status":"SUCCESS","subCode":"200", "message":"Vendor Details","data": {"vendorId":"VEN343", "name":"343 Industries", "commission":"34.30", "balance":"90.32", "email":"three43@gmail.com", "phone":"9900034300", "accountHolder":"TFT", "bankAccount":"30004343400003", "ifsc":"HDFC0000343", "status":"VERIFIED", "panNo":"AAAPL1234C", "aadharNo":"499118665246", "gstin":"22AAAAA0000A1Z5", "remarks":""}}

Note on Vendor Status

  • Vendor Status expresses the verification status of the vendor and it can have the following values.

Status Values

Beneficiary Status Description
PENDING The verification for vendor has not been completed yet. Please forward the necessary documents for the same.
VERIFIED The verification of vendor is successfully completed and now outgoing payments to the vendors bank account can now be made.
REJECTED The verification of vendor has failed due to some irregularities in the provided documents. Please check the remarks field in /getVendor request for more information on the reason for the rejection.

Import Transaction

You can manually add new transactions to your Marketplace account using the following API operation. Note: Use this only for transactions that are not coming through payment gateway (example: Cash on Delivery Orders).

Endpoint

Method URL
POST /ces/v1/importTransaction

Request Parameters

Type Params Values
HEAD Authorization String (Format: Bearer <token>)
HEAD Content-Type application/json
POST orderId* String. Alphanumeric. No Spaces. Unique Identifier for the transaction. This identifier is used by other Marketplace API method to identify the transaction. Ex: CF943
POST orderAmount* Number. The total value of this order in INR.
POST orderNote* String. Associate a note/message with this transaction.
POST customerName* String. The Name of the customer for this transaction.
POST customerPhone* Number. Vendor’s phone number.
POST customerEmail* String (Ex: johndoe_1@cashfree.com)
POST vendors* JSON Array. This is an array of JSON objects of all the vendors associated with the txn. For Example: [{"vendorId":"VENDOR1","commission":30}, {"vendorId":"VENDOR2","commissionAmount":400}] Each item of the array needs to contain a vendorId field. You can either provide commission as percent or commissionAmount as a numeric amount. If commission/commissionAmount is not provided then the default value of commission provided during vendor creation will be used.

Response

Status Request/Response
200 Request {"orderId":"CF943", "orderAmount":10999, "orderNote":"Test Trans", "customerName":"CustTEST", "customerEmail":"cust@gmail.com", "customerPhone":9900012345, "vendors":[{"vendorId":"VEN343", "commission":15.5}, {"vendorId":"VEN007"}]}
Response {"status":"SUCCESS", "subCode":200, "message":"Added Transaction"}

Get Transactions

Get the details of all transactions associated with your account.

Endpoint

Method URL
POST /ces/v1/getTransactions

Request Parameters

Type Params Values
HEAD Authorization String (Format: Bearer <token>)
URL maxReturn[optional] Number (0 < maxReturn <= 200, default maxReturn = 20). For pagination support. Details the maximum number of records that should be returned from this query
URL lastReturnId [optional] Number. For pagination support. Every payments endpoint response has a lastReturnId param. Set this value in lastReturnId to get the next page.

Example URL: /ces/v1/getTransactions?maxReturn=1&lastReturnId=1511445412

Response

Status Request/Response
200 Response {"status": "SUCCESS", "subCode": "200", "message": "Transaction Details", "data":[{"orderId": "1067", "orderAmount":800, "orderNote": "Test Trans", "customerName": "CustTEST", "customerEmail": "cust@gmail.com", "customerPhone": "9900012345", "vendors":[{ "vendorId": "VEN345", "commission":100 }],},{"orderId": "1066", "orderAmount":10, "orderNote": "Test Trans", "customerName": "CustTEST", "customerEmail": "cust@gmail.com", "customerPhone": "9900012345", "vendors":[{ "vendorId": "VEN345", "commission":50 },{ "vendorId": "VEN343", "commission":50 }],},{"orderId": "1065", "orderAmount":100, "orderNote": "Test Trans", "customerName": "CustTEST", "customerEmail": "cust@gmail.com", "customerPhone": "9900012345", "vendors":[{ "vendorId": "VEN345", "commission":50 }, {"vendorId": "VEN343", "commission":50}],}], "lastReturnId":1511426413}

Get Transaction

Get the details of any transaction associated with your account by providing its orderId.

Endpoint

Method URL
POST /ces/v1/getTransaction/<orderId>

Request Parameters

Type Params Values
HEAD Authorization String (Format: Bearer <token>)

Response

Status Request/Response
200 Request GET /ces/v1/getTransaction/CF945
Response {"status":"SUCCESS", "subCode":"200", "message":"Transaction Details", "data": {"orderId":"CF945", "orderAmount":10999, "orderNote":"Test Trans", "customerName":"CustTEST", "customerEmail":"cust@gmail.com", "customerPhone":"9900012345", "vendors": [{ "vendorId":"VEN343", "commission":15.5 },{ "vendorId":"VEN007", "commission":7 }]}}

Attach Vendor

Allows you to attach vendors to an existing transaction. If the vendor is already added to Transaction its commission will be updated.

Endpoint

Method URL
POST /ces/v1/attachVendor

Request Parameters

Type Params Values
HEAD Authorization String (Format: Bearer <token>)
HEAD Content-type application/json
POST orderId* String. OrderId of a valid transaction.
POST vendorId* String. VendorId of a vendor associated to your account.
POST commission Percent. Commission as Percent of order amount (1 to 100) for the attached vendor. commission or commissionAmount is needed to attach a vendor.
POST commissionAmount Number. Commission in rupees. Use this for precisely specifying the commission. commission or commissionAmount is needed to attach a vendor.

Response

Status Request/Response
200 Response {"orderId" : "796", "vendorId" : "VEN1", "commission" : 12}
Response {"status":"SUCCESS", "subCode":200, "message":"Attached vendor to transaction"}

Detach Vendor

Allows you to remove vendors from an existing transaction.

Endpoint

Method URL
POST /ces/v1/detachVendor

Request Parameters

Type Params Values
HEAD Authorization String (Format: Bearer <token>)
HEAD Content-type application/json
POST orderId* String. OrderId of a valid transaction.
POST vendorId* String. VendorId of a vendor associated to your account.

Response

Status Request/Response
200 Response {"orderId" : "796", "vendorId" : "VEN1"}
Response {"status":"SUCCESS", "subCode":200, "message":"Removed Vendor from transaction"}

Adjust Vendor Balance

Allows you to adjust vendor balance.

Endpoint

Method URL
POST /ces/v1/adjustVendor

Request Parameters

Type Params Values
HEAD Authorization String (Format: Bearer <token>)
HEAD Content-type application/json
POST vendorId* String. VendorId of a vendor associated to your account.
POST adjustmentId* Number. A vendor generated id which uniquely identifies an adjustment.
POST amount* Number. Greater than zero. This is the value by which the vendor balance will be adjusted. Note: The vendor balance is allowed to be reduced to less than zero. This will halt all payouts to the vendor until his balance reaches a value greater than zero.
POST type String. Either “CREDIT” or “DEBIT”. This tells whether the balance needs to be increased or decreased. Defaulted to “CREDIT”.
POST remarks String. Information on ledger adjustment. Will be visible alongside ledger row in API and Dashboard.

Response

Status Request/Response
200 Response { "vendorId":"VEN113", "amount":3, "type":"DEBIT", "adjustmentId":124 }
Response {"status":"SUCCESS", "subCode":200, "subCode": 200, "message": "Adjust Vendor Balance done", "adjustment": 3 }

Request Vendor Payout

Allows you to request settlement to vendor manually. Please note that settlement might not happen immediately.

Endpoint

Method URL
POST /ces/v1/requestVendorPayout

Request Parameters

Type Params Values
HEAD Authorization String (Format: Bearer <token>)
HEAD Content-type application/json
POST vendorId* String. VendorId of a vendor associated to your account
POST amount* Number. This is the amount of settlement which you want to initiate. Should be less than or equal to balance of vendor.

Response

Status Request/Response
200 Response {"vendorId":"VEN113", "amount": 100}
Response {"status":"SUCCESS", "subCode":200, "subCode": 200, "message": "Vendor Payout Request Accepted"}

Get Vendor Ledger

Get the vendor ledger for a vendor which shows all changes to vendor balance.

Endpoint

Method URL
GET /ces/v1/getVendorLedger/<vendorId>

Request Parameters

Type Params Values
HEAD Authorization String (Format: Bearer <token>)
URL maxReturn [optional] Number (0 < maxReturn <= 200, default maxReturn = 20). For pagination support. Details the maximum number of records that should be returned from this query
URL lastReturnId [optional] Number. For pagination support. Every payments endpoint response has a lastReturnId param. Set this value in lastReturnId to get the next page.

Example URL: /ces/v1/getVendorLedger/VEN343?maxReturn=2&lastReturnId=3605

Response

{ "status": "SUCCESS",
  "subCode": "200",
  "message": "Vendor Ledger",
  "data": [
    {
      "amount": "800.00",
      "eventType": "CREDIT",
      "eventTag": "VENDOR_COMMISSION",
      "eventId": "1064",
      "remarks": "Order Id: 1064",
      "closingBalance": "800.00",
      "addedOn": "2017-11-23 14:00:43"
    },
    {
      "amount": "24400.00",
      "eventType": "DEBIT",
      "eventTag": "VENDOR_PAYOUT",
      "eventId": "13122",
      "remarks": "Automated Transfer to 30004343400003",
      "closingBalance": "0.00",
      "addedOn": "2017-11-23 13:56:34"
    }
  ],
  "lastReturnId": 3604
}

Order Settlement Status

Check status of the vendor transfers corresponding to a particular OrderId. Check the settlementStatus (described here) in the response object for getting the overall status of individual vendor transfers.

Endpoint

Method URL
GET /ces/v1/getOrderSettlementStatus/<orderId>

Request Parameters

Type Params Values
HEAD Authorization String (Format: Bearer <token>)

Response

{
    "status": "SUCCESS",
    "subCode": "200",
    "message": "Settlement to vendor has been done successfully",
    "settlementStatus": "SETTLED",
    "vendorTransfers": [
        {
            "vendorId": "VEN345",
            "amount": "64.00",
            "serviceCharge": "10.00",
            "serviceTax": "1.80",
            "totalAmount": "64.00",
            "status": "SUCCESS",
            "utr": "1387420170403001552660305",
            "addedOn": "2019-03-15 20:01:41",
            "vendorTransferId": 13213
        },
        {
            "vendorId": "VEN346",
            "amount": "80.00",
            "serviceCharge": "10.00",
            "serviceTax": "1.80",
            "totalAmount": "80.00",
            "status": "SUCCESS",
            "utr": "1387420170403001552660305",
            "addedOn": "2019-03-15 20:01:41",
            "vendorTransferId": 13214
        }
    ]
}

Settlement Status Values

Beneficiary Status Description
PG_UNPAID The order is still not paid. Unpaid orders can be settled to vendors
PG_SETTLEMENT_PENDING The order is still not settled from PG to marketplace. Settlement to vendors only happens after settlement at PG.
READY_FOR_SETTLEMENT The Order is ready for settlement and will be settled within one working day typically.
INITIATED_SETTLEMENT The Settlement to vendors has been initiated but not all vendors have been settled. Check vendorTransfers in response for more details.
SETTLED The Settlemend to all vendors has been completed. Check vendorTransfers in response for more details.

Get Vendor Transfer

Get the vendor transfer by vendorTransferId. Also shows orders which correspond to the vendorTransfer.

Endpoint

Method URL
GET /ces/v1/getVendorTransfer/<vendorTransferId>

Request Parameters

Type Params Values
HEAD Authorization String (Format: Bearer <token>)

Response

Status Response
200 Response {"status": "SUCCESS", "subCode": "200", "message": "Vendor Transfer", "data": {"vendorId": "VEN345", "amount": "2.00", "serviceCharge": "10.00", "serviceTax": "1.80", "totalAmount": "13.80", "status": "PENDING", "utr": "", "addedOn": "2017-11-27 14:42:48"}}

Get Vendor Transfers

Get the vendor ledger for a vendor which shows all changes to vendor balance.

Endpoint

Method URL
GET /ces/v1/getVendorTransfers/<vendorId>

Request Parameters

Type Params Values
HEAD Authorization String (Format: Bearer <token>)
URL maxReturn [optional] Number (0 < maxReturn <= 200, default maxReturn = 20). For pagination support. Details the maximum number of records that should be returned from this query
URL lastReturnId [optional] Number. For pagination support. Every payments endpoint response has a lastReturnId param. Set this value in lastReturnId to get the next page.
URL startDate [optional] Date in YYYYMMDD format. For pagination support. Start of period you want to search. Starts search from the 0000 Hrs on startDate
URL endDate [optional] Date in YYYYMMDD format. For pagination support. End of period you want to search. Ends search at the 2359 Hrs on endDate

Example URL: /ces/v1/getVendorTransfers/VEN343?maxReturn=2&lastReturnId=13114&startDate=20171121&endDate=20171122

Response

{ 
	"status": "SUCCESS", 
	"subCode": "200", 
	"message": "Vendor Transfers", 
	"data":[
		{ 
			"vendorTransferId":13113, 
			"amount": "2.00", 
			"serviceCharge": "11.80", 
			"serviceTax": "0.00", 
			"totalAmount": "13.80", 
			"status": "SUCCESS", 
			"utr": "1387420170403001511342700", 
			"addedOn": "2017-11-22 14:54:34"
		},{ 
			"vendorTransferId":13104, 
			"amount": "2.00", 
			"serviceCharge": "11.80", 
			"serviceTax": "0.00", 
			"totalAmount": "13.80", 
			"status": "SUCCESS", 
			"utr": "1387420170403001511268686", 
			"addedOn": "2017-11-21 18:17:26"
		}
	], 
	"lastReturnId":13104
}

Transfer Vendor Balance

Allows you to transfer balance from one vendor account to another vendor account.

Endpoint

Method URL
POST /ces/v1/transferVendorBalance

Request Parameters

Type Params Values
HEAD Authorization String (Format: Bearer <token>)
POST fromVendorId* String. VendorId of a vendor associated to your account from whose balance you want to DEBIT amount.
POST toVendorId* String. VendorId of a vendor associated to your account to whose balance you want to CREDIT amount.
POST adjustmentId* Number. A vendor generated id which uniquely identifies an adjustment.
POST amount* Number. Greater than zero. This is the value by which the vendor balance will be adjusted. Note: The vendor balance is allowed to be reduced to less than zero. This will halt all payouts to the vendor until his balance reaches a value greater than zero.

Response

Status Response
200 Request {"fromVendorId":"VEN113", "toVendorId":"VEN343", "adjustmentId":128, "amount":1}
Response {"status": "SUCCESS", "subCode": "200", "message": "Vendor Balance Transfer Done"}

Request Withdrawal

Allows you to withdraw balance from Marketplace Settlements to your bank account.

Endpoint

Method URL
POST /ces/v1/requestWithdrawal

Request Parameters

Type Params Values
HEAD Authorization String (Format: Bearer <token>)
POST amount* Number. Greater than zero. This is the value which will be withdrawn from your Marketplace Settlements ledger to your registered bank account.
POST remarks String. Remarks for this withdrawal.

Response

Status Response
200 Request {"amount":500, "remarks":"Withdrawal"}
Response {"status":"SUCCESS", "subCode":"200", "message":"Withdrawal Request Accepted"}

Check Balance

Allows you to check balance of your Marketplace Settlements account.

Endpoint

Method URL
GET /ces/v1/getBalance

Request Parameters

Type Params Values
HEAD Authorization String (Format: Bearer <token>)

Response

Status Response
200 Request {"status":"SUCCESS","subCode":"200","message":"Fetched account balance","balance":"903027.20"}

Get Merchant Ledger

Allows you to check balance of your Marketplace Settlements account.

Endpoint

Method URL
GET /ces/v1/getLedger

Request Parameters

Type Params Values
HEAD Authorization String (Format: Bearer <token>)
URL maxReturn [optional] Number (0 < maxReturn <= 200, default maxReturn = 20). For pagination support. Details the maximum number of records that should be returned from this query
URL lastReturnId [optional] Number. For pagination support. Every payments endpoint response has a lastReturnId param. Set this value in lastReturnId to get the next page.

Example URL: /ces/v1/getLedger?maxReturn=2&lastReturnId=223

Response

Status Response
200 Response {"status":"SUCCESS","subCode":"200", "message":"Fetched account ledger", "ledger":[{"ledgerId":222, "eventType":"DEBIT", "amount":"17.80", "closingBalance":"645866.58", "particulars":"VENDOR_PAYOUT", "remarks":"Vendor: NAFEY", "addedOn":"2018-01-23 18:49:29"},{"ledgerId":221, "eventType":"DEBIT", "amount":"22667.38", "closingBalance":"645884.38", "particulars":"VENDOR_PAYOUT", "remarks":"Vendor: VEN345", "addedOn":"2018-01-23 18:49:29"}], "lastId":221}