Refunds

Refund a full or partial charge — from the dashboard or with the API.

Refunds

Refunds can be issued through the Dashboard → Transactions → Refund action or with the public API.

Endpoints

Method Path Scope Purpose
POST /v1/refunds refunds:write Issue a full or partial refund.
GET /v1/refunds?charge=ch_… refunds:read List refunds for one charge (payment_intent= also accepted).
GET /v1/refunds/{id} refunds:read Retrieve a single refund.

Listing requires a charge or payment_intent filter — refunds are always scoped to a charge that belongs to your account.

How it works

  1. Merchant clicks Refund on a succeeded transaction and enters an amount (full or partial).
  2. Southbill issues a reversal of the destination transfer on the platform account so the money comes out of the merchant's balance, not Southbill's.
  3. Southbill also reverses the pro-rata application fee — you only keep fees for what the buyer actually paid.
  4. Transaction status becomes refunded (full) or partially_refunded (partial).
  5. A checkout.session.refunded webhook fires.

Rules

  • You cannot refund a disputed charge — resolve the dispute first. The API returns 422 invalid_state with code charge_disputed.
  • Refunds can be issued for up to 180 days after the original charge (processor limit).
  • Partial refunds can be issued multiple times up to the total captured amount.
  • Fee reversal is automatic and visible in the merchant's Wallet as Southbill fee refund.

Webhook payload (checkout.session.refunded)

{
  "type": "checkout.session.refunded",
  "data": {
    "object": {
      "charge_id": "ch_…",
      "session_id": "cs_…",
      "amount_refunded": 1990,
      "amount": 4990,
      "currency": "EUR",
      "reason": "requested_by_customer",
      "fully_refunded": false
    }
  }
}