Transactions API

The Transactions API allows you to retrieve and manage transaction history. Every quote that is processed becomes a transaction with different statuses throughout its lifecycle.

List Transactions

Retrieve a paginated list of transactions with comprehensive filtering options. Use this endpoint to display transaction history, generate reports, or track transaction statuses.

Endpoint

GET /api/v1/transactions/v2

Note: We recommend using the V2 endpoint (/transactions/v2) as it provides enhanced payment tracking, smart currency mapping for crypto transactions, and more comprehensive transaction details.

Authentication

This endpoint requires JWT authentication. Include your access token in the Authorization header:

Authorization: Bearer <your-access-token>

Query Parameters

Parameter	Type	Description	Example
`page`	integer	Page number for pagination (default: 1, minimum: 1)	`1`
`limit`	integer	Number of transactions per page (default: 10, minimum: 1, maximum: 100)	`20`
`type`	string	Filter by transaction type	`DEPOSIT`, `WITHDRAWAL`, `EXCHANGE`, `TRANSFER`, `DIRECT_EXCHANGE`, `FEE`
`status`	string	Filter by transaction status	`PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`, `CANCELLED`
`source_currency`	string	Filter by source currency code	`USD`, `EUR`, `NGN`
`destination_currency`	string	Filter by destination currency code	`NGN`, `GBP`
`from`	string (ISO 8601)	Start date for filtering transactions	`2024-01-01T00:00:00Z`
`to`	string (ISO 8601)	End date for filtering transactions	`2024-01-31T23:59:59Z`
`time_type`	string	Predefined time period filter (requires `tz`)	`TODAY`, `THIS_WEEK`, `THIS_MONTH`, `THIS_YEAR`, `RANGE`
`tz`	string	IANA timezone identifier (required with `time_type`)	`America/New_York`, `UTC`, `Asia/Lagos`
`amount_from`	number	Minimum transaction amount	`100.50`
`amount_to`	number	Maximum transaction amount	`1000.00`
`wallet_id`	string (UUID)	Filter transactions by wallet ID	`550e8400-e29b-41d4-a716-446655440000`
`user_id`	string (UUID)	Filter transactions by user ID (admin only)	`550e8400-e29b-41d4-a716-446655440000`
`asset_type`	string	Filter by payment method type	`FIAT`, `CRYPTO`

Transaction Types

DEPOSIT - Funds deposited into an account
WITHDRAWAL - Funds withdrawn from an account
EXCHANGE - Currency exchange between two currencies
TRANSFER - Transfer between users
DIRECT_EXCHANGE - Direct currency exchange
FEE - Fee transactions

Transaction Statuses

PENDING - Transaction is pending processing
PROCESSING - Transaction is being processed
COMPLETED - Transaction completed successfully
FAILED - Transaction failed
CANCELLED - Transaction was cancelled

Success Response (200 OK)

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "user_id": "111e4567-e89b-12d3-a456-426614174000",
      "quote_id": "333e4567-e89b-12d3-a456-426614174111",
      "transaction_reference": "TRX-20240501-XYZ123",
      "transaction_type_name": "EXCHANGE",
      "payment_method": "FIAT",
      "source_currency": "USD",
      "target_currency": "NGN",
      "source_amount": "1000.00",
      "target_amount": "1500000.00",
      "quote_rate": "1500.00",
      "beneficiary_id": "222e4567-e89b-12d3-a456-426614174000",
      "fee_currency": "USD",
      "markup_rate": "0.025",
      "total_markup": "25.00",
      "fees_currency": "USD",
      "fees": "15.00",
      "processing_fee": "10.00",
      "deposit_fee": "3.00",
      "payout_fee": "2.00",
      "status_name": "COMPLETED",
      "created_at": "2024-05-01T14:00:00Z",
      "updated_at": "2024-05-01T14:30:00Z",
      "completed_at": "2024-05-01T14:30:00Z"
    }
  ],
  "pagination": {
    "total": 150,
    "page": 1,
    "size": 10,
    "total_pages": 15
  }
}

Response Fields

Field	Type	Description
`id`	string (UUID)	Unique transaction identifier
`user_id`	string (UUID)	User who initiated the transaction
`quote_id`	string (UUID)	Associated quote identifier
`transaction_reference`	string	External transaction reference
`transaction_type_name`	string	Type of transaction
`payment_method`	string	Payment method: `FIAT` or `CRYPTO`
`source_currency`	string	Source currency code
`target_currency`	string	Target currency code
`source_amount`	string	Source amount (decimal string)
`target_amount`	string	Target amount (decimal string)
`quote_rate`	string	Exchange rate used
`beneficiary_id`	string (UUID)	Associated beneficiary identifier
`fee_currency`	string	Currency in which fees are charged
`markup_rate`	string	Markup rate applied
`total_markup`	string	Total markup amount
`fees`	string	Total fees charged
`processing_fee`	string	Processing fee amount
`deposit_fee`	string	Deposit fee amount
`payout_fee`	string	Payout fee amount
`status_name`	string	Current transaction status
`created_at`	string (ISO 8601)	Transaction creation timestamp
`updated_at`	string (ISO 8601)	Last update timestamp
`completed_at`	string (ISO 8601)	Transaction completion timestamp

Error Responses

Status Code	Description
`400`	Bad request - invalid parameters
`401`	Unauthorized - invalid or missing JWT token
`500`	Internal server error

Example: cURL

# Get all transactions (default pagination)
curl -X GET "/api/v1/transactions/v2" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
 
# Get completed transactions with pagination
curl -X GET "/api/v1/transactions/v2?status=COMPLETED&page=1&limit=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
 
# Get transactions filtered by type and date range
curl -X GET "/api/v1/transactions/v2?type=EXCHANGE&from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
 
# Get today's transactions
curl -X GET "/api/v1/transactions/v2?time_type=TODAY&tz=America/New_York" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
 
# Get transactions by currency and amount range
curl -X GET "/api/v1/transactions/v2?source_currency=USD&amount_from=100&amount_to=1000" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Example: HTTP Request

GET /api/v1/transactions/v2?status=COMPLETED&page=1&limit=20 HTTP/1.1
Host: api.sznd.app
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

Get Transaction By ID

Retrieve detailed information about a specific transaction, including all amounts, currencies, fees, status, and timestamps.

Endpoint

GET /api/v1/transactions/v2/{id}

Authentication

This endpoint requires JWT authentication. Include your access token in the Authorization header:

Authorization: Bearer <your-access-token>

Path Parameters

Parameter	Type	Description
`id`	string (UUID)	Unique transaction identifier

Success Response (200 OK)

Returns the same transaction object structure as in the list endpoint, but for a single transaction:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "user_id": "111e4567-e89b-12d3-a456-426614174000",
  "quote_id": "333e4567-e89b-12d3-a456-426614174111",
  "transaction_reference": "TRX-20240501-XYZ123",
  "transaction_type_name": "EXCHANGE",
  "payment_method": "FIAT",
  "source_currency": "USD",
  "target_currency": "NGN",
  "source_amount": "1000.00",
  "target_amount": "1500000.00",
  "quote_rate": "1500.00",
  "beneficiary_id": "222e4567-e89b-12d3-a456-426614174000",
  "fee_currency": "USD",
  "markup_rate": "0.025",
  "total_markup": "25.00",
  "fees_currency": "USD",
  "fees": "15.00",
  "processing_fee": "10.00",
  "deposit_fee": "3.00",
  "payout_fee": "2.00",
  "status_name": "COMPLETED",
  "created_at": "2024-05-01T14:00:00Z",
  "updated_at": "2024-05-01T14:30:00Z",
  "completed_at": "2024-05-01T14:30:00Z"
}

Error Responses

Status Code	Description
`400`	Bad request - invalid transaction ID format
`401`	Unauthorized - invalid or missing JWT token
`403`	Forbidden - transaction does not belong to authenticated user
`404`	Transaction not found
`500`	Internal server error

Example: cURL

curl -X GET "/api/v1/transactions/v2/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Example: HTTP Request

GET /api/v1/transactions/v2/123e4567-e89b-12d3-a456-426614174000 HTTP/1.1
Host: api.sznd.app
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

Use Cases

Transaction History - Display user transaction history with pagination
Status Tracking - Monitor transaction status changes (PENDING → PROCESSING → COMPLETED)
Reporting - Generate reports filtered by date, type, status, or currency
Reconciliation - Match transactions with external records using transaction references
Analytics - Analyze transaction patterns, volumes, and success rates
Audit Trail - Maintain detailed records of all financial transactions

Best Practices

Use Pagination - Always implement pagination for large transaction lists
Cache Results - Cache transaction details that don't change frequently
Filter Efficiently - Use specific filters to reduce response size and improve performance
Handle Errors - Implement proper error handling for 404 (not found) and 403 (forbidden) responses
Store References - Keep transaction references and IDs for reconciliation purposes
Poll for Updates - For pending transactions, poll the Get Transaction endpoint to check status updates

Time Filtering Tips

When using time_type, always provide the tz parameter:

TODAY - Transactions from today in the specified timezone
THIS_WEEK - Transactions from the current week
THIS_MONTH - Transactions from the current month
THIS_YEAR - Transactions from the current year
RANGE - Use from and to parameters for custom date ranges

Example:

# Get today's transactions in New York timezone
GET /api/v1/transactions/v2?time_type=TODAY&tz=America/New_York
 
# Get this month's transactions in Lagos timezone
GET /api/v1/transactions/v2?time_type=THIS_MONTH&tz=Africa/Lagos

Next Steps

Quotes API - Learn how quotes become transactions
Webhooks - Set up webhooks to receive real-time transaction updates
Wallets API - View wallet balances and transaction history

Quotes Transfers