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:

http
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

ParameterTypeDescriptionExample
pageintegerPage number for pagination (default: 1, minimum: 1)1
limitintegerNumber of transactions per page (default: 10, minimum: 1, maximum: 100)20
typestringFilter by transaction typeDEPOSIT, WITHDRAWAL, EXCHANGE, TRANSFER, DIRECT_EXCHANGE, FEE
statusstringFilter by transaction statusPENDING, PROCESSING, COMPLETED, FAILED, CANCELLED
source_currencystringFilter by source currency codeUSD, EUR, NGN
destination_currencystringFilter by destination currency codeNGN, GBP
fromstring (ISO 8601)Start date for filtering transactions2024-01-01T00:00:00Z
tostring (ISO 8601)End date for filtering transactions2024-01-31T23:59:59Z
time_typestringPredefined time period filter (requires tz)TODAY, THIS_WEEK, THIS_MONTH, THIS_YEAR, RANGE
tzstringIANA timezone identifier (required with time_type)America/New_York, UTC, Asia/Lagos
amount_fromnumberMinimum transaction amount100.50
amount_tonumberMaximum transaction amount1000.00
wallet_idstring (UUID)Filter transactions by wallet ID550e8400-e29b-41d4-a716-446655440000
user_idstring (UUID)Filter transactions by user ID (admin only)550e8400-e29b-41d4-a716-446655440000
asset_typestringFilter by payment method typeFIAT, 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)

json
{  "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",      "source_amount_with_fees": "1015.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

FieldTypeDescription
idstring (UUID)Unique transaction identifier
user_idstring (UUID)User who initiated the transaction
quote_idstring (UUID)Associated quote identifier
transaction_referencestringExternal transaction reference
transaction_type_namestringType of transaction
payment_methodstringPayment method: FIAT or CRYPTO
source_currencystringSource currency code
target_currencystringTarget currency code
source_amountstringSource amount (decimal string)
source_amount_with_feesstringSource amount including fees (decimal string)
target_amountstringTarget amount (decimal string)
quote_ratestringExchange rate used
beneficiary_idstring (UUID)Associated beneficiary identifier
fee_currencystringCurrency in which fees are charged
markup_ratestringMarkup rate applied
total_markupstringTotal markup amount
feesstringTotal fees charged
processing_feestringProcessing fee amount
deposit_feestringDeposit fee amount
payout_feestringPayout fee amount
status_namestringCurrent transaction status
created_atstring (ISO 8601)Transaction creation timestamp
updated_atstring (ISO 8601)Last update timestamp
completed_atstring (ISO 8601)Transaction completion timestamp

Error Responses

Status CodeDescription
400Bad request - invalid parameters
401Unauthorized - invalid or missing API key or signature
500Internal server error

Example: cURL

bash
# 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 paginationcurl -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 rangecurl -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 transactionscurl -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 rangecurl -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

http
GET /api/v1/client/transactions/v2?status=COMPLETED&page=1&limit=20 HTTP/1.1Host: api.sznd.appx-api-key: your_api_key_herex-timestamp: 2025-01-30T12:20:15Zx-signature: generated_signature_hereContent-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:

http
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

ParameterTypeDescription
idstring (UUID)Unique transaction identifier

Success Response (200 OK)

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

json
{  "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",  "source_amount_with_fees": "1015.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 CodeDescription
400Bad request - invalid transaction ID format
401Unauthorized - invalid or missing API key or signature
403Forbidden - transaction does not belong to authenticated customer
404Transaction not found
500Internal server error

Example: cURL

bash
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

http
GET /api/v1/client/transactions/v2/123e4567-e89b-12d3-a456-426614174000 HTTP/1.1Host: api.sznd.appx-api-key: your_api_key_herex-timestamp: 2025-01-30T12:20:15Zx-signature: generated_signature_hereContent-Type: application/json

Use Cases

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

Best Practices

  1. Use Pagination - Always implement pagination for large transaction lists
  2. Cache Results - Cache transaction details that don't change frequently
  3. Filter Efficiently - Use specific filters to reduce response size and improve performance
  4. Handle Errors - Implement proper error handling for 404 (not found) and 403 (forbidden) responses
  5. Store References - Keep transaction references and IDs for reconciliation purposes
  6. 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:

bash
# Get today's transactions in New York timezoneGET /api/v1/client/transactions/v2?time_type=TODAY&tz=America/New_York
# Get this month's transactions in Lagos timezoneGET /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