> 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/capture.md).

# 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><p>A unique alpha-numerical ID generated for each user session </p><p>on a website.</p></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": "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",
      "fingerprint_session_id": "0a76c25669713d8d6d306ba8c21259b7"
    }
  }'
```

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