Mark as Settled (Sandbox)

Mark payments as settled (sandbox)

curl --request POST \
  --url https://api-pacb-uat.eximpe.com/pg/settlements/mark-settled/ \
  --header 'Content-Type: application/json' \
  --header 'X-API-Version: <api-key>' \
  --header 'X-Client-ID: <api-key>' \
  --header 'X-Client-Secret: <api-key>' \
  --header 'X-Merchant-ID: <api-key>' \
  --data '
{
  "payment_uids": [
    "PR1234567890",
    "PR1234567891"
  ],
  "refund_uids": [
    "RF9876543210"
  ],
  "chargeback_uids": [
    "CB5555555555"
  ]
}
'

import requests

url = "https://api-pacb-uat.eximpe.com/pg/settlements/mark-settled/"

payload = {
    "payment_uids": ["PR1234567890", "PR1234567891"],
    "refund_uids": ["RF9876543210"],
    "chargeback_uids": ["CB5555555555"]
}
headers = {
    "X-Client-ID": "<api-key>",
    "X-Client-Secret": "<api-key>",
    "X-Merchant-ID": "<api-key>",
    "X-API-Version": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Client-ID': '<api-key>',
    'X-Client-Secret': '<api-key>',
    'X-Merchant-ID': '<api-key>',
    'X-API-Version': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    payment_uids: ['PR1234567890', 'PR1234567891'],
    refund_uids: ['RF9876543210'],
    chargeback_uids: ['CB5555555555']
  })
};

fetch('https://api-pacb-uat.eximpe.com/pg/settlements/mark-settled/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-pacb-uat.eximpe.com/pg/settlements/mark-settled/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'payment_uids' => [
        'PR1234567890',
        'PR1234567891'
    ],
    'refund_uids' => [
        'RF9876543210'
    ],
    'chargeback_uids' => [
        'CB5555555555'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Version: <api-key>",
    "X-Client-ID: <api-key>",
    "X-Client-Secret: <api-key>",
    "X-Merchant-ID: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-pacb-uat.eximpe.com/pg/settlements/mark-settled/"

	payload := strings.NewReader("{\n  \"payment_uids\": [\n    \"PR1234567890\",\n    \"PR1234567891\"\n  ],\n  \"refund_uids\": [\n    \"RF9876543210\"\n  ],\n  \"chargeback_uids\": [\n    \"CB5555555555\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Client-ID", "<api-key>")
	req.Header.Add("X-Client-Secret", "<api-key>")
	req.Header.Add("X-Merchant-ID", "<api-key>")
	req.Header.Add("X-API-Version", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-pacb-uat.eximpe.com/pg/settlements/mark-settled/")
  .header("X-Client-ID", "<api-key>")
  .header("X-Client-Secret", "<api-key>")
  .header("X-Merchant-ID", "<api-key>")
  .header("X-API-Version", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"payment_uids\": [\n    \"PR1234567890\",\n    \"PR1234567891\"\n  ],\n  \"refund_uids\": [\n    \"RF9876543210\"\n  ],\n  \"chargeback_uids\": [\n    \"CB5555555555\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-pacb-uat.eximpe.com/pg/settlements/mark-settled/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Client-ID"] = '<api-key>'
request["X-Client-Secret"] = '<api-key>'
request["X-Merchant-ID"] = '<api-key>'
request["X-API-Version"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"payment_uids\": [\n    \"PR1234567890\",\n    \"PR1234567891\"\n  ],\n  \"refund_uids\": [\n    \"RF9876543210\"\n  ],\n  \"chargeback_uids\": [\n    \"CB5555555555\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "Payments marked as settled successfully",
  "data": {
    "settlement_id": "ST7362075798",
    "utr_number": "bb6708d5-367f-4ff4-baea-2743a7e649a3",
    "settlement_completed_at": "2026-08-12T11:32:50.432063Z",
    "forex_rate": "96",
    "settlement_amount": "791.00",
    "settlement_charges": "50.00",
    "settlement_gst": "9.00"
  }
}

{
  "success": false,
  "error": {
    "code": "ERR_SERVICE_ERROR_000",
    "message": "Payment gateway error",
    "details": {
      "payment_uids": "PR4673100896 is not on the simulator gateway"
    }
  }
}

{
  "success": true,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

POST

settlements

mark-settled

Mark payments as settled (sandbox)

curl --request POST \
  --url https://api-pacb-uat.eximpe.com/pg/settlements/mark-settled/ \
  --header 'Content-Type: application/json' \
  --header 'X-API-Version: <api-key>' \
  --header 'X-Client-ID: <api-key>' \
  --header 'X-Client-Secret: <api-key>' \
  --header 'X-Merchant-ID: <api-key>' \
  --data '
{
  "payment_uids": [
    "PR1234567890",
    "PR1234567891"
  ],
  "refund_uids": [
    "RF9876543210"
  ],
  "chargeback_uids": [
    "CB5555555555"
  ]
}
'

import requests

url = "https://api-pacb-uat.eximpe.com/pg/settlements/mark-settled/"

payload = {
    "payment_uids": ["PR1234567890", "PR1234567891"],
    "refund_uids": ["RF9876543210"],
    "chargeback_uids": ["CB5555555555"]
}
headers = {
    "X-Client-ID": "<api-key>",
    "X-Client-Secret": "<api-key>",
    "X-Merchant-ID": "<api-key>",
    "X-API-Version": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Client-ID': '<api-key>',
    'X-Client-Secret': '<api-key>',
    'X-Merchant-ID': '<api-key>',
    'X-API-Version': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    payment_uids: ['PR1234567890', 'PR1234567891'],
    refund_uids: ['RF9876543210'],
    chargeback_uids: ['CB5555555555']
  })
};

fetch('https://api-pacb-uat.eximpe.com/pg/settlements/mark-settled/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-pacb-uat.eximpe.com/pg/settlements/mark-settled/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'payment_uids' => [
        'PR1234567890',
        'PR1234567891'
    ],
    'refund_uids' => [
        'RF9876543210'
    ],
    'chargeback_uids' => [
        'CB5555555555'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Version: <api-key>",
    "X-Client-ID: <api-key>",
    "X-Client-Secret: <api-key>",
    "X-Merchant-ID: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-pacb-uat.eximpe.com/pg/settlements/mark-settled/"

	payload := strings.NewReader("{\n  \"payment_uids\": [\n    \"PR1234567890\",\n    \"PR1234567891\"\n  ],\n  \"refund_uids\": [\n    \"RF9876543210\"\n  ],\n  \"chargeback_uids\": [\n    \"CB5555555555\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Client-ID", "<api-key>")
	req.Header.Add("X-Client-Secret", "<api-key>")
	req.Header.Add("X-Merchant-ID", "<api-key>")
	req.Header.Add("X-API-Version", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-pacb-uat.eximpe.com/pg/settlements/mark-settled/")
  .header("X-Client-ID", "<api-key>")
  .header("X-Client-Secret", "<api-key>")
  .header("X-Merchant-ID", "<api-key>")
  .header("X-API-Version", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"payment_uids\": [\n    \"PR1234567890\",\n    \"PR1234567891\"\n  ],\n  \"refund_uids\": [\n    \"RF9876543210\"\n  ],\n  \"chargeback_uids\": [\n    \"CB5555555555\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-pacb-uat.eximpe.com/pg/settlements/mark-settled/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Client-ID"] = '<api-key>'
request["X-Client-Secret"] = '<api-key>'
request["X-Merchant-ID"] = '<api-key>'
request["X-API-Version"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"payment_uids\": [\n    \"PR1234567890\",\n    \"PR1234567891\"\n  ],\n  \"refund_uids\": [\n    \"RF9876543210\"\n  ],\n  \"chargeback_uids\": [\n    \"CB5555555555\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "Payments marked as settled successfully",
  "data": {
    "settlement_id": "ST7362075798",
    "utr_number": "bb6708d5-367f-4ff4-baea-2743a7e649a3",
    "settlement_completed_at": "2026-08-12T11:32:50.432063Z",
    "forex_rate": "96",
    "settlement_amount": "791.00",
    "settlement_charges": "50.00",
    "settlement_gst": "9.00"
  }
}

{
  "success": false,
  "error": {
    "code": "ERR_SERVICE_ERROR_000",
    "message": "Payment gateway error",
    "details": {
      "payment_uids": "PR4673100896 is not on the simulator gateway"
    }
  }
}

{
  "success": true,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

Sandbox only. This endpoint returns 400 in production. It operates only on transactions created through the Simulator payment gateway — a real Cashfree or ICICI transaction is rejected.Your account must be assigned the Simulator gateway in sandbox. Contact your EximPe integration manager if it isn’t.

Overview

Settlement is the one part of the payment lifecycle you cannot trigger yourself: it happens when money actually moves, on the bank’s schedule. That makes settlement webhook handlers and reconciliation logic awkward to test. This endpoint settles payments on demand. It applies a simulated fee schedule, creates a real settlement record, and fires PAYMENT_SETTLED exactly as production would.

How the amounts are calculated

Per payment, against the order amount:

Component	Rule
Platform fee	5% of the order amount
GST	18% of the platform fee
Net	order amount − platform fee − GST
Forex rate	Fixed at `96`

The settlement totals are the sums across the batch:

settlement_amount = Σ payment net − Σ refund amounts − Σ chargeback amounts
settlement_charges = Σ platform fees
settlement_gst = Σ GST

Refunds and chargebacks carry no fee of their own. They debit the total at their full amount, mirroring the real settlement pipeline.

Worked example — ₹1,000 payment, ₹100 refund, ₹50 chargeback

Payment order amount        ₹1,000.00
  platform fee (5%)         −  ₹50.00
  GST (18% of fee)          −   ₹9.00
  net                       =  ₹941.00

Refund                      − ₹100.00
Chargeback                  −  ₹50.00
                            ──────────
settlement_amount           =  ₹791.00
settlement_charges          =   ₹50.00
settlement_gst              =    ₹9.00

These are simulator figures, not your contracted rates. Use them to check that your reconciliation arithmetic holds, not to predict production settlement amounts.

Side effects

Each payment in the batch gets settlement_status = SETTLED and its per-payment breakdown populated — fee, tax, net, forex rate, settlement currency — in the same shape a real settlement produces.

The batch is atomic. If any payment fails validation nothing is written, so a partially-settled batch is not a state you can reach.

What each payment must satisfy

A payment is rejected unless it is:

Yours — belonging to your merchant account or one of your sub-merchants
On the Simulator gateway
CAPTURED
Not already settled — a payment belongs to exactly one settlement

A UID owned by a different merchant is indistinguishable from one that does not exist. Both simply fail to resolve.

Reading validation errors

Unresolvable UIDs come back grouped by category, with the first failure in each. Empty categories return [].

{
  "success": false,
  "error": {
    "code": "ERR_SERVICE_ERROR_000",
    "message": "Payment gateway error",
    "details": {
      "payment_uids": "PR0000000000",
      "refund_uids": [],
      "chargeback_uids": []
    }
  }
}

Because only the first failure per category is reported, fix them one at a time or pre-validate your list. State problems name the offending UID directly:

`details.payment_uids`	Meaning
`PR… is not on the simulator gateway`	Created on a real gateway
`PR… is not captured`	Payment has not succeeded
`PR… is already settled`	Belongs to another settlement — create a fresh payment

Testing your settlement handler

Capture a payment

Create an order and complete it on the Simulator gateway so the payment reaches CAPTURED.

Settle it

POST /pg/settlements/mark-settled/ with that payment’s UID.

Receive the webhook

Your endpoint gets PAYMENT_SETTLED carrying the new settlement.

Reconcile

GET /pg/settlements/{settlement_id}/ and check your records agree.

To exercise a net settlement, create a refund and a chargeback against the payment first, then pass all three UIDs in one call and confirm settlement_amount equals the payment net minus both.

Gotchas

Amounts are strings in rupees, not integer paise

"941.00", not 94100. Parse as decimal — never as a float, for money.

A payment can be settled only once

Re-settling returns is already settled. Create a fresh payment for each settlement test.

settlement_charges and settlement_gst cover payments only

Refunds and chargebacks carry no fee. They only reduce settlement_amount.

It is a POST, despite reading like a bulk update

Both simulator endpoints are POST.

Set Refund Status

Drive a refund to any status on demand.

PAYMENT_SETTLED

The event this endpoint fires.

Authorizations

X-Client-ID

string

header

required

Client Application ID - Your unique application identifier used to authenticate API requests. You can find your Client ID in the Developer Settings section of the merchant dashboard.

X-Client-Secret

string

header

required

Client Secret Key - Your secret key used alongside the Client ID for secure authentication. Keep this confidential and never expose it in client-side code. Available in the Developer Settings section of the merchant dashboard.

X-Merchant-ID

string

header

required

Merchant Identifier - The unique ID for the merchant account. This is required for PSP (Payment Service Provider) merchants who manage multiple merchant accounts. You can find merchant IDs in the Merchant Management section of the dashboard.

X-API-Version

string

header

required

API Version - Specifies which version of the API to use (e.g., '1.X.X', '2.X.X', or '3.X.X'). This header allows you to control which API version your integration uses. Default version information is available in the Developer Settings.

Body

application/json

payment_uids

string[]

required

Payments to settle. Each must be CAPTURED, on the Simulator gateway, yours, and not already settled.

Minimum array length: 1

Example:

["PR1234567890", "PR1234567891"]

refund_uids

string[]

Refunds to fold into the same settlement. Each debits the total at its full amount and carries no fee of its own.

Example:

["RF9876543210"]

chargeback_uids

string[]

Chargebacks to fold in. Same treatment as refunds.

Example:

["CB5555555555"]

Response

Settlement created and the payments marked settled.

success

boolean

Example:

true

message

string

Example:

"Payments marked as settled successfully"

data

object

Show child attributes

Order

Payment

Merchant

Settlement

Refund

Virtual Bank Accounts

LRS

Webhooks

Mark as Settled (Sandbox)

Overview

How the amounts are calculated

Side effects

What each payment must satisfy

Reading validation errors

Testing your settlement handler

Gotchas

Set Refund Status

PAYMENT_SETTLED

Authorizations

Body

Response

​Overview

​How the amounts are calculated

​Side effects

​What each payment must satisfy

​Reading validation errors

​Testing your settlement handler

​Gotchas

​Related

Set Refund Status

PAYMENT_SETTLED

Authorizations

Body

Response

Overview

How the amounts are calculated

Side effects

What each payment must satisfy

Reading validation errors

Testing your settlement handler

Gotchas

Related