Developers

Search for documents

Dev

Transactions

Operations related to transactions

All endpoints require a JWT Bearer token in the Authorization header; most also require an API key in the X-API-KEY header.

GET `/v1/transactions`

Get a list of transactions with pagination

Parameters

Name	In	Type	Required	Description
`limit`	query	`integer`	Yes	Maximum number of records to return. Starts from 1 to 1000.
`page`	query	`integer`	Yes	Page number to retrieve, starting from 0.
`selectFields`	query	`string`	No	Choose specific fields to include in the response (comma-separated). If provided, excludeFields will be ignored.
`excludeFields`	query	`string`	No	Exclude specific fields from the response (comma-separated).
`filter`	query	`string`	No	JSON object representing filter criteria in MongoDB Query Language (MQL) format.
`sort`	query	`string`	No	JSON object representing sort criteria in MongoDB Query Language (MQL) format.
`populateOptions`	query	`string`	No	Include related data in query results using a JSON object.

Responses

Status	Description
`200`	Successfully retrieved a paginated list of transactions.

GET `/v1/transactions/{id}`

Get a specific transaction by ID

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	The transactionId field
`selectFields`	query	`string`	No	Choose specific fields to include in the response (comma-separated). If provided, excludeFields will be ignored.
`excludeFields`	query	`string`	No	Exclude specific fields from the response (comma-separated).
`populateOptions`	query	`string`	No	Include related data in query results using a JSON object.

Responses

Status	Description
`200`	Transaction details retrieved successfully

PATCH `/v1/transactions/{id}`

Update a transaction's customFields

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	The transactionId field

Request body (required)

Field	Type	Required	Description
`customFields`	`object`	Yes	Custom fields to store on the transaction. On update: arrays are merged by label (incoming labels overwrite existing; new labels append). Passing an empty array for a field resets that list to empty.

Responses

Status	Description
`200`	Transaction updated successfully

Examples

GET `/v1/transactions`

First page of USD transactions, newest first:

curl "https://api.valpay.com/v1/transactions?limit=10&page=0&filter=%7B%22currency%22%3A%22USD%22%7D&sort=%7B%22date%22%3A-1%7D" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY"

curl "https://api.valpay.com/v1/transactions?limit=10&page=0&filter=%7B%22currency%22%3A%22USD%22%7D&sort=%7B%22date%22%3A-1%7D" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY"

curl "https://api.valpay.com/v1/transactions?limit=10&page=0&filter=%7B%22currency%22%3A%22USD%22%7D&sort=%7B%22date%22%3A-1%7D" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY"

Response 200 (illustrative):

{
  "data": [
    {
      "_id": "665f1e2a9c8b4a0012d3e4f1",
      "transactionId": "TXN_EXAMPLE_001",
      "storeId": "665f1e2a9c8b4a0012d3e4b1",
      "amount": { "value": 2599, "currency": "USD" },
      "status": "Settled",
      "date": "2026-06-10T15:21:00.000Z"
    }
  ],
  "total": 412,
  "page": 0,
  "limit": 10
}

{
  "data": [
    {
      "_id": "665f1e2a9c8b4a0012d3e4f1",
      "transactionId": "TXN_EXAMPLE_001",
      "storeId": "665f1e2a9c8b4a0012d3e4b1",
      "amount": { "value": 2599, "currency": "USD" },
      "status": "Settled",
      "date": "2026-06-10T15:21:00.000Z"
    }
  ],
  "total": 412,
  "page": 0,
  "limit": 10
}

{
  "data": [
    {
      "_id": "665f1e2a9c8b4a0012d3e4f1",
      "transactionId": "TXN_EXAMPLE_001",
      "storeId": "665f1e2a9c8b4a0012d3e4b1",
      "amount": { "value": 2599, "currency": "USD" },
      "status": "Settled",
      "date": "2026-06-10T15:21:00.000Z"
    }
  ],
  "total": 412,
  "page": 0,
  "limit": 10
}

GET `/v1/transactions/{id}`

curl "https://api.valpay.com/v1/transactions/TXN_EXAMPLE_001?selectFields=transactionId,amount,status" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY"

curl "https://api.valpay.com/v1/transactions/TXN_EXAMPLE_001?selectFields=transactionId,amount,status" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY"

curl "https://api.valpay.com/v1/transactions/TXN_EXAMPLE_001?selectFields=transactionId,amount,status" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY"

Response 200: the transaction object.

PATCH `/v1/transactions/{id}`

curl -X PATCH https://api.valpay.com/v1/transactions/TXN_EXAMPLE_001 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customFields": {
      "tags": [ { "label": "order", "value": "SO-1042" } ]
    }
  }'

curl -X PATCH https://api.valpay.com/v1/transactions/TXN_EXAMPLE_001 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customFields": {
      "tags": [ { "label": "order", "value": "SO-1042" } ]
    }
  }'

curl -X PATCH https://api.valpay.com/v1/transactions/TXN_EXAMPLE_001 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customFields": {
      "tags": [ { "label": "order", "value": "SO-1042" } ]
    }
  }'