HTP Developer

Payments

Refunds

Refund all or part of a paid payment from your developer wallet.

http
POST /open/v1/payments/{payment_id}/refunds
Idempotency-Key: 7a1f3c9e0b2d4e6f
json
{
  "out_refund_no": "R20261107-0001",
  "amount": "15.00",
  "reason": "Customer cancelled"
}
Field Required Notes
out_refund_no ✓ Your refund number, [A-Za-z0-9_-]{1,64}, unique per environment
amount ✓ Up to amount − refunded_amount of the payment
reason Max 255, shown in the order

Behaviour

  • Only PAID payments can be refunded (REFUND_NOT_ALLOWED otherwise).
  • The refund completes synchronously: the response has status: "SUCCEEDED". The amount moves back to the original payer.
  • The full refund amount is debited from your wallet; the fee is not returned. If your balance is too low you get INSUFFICIENT_BALANCE.
  • You can refund several times (partial refunds) until refunded_amount equals amount (REFUND_AMOUNT_EXCEEDED beyond that).
  • The refund is a separate order: order_type: "REFUND", parent_id = the payment id. A payment.refunded callback is also sent.
  • The payment stays PAID; its refunded_amount increases.
json
{
  "id": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
  "out_order_no": "R20261107-0001",
  "order_type": "REFUND",
  "parent_id": "0b7a9c62-3f1e-4a2b-9d6c-5e4f3a2b1c0d",
  "status": "SUCCEEDED",
  "amount": "15.00",
  "fee_amount": "0.00",
  "net_amount": "15.00",
  "currency": "USDT",
  "user_sub": "2f6c0d1e8a9b4c7d",
  "completed_at": "2026-11-07T10:00:00Z",
  "…": "…"
}

Recovering from timeouts

If the refund request times out, retry with the same Idempotency-Key and body, or look it up:

http
GET /open/v1/orders?out_order_no=R20261107-0001&order_type=REFUND

ORDER_NOT_FOUND means it was not created; retry safely.

← PreviousCallbacksNext →Payouts