Developer documentation

Refund a payment

Last updated:

The refundPayment method reverses a previously settled payment, in full or in part. Refunds are server-to-server only — never expose the secret key to client-side code.

When you can refund

  • The payment must be in paid status. Pending or failed payments cannot be refunded.
  • One refund per payment. After a partial refund is issued, that payment can no longer be refunded again — the remaining amount stays with the customer's order.
  • The refund window depends on the payment method (typically 180 days for cards, shorter for some VA and QRIS rails). The cabinet rejects refunds outside the window.

Endpoint

Send a request to https://api.unitpay.net/api. POST over TLS is recommended for production traffic; GET is accepted for compatibility but exposes the secret key in URL logs and proxy buffers — do not use it.

Required parameters

ParameterTypeDescription
methodstringAlways refundPayment.
params[paymentId]integerUnitPay payment identifier returned by initPayment and echoed in callbacks as unitpayId.
params[secretKey]stringProject secret key. Send it only over TLS in a POST body, never in a GET query string.

Optional parameters

ParameterTypeDescription
params[sum]numberRefund amount in major currency units. Omit for a full refund. Must be less than or equal to the original payment sum.

Example request

POST https://api.unitpay.net/api
Content-Type: application/x-www-form-urlencoded

method=refundPayment
&params[paymentId]=1234512345
&params[secretKey]=<your-project-secret-key>
&params[sum]=50000.00

The example above issues a partial refund of IDR 50,000 against payment 1234512345. Omitting params[sum] would refund the full original amount.

Successful response

{
  "result": {
    "message": "Refund issued."
  }
}

UnitPay returns HTTP 200 once the refund is queued. Funds reach the customer within the timeframe of the underlying payment rail (cards: same business day to several business days; QRIS and VA: typically faster). The refund also flows back through your callback handler as a balance adjustment, so you can reconcile by listening to those events.

Error response

{
  "error": {
    "message": "Invalid secretKey.",
    "code": -32000
  }
}

Common causes:

codeMeaning
-32000Invalid secret key. Rotate from Settings → Project → Secret key and update your application secret store.
-32001Payment not found. Verify the paymentId matches a payment on the project that owns the secret key.
-32002Payment not in a refundable state — pending, failed, or already refunded.
-32003Refund amount exceeds the original payment sum or the remaining refundable balance.
-32004Refund window expired for this payment method.

Treat any error response as a hard failure: do not retry the same request blindly. Investigate, fix the input, and resubmit.

Important restrictions

  • One refund per payment. If you issue a partial refund and later need to refund more, that is not supported — size partial refunds carefully.
  • No client-side duplicate suppression. Two near-simultaneous partial refunds for the same amount on the same payment are not blocked by the API. Add idempotency on your side: keep the refund request behind a database-locked operation that records "refund attempted" before calling UnitPay, and never retry without first checking the recorded outcome.
  • Test mode. Test-mode payments use the test secret key and a separate refundPayment sandbox; refunds in test mode never move real funds. Validate your refund flow in test mode before enabling live refunds.

Refunds via the merchant cabinet

Operators can also issue refunds without writing code: open Statistics → Payment details for the payment in the merchant cabinet and click Issue refund. The cabinet wraps the same API call and is the recommended path for one-off, manually-approved refunds (chargebacks, disputed orders, customer-service exceptions).

Next steps