Transactions API

The Transactions API gives you your wallets' transaction history: every credit and debit, with currency-conversion details where they apply.

Overview

The Transactions API consists of two endpoints:

List Transactions - Retrieve paginated transaction history with filtering options
Get Transaction by ID - Get a single transaction

Both endpoints only ever return your own client's transactions.

All dates are UTC. created_at is returned in UTC (2025-01-15T10:30:00Z), and a date-only from_date / to_date filter is interpreted as a UTC calendar day.

List Transactions

Retrieve a paginated list of transactions, newest first by default.

Endpoint

GET /api/v1/transactions

Authentication: API Key + Secret required

Query Parameters

These are the only filters the endpoint accepts. Any other query parameter is ignored.

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	50	Items per page (min: 1, max: 10,000). `page_size` is accepted as an alias.
`transaction_type`	string	-	`CREDIT` or `DEBIT` (case-insensitive). `type` is accepted as an alias. Any other value returns `400`.
`status`	string	-	Exact match on status, case-insensitive: `PENDING`, `COMPLETED` or `FAILED`. A value that matches no status returns an empty list.
`wallet_id`	integer	-	Only transactions on this wallet. Must be a positive integer, otherwise `400`.
`currency_id`	integer	-	Only transactions in this currency. Must be a positive integer, otherwise `400`.
`search`	string	-	Case-insensitive substring match on `remarks`
`from_date`	string	-	Earliest `created_at`, inclusive. `YYYY-MM-DD` (start of that day, UTC) or an RFC 3339 timestamp. Any other format returns `400`.
`to_date`	string	-	Latest `created_at`, inclusive. `YYYY-MM-DD` covers that whole UTC day; an RFC 3339 timestamp is used as given. Any other format returns `400`.
`sort`	JSON object	`{"field":"id","direction":"DESC"}`	Sort configuration (see below).
`sort_by` / `sort_dir`	string	-	Non-JSON alternative to `sort`, e.g. `sort_by=created_at&sort_dir=ASC`. `sort_order` is accepted for `sort_dir`.

RFC 3339 timestamps may carry any offset (2025-01-15T10:00:00+05:30); the offset is honoured.

Sort Object Format

{
  "field": "id",
  "direction": "DESC"
}

Use id, amount or created_at as field; direction is ASC or DESC. Malformed sort JSON or a direction other than ASC/DESC returns 400.

Response

Success Response (200 OK)

Headers:

X-Page: 1
X-Per-Page: 50
X-Total-Count: 150
X-Total-Pages: 3
X-Page-Size: 50
X-Has-More: true

Response Body:

[
  {
    "id": 1003,
    "wallet_id": 102,
    "currency_id": 2,
    "amount": 100.00,
    "transaction_type": "CREDIT",
    "status": "COMPLETED",
    "source_currency": "USD",
    "destination_currency": "EUR",
    "forex_rate": 0.92,
    "conversion_charges": 2.50,
    "remarks": "Forex conversion from USD wallet",
    "created_at": "2025-01-15T12:00:00Z"
  },
  {
    "id": 1002,
    "wallet_id": 101,
    "currency_id": 1,
    "amount": 25.00,
    "transaction_type": "DEBIT",
    "status": "COMPLETED",
    "remarks": "Order #12345 - Amazon Gift Card",
    "created_at": "2025-01-15T11:45:00Z"
  },
  {
    "id": 1001,
    "wallet_id": 101,
    "currency_id": 1,
    "amount": 500.00,
    "transaction_type": "CREDIT",
    "status": "COMPLETED",
    "remarks": "Wallet funding via bank transfer",
    "created_at": "2025-01-15T10:30:00Z"
  }
]

Response Fields

Field	Type	Description
`id`	number	Unique transaction identifier
`wallet_id`	number	Associated wallet ID
`currency_id`	number	Currency ID for the transaction
`amount`	number	Transaction amount. Always a positive magnitude; `transaction_type` gives the direction.
`transaction_type`	string	`CREDIT` (funds into the wallet) or `DEBIT` (funds out of the wallet)
`status`	string	`PENDING`, `COMPLETED` or `FAILED`
`source_currency`	string	Source currency code for a conversion. Omitted when not set.
`destination_currency`	string	Destination currency code for a conversion. Omitted when not set.
`forex_rate`	number	Exchange rate applied. Omitted when not set.
`conversion_charges`	number	Charges for the currency conversion. Omitted when not set.
`remarks`	string	Free-text description of the transaction
`created_at`	string	Transaction time, RFC 3339 in UTC

Transaction Types

Type	Effect on wallet	Sign of `amount`
`CREDIT`	Funds added	Positive
`DEBIT`	Funds removed	Positive — subtract it yourself

To compute a net movement, add CREDIT amounts and subtract DEBIT amounts. Do not infer direction from the sign of amount.

Transaction Status

Status	Description
`PENDING`	Transaction initiated, awaiting processing
`COMPLETED`	Transaction successfully completed
`FAILED`	Transaction failed

Pagination Headers

Header	Description
`X-Page`	Current page number
`X-Per-Page`	Items per page
`X-Total-Count`	Total number of matching transactions
`X-Total-Pages`	Total number of pages
`X-Page-Size`	Number of items on this page
`X-Has-More`	Whether more pages are available

Error Responses

400 Bad Request — a filter value was rejected. message names the parameter:

{
  "error": {
    "name": "BadRequestError",
    "code": "BAD_REQUEST",
    "message": "transaction_type must be CREDIT or DEBIT",
    "messages": {}
  }
}

Cause	`message`
`transaction_type` / `type` not `CREDIT` or `DEBIT`	`transaction_type must be CREDIT or DEBIT`
`wallet_id` not a positive integer	`wallet_id must be a positive integer`
`currency_id` not a positive integer	`currency_id must be a positive integer`
`from_date` not `YYYY-MM-DD` or RFC 3339	`from_date: must be YYYY-MM-DD or RFC 3339`
`to_date` not `YYYY-MM-DD` or RFC 3339	`to_date: must be YYYY-MM-DD or RFC 3339`
bad `page`, `limit` or `sort`	`Invalid query parameters`

500 Internal Server Error — the message is generic and messages.request_id carries a reference for support.

Examples

# First page of transactions, default pagination
curl -sS "$HOST/api/v1/transactions" \
  -H "X-API-Key: $API_KEY" \
  -H "X-API-Secret: $API_SECRET"

# Debits on one wallet during January 2025 (UTC days, both ends inclusive)
curl -sS "$HOST/api/v1/transactions?wallet_id=101&transaction_type=DEBIT&from_date=2025-01-01&to_date=2025-01-31" \
  -H "X-API-Key: $API_KEY" \
  -H "X-API-Secret: $API_SECRET"

# Completed transactions in one currency, 20 per page
curl -sS "$HOST/api/v1/transactions?currency_id=1&status=COMPLETED&limit=20&page=1" \
  -H "X-API-Key: $API_KEY" \
  -H "X-API-Secret: $API_SECRET"

# Remarks mentioning an order, oldest first
curl -sS "$HOST/api/v1/transactions?search=Order%20%2312345&sort_by=created_at&sort_dir=ASC" \
  -H "X-API-Key: $API_KEY" \
  -H "X-API-Secret: $API_SECRET"

Get Transaction by ID

Retrieve a single transaction.

Endpoint

GET /api/v1/transactions/:id

Authentication: API Key + Secret required

Path Parameters

Parameter	Type	Required	Description
`id`	number	Yes	Unique transaction identifier

Response

Success Response (200 OK)

{
  "id": 1003,
  "wallet_id": 102,
  "currency_id": 2,
  "amount": 100.00,
  "transaction_type": "CREDIT",
  "status": "COMPLETED",
  "source_currency": "USD",
  "destination_currency": "EUR",
  "forex_rate": 0.92,
  "conversion_charges": 2.50,
  "remarks": "Forex conversion from USD wallet",
  "created_at": "2025-01-15T12:00:00Z"
}

Response Fields

Same as the List Transactions response fields.

Error Responses

400 Bad Request — id is not a non-negative integer:

{
  "error": {
    "name": "BadRequestError",
    "code": "BAD_REQUEST",
    "message": "Invalid transaction ID",
    "messages": {}
  }
}

404 Not Found — no transaction with that id belongs to you:

{
  "error": {
    "name": "NotFoundError",
    "code": "NOT_FOUND",
    "message": "Transaction not found",
    "messages": {}
  }
}

Examples

curl -sS "$HOST/api/v1/transactions/1003" \
  -H "X-API-Key: $API_KEY" \
  -H "X-API-Secret: $API_SECRET"

Implementation Notes

Amounts and direction

amount is always a positive magnitude, for credits and debits alike.
transaction_type is the only indicator of direction: CREDIT adds to the wallet, DEBIT removes from it.

Wallet Management - View wallet balances and details
Order Tracking - Monitor order-related transactions

Integration Support

For immediate assistance with transaction operations:

API Status: Check system status at status.starship.com
Technical Support: Contact support@starshiprewards.com
Emergency Support: Use priority support channel for critical issues

Transactions API

Transactions API

Overview

List Transactions

Endpoint

Query Parameters

Sort Object Format

Response

Response Fields

Transaction Types

Transaction Status

Error Responses

Examples

Get Transaction by ID

Endpoint

Path Parameters

Response

Response Fields

Error Responses

Examples

Implementation Notes

Amounts and direction

Reconciliation

Rate Limiting

Next Steps

Integration Support

On this page