# 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                    |
| ----------------------------- | ------ | -------- | ------------------------------ |
| `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         |

#### refund\_info (Required)

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

#### Device Info

<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 numerical ID generated for each user session on a website.</td></tr></tbody></table>

<p align="center"><sub>(*) The <code>fingerprint_session_id</code> is generated using a Koin script that is called from the webpage.</sub></p>

### 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"
    }
  }'
```

### 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://firstoken.gitbook.io/api-docs/api-reference/payments/payments-api-koin/payment-refund.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.