> For the complete documentation index, see [llms.txt](https://firstoken.gitbook.io/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://firstoken.gitbook.io/api-docs/api-reference/payments/payments-api-koin/payment-refund.md).

# Payment Refund

### Overview

The Payment Refund endpoint refunds a completed payment transaction. This is used when you need to return money for a payment that was already captured/collected. The refund will return the full amount back to the customer's card.

**POST** `/v1/payments/{transactionId}/refund`

### What Happens Internally

```
Client Request → Firstoken API → [KOIN Refund] → Response
```

1. **Validation**: Verify the payment exists and is refundable
2. **Refund Processing**: Process the refund for the completed payment
3. **Return Funds**: Process refund back to customer's card
4. **Response**: Refund confirmation with transaction details

### Request Body

```json
{
  "transaction_info": {
    "type": "payment_refund",
    "reference_code": "123456789"
  },
  "refund_info": {
    "amount_details": {
      "total_amount": 1000,
      "currency": "BRL"
    },
    "installments": 1
  },
  "device_info": {
      "ip_address": "12.7.8.120",
      "fingerprint_session_id": "0a76c25669713d8d6d306ba8c21259b7",
  }
}
```

### Field Specifications

#### URL Parameters

| Parameter       | Type   | Required | Description                                       |
| --------------- | ------ | -------- | ------------------------------------------------- |
| `transactionId` | String | Yes      | Transaction ID from the original payment response |

#### transaction\_info (Required)

| Field            | Type   | Required | Description                              |
| ---------------- | ------ | -------- | ---------------------------------------- |
| `type`           | String | Yes      | Must be "payment\_refund"                |
| `reference_code` | String | Yes      | Your reference for this refund operation |

#### refund\_info (Required)

| Field                         | Type   | Required | Description                    |
| ----------------------------- | ------ | -------- | ------------------------------ |
| `amount_details.total_amount` | Number | Yes      | Total amount for transaction   |
| `amount_details.currency`     | String | Yes      | Currency code (BRL, USD, etc.) |
| `installments`                | Number | Yes      | Number of installments         |

#### Device Info (Required)

<table><thead><tr><th width="222.50390625">Parameter</th><th width="108.1484375">Type</th><th width="119.70703125">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>ip_address</code></td><td>String</td><td>Yes</td><td>Customer's IP address</td></tr><tr><td><code>fingerprint_session_id</code>*</td><td>String</td><td>Yes </td><td>A unique alpha-numerical ID generated for each user session on a website.</td></tr></tbody></table>

{% hint style="info" %}
`fingerprint_session_id` is required for all KOIN requests. See [KOIN - Device Fingerprint Session ID](/api-docs/guides/koin-device-fingerprint-session-id.md) for implementation by platform (Web, Android, iOS).
{% endhint %}

***

### Response Format

#### Success Response (200)

```json
{
    "status": "success",
    "message": "Refund successful",
    "data": {
        "transaction_info": {
            "type": "payment_refund_response",
            "reference_code": "123456789",
            "transaction_id": "0001753749137961743055",
            "request_id": "7537491383836265204807",
            "status": "Pending",
            "reconciliation_id": "7537491301256093704806",
            "created_at": "2025-07-29T00:32:18Z"
        },
        "order_info": {
            "amount_details": {
                "currency": "COP"
            }
        }
    }
}
```

#### Error Response (400/500)

```json
{
    "status": "fail",
    "message": "Invalid request",
    "data": {
        "code": 400,
        "description": "Invalid transaction_id"
    }
}
```

### cURL Example

```bash
curl -X POST https://api.firstoken.co/v1/payments/0001750977715315130387/refund \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction_info": {
      "type": "payment_refund",
      "reference_code": "refund_{{$guid}}"
    },
    "refund_info": {
        "amount_details": {
            "total_amount": 1000,
            "currency": "BRL"
        },
        "installments": 1
    },
    "device_info": {
        "ip_address": "12.7.8.120",
      "fingerprint_session_id": "0a76c25669713d8d6d306ba8c21259b7"
    }
  }'
```

### Refund Status Values

| Status     | Description                          |
| ---------- | ------------------------------------ |
| `Refunded` | Payment successfully refunded        |
| `Pending`  | Refund request submitted, processing |
| `Failed`   | Refund operation failed              |

### Use Cases

#### When to Use Payment Refund

* **Customer Cancellation**: Customer cancels order after payment
* **Merchant Error**: Wrong amount charged or duplicate payment
* **Inventory Issues**: Product not available after payment
* **Fraudulent Transaction**: Suspected fraud detected after payment
* **System Error**: Technical error resulted in incorrect charge
* **Refund Request**: Customer requests immediate refund
* **Order Modification**: Order cancelled and new one created

#### Void vs Refund

| Aspect                 | Payment Void                 | Refund                         |
| ---------------------- | ---------------------------- | ------------------------------ |
| **Timing**             | Before settlement            | After settlement               |
| **Process**            | Cancels original transaction | Creates new refund transaction |
| **Customer Statement** | Original charge disappears   | Shows original charge + refund |
| **Processing Time**    | Immediate                    | 3-5 business days typically    |
| **Fees**               | Usually no fees              | May incur refund fees          |

#### Customer Experience

* **Processing Time**: Refund typically takes 3-5 business days to appear
* **Statement**: Customer sees original charge and separate refund entry
* **Notification**: Customer should be notified of the refund processing