---
name: refunds
description: >-
  Guides through refunding payments via Smart Glocal API: full and partial
  refunds via session/refund, handling payment_refunded webhook, and
  chargeback notifications.
---

# Refunds

## Purpose

Use this skill to process full or partial refunds after a successful payment. Also covers chargeback handling.

## Primary references

- [Refunds docs](https://developer.smart-glocal.com/payments/payment-refund)
- [session/refund](https://developer.smart-glocal.com/reference/methods/session-refund)
- [payment_refunded webhook](https://developer.smart-glocal.com/reference/webhooks/payment-refunded)

## Preconditions

- [ ] Successful payment session exists (status `succeeded` or `accepted`)
- [ ] Partial refunds: check with your Account Manager if enabled

---

## Flow

```
session/refund → payment_refunded (webhook)
```

Just one request and one webhook in response.

## Full Refund

Send `POST /api/v2/session/refund` with the `session_id` of the successful payment:

```bash
curl -X POST https://demo.smart-glocal.com/api/v2/session/refund \
  -H "Content-Type: application/json" \
  -H "X-PARTNER-PROJECT: shop1" \
  -H "X-PARTNER-SIGN: <signature>" \
  -d '{
    "session_id": "ps_xxx"
  }'
```

If you omit `amount_details`, the **full amount** is refunded.

## Partial Refund

Specify the amount in `amount_details`:

```bash
curl -X POST https://demo.smart-glocal.com/api/v2/session/refund \
  -H "Content-Type: application/json" \
  -H "X-PARTNER-PROJECT: shop1" \
  -H "X-PARTNER-SIGN: <signature>" \
  -d '{
    "session_id": "ps_xxx",
    "amount_details": {
      "amount": 3000,
      "currency": "usd"
    }
  }'
```

Only 30 USD out of 100 will be refunded. Multiple partial refunds on the same session are allowed.

## Response

```json
{
  "status": "ok",
  "session": {
    "id": "ps_xxx",
    "status": "in_progress",
    "payment_list": [{
      "id": "pm_xxx",
      "status": "succeeded",
      "refunds": [{
        "id": "rf_001",
        "status": "in_progress",
        "amount_details": {
          "amount": 3000,
          "currency": "usd"
        }
      }]
    }]
  }
}
```

The refund status is `in_progress`. The final result arrives via webhook.

## Webhook: payment_refunded

Smart Glocal sends `payment_refunded` when the refund is complete:

```json
{
  "type": "payment_refunded",
  "session": {
    "id": "ps_xxx",
    "status": "accepted",
    "payment_list": [{
      "id": "pm_xxx",
      "status": "succeeded",
      "amount_details": {
        "amount": 10000,
        "currency": "usd"
      },
      "refunds": [{
        "id": "rf_001",
        "status": "accepted",
        "amount_details": {
          "amount": 3000,
          "currency": "usd"
        }
      }]
    }]
  }
}
```

`refunds[].status` = `accepted` means the funds have been returned.

## Chargeback (Not Initiated by Merchant)

A chargeback is a return initiated by the buyer's bank (e.g., in case of a disputed transaction). You **cannot** initiate it — Smart Glocal will notify you automatically. In this case, the amount is deducted from your compensation.

## Limitations

- For payments from [certain countries](https://developer.smart-glocal.com/payments/payment-intro#countries), refunds are available **only the next day** after the payment.
- Partial refunds may not be available for all projects — check with your Account Manager.