Skip to main content

​
Overview

The Yativo Card API provides full transaction history for both individual cards and the overall account. You can filter transactions by status, date range, and paginate results for large histories. 
interface CardTransaction {
  transaction_id: string;
  card_id: string;
  type: "purchase" | "refund" | "reversal" | "atm_withdrawal";
  amount: number;
  currency: string;
  merchant_name?: string;
  merchant_category?: string;
  status: "pending" | "completed" | "failed" | "reversed";
  created_at: string;
}

interface CardTransactionListParams {
  limit?: number;
  offset?: number;
  status?: "pending" | "completed" | "failed" | "reversed";
  from_date?: string; // ISO 8601
  to_date?: string;   // ISO 8601
}

​
Get Transactions for a Specific Card

Retrieve transactions for a single card, with optional filters. 
GET /yativo-card/{yativoCardId}/cards/{cardId}/transactions
​
yativoCardId
string
required
Your Yativo Card account ID.
​
cardId
string
required
The card ID to retrieve transactions for.
​
limit
integer
Number of results to return per page. Default: 20. Max: 100.
​
offset
integer
Number of results to skip (for pagination). Default: 0.
​
status
string
Filter by transaction status. Accepted values: pending, completed, failed, reversed.
​
from_date
string
Start of the date range (ISO 8601 format). Example: 2026-01-01T00:00:00Z.
​
to_date
string
End of the date range (ISO 8601 format). Example: 2026-03-31T23:59:59Z.
curl -X GET 'https://crypto-api.yativo.com/api/yativo-card/yc_01HX9KZMB3F7VNQP8R2WDGT4E5/cards/card_01HX9KZMB3F7VNQP8R2WDGT4E5/transactions?limit=20&offset=0&status=completed&from_date=2026-03-01T00:00:00Z' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "status": "success",
  "data": {
    "transactions": [
      {
        "transaction_id": "txn_01HX9KZMB3F7VNQP8R2WDGT901",
        "card_id": "card_01HX9KZMB3F7VNQP8R2WDGT4E5",
        "amount": 42.50,
        "currency": "USD",
        "merchant_name": "Amazon",
        "merchant_category": "Online Retail",
        "status": "completed",
        "type": "purchase",
        "created_at": "2026-03-20T15:30:00Z",
        "settled_at": "2026-03-21T10:00:00Z"
      },
      {
        "transaction_id": "txn_01HX9KZMB3F7VNQP8R2WDGT902",
        "card_id": "card_01HX9KZMB3F7VNQP8R2WDGT4E5",
        "amount": 12.99,
        "currency": "USD",
        "merchant_name": "Netflix",
        "merchant_category": "Streaming",
        "status": "completed",
        "type": "purchase",
        "created_at": "2026-03-15T08:00:00Z",
        "settled_at": "2026-03-16T09:00:00Z"
      }
    ],
    "total": 2,
    "limit": 20,
    "offset": 0
  }
}

​
Get All Account Transactions

Retrieve transactions across all cards in the account. Useful for generating account-level reports. 
GET /yativo-card/{yativoCardId}/transactions
​
yativoCardId
string
required
Your Yativo Card account ID.
​
limit
integer
Number of results per page. Default: 20. Max: 100.
​
offset
integer
Offset for pagination. Default: 0.
​
status
string
Filter by transaction status: pending, completed, failed, reversed.
curl -X GET 'https://crypto-api.yativo.com/api/yativo-card/yc_01HX9KZMB3F7VNQP8R2WDGT4E5/transactions?limit=50&offset=0&status=completed' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "status": "success",
  "data": {
    "transactions": [
      {
        "transaction_id": "txn_01HX9KZMB3F7VNQP8R2WDGT901",
        "card_id": "card_01HX9KZMB3F7VNQP8R2WDGT4E5",
        "card_display_name": "Online Shopping",
        "amount": 42.50,
        "currency": "USD",
        "merchant_name": "Amazon",
        "merchant_category": "Online Retail",
        "status": "completed",
        "type": "purchase",
        "created_at": "2026-03-20T15:30:00Z",
        "settled_at": "2026-03-21T10:00:00Z"
      }
    ],
    "total": 1,
    "limit": 50,
    "offset": 0
  }
}

​
Transaction Status Values

StatusDescription
pendingTransaction has been authorized but not yet settled. Funds are reserved.
completedTransaction has settled successfully. Funds have been deducted.
failedTransaction was declined or failed to process. No funds were deducted.
reversedTransaction was reversed or refunded. Funds have been returned to the card balance.

​
Transaction Types

TypeDescription
purchaseA standard card purchase at a merchant.
refundA merchant-initiated refund to the card.
atm_withdrawalA cash withdrawal at an ATM (physical cards only).
feeA fee charged to the card (e.g., foreign transaction fee).
authorizationA pre-authorization hold placed by a merchant.

​
Pagination

Use limit and offset for paginating through large transaction histories: 
curl -X GET 'https://crypto-api.yativo.com/api/yativo-card/yc_01HX9KZMB3F7VNQP8R2WDGT4E5/transactions?limit=20&offset=0' \
  -H 'Authorization: Bearer YOUR_API_KEY'
The total field in the response indicates the total number of matching transactions, allowing you to calculate the number of pages: pages = ceil(total / limit).

​
Filtering by Date Range

To export transactions for a specific month: 
curl -X GET 'https://crypto-api.yativo.com/api/yativo-card/yc_01HX9KZMB3F7VNQP8R2WDGT4E5/transactions?from_date=2026-03-01T00:00:00Z&to_date=2026-03-31T23:59:59Z' \
  -H 'Authorization: Bearer YOUR_API_KEY'
If you need to file a dispute on a transaction, see the Disputes documentation. The transaction_id from the transaction list is used when submitting a dispute.

​
Sandbox Testing

Replace YOUR_SANDBOX_TOKEN with a token obtained by authenticating against https://crypto-sandbox.yativo.com/api/. See Sandbox Overview. Card transactions in the sandbox environment return mock data.
curl -X GET 'https://crypto-sandbox.yativo.com/api/yativo-card/yc_sandbox_example/cards/card_sandbox_example/transactions?limit=20&offset=0&status=completed' \
  -H 'Authorization: Bearer YOUR_SANDBOX_TOKEN'