# Capture

### Overview

The Capture endpoint collects funds from a previously authorized transaction. You can capture the full authorized amount or a partial amount (less than authorized). This endpoint is used after you've successfully authorized a payment and are ready to collect the money.

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

### What Happens Internally

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

1. **Validation**: Verify the authorization exists and is capturable
2. **Capture**: Collect the specified amount from the held funds
3. **Response**: Capture confirmation with transaction details

### Request Body

```json
{
  "transaction_info": {
    "type": "capture",
    "reference_code": "123456789"
  },
  "capture_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 authorization response |

#### transaction\_info (Required)

| Field            | Type   | Required | Description                     |
| ---------------- | ------ | -------- | ------------------------------- |
| `type`           | String | Yes      | Must be "capture"               |
| `reference_code` | String | Yes      | Your reference for this capture |

#### capture\_info (Required)

| Field                         | Type   | Required | Description                              |
| ----------------------------- | ------ | -------- | ---------------------------------------- |
| `amount_details.total_amount` | Number | Yes      | Amount to capture  (≤ authorized amount) |
| `amount_details.currency`     | String | Yes      | Currency code (must match authorization) |
| `installments`                | Number | Yes      | Number of installments                   |

#### Device Info

<table><thead><tr><th width="225.6953125">Parameter</th><th width="142.41796875">Type</th><th width="107.63671875">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": "Capture successful",
  "data": {
    "transaction_info": {
      "type": "capture_response",
      "reference_code": "123456789",
      "transaction_id": "0001753573246478085855",
      "request_id": "7535732468686082504805",
      "status": "Collected",
      "reconciliation_id": "7535732368226274904807",
      "created_at": "2025-07-26T23:40:47Z"
    },
    "order_info": {
      "amount_details": {
        "total_amount": "1000",
        "currency": "BRL"
      }
    }
  }
}
```

#### Error Response (400/500)

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

### cURL Example

```bash
curl -X POST https://api.firstoken.co/v1/payments/0001753573236419268758/capture \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction_info": {
      "type": "capture",
      "reference_code": "capture_{{$guid}}"
    },
    "capture_info": {
      "amount_details": {
        "total_amount": 1000,
        "currency": "BRL"
      },
      "installments": 1
    },
    "device_info": {
      "ip_address": "192.168.1.100"
    }
  }'
```

### Capture Status Values

| Status      | Description                           |
| ----------- | ------------------------------------- |
| `Opened`    | Capture request submitted, processing |
| `Collected` | Capture completed successfully        |
| `Failed`    | Capture failed                        |

### Important Notes

#### Capture Rules

* **Amount Limit**: Cannot capture more than the authorized amount
* **Single Capture**: Most authorizations allow only one capture
* **Time Limit**: Capture before authorization expires (typically 7 days)
* **Currency Match**: Capture currency must match authorization currency

#### After Capture

* **Final Status**: Transaction moves to "Captured" state
* **Settlement**: Funds will be settled to your account according to your agreement
* **No Reversal**: Captured amounts cannot be reversed (use void instead)

#### Partial Capture Effects

* **Remaining Authorization**: Usually cancels remaining authorized amount
* **Customer Statement**: Customer sees the captured amount on their statement
* **Reconciliation**: Use reconciliation\_id for tracking

#### Best Practices

* **Verify Status**: Check authorization status before attempting capture
* **Handle Timeouts**: Implement retry logic for network timeouts
* **Track Captures**: Store capture transaction IDs for reconciliation


---

# 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/capture.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.