---
updatedAt: 2026-04-03T20:30:42.000Z
---
Fetch the complete documentation index at: https://developers.privacy.com/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.
# Transactions
Learn more about transactions.
# Transaction Schema
```json
{
"amount": Integer,
"authorization_amount": Integer,
"card_token": String,
"merchant_amount": Integer,
"merchant_authorization_amount": Integer,
"merchant_currency": String,
"acquirer_fee": Integer,
"created": String,
"events": [
Event
],
"funding": [
{
"amount": Integer,
"token": String,
"type": String
}
],
"merchant": Merchant,
"result": String,
"settled_amount": Integer,
"status": String,
"token": String,
"authorization_code": String
}
```
| | |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| amount | Authorization amount of the transaction in the currency's smallest unit (e.g., cents for USD). This may change over time, and will represent the settled amount once the transaction is settled. |
| authorization\_amount | Authorization amount (in cents) of the transaction in the currency's smallest unit (e.g., cents for USD). This amount always represents the amount authorized for the transaction, unaffected by settlement. |
| card\_token | Globally unique identifier for the Card. |
| merchant\_amount | Analogous to the "amount" property, but will represent the amount in the transaction's local currency. |
| merchant\_authorization\_amount | Analogous to the "authorization\_amount" property, but will represent the amount in the transaction's local currency. |
| merchant\_currency | 3-digit alphabetic ISO 4217 code for the local currency of the transaction. |
| acquirer\_fee | Fee (in the currency's smallest unit) assessed by the merchant and paid for by the cardholder. Will be zero if no fee is assessed. Rebates may be transmitted as a negative value to indicate credited fees. |
| created | Date and time when the transaction first occurred. |
| events (Issuing) | A list of all events that have modified this transaction. |
| funding | A list of objects that describe how this transaction was funded, with the `amount` represented in the currency's smallest unit. A reference to the funding source for the card that made this transaction may appear here and the `token` will match the `token` for the funding source in the `card` field. If any promotional credit was used in paying for this transaction, its `type` will be `PROMO`. |
| merchant | See Merchant Schema definition below. |
| result | `APPROVED` or decline reason. See below for full enumeration. |
| settled\_amount | Amount (in cents) of the transaction that has been settled. This may change over time. |
| status | `PENDING`, `VOIDED`, `SETTLING`, `SETTLED`, `BOUNCED`, `DECLINED`. |
| token | Globally unique identifier for the transaction. |
| authorization\_code | A fixed-width 6-digit numeric identifier that can be used to identify a transaction with networks. |
# Event Schema
```json
{
"amount": Integer,
"created": String,
"result": String,
"type": String,
"token": String
}
```
A single card transaction may include multiple events that affect the transaction state and lifecycle.
| | |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| amount | Amount of the transaction event. This is always a positive value, unlike the transaction amount in the [Transaction Schema](https://developers.privacy.com/docs/transactions#transaction-schema). Whether the amount is a debit or credit depends on the event type: `AUTHORIZATION`, `AUTHORIZATION_ADVICE`, and `CLEARING` are debits; `VOID` and `RETURN` are credits. |
| created | Date and time this event entered the system. |
| result | `APPROVED` or decline reason. See below for full enumeration. |
| token | Globally unique identifier for the event. |
| type | `AUTHORIZATION`, `AUTHORIZATION_ADVICE`, `CLEARING`, `VOID`, `RETURN`. |
# Merchant Schema
```json
{
"acceptor_id": String,
"city": String,
"country": String,
"descriptor": String,
"mcc": String,
"state": String
}
```
| | |
| ------------ | ----------------------------------------- |
| acceptor\_id | Identifier for the payment card acceptor. |
| city | City of card acceptor. |
| country | Country of card acceptor. |
| descriptor | Short description of card acceptor. |
| mcc | Merchant category code. |
| state | Geographic state of card acceptor. |
# List Transactions
API Reference: [List transactions](https://developers.privacy.com/reference/get_transactions)
```
GET https://api.privacy.com/v1/transactions
```
#### Sample Request
```bash
curl https://api.privacy.com/v1/transactions?result=APPROVED&page=1&page_size=50 \
-H "Authorization: api-key YOUR_API_KEY"
```
#### Sample Response
```json
{
"data": [
{
"card": {
"created": "2020-07-15T17:48:48Z",
"token": "079d1898-65f7-4d66-b0bc-172d2935a5fa",
"last_four": "6749",
"hostname": "",
"memo": "card 2",
"type": "UNLOCKED",
"spend_limit": 0,
"spend_limit_duration": "TRANSACTION",
"state": "OPEN",
"funding": {
"created": "2020-07-08 17:57:36",
"token": "b0f0d91a-3697-46d8-85f3-20f0a585cbea",
"type": "DEPOSITORY_CHECKING",
"state": "ENABLED",
"nickname": "",
"account_name": "Sandbox",
"last_four": "5263"
},
"auth_rule_tokens": []
},
"amount": -7666,
"authorization_amount": -7666,
"merchant_amount": -7666,
"merchant_authorization_amount": -7666,
"merchant_currency": "USD",
"acquirer_fee": 0,
"created": "2020-07-15T19:17:22Z",
"events": [
{
"amount": 7666,
"created": "2020-07-15T19:17:22Z",
"result": "APPROVED",
"type": "RETURN",
"token": "6a885bcb-89f6-4fcb-a0ce-7f0233ae20a0"
}
],
"funding": [
{
"amount": -7666,
"token": "b0f0d91a-3697-46d8-85f3-20f0a585cbea",
"type": "DEPOSITORY_CHECKING"
}
],
"merchant": {
"acceptor_id": "174030075991",
"city": "NEW YORK",
"country": "USA",
"descriptor": "RESTAURANT ABC",
"mcc": "5812",
"state": "NY"
},
"result": "APPROVED",
"settled_amount": -7666,
"status": "SETTLING",
"token": "764fa5a3-2371-40f0-8cbb-9a2e1230d955",
"authorization_code": "123456"
}
],
"page": 1,
"total_entries": 1,
"total_pages": 1
}
```
| | |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| account\_token *(optional, query parameter)* | Globally unique identifier for the account whose associated transactions should be returned.
*String. Permitted values: 36-digit version 4 UUID (including hyphens).* |
| card\_token *(optional, query parameter)* | Globally unique identifier for the card whose associated transactions should be returned.
*String. Permitted values: 36-digit version 4 UUID (including hyphens).* |
| result *(optional, query parameter)* | Transaction result type to be returned.
*String. Permitted values: `APPROVED`, `DECLINED`.* |
| begin *(optional, query parameter)* | Transaction entries created on or after the specified date will be included.
*String. Permitted values: Date string in the form YYYY-MM-DD.* |
| end *(optional)* | Transaction entries created before the specified date will be included (i.e., transaction entries created on the specified date will not be included).
*String. Permitted values: Date string in the form YYYY-MM-DD.* |
| page\_size *(optional, query parameter)* | For pagination - specifies the number of entries to be included on each page in the response. Default value is 50.
*Integer. Permitted values: 1-1000.* |
| page *(optional, query parameter)* | For pagination - specifies the desired page to be included in the response. For example, if there are 3 total entries, and `page_size` is 2 (i.e., 2 entries per page), then entering the value `2` for `page` would return the second page and only the third entry. The default is one.
*Integer. Permitted values: 1 or greater.* |
# Enumerations
## Transaction.status
| | |
| -------- | -------------------------------------------------------------------------------------------------------- |
| BOUNCED | There was an error settling the transaction against the funding source. Your API account may be disabled |
| DECLINED | The transaction was declined |
| PENDING | Authorization is pending completion from the merchant |
| SETTLING | The merchant has completed the transaction and the funding source is being debited |
| SETTLED | The transaction is complete |
| VOIDED | The merchant has voided the previously pending authorization |
## Transaction.result
| | | |
| :-------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------- |
| ACCOUNT\_STATE\_TRANSACTION\_FAIL | Contact | |
| APPROVED | | Successful transaction; no reason to decline |
| BANK\_CONNECTION\_ERROR | Please reconnect a funding source | |
| BANK\_NOT\_VERIFIED | Please confirm the funding source | |
| CARD\_PAUSED | Card state was paused at the time of authorization | |
| CARD\_CLOSED | Card state was closed at the time of authorization | |
| FRAUD\_ADVICE | Transaction declined due to risk | |
| GLOBAL\_MONTHLY\_LIMIT | Platform spend limit exceeded, contact | |
| GLOBAL\_TRANSACTION\_LIMIT | Platform spend limit exceeded, contact | |
| GLOBAL\_WEEKLY\_LIMIT | Platform spend limit exceeded, contact | |
| INACTIVE\_ACCOUNT | Contact | |
| INCORRECT\_PIN | PIN verification failed | |
| INSUFFICIENT\_FUNDS | Please ensure the funding source is connected and up to date | |
| INSUFFICIENT\_FUNDS\_PRELOAD | Result given when client responds to ASA request with `INSUFFICIENT_FUNDS`. See [ASA Response Result](https://developers.privacy.com/docs/auth-stream-access-asa#asa-response-result) | |
| INVALID\_CARD\_DETAILS | Incorrect CVV or expiry date | |
| MERCHANT\_BLACKLIST | This merchant is disallowed on the platform | |
| SINGLE\_USE\_RECHARGED | Single-use card attempted multiple times | |
| SWITCH\_INOPERATIVE\_ADVICE | Network error, re-attempt the transaction | |
| UNAUTHORIZED\_MERCHANT | Merchant locked card attempted at different merchant | |
| UNKNOWN\_HOST\_TIMEOUT | Network error, re-attempt the transaction | |
| USER\_TRANSACTION\_LIMIT | User-set spend limit exceeded | |