> ## Documentation Index
> Fetch the complete documentation index at: https://galacticagames.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Refunds

> Initiate and track refunds

## Refund Flow

```mermaid theme={null}
sequenceDiagram
    participant Game as Game
    participant Server as Game Server
    participant API as ToffeePay

    Game->>Server: Request refund
    Server->>API: Create Refund
    API->>Server: Return refund object
    Server->>Game: Confirm refund initiated

    Note over API: Processing refund...

    API->>Server: Send refund webhook (signed)
    Server->>Server: Verify webhook signature
    Server->>Server: Process refund & revoke item
    Server->>Game: Notify refund completed
```

***

## Create a Refund

Send a server-side request to [create a refund](https://galacticagames.mintlify.site/api-reference/refunds/create.md) for a paid session.

> [tab] TypeScript
>
> ```typescript theme={null}
> const { refund } = await toffee.refunds.create({
>   paymentId: "pay_xyz789",
>   reason: "Customer request",
> });
> ```

> [tab] Python
>
> ```python theme={null}
> resp = await toffee.refunds.create(CreateRefundRequest(
>     payment_id="pay_xyz789",
>     reason="Customer request",
> ))
> refund = resp.refund
> ```

> [tab] Go
>
> ```go theme={null}
> resp, err := toffee.Refunds.Create(ctx, &sdk.CreateRefundRequest{
>   PaymentId: "pay_xyz789",
>   Reason:    "Customer request",
> })
> refund := resp.GetRefund()
> ```

> [tab] API
>
> ```http theme={null}
> POST /v1/refunds
> Authorization: Bearer <your_access_token>
> Content-Type: application/json
>
> {
>   "payment_id": "pay_xyz789",
>   "reason": "Customer request"
> }
> ```

**Parameters:**

* `payment_id`: The original payment ID to refund
* `reason`: Optional reason for the refund

**Response:** A Refund object.

```json theme={null}
{
  "id": "ref_xyz789",
  "payment_id": "pay_xyz789",
  "status": "pending",
  "reason": "Customer request",
  "created_at": "2023-06-01T12:00:00Z"
}
```

***

## Refund Statuses

Refunds can have the following statuses:

* `pending`: Refund created but not yet processed
* `succeeded`: Refund has been successfully processed and funds returned
* `failed`: Refund failed (e.g., insufficient funds, payment method issues)
* `cancelled`: Refund was cancelled before completion

**Status Flow:**

1. Refund starts as `pending`
2. Refund resolves to either `succeeded`, `failed`, or `cancelled`

### Timestamp Fields

Refunds include relevant timestamp fields based on their final status:

* `created_at`: When the refund was initiated
* `succeeded_at`: When the refund completed successfully (if applicable)
* `failed_at`: When the refund failed (if applicable)
* `cancelled_at`: When the refund was cancelled (if applicable)

***

## Webhook Events

ToffeePay sends webhooks for the following refund-related events:

* [`refund.created`](https://galacticagames.mintlify.site/api-reference/webhooks/refund.created): When a refund is created and processing begins
* [`refund.succeeded`](https://galacticagames.mintlify.site/api-reference/webhooks/refund.succeeded): When a refund has been processed successfully
* [`refund.failed`](https://galacticagames.mintlify.site/api-reference/webhooks/refund.failed): When a refund attempt fails

See the [Webhooks](https://galacticagames.mintlify.site/webhooks.md) page for implementation details and signature verification.

***

## Handle Refund Notifications

When a refund is processed, ToffeePay sends a **signed webhook** to your backend.

**Sample Payload:**

```json theme={null}
{
  "type": "refund.succeeded",
  "timestamp": "2023-06-01T12:10:00Z",
  "data": {
    // Refund object
  }
}
```

For webhook signature verification, see the [Webhooks](https://galacticagames.mintlify.site/webhooks.md#webhook-signature-verification) page.

***

## Check Refund Status

You can [check the status](https://galacticagames.mintlify.site/api-reference/refunds/get.md) of a refund at any time:

> [tab] TypeScript
>
> ```typescript theme={null}
> const { refund } = await toffee.refunds.get({ id: "ref_xyz789" });
> ```

> [tab] Python
>
> ```python theme={null}
> resp = await toffee.refunds.get(GetRefundRequest(id="ref_xyz789"))
> refund = resp.refund
> ```

> [tab] Go
>
> ```go theme={null}
> resp, err := toffee.Refunds.Get(ctx, &sdk.GetRefundRequest{Id: "ref_xyz789"})
> refund := resp.GetRefund()
> ```

> [tab] API
>
> ```http theme={null}
> GET /v1/refunds/ref_xyz789
> Authorization: Bearer <your_access_token>
> ```

**Response:**

```json theme={null}
{
  "id": "ref_xyz789",
  "payment_id": "pay_xyz789",
  "status": "succeeded",
  "reason": "Customer request",
  "created_at": "2023-06-01T12:00:00Z",
  "succeeded_at": "2023-06-01T12:05:00Z"
}
```

***

## List Refunds

[Retrieve historical refunds](https://galacticagames.mintlify.site/api-reference/refunds/list.md) for audit and analytics:

> [tab] TypeScript
>
> ```typescript theme={null}
> const { refunds } = await toffee.refunds.list({ paymentId: "pay_xyz789" });
> ```

> [tab] Python
>
> ```python theme={null}
> resp = await toffee.refunds.list(ListRefundsRequest(payment_id="pay_xyz789"))
> refunds = resp.refunds
> ```

> [tab] Go
>
> ```go theme={null}
> paymentId := "pay_xyz789"
> resp, err := toffee.Refunds.List(ctx, &sdk.ListRefundsRequest{
>   PaymentId: &paymentId,
> })
> refunds := resp.GetRefunds()
> ```

> [tab] API
>
> ```http theme={null}
> GET /v1/refunds?payment_id=pay_xyz789&status=succeeded&limit=50&offset=0
> Authorization: Bearer <your_access_token>
> ```

**Response:**

```json theme={null}
[
  {
    "id": "ref_xyz789",
    "payment_id": "pay_xyz789",
    "status": "succeeded",
    "reason": "Customer request",
    "created_at": "2023-06-01T12:00:00Z",
    "succeeded_at": "2023-06-01T12:05:00Z"
  }
]
```

***

## Best Practices

1. **Idempotency**: Use [Idempotency-Key](https://galacticagames.mintlify.site/idempotency.md) header to prevent duplicate refunds
2. **Revoke Items**: When processing a refund webhook, revoke the purchased items from the user's account
3. **Webhook verification**: Always verify webhook signatures (see [Webhooks](https://galacticagames.mintlify.site/webhooks.md))


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.