The Valpay APIs let you manage merchants, stores, transactions, deposits, disputes, payments, and related resources. This guide covers the basics you need before calling any endpoint.

Base URLs

The API is split across three services, each versioned under the /v1 prefix:

Each resource page notes the base URL when an endpoint is served from a host other than api.valpay.com.

Conventions

The API speaks JSON: send Content-Type: application/json on requests with a body, and expect JSON responses. List endpoints support pagination, MongoDB Query Language (MQL) filtering and sorting, and field selection.

Authentication

Every endpoint requires a JWT Bearer token in the Authorization header. Most Core API and Payments endpoints also require an API key in the X-API-KEY header; Onboarding endpoints accept either credential. See the Authentication guide for details.

Making your first request

curl "https://api.valpay.com/v1/stores?limit=10&page=0" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY"

curl "https://api.valpay.com/v1/stores?limit=10&page=0" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY"

curl "https://api.valpay.com/v1/stores?limit=10&page=0" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY"

Available resources

The API is organised into the following resource groups, each documented under the API section: Transactions, Deposits, Disputes, Stores, Merchants, Statements, Branding, Terminals, Agreements, TC Documents, Payments, and Shoppers.

Next steps

Read the Authentication, Pagination, and Filtering, Sorting & Fields guides to learn the patterns shared across every list endpoint.