Transactions

`GET /api/v1/transactions`

Returns a paginated list of transactions across your wallets, newest first. Filter server-side by wallet_id; narrow further (by transaction_type, status, date range, amount range) on the response fields client-side.

Request

curl "https://api.octopuscards.io/api/v1/transactions?wallet_id=1&page=1&limit=25" \
  -H "Authorization: Bearer <token>"

Query Parameters

Key	Type	Default	Description
`page`	integer	`1`	Page number (1-based)
`limit`	integer	`50`	Items per page (1–10,000)
`wallet_id`	integer	-	Filter to a single wallet's transactions. Must be a positive integer — `wallet_id=0` returns `400`.

For other filtering needs (transaction_type, status, date range, amount range, free-text search on remarks), page through the results and narrow on the response fields client-side.

Response

[
  {
    "id": 456,
    "wallet_id": 1,
    "currency_id": 1,
    "amount": 50.00,
    "transaction_type": "DEBIT",
    "status": "COMPLETED",
    "source_currency": null,
    "destination_currency": null,
    "forex_rate": null,
    "conversion_charges": null,
    "remarks": "USD Wallet debited by amount 50.00 - Order #12345",
    "created_at": "2025-01-15T14:30:00Z"
  },
  {
    "id": 455,
    "wallet_id": 1,
    "currency_id": 1,
    "amount": 1000.00,
    "transaction_type": "CREDIT",
    "status": "COMPLETED",
    "source_currency": "EUR",
    "destination_currency": "USD",
    "forex_rate": 1.0850,
    "conversion_charges": 2.50,
    "remarks": "FX conversion from EUR wallet",
    "created_at": "2025-01-15T10:00:00Z"
  }
]

Response Headers

Header	Description
`X-Page`	Current page number
`X-Per-Page`	Items per page
`X-Total-Count`	Total matching transactions
`X-Total-Pages`	Total pages
`X-Page-Size`	Items in current page
`X-Has-More`	`true` if more pages exist

Response Fields

Key	Type	Description
`id`	integer	Unique transaction identifier
`wallet_id`	integer	Wallet this transaction belongs to
`currency_id`	integer	Currency of the transaction
`amount`	number	Transaction amount (always positive - direction is indicated by `transaction_type`)
`transaction_type`	string	`CREDIT` (money in) or `DEBIT` (money out)
`status`	string	`PENDING`, `COMPLETED`, or `FAILED`
`source_currency`	string or null	Source currency code for FX conversions (e.g. `EUR`)
`destination_currency`	string or null	Destination currency code for FX conversions (e.g. `USD`)
`forex_rate`	number or null	Exchange rate applied, if FX conversion
`conversion_charges`	number or null	Fee charged for FX conversion
`remarks`	string	Human-readable description of the transaction
`created_at`	string	ISO 8601 / RFC 3339 timestamp

Enumerations

transaction_type

Value	Description
`CREDIT`	Funds added to wallet (top-up, refund, FX conversion in)
`DEBIT`	Funds removed from wallet (order settlement, adjustment, FX conversion out)

status

Value	Description
`PENDING`	Transaction awaiting processing
`COMPLETED`	Transaction settled, balance updated
`FAILED`	Transaction did not complete, balance unchanged

Errors

400 Bad Request — wallet_id was supplied but isn't a positive integer.

{
  "error": {
    "name": "ValidationException",
    "code": "VALIDATION_FAILURE",
    "message": "wallet_id must be a positive integer"
  }
}

`GET /api/v1/transactions/:id`

Returns a single transaction by its ID. The transaction must belong to your client account.

Request

curl "https://api.octopuscards.io/api/v1/transactions/456" \
  -H "Authorization: Bearer <token>"

Request Parameters

Key	Type	Required	Description
`id`	integer	Yes	Transaction ID (path parameter). Must be between 1 and 2,147,483,647.

Response

{
  "id": 456,
  "wallet_id": 1,
  "currency_id": 1,
  "amount": 50.00,
  "transaction_type": "DEBIT",
  "status": "COMPLETED",
  "source_currency": null,
  "destination_currency": null,
  "forex_rate": null,
  "conversion_charges": null,
  "remarks": "USD Wallet debited by amount 50.00 - Order #12345",
  "created_at": "2025-01-15T14:30:00Z"
}

Response fields are identical to the list endpoint above.

Errors

400 Bad Request - ID is not a valid integer or out of range.

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

On this page