Transaction List

Retrieve a paginated list of your transactions with rich filter options. Use this endpoint for reconciliation, reporting, and transaction lookups.

INFO

Service available in Mexico only.

Requirements

A valid account

Your user token

Environments

Environment	Base URL
Dev	`https://valquiria.billpocket.dev`
Live	`https://valquiria.billpocket.com`

Authentication flow

The Transaction List API uses a short-lived JWT. Exchange your user token for a session token before querying.

WARNING

Session token expires after 6 hours.

1. Get a session token

POST /api/v1/token

{
  "token": "your-user-token"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

2. Query the transaction list

GET /api/v1/transactions?dateFrom={ISO8601}&dateTo={ISO8601}

Pass the session token in the Authorization header.

https://valquiria.billpocket.dev/api/v1/transactions?dateFrom=2024-01-01T00:00:00&dateTo=2024-01-31T23:59:59

Response:

{
  "data": [
    {
      "transaction_id": 105242,
      "authorization_number": "BP4460",
      "bank": "BANCOMER",
      "card_brand": "Visa",
      "card_type": "CREDIT",
      "capture_method": "ec",
      "commission": 8.94,
      "countercharged": false,
      "date": "2024-01-15T13:48:12.000Z",
      "details": "Product description",
      "device": "Terminal-001",
      "error_detail": "",
      "masked_card": "424242******4242",
      "msi": null,
      "retention": 0.93,
      "rejection_code": null,
      "subtotal": 437.71,
      "surcharge": 0,
      "tip": 0,
      "total_amount": 449,
      "transaction_type": "venta",
      "transaction_status": "aprobada",
      "vat": 1.43
    }
  ],
  "currentPage": 1,
  "perPage": 100,
  "total": 456
}

Available filters

Append query parameters to narrow results:

Parameter	Description
`dateFrom`	Start date (ISO 8601, e.g., `2024-01-01T00:00:00`)
`dateTo`	End date (ISO 8601)
`size`	Results per page
`page`	Page number
`device`	Filter by device name
`bin`	Filter by card BIN
`captureMethod`	`ec`, `nfc`, `msc`, etc.
`transactionStatus`	`aprobada`, `rechazada`, `rechazadaRiesgo`, etc.
`transactionType`	`venta`, `devolucion`
`card`	Masked card number
`uniqueReference`	Reference from Cloud Terminal API (v2+)
`timezone`	Timezone for date filtering (v4+)

Example with filters:

GET /api/v1/transactions?dateFrom=2024-01-01T00:00:00&dateTo=2024-01-31T23:59:59&captureMethod=ec&transactionStatus=aprobada&page=1&size=50

API versions

Version	Key changes
v1	Original. Snake case field names
v2	Camel case fields, `uniqueReference` filter, `chargeback` field
v3	`rejectionCode`, `finalAmount`, `msiFee`, `refundedTransactionId` renamed
v4	`timezone` filter, RFC 9557 date format

Next steps

Review the Transaction List API reference

Got a suggestion on this documentation? Contact us.

Transaction List

Transaction List#

Requirements#

Environments#

Authentication flow#

1. Get a session token#

2. Query the transaction list#

Available filters#

API versions#

Next steps#

Transaction List

Requirements

Environments

Authentication flow

1. Get a session token

2. Query the transaction list

Available filters

API versions

Next steps