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

Client API Endpoint: GET /api/v1/client/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 HMAC authentication (Business API Key). Include your API key and signature in the request headers:

x-api-key: <your-api-key>
x-timestamp: <RFC3339-timestamp>
x-signature: <HMAC-signature>

Note: For HMAC authentication details, see the Authentication guide.

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 API key or signature
`500`	Internal server error

Example: cURL

# Get all transactions (default pagination)
curl -X GET "https://api.sznd.app/api/v1/client/transactions/v2" \
  -H "x-api-key: your_api_key_here" \
  -H "x-timestamp: 2025-01-30T12:20:15Z" \
  -H "x-signature: generated_signature_here"
 
# Get completed transactions with pagination
curl -X GET "https://api.sznd.app/api/v1/client/transactions/v2?status=COMPLETED&page=1&limit=20" \
  -H "x-api-key: your_api_key_here" \
  -H "x-timestamp: 2025-01-30T12:20:15Z" \
  -H "x-signature: generated_signature_here"
 
# Get transactions filtered by type and date range
curl -X GET "https://api.sznd.app/api/v1/client/transactions/v2?type=EXCHANGE&from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z" \
  -H "x-api-key: your_api_key_here" \
  -H "x-timestamp: 2025-01-30T12:20:15Z" \
  -H "x-signature: generated_signature_here"
 
# Get today's transactions
curl -X GET "https://api.sznd.app/api/v1/client/transactions/v2?time_type=TODAY&tz=America/New_York" \
  -H "x-api-key: your_api_key_here" \
  -H "x-timestamp: 2025-01-30T12:20:15Z" \
  -H "x-signature: generated_signature_here"
 
# Get transactions by currency and amount range
curl -X GET "https://api.sznd.app/api/v1/client/transactions/v2?source_currency=USD&amount_from=100&amount_to=1000" \
  -H "x-api-key: your_api_key_here" \
  -H "x-timestamp: 2025-01-30T12:20:15Z" \
  -H "x-signature: generated_signature_here"

Example: HTTP Request

GET /api/v1/client/transactions/v2?status=COMPLETED&page=1&limit=20 HTTP/1.1
Host: api.sznd.app
x-api-key: your_api_key_here
x-timestamp: 2025-01-30T12:20:15Z
x-signature: generated_signature_here
Content-Type: application/json

Get Transaction By ID

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

Endpoint

Client API Endpoint: GET /api/v1/client/transactions/v2/{id}

Authentication

This endpoint requires HMAC authentication (Business API Key). Include your API key and signature in the request headers:

x-api-key: <your-api-key>
x-timestamp: <RFC3339-timestamp>
x-signature: <HMAC-signature>

Note: For HMAC authentication details, see the Authentication guide.

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 API key or signature
`403`	Forbidden - transaction does not belong to authenticated customer
`404`	Transaction not found
`500`	Internal server error

Example: cURL

curl -X GET "https://api.sznd.app/api/v1/client/transactions/v2/123e4567-e89b-12d3-a456-426614174000" \
  -H "x-api-key: your_api_key_here" \
  -H "x-timestamp: 2025-01-30T12:20:15Z" \
  -H "x-signature: generated_signature_here"

Example: HTTP Request

GET /api/v1/client/transactions/v2/123e4567-e89b-12d3-a456-426614174000 HTTP/1.1
Host: api.sznd.app
x-api-key: your_api_key_here
x-timestamp: 2025-01-30T12:20:15Z
x-signature: generated_signature_here
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/client/transactions/v2?time_type=TODAY&tz=America/New_York
 
# Get this month's transactions in Lagos timezone
GET /api/v1/client/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
Virtual Wallets API - View virtual wallet balances and transaction history

💱 Quotes 🔄 Transfers