Actions (Capture/Void/Refund)

Capture, void, and refund transactions using the Flintn API.

Prerequisites

An API key with the appropriate permissions:

• transaction.capture for capturing

• transaction.void for voiding

• transaction.refund for refunding

See Authentication.

Action Overview

Action	Description	Valid From	Results In
Capture	Finalize an authorization and collect funds	AUTHORIZED	CAPTURED
Void	Cancel an authorization before capture	AUTHORIZED	VOIDED
Refund	Return funds to customer	SETTLED	REFUNDED
Partial Refund	Return partial amount	SETTLED	PARTIALLY_REFUNDED

Capture

Convert an authorization into an actual charge.

Full Capture

curl -X POST https://api.flintn.com/v1/transactions/txn_abc123def456/capture \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response:

{
  "id": "txn_abc123def456",
  "amount": 2999,
  "currency": "USD",
  "status": "CAPTURED",
  "captured_at": "2024-01-15T10:35:00Z"
}

Partial Capture

Capture less than the authorized amount:

curl -X POST https://api.flintn.com/v1/transactions/txn_abc123def456/capture \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1999
  }'

Note: Partial capture releases the remaining authorized funds back to the customer's card.

When to Capture

• Immediate capture: For digital goods or services delivered instantly

• Delayed capture: For physical goods (capture when shipped)

• Partial capture: When order total changes (e.g., out of stock items)

Auto-Capture

If configured in your subscription plan's settlement_interval_hours, authorized transactions are automatically captured after the specified time.

Void

Cancel an authorization before it's captured or settled.

curl -X POST https://api.flintn.com/v1/transactions/txn_abc123def456/void \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response:

{
  "id": "txn_abc123def456",
  "amount": 2999,
  "currency": "USD",
  "status": "VOIDED",
  "voided_at": "2024-01-15T10:35:00Z"
}

When to Void

• Customer cancels order before shipment

• Fraud detected before capture

• Duplicate authorization

• Order cannot be fulfilled

Void vs Refund

Scenario	Use
Authorization not yet captured	Void
Transaction already settled	Refund

Voids are preferred when possible because:

• They release funds immediately

• No processing fees are incurred

• No chargeback risk

Refund

Return funds to a customer after settlement.

Full Refund

curl -X POST https://api.flintn.com/v1/transactions/txn_abc123def456/refund \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response:

{
  "id": "txn_refund_xyz789",
  "original_transaction_id": "txn_abc123def456",
  "amount": 2999,
  "currency": "USD",
  "status": "REFUNDED",
  "refunded_at": "2024-01-15T10:35:00Z"
}

Partial Refund

Refund a portion of the transaction:

curl -X POST https://api.flintn.com/v1/transactions/txn_abc123def456/refund \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "reason": "Partial item return"
  }'

Response:

{
  "id": "txn_refund_xyz789",
  "original_transaction_id": "txn_abc123def456",
  "amount": 1000,
  "currency": "USD",
  "status": "PARTIALLY_REFUNDED",
  "reason": "Partial item return",
  "refunded_at": "2024-01-15T10:35:00Z"
}

Multiple Partial Refunds

You can issue multiple partial refunds up to the original amount:

# First partial refund: $10.00
curl -X POST https://api.flintn.com/v1/transactions/txn_abc123def456/refund \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"amount": 1000, "reason": "Item 1 return"}'

# Second partial refund: $5.00
curl -X POST https://api.flintn.com/v1/transactions/txn_abc123def456/refund \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"amount": 500, "reason": "Item 2 return"}'

Refund Request Fields

Field	Type	Required	Description
amount	integer	No	Amount in cents (full refund if omitted)
reason	string	No	Reason for refund

Refund Timing

• Refunds are typically processed within 5-10 business days

• The exact timing depends on the customer's bank

• The refund appears on the original payment method

Code Examples

JavaScript

async function processRefund(transactionId, amount = null, reason = null) {
  const body = {};
  if (amount) body.amount = amount;
  if (reason) body.reason = reason;

  const response = await fetch(
    `https://api.flintn.com/v1/transactions/${transactionId}/refund`,
    {
      method: 'POST',
      headers: {
        'X-Api-Key': process.env.FLINTN_API_KEY,
        'Content-Type': 'application/json'
      },
      body: Object.keys(body).length ? JSON.stringify(body) : undefined
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message);
  }

  return response.json();
}

// Full refund
await processRefund('txn_abc123def456');

// Partial refund with reason
await processRefund('txn_abc123def456', 1500, 'Customer request');

Python

import requests

def capture_transaction(transaction_id, amount=None):
    payload = {}
    if amount is not None:
        payload['amount'] = amount

    response = requests.post(
        f'https://api.flintn.com/v1/transactions/{transaction_id}/capture',
        headers={
            'X-Api-Key': os.environ['FLINTN_API_KEY'],
            'Content-Type': 'application/json'
        },
        json=payload if payload else None
    )

    response.raise_for_status()
    return response.json()

def void_transaction(transaction_id):
    response = requests.post(
        f'https://api.flintn.com/v1/transactions/{transaction_id}/void',
        headers={'X-Api-Key': os.environ['FLINTN_API_KEY']}
    )

    response.raise_for_status()
    return response.json()

Error Responses

400 Bad Request - Invalid State

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "path": "/v1/transactions/txn_abc123def456/void",
  "message": "Cannot void transaction in SETTLED status",
  "code": "INVALID_STATE",
  "timestamp": "2024-01-15T10:30:00.123456Z"
}

400 Bad Request - Exceeds Amount

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "path": "/v1/transactions/txn_abc123def456/refund",
  "message": "Refund amount exceeds available balance",
  "code": "AMOUNT_EXCEEDS_BALANCE",
  "timestamp": "2024-01-15T10:30:00.123456Z"
}

404 Not Found

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "path": "/v1/transactions/txn_invalid/capture",
  "message": "Transaction not found",
  "code": "NOT_FOUND",
  "timestamp": "2024-01-15T10:30:00.123456Z"
}

Webhook Events

Actions trigger corresponding webhook events:

Action	Event
Capture	TRANSACTION_CAPTURED
Void	TRANSACTION_VOIDED
Full Refund	TRANSACTION_REFUNDED
Partial Refund	TRANSACTION_PARTIALLY_REFUNDED

See Webhook Events for payload details.

Best Practices

Capture

• Capture only when you're ready to fulfill the order

• Use partial capture when order amounts change

• Set up auto-capture for subscription payments

Void

• Void authorizations promptly when orders are cancelled

• Prefer void over refund when possible

Refund

• Include a reason for audit purposes

• Process refunds promptly (within 24-48 hours of request)

• Send confirmation to customer after refund is processed

Next Steps

• Transactions Overview - Understanding transaction states

• API Access - Query transaction data

• Dashboard View - Visual transaction management