API Access

Access transaction data programmatically using the Flintn API.

Prerequisites

An API key with transaction.read or transaction.search permission. See Authentication.

Get a Transaction

Retrieve a single transaction by ID.

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

Response:

{
  "id": "txn_abc123def456",
  "amount": 2999,
  "currency": "USD",
  "status": "SETTLED",
  "customer_id": "cust_123456",
  "customer_email": "[e-mail]",
  "card_brand": "visa",
  "card_last4": "4242",
  "card_exp_month": 12,
  "card_exp_year": 2025,
  "avs_result": "Y",
  "cvv_result": "M",
  "subscription_id": "sub_xyz789",
  "created_at": "2024-01-15T10:30:00Z",
  "captured_at": "2024-01-15T10:30:05Z",
  "settled_at": "2024-01-16T08:00:00Z"
}

List Transactions

Retrieve multiple transactions with optional filters.

curl -X GET "https://api.flintn.com/v1/transactions?limit=20&status=SETTLED" \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Query Parameters

Parameter	Type	Description
limit	integer	Number of results (default: 20, max: 100)
offset	integer	Pagination offset
status	string	Filter by status
customer_id	string	Filter by customer ID
subscription_id	string	Filter by subscription ID
card_brand	string	Filter by card brand
min_amount	integer	Minimum amount in cents
max_amount	integer	Maximum amount in cents
created_after	string	ISO 8601 datetime
created_before	string	ISO 8601 datetime

Response:

{
  "data": [
    {
      "id": "txn_abc123def456",
      "amount": 2999,
      "currency": "USD",
      "status": "SETTLED",
      "customer_id": "cust_123456",
      "card_brand": "visa",
      "card_last4": "4242",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "txn_def456ghi789",
      "amount": 4999,
      "currency": "USD",
      "status": "SETTLED",
      "customer_id": "cust_789012",
      "card_brand": "mastercard",
      "card_last4": "5555",
      "created_at": "2024-01-14T15:20:00Z"
    }
  ],
  "total": 150,
  "limit": 20,
  "offset": 0
}

Search Transactions

Search transactions with advanced filters.

curl -X POST https://api.flintn.com/v1/transactions/search \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "status": ["SETTLED", "REFUNDED"],
      "created_at": {
        "gte": "2024-01-01T00:00:00Z",
        "lte": "2024-01-31T23:59:59Z"
      },
      "amount": {
        "gte": 1000,
        "lte": 10000
      }
    },
    "sort": {
      "field": "created_at",
      "order": "desc"
    },
    "limit": 50
  }'

Search Request Body

Field	Type	Description
filters	object	Filter conditions
sort	object	Sort configuration
limit	integer	Results per page
offset	integer	Pagination offset

Filter Options

Filter	Type	Description
status	array	List of statuses to include
customer_id	string	Exact customer ID match
customer_email	string	Exact email match
subscription_id	string	Exact subscription ID match
card_brand	array	List of card brands
card_last4	string	Last 4 digits
amount	object	gte and/or lte values in cents
created_at	object	gte and/or lte ISO dates

Sort Options

Field	Description
created_at	Sort by creation date
amount	Sort by amount
status	Sort by status

Set order to asc or desc.

Transaction Fields

Core Fields

Field	Type	Description
id	string	Unique transaction ID
amount	integer	Amount in minor units (cents)
currency	string	Three-letter currency code
status	string	Current status
created_at	string	ISO 8601 creation timestamp

Customer Fields

Field	Type	Description
customer_id	string	Your customer identifier
customer_email	string	Customer email
customer_name	string	Customer name
billing_address	object	Billing address details

Card Fields

Field	Type	Description
card_brand	string	visa, mastercard, amex, discover
card_last4	string	Last 4 digits
card_exp_month	integer	Expiration month
card_exp_year	integer	Expiration year
card_bin	string	Bank Identification Number

Risk Fields

Field	Type	Description
avs_result	string	AVS verification result code
cvv_result	string	CVV verification result code
fraud_score	number	Risk score (0-100)

Relationship Fields

Field	Type	Description
subscription_id	string	Associated subscription ID
refund_of	string	Original transaction ID (for refunds)

Timestamp Fields

Field	Type	Description
authorized_at	string	When authorization occurred
captured_at	string	When capture occurred
settled_at	string	When settlement occurred
voided_at	string	When void occurred
refunded_at	string	When refund occurred

Code Examples

JavaScript

async function getRecentTransactions(customerId) {
  const response = await fetch(
    `https://api.flintn.com/v1/transactions?customer_id=${customerId}&limit=10`,
    {
      headers: {
        'X-Api-Key': process.env.FLINTN_API_KEY
      }
    }
  );

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  return response.json();
}

Python

import requests

def search_transactions(start_date, end_date, min_amount=None):
    response = requests.post(
        'https://api.flintn.com/v1/transactions/search',
        headers={
            'X-Api-Key': os.environ['FLINTN_API_KEY'],
            'Content-Type': 'application/json'
        },
        json={
            'filters': {
                'created_at': {
                    'gte': start_date,
                    'lte': end_date
                },
                'amount': {'gte': min_amount} if min_amount else None
            },
            'sort': {'field': 'created_at', 'order': 'desc'},
            'limit': 100
        }
    )

    response.raise_for_status()
    return response.json()

Pagination

For large result sets, use pagination:

async function getAllTransactions() {
  const allTransactions = [];
  let offset = 0;
  const limit = 100;

  while (true) {
    const response = await fetch(
      `https://api.flintn.com/v1/transactions?limit=${limit}&offset=${offset}`,
      {
        headers: { 'X-Api-Key': process.env.FLINTN_API_KEY }
      }
    );

    const { data, total } = await response.json();
    allTransactions.push(...data);

    if (allTransactions.length >= total) {
      break;
    }

    offset += limit;
  }

  return allTransactions;
}

Error Responses

404 Not Found

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

403 Forbidden

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "path": "/v1/transactions",
  "message": "Insufficient permissions for this operation",
  "code": "FORBIDDEN",
  "timestamp": "2024-01-15T10:30:00.123456Z"
}

Next Steps

• Dashboard View - Visual transaction management

• Transaction Actions - Capture, void, and refund