Refund requests

The refund API starts and tracks monetary refunds owned by the payment service. It uses payment-row locking, cumulative partial-refund accounting, and a durable merchant c_id to prevent duplicate money movement.

Prerequisites: use refunds.create to request a refund, refunds.read to query it, and refunds.comment to add a merchant note. The referenced payment must belong to the same merchant and satisfy the API key’s actual currency and service policy.

Methods

Method	Scope	Purpose
`refund.request`	`refunds.create`	Request a full or partial monetary refund
`refund.get`	`refunds.read`	Read one request by exactly one `c_id` or `h_id`
`refund.list`	`refunds.read`	List requests with cursor pagination
`refund.summary`	`refunds.read`	Count requests by status
`refund.comment.create`	`refunds.comment`	Add a merchant-visible comment
`refund.comments.list`	`refunds.read`	List merchant-visible comments

Refund statuses are pending, approved, rejected, and processed.

Money contract

amount is a JSON string containing a positive integer in the payment currency’s minor units. Do not send a JSON number, decimal point, sign, currency, or thousands separators.

"5000" means 5,000 minor units.
Omitting amount requests the complete refundable remainder calculated at execution time.
Currency is resolved from the payment and cannot be overridden.
The requested amount cannot exceed the current payment remainder after all processed partial refunds.
The largest accepted value is 9223372036854775807, the PostgreSQL signed bigint limit.

Always keep refund money as integer strings. Values such as "9007199254740993" are valid but cannot be represented exactly by a JavaScript number; preserve the string through signing, storage, retries, webhook handling, and reconciliation.

Request a refund

Use a stable, merchant-generated params.identifiers.c_id. It is the durable creation idempotency key.

BODY='{"method":"refund.request","params":{"identifiers":{"c_id":"refund-order-8401-1"},"payment":{"c_id":"order-8401"},"amount":"5000","reason":"Duplicate customer payment","notes":"Refund the second capture only"}}'
SECRET='your_secret_key'
HASH=$(printf '%s%s' "$BODY" "$SECRET" | openssl dgst -sha512 -r | awk '{print $1}')
curl -X POST 'https://api.bafanglaicai88.com/public/api/multihub/v1' \
  -H 'Content-Type: application/json' -H 'X-Data-Application-Id: 1' \
  -H "X-Data-Hash: $HASH" -H "X-Data-Timestamp: $(date +%s)" \
  -H "X-Data-Nonce: $(uuidgen)" --data-binary "$BODY"

import hashlib, json, time, uuid, requests

payload = {"method": "refund.request", "params": {
    "identifiers": {"c_id": "refund-order-8401-1"},
    "payment": {"c_id": "order-8401"}, "amount": "5000",
    "reason": "Duplicate customer payment", "notes": "Refund the second capture only",
}}
body = json.dumps(payload, separators=(",", ":")); secret = "your_secret_key"
response = requests.post("https://api.bafanglaicai88.com/public/api/multihub/v1", data=body, headers={
    "Content-Type": "application/json", "X-Data-Application-Id": "1",
    "X-Data-Hash": hashlib.sha512((body + secret).encode()).hexdigest(),
    "X-Data-Timestamp": str(int(time.time())), "X-Data-Nonce": str(uuid.uuid4()),
}, timeout=30)
print(response.json())

import crypto from "node:crypto";

const payload = {
  method: "refund.request",
  params: {
    identifiers: { c_id: "refund-order-8401-1" },
    payment: { c_id: "order-8401" },
    amount: "5000",
    reason: "Duplicate customer payment",
    notes: "Refund the second capture only",
  },
};
const body = JSON.stringify(payload);
const secret = "your_secret_key";
const response = await fetch("https://api.bafanglaicai88.com/public/api/multihub/v1", {
  method: "POST",
  body,
  headers: {
    "Content-Type": "application/json",
    "X-Data-Application-Id": "1",
    "X-Data-Hash": crypto
      .createHash("sha512")
      .update(body + secret)
      .digest("hex"),
    "X-Data-Timestamp": String(Math.floor(Date.now() / 1000)),
    "X-Data-Nonce": crypto.randomUUID(),
  },
});
console.log(await response.json());

Example result:

{
  "success": true,
  "result": {
    "identifiers": {
      "c_id": "refund-order-8401-1",
      "h_id": "40776f5f-970c-439d-a936-92917802d0c0"
    },
    "payment": { "h_id": "3c3708bc-78d6-4bcb-b626-43dc9c05d0d6" },
    "status": "pending",
    "amount": "5000",
    "processed_amount": null,
    "currency": "INR",
    "reason": "Duplicate customer payment",
    "notes": "Refund the second capture only",
    "resolved_at": null,
    "created_at": "2026-07-15T10:00:00.000Z",
    "updated_at": "2026-07-15T10:00:00.000Z"
  },
  "request_id": "7a0bc676-1706-4f4d-be82-991a56340c8e",
  "processing_time": 29
}

Safe retries and partial refunds

If refund.request times out, retry the exact body with the same c_id, a fresh timestamp, and a fresh nonce. A committed request returns the same public refund result. Reusing that c_id with another amount, reason, notes, or payment returns code 1013. Only one active pending or approved request is allowed for a payment. After a partial request becomes processed, you may create another request with a new c_id; the available amount is calculated from the current cumulative remainder under a database lock. Do not create a new c_id while the status of a timed-out request is unknown. First query:

{
  "method": "refund.get",
  "params": { "identifiers": { "c_id": "refund-order-8401-1" } }
}

List and summarize

refund.list accepts statuses, one payment reference, created_from, created_to, limit, and an opaque cursor:

{
  "method": "refund.list",
  "params": {
    "statuses": ["pending", "approved"],
    "payment": { "c_id": "order-8401" },
    "limit": 25
  }
}

The response contains items and next_cursor, never a full total. Use refund.summary with optional ISO 8601 created_from/created_to to obtain by_status counts.

Refund comments

Refund comments are a separate merchant-visible conversation store. Adding a comment does not create or link a support ticket and does not approve or process the refund.

{
  "method": "refund.comment.create",
  "operation_id": "refund-order-8401-1-comment-1",
  "params": {
    "refund": { "c_id": "refund-order-8401-1" },
    "body": "The customer confirmed the destination account."
  }
}

Use refund.comments.list with the refund identifier, optional limit, and optional cursor. Returned comments contain a public comment h_id, author (merchant or support), body, and timestamps.

Error handling

Code	HTTP	Meaning	Recovery
`11001`	404	Refund or merchant-owned payment is not visible	Verify the identifier and credential
`11002`	409	Payment status is not refundable	Refresh payment status; do not retry unchanged
`11003`	400	Amount is zero, malformed, or above `9223372036854775807`	Send a positive digit-string within the signed `bigint` range
`11004`	409	Amount exceeds the locked current remainder	Query current refund history and submit a valid new operation
`11005`	409	A `pending` or `approved` request already exists	Query and finish the active request
`1013`	409	Existing `c_id` has another canonical payload	Recover the original request; never overwrite its meaning
`2002`	503	Refund dependency is unavailable	Retry with the same `c_id` and exact payload after backoff

Best practices

Generate refund c_id values on your server before the first attempt and persist them with the order.
Keep amounts as decimal digit strings at database, queue, and JSON boundaries, including values above JavaScript’s safe-integer limit.
Reconcile on both refund h_id and payment h_id; never use internal numeric IDs.
Treat processed_amount as an observed result, not permission to calculate a new refund without querying current state.

Getting Started

Guides

SDKs & Examples

Reference

Refund requests

Refund requests

Methods

Money contract

Request a refund

Safe retries and partial refunds

List and summarize

Refund comments

Error handling

Best practices

​Refund requests

​Methods

​Money contract

​Request a refund

​Safe retries and partial refunds

​List and summarize

​Refund comments

​Error handling

​Best practices

Refund requests

Methods

Money contract

Request a refund

Safe retries and partial refunds

List and summarize

Refund comments

Error handling

Best practices