> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stablemint.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Transactions
> One endpoint, filtered. Every movement of value on your account.
Every movement of value on your account is a transaction — deposits, withdrawals, payouts,
conversions and token transfers, yours and your customers'. They all come from **one endpoint**,
narrowed with filters.
```bash theme={null}
# Your own transactions, most recent first
curl "https://api.stablemint.net/v1/transactions?scope=Partner&sortBy=Date&sortDirection=Descending" \
-H "ApiKey: $STABLEMINT_API_KEY" \
-H "Timestamp: $TIMESTAMP" \
-H "Nonce: $NONCE" \
-H "Signature: $SIGNATURE"
```
**`scope` is how you separate your money from your customers'.** `Partner` returns your own
transactions, `Customer` returns your customers', and `All` returns both — which is rarely what
you want on a reconciliation run.
## Narrowing to one customer
Pass `partnerCustomerGuid` to get a single customer's transactions.
```bash theme={null}
curl "https://api.stablemint.net/v1/transactions?scope=Customer&partnerCustomerGuid=3f2a9c14-7b5e-4d21-9c6a-8e0f1d2b3c45" \
-H "ApiKey: $STABLEMINT_API_KEY" \
-H "Timestamp: $TIMESTAMP" \
-H "Nonce: $NONCE" \
-H "Signature: $SIGNATURE"
```
This replaces the separate per-customer transaction endpoints that used to exist. Everything is
now a filter on `/v1/transactions`, so one code path and one response shape covers every case.
The parameter keeps its wire name, `partnerCustomerGuid` — send it exactly as spelled here.
## Filters
All parameters are optional and combine with AND.
| Parameter | Type | Notes |
| ------------------------- | ------- | ------------------------------------------------------------------------- |
| `page` | integer | 1-based. Defaults to 1. |
| `pageSize` | integer | Items per page. |
| `scope` | string | `Partner`, `Customer` or `All`. |
| `partnerCustomerGuid` | string | A single customer's id. Pair with `scope=Customer`. |
| `partyType` | string | `Partner` or `Customer`. |
| `direction` | string | `Internal`, `Inward` or `Outward`. |
| `category` | string | `Deposit`, `Withdrawal` or `Conversion`. |
| `type` | string | The specific transaction type — see the table below. |
| `method` | string | `Fiat` or `Token`. |
| `status` | string | `Pending`, `Completed`, `Unsuccessful`, `Cancelled` or `Expired`. |
| `currency` | string | ISO 4217, e.g. `EUR`. |
| `from` / `to` | string | ISO 8601 date-time bounds on the transaction date. |
| `minAmount` / `maxAmount` | number | Inclusive amount bounds. |
| `sortBy` | string | `Date`, `Amount`, `Status`, `Type`, `MonitorResultStatus`, `UpdatedDate`. |
| `sortDirection` | string | `Ascending` or `Descending`. |
The response is paginated:
```json theme={null}
{
"items": [ /* ... */ ],
"pageNumber": 1,
"pageSize": 50,
"totalCount": 412,
"totalPages": 9,
"hasNextPage": true,
"hasPreviousPage": false
}
```
## The four ways a transaction is classified
These are independent axes, not a hierarchy. A single transaction has a value for each.
| Axis | Values | Answers |
| ---------------------- | ------------------------------------- | --------------------------------- |
| `category` | `Deposit`, `Withdrawal`, `Conversion` | What kind of movement? |
| `transactionDirection` | `Inward`, `Outward`, `Internal` | Which way relative to StableMint? |
| `method` | `Fiat`, `Token` | Bank rail or blockchain? |
| `partyType` | `Partner`, `Customer` | Whose money? |
Use `scope` to filter; `partyType` is the value you read back on each item.
`transactionType` is the precise label, and is the one to switch on in code:
| Value | Meaning |
| --------------------------------------------------------- | -------------------------------------------------- |
| `PartnerDeposit` / `PartnerWithdraw` | Your own money in or out. |
| `PartnerCustomerDeposit` / `PartnerCustomerWithdraw` | A customer's money in or out. |
| `PartnerCustomerRefund` | A customer deposit returned. |
| `TokenTransferIn` / `TokenTransferOut` | Stablecoin arriving at or leaving your wallet. |
| `Conversion` | An FX conversion between two of your currencies. |
| `CustomerDeposit` / `CustomerWithdraw` / `CustomerRefund` | Legacy direct-customer types. |
| `NotDefined` | Unclassified. Treat as a data issue and report it. |
## List items are trimmed
The list returns enough to render a table. Fetching one transaction returns considerably more —
including the fields you need to investigate a failure. Look it up by its `reference`.
```bash theme={null}
curl https://api.stablemint.net/v1/transactions/QJ7XKDMZRTPW \
-H "ApiKey: $STABLEMINT_API_KEY" \
-H "Timestamp: $TIMESTAMP" \
-H "Nonce: $NONCE" \
-H "Signature: $SIGNATURE"
```
Only on the single-transaction response:
| Field | Why you want it |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `timeline` | Ordered `{ step, status, createdAt }` entries: `Created`, `Initiated`, `Submitted`, `Processing`, `Received`, `Completed`, `Failed`. This is how you find out *where* something stalled. |
| `errorKey` | Why it failed — see [Errors](/guides/errors). |
| `debtorDetails` / `creditorDetails` | Both sides in full: name, IBAN, BIC, country, wallet address. |
| `hasFx`, `userAmount`, `userCurrency`, `fxQuoteExpiryTime` | The FX leg, when there was one. |
| `rail` | `Sepa`, `Swift` or `Wallet`. |
| `idempotencyKey`, `endToEndId`, `sessionId` | Your correlation handles. |
**`reference` is the transaction's id.** It is the value the dashboard shows as the ID, the
string that travels on the payment, and what your customer quotes on a bank transfer — so it is
the one you already have. Every row of the list response carries it.
**This path used to take a numeric `id`, and no longer does.** The list response also carries an
`id`, which is StableMint's internal identifier. It is not the key this endpoint takes, and
passing it now returns `404`.
If your integration passes `id` today, switch to `reference` from the same row. Nothing else
about the call changes.
## Reconciling a deposit
`?scope=Customer&category=Deposit&status=Completed&from=2026-09-01&to=2026-09-30`
If you provisioned the customer a virtual IBAN, the transaction is already attributed. If you
are sharing one IBAN across customers, match on `reference` — see [Customers](/guides/customers).
Fetch it by `id` and read the `timeline`. The last entry tells you which step it is sitting on.
Prefer webhooks to polling. Subscribe to transaction status events and you will be told when
something reaches a terminal state — see [Receiving webhooks](/guides/webhooks).