Create Account

Split Vendor Payments

Suggest Edits

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 Vendors
  2. Create Order
  3. Accept Payment
  4. Split Payment
  5. Settle Payments to Vendors
  6. Manage Refunds
  7. Manage Adjustments
  8. Get Notified about your settlements and vendor settlements.

Add Vendors

To initiate payments to multiple parties 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.

📘

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": "john@vpa",
        "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": "arun@okicici"
          }
     },
     "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"
}

Defer Settlement Time

You can add delay at:

  • Overall order level delay
  • Specific order and vendor level delay

Overall Order Level Delay

You can defer overall order settlements to your vendors by increasing the order split delay. By default, we support a split delay of t+2 days (after successful payments) within which you have to specify the split details with vendor ID to process settlements to your vendors.

If you want to further increase the order split delay for your orders, contact [email protected] or your account manager.

Specific Order and Vendor Level Delay

To delay settlements for a particular order and a specific vendor for an order, you use the Vendor Settlement Eligibility Date for Orders - https://api.cashfree.com/api/v2/easy-split/orders/{orderId}/settlement-eligibility/vendors/{vendorId} API and specify the vendor ID, order ID, and settlement eligibility date to process the settlement.

settlementEligibiltyDate is the date before which the settlements will not be processed to the vendor for a specific order provided in the request.

Sample Request


curl --location --request PUT 'https://api.cashfree.com/api/v2/easy-split/orders/{{orderid}}/settlement-eligibility/vendors/{{vendorid}}
' \
--header 'X-Client-Id: {{clientId}}' \
--header 'X-Client-Secret: {{secretKey}}' \
--header 'Content-Type: application/json' \
{
    "settlementEligibilityDate": "2022-05-24 08:13:00"
}

Sample Response


{
    "status": "OK",
    "subCode": "200",
    "message": "Updated vendor settlement eligibility date."
}

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.

Updated about 1 year ago