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

{
  "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

Parameter	Type	Required	Description
ip_address	String	Yes	Customer's IP address
fingerprint_session_id*	String	Yes	A unique numerical ID generated for each user session on a website.

_{(*) The fingerprint_session_id is generated using a Koin script that is called from the webpage.}

Response Format

Success Response (200)

{
  "status": "success",
  "message": "Capture successful",
  "data": {
    "transaction_info": {
      "type": "capture_response",
      "reference_code": "123456789",
      "transaction_id": "0001753573246478085855",
      "request_id": "7535732468686082504805",
      "status": "Pending",
      "reconciliation_id": "7535732368226274904807",
      "created_at": "2025-07-26T23:40:47Z"
    },
    "order_info": {
      "amount_details": {
        "total_amount": "1000",
        "currency": "BRL"
      }
    }
  }
}

Error Response (400/500)

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

cURL Example

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
Pending	Capture request submitted, processing
Captured	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