Create a refund

Initiates a refund for a successful payment.

Provider behaviour:

• Khalti — refund is processed immediately via the Khalti API. The response status will be succeeded on success or failed if Khalti rejects it.
• eSewa — eSewa does not expose a public refund API. The refund is recorded with status requires_action. You must process it manually through the eSewa merchant portal and the record will serve as your audit trail.

Partial refunds: You can issue multiple partial refunds against a single payment as long as the total does not exceed the original payment amount.

POST /v1/refunds

curl

cURL

curl -X POST https://api.paybridgenp.com/v1/refunds \
  -H "Authorization: Bearer pk_sandbox_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentId": "pay_01j9x2k3m4n5p6q7r8s9t0u1v2",
    "amount": 10000,
    "reason": "customer_request",
    "notes": "Customer requested refund"
  }'

201

{
  "id": "ref_01j9x2k3m4n5p6q7r8s9t0u1v2",
  "livemode": true,
  "paymentId": "pay_01j9x2k3m4n5p6q7r8s9t0u1v2",
  "projectId": "<string>",
  "mode": "sandbox",
  "amount": 10000,
  "currency": "NPR",
  "reason": "customer_request",
  "status": "processing",
  "providerRefundId": "<string>",
  "failureReason": "<string>",
  "notes": "<string>",
  "mobileNumber": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization · string · header · required

Your PayBridge API key. Obtain one from the dashboard under Settings → API Keys. Prefix: pk_sandbox_ for testing, pk_live_ for production.

Body

application/json

paymentId · string · required

ID of the payment to refund (prefix: pay_).

Example:

"pay_01j9x2k3m4n5p6q7r8s9t0u1v2"

amount · integer · required

Amount to refund in paisa. Must be ≤ the remaining refundable amount.

Example:

10000

reason · enum<string> · required

Reason for the refund.

Available options: customer_request, duplicate, fraudulent, other

Example:

"customer_request"

notes · string

Internal note visible in the dashboard. Not shown to customers.

Example:

"Customer contacted support, order not delivered."

mobileNumber · string

Customer mobile number. Required by some Khalti configurations.

Example:

"9801234567"

Response

201

application/json

Refund created.

id · string

Example:

"ref_01j9x2k3m4n5p6q7r8s9t0u1v2"

livemode · boolean

true when created with a live key, false for sandbox.

paymentId · string

Example:

"pay_01j9x2k3m4n5p6q7r8s9t0u1v2"

projectId · string

mode · enum<string>

Available options: sandbox, live

amount · integer

Refunded amount in paisa.

Example:

10000

currency · string

Example:

"NPR"

reason · enum<string>

Available options: customer_request, duplicate, fraudulent, other

status · enum<string>

succeeded — refund processed. requires_action — eSewa: must be processed manually via merchant portal. failed — provider rejected the refund.

Available options: processing, succeeded, failed, requires_action

providerRefundId · string | null

Provider's refund reference (Khalti only).

failureReason · string | null

Set when status is failed or requires_action.

notes · string | null

mobileNumber · string | null

createdAt · string<date-time>

updatedAt · string<date-time>