Steps in Split Vendor Payments

To split payments to your vendors using Easy Split, you must first ensure the feature activated for your Payment Gateway account. Write to [email protected] or contact your Account manager to enable it for you. The feature should be activated for your Test and Production environment.

To split payments to vendors,

  1. Add Vendor
  2. Create Order
  3. Accept Payment
  4. Split Payment
  5. View Split Settlement Details
  6. Manage Refunds
  7. Manage Adjustments
  8. Get Notified about your settlements and vendor settlements.

Add Vendors

To initiate payments to multiple vendors involved in a transaction, you need to first add their details, and specify the settlement cycle details for each vendor. Each vendor can have different settlement cycle based on their requirements. You must define it when you add the vendor details.

You can add vendor details using the product dashboard, or using our Add Vendor API - https://api.cashfree.com/api/v2/easy-split/vendors.

To process settlements to vendors, you must specify their bank account details or their UPI details. Read more on adding vendors.

📘

Ensure you have the right account details of the vendor to process settlements successfully. You can use our Verification Suite to verify the vendor account details before initiating settlements.

You can also edit and manage vendors using our Update Merchant Vendor API - https://api.cashfree.com/api/v2/easy-split/vendors/{vendorId}.

Sample Request to Add Vendor


curl --location --request POST 'https://api.cashfree.com/api/v2/easy-split/vendors' \
--header 'x-client-id: {{clientId}}' \
--header 'x-client-secret: {{clientKey}}' \
--header 'Content-Type: application/json' \
--data-raw '
{
    "email": "[email protected]",
    "status": "ACTIVE",
    "upi": {
        "vpa": "[email protected]",
        "accountHolder": "merchantVendorId1"
    },
    "phone": "9999900000",
    "name": "merchantVendorId1",
    "id": "merchantVendorId123",
    "settlementCycleId": 1
}

Sample Response


{
  "message": "Vendor is added successfully",
  "status": "OK"
}

Create Order

After adding vendors you must create an order to accept payments from your customers. Use our Create Order API - https://api.cashfree.com/pg/orders to do this.

Sample Request


curl --request POST \
--url https://api.cashfree.com/pg/orders \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'x-client-id: {{clientId}}' \
--header 'x-client-secret: {{clientKey}}' \
--header 'x-api-version: 2022-01-01' \
--data '
{
     "customer_details": 
     {
          "customer_id": "7112AAA812234",
          "customer_email": "[email protected]",
          "customer_phone": "9908734801",
          "customer_bank_account_number": "1518121112",
          "customer_bank_ifsc": "CITI0000001",
          "customer_bank_code": 3333
     },
     "order_id": "ES_TEST1",
     "order_amount": 10.15,
     "order_currency": "INR",
     "order_expiry_time": "2022-05-29T00:00:00Z",
     "order_note": "Test order"
}'

Sample Response


{
    "cf_order_id": 1072946546,
    "order_id": "ES_TEST1",
    "entity": "order",
    "order_currency": "INR",
    "order_amount": 10.15,
    "order_expiry_time": "2022-05-29T05:30:00+05:30",
    "customer_details": {
        "customer_id": "7112AAA812234",
        "customer_name": null,
        "customer_email": "[email protected]",
        "customer_phone": "9908734801"
    },
    "order_meta": {
        "return_url": null,
        "notify_url": null,
        "payment_methods": null
    },
    "settlements": {
        "url": "https://api.cashfree.com/pg/orders/ES_TEST1/settlements"
    },
    "payments": {
        "url": "https://api.cashfree.com/pg/orders/ES_TEST1/payments"
    },
    "refunds": {
        "url": "https://api.cashfree.com/pg/orders/ES_TEST1/refunds"
    },
    "order_status": "ACTIVE",
    "order_token": "tScwuwzJgZ0PJuVciw1b",
    "order_note": "Test order",
    "payment_link": "https://payments.cashfree.com/order/#tScwuwzJgZ0PJuVciw1b",
    "order_tags": null,
    "order_splits": []
}

Accept Payments

After orders are created you must use our Order Pay - https://api.cashfree.com/pg/orders/pay API to accept payments from your customers.

Sample Request


curl --request POST \
     --url https://api.cashfree.com/pg/orders/pay \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'x-api-version: 2022-01-01' \
     --data '
{
     "payment_method": {
          "upi": {
               "channel": "collect",
               "upi_id": "[email protected]"
          }
     },
     "order_token": "tScwuzJgZ0PJuVc1b"
}

Sample Response


{
    "payment_method": "upi",
    "channel": "collect",
    "action": "custom",
    "data": {
        "url": null,
        "payload": null,
        "content_type": null,
        "method": null
    },
    "cf_payment_id": 971632209
}

Split Payment

Before you split the details, ensure vendors involved in the transaction are added. After adding the vendor details you can initiate payment split to your vendors. To split the payment use Split after Payment API - https://api.cashfree.com/api/v2/easy-split/orders/{orderId}/split.

You have the option to specify the split percentage-wise or amount-wise. The split amount is always calculated based on the order amount.

Sample Request - Split details after collecting the payment


curl --location --request POST 'https://api.cashfree.com/api/v2/easy-split/orders/{{orderId}}/split' \
--header 'X-Client-Id: {{clientId}}' \
--header 'X-Client-Secret: {{secretKey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "split": [
        {
            "vendorId": "merchantVendorId123",
            "amount": 5.15,
            "percentage": null
        },
        {
            "vendorId": "merchantVendorId321",
            "amount": 5.00,
            "percentage": null
        }
    ],
    "splitType": "ORDER_AMOUNT"
}

Sample Response


{
  "status": "OK",
  "message": "Order split created"
}

Split Settlements Scenarios

Scenario 1: Split After Payment Success

The flow diagram below shows how a split happens if the payment is successful. It is a two step process.

12001200

Split After Payment Success

First Step: Customer completes the payment

  • Step 1: The customer visits the merchant website or the application and adds goods from different vendors to the shopping cart. The customer proceeds to complete the payment.
  • Step 1.1: The merchant receives the payment request from the customer and creates an order. The order details contain information such as order ID, order amount, and customer name. The merchant creates an order in the Cashfree Payment system.
  • Step 1.2: Cashfree Payment Gateway receives the order details and creates a payment link for that order. This payment link is sent to the merchant.
  • Step 1.3: The merchant receives the payment link and sends it to the customer to complete the payment.
  • Step 1.4: The customer clicks the link and completes the payment. The amount is received by Cashfree Payment Gateway.
  • Step 1.5: The merchant sends the payment details, and it is captured at Cashfree Payment Gateway end.
  • Step 1.6: The payment details are stored in the Cashfree system and the payment status is sent to the merchant through payment webhooks.
  • Step 1.7: The merchant notifies the payment status to the customer.

Second Step: Easy Split processes the split

  • Step 2: Once the payment is successful, the payment success webhook is triggered. The merchant shares the split details that contain the split information via the Split API to Cashfree Payment Gateway.
  • Step 2.1: The split is created in the Cashfree system, and Easy Split processes the split based on the split information received from the merchant. The split information has details such as vendor ID, split type, and the amount or percentage to be split with the merchant and vendors.
  • Step 2.2: Easy Split processes the vendor split amount first. The amount is settled to the vendor bank account based on the vendor settlement cycle. The vendor settlement webhook is initiated.
  • Step 2.3: Easy Split processes the merchant split amount and settles the amount to the merchant bank account based on the merchant settlement cycle. The merchant settlement webhook is initiated.

Scenario 2: Split After Payment Success

The flow diagram below shows how a split happens when an order is created irrespective of the payment status. It is a two step process.

12001200

Split During Order Creation

First Step: Customer completes the payment

  • Step 1: Customer visits the merchant website or the application and adds goods from different vendors to the shopping cart. The customer proceeds to complete the payment.
  • Step 1.1: The merchant receives the payment request from the customer and creates an order. The order details contain split details such as order ID, order amount, and customer name. The merchant creates an order in the Cashfree Payment system.
  • Step 1.2: Cashfree Payment Gateway receives the order details and creates a payment link for that order. This payment link is sent bck to the merchant.
  • Step 1.3: The merchant receives the payment link and sends it to the customer to complete the payment.
  • Step 1.4: The customer clicks the link and completes the payment. The amount is received by Cashfree Payment Gateway.
  • Step 1.5: The payment details are stored in the Cashfree system, and the payment status is sent to the merchant through payment webhooks. Easy Split initiates the split irrespective of the payment status.
  • Step 1.6: Cashfree Payments captures the payment details, and the payment status is shared to the merchant through payment webhooks.
  • Step 1.7: The merchant sends the payment status to the customer.

Second Step: Easy Split processes the split irrespective of the payment status

  • Step 2: Once the payment is initiated, internal split calls take place. The amount is split based on the split information the merchant provides.
  • Step 2.1: Easy Split processes the vendor split amount first and settles the amount to the vendor bank account based on the vendor settlement cycle. The vendor settlement webhook is initiated.
  • Step 2.2: Easy Split processes the merchant split amount and settles the amount to the merchant bank account based on the merchant settlement cycle. The merchant settlement webhook is initiated.

Defer Settlement Time

You can add delay at:


View Split Settlement Details

Settlements will be processed to vendors based on the settlement cycle defined for each vendor during vendor creation. The applicable service charges for the order - PG serviceCharge, PG serviceTax, splitServiceCharge, and splitServiceTax will be shown in the response.

Use the Settlement Details - https://api.cashfree.com/api/v2/easy-split/orders/{orderId} API to view the settlements received.

Sample Response


{
    "message": "Order settlement details",
    "status": "OK",
    "vendors": [
        {
            "id": "merchantVendorId123",
            "settlementId": 0,
            "settlementAmount": 5.15,
            "settlementEligibilityDate": "2022-05-24 16:33:28"
        },
        {
            "id": "merchantVendorId321",
            "settlementId": 0,
            "settlementAmount": 5,
            "settlementEligibilityDate": "2022-05-24 16:33:28"
        }
    ],
    "orderAmount": 10.15,
    "orderSplit": [
        {
            "vendorId": "merchantVendorId123",
            "amount": 5.15
        },
        {
            "vendorId": "merchantVendorId321",
            "amount": 5
        }
    ],
    "serviceCharge": 0,
    "serviceTax": 0,
    "splitServiceCharge": 0.01,
    "splitServiceTax": 0,
    "settlementAmount": -0.01,
    "settlementEligibilityDate": "2022-05-23 16:43:25"
}

Manage Refunds

To initiate partial or full refunds to your customers you can use our Create Refund - https://api.cashfree.com/pg/orders/{order_id}/refunds API.

Sample Request


curl --request POST \
     --url https://api.cashfree.com/pg/orders/order_id/refunds \
     --header 'Accept: application/json' \
     --header 'X-Client-Id: {{clientId}}' \
     --header 'X-Client-Secret: {{secretKey}}' \
     --header 'Content-Type: application/json' \
     --header 'x-api-version: 2022-01-01'
{
     "refund_splits": [
          {
               "vendor_id": "merchantVendorId123",
               "amount": 5.15
          }
     ],
     "refund_amount": 5.15,
     "refund_id": "TestRefundX12356"
}

Sample Response


{
    "cf_payment_id": 971612209,
    "cf_refund_id": "refund_13583383",
    "created_at": "2022-05-23T16:47:05+05:30",
    "entity": "refund",
    "metadata": null,
    "order_id": "ES_TEST1",
    "processed_at": null,
    "refund_amount": 5.15,
    "refund_arn": null,
    "refund_charge": 0.00,
    "refund_currency": "INR",
    "refund_id": "TestRefundX12356",
    "refund_mode": "STANDARD",
    "refund_note": null,
    "refund_splits": [
        {
            "vendor_id": "merchantVendorId123",
            "amount": 5.15
        }
    ],
    "refund_status": "PENDING",
    "refund_type": "MERCHANT_INITIATED",
    "status_description": "In Progress"
}

Transfer Balance

To manage any adjustments with your vendors you can use our Transfer Vendor Balance - https://api.cashfree.com/api/v2/easy-split/vendors/{vendorId}/adjustment API.

Sample Request


  curl -X POST \
  https://api.cashfree.com/api/v2/easy-split/vendors/{{vendorId}}/adjustment \
  -H 'content-type: application/json' \
  -H 'x-client-id: {{clientId}}' \
  -H 'x-client-secret: {{clientKey}}' \
  -d '{
{
  "adjustmentId":"30021067",
  "amount": 5.00,
  "type":"DEBIT",
  "remarks":"transfer"
}

Sample Response


{
    "status": "OK",
    "subCode": "200",
    "message": "Vendor and merchant balances updated"
}

Get Notified via Webhooks

You can receive automatic updates about settlements made to you and your vendor by configuring the webhooks. Click here to know how to configure webhooks.

Webhooks supported for vendors settlements:

You can also receive updates about your settlements with Cashfree Payments.