Skip to main content

Onboarding API: authentication and environments

How to authenticate onboarding API requests and which test and production hosts to use.

Every onboarding request is authenticated with one credential, a JWT or an API key, and goes to the test or production hosts.

Authentication

Send exactly one of these headers with each request:

Credential

Header

JWT

Authorization: Bearer <token>

API key

X-API-KEY: <key>

API keys are issued by ValPay Support, for a partner integration or a single merchant. Send request bodies as JSON with Content-Type: application/json.

Environments

Each environment has two hosts: the onboarding host creates merchants and serves the API spec at /api-docs/, and the API host serves lookups such as brands, industry codes and merchants.

Environment

Onboarding host

API host

Test

https://onboarding.valpay.dev

https://api.valpay.dev

Production

https://onboarding.valpay.com

https://api.valpay.com

Both environments run the full onboarding flow. A successful create in test makes a test merchant and sends the same contract and KYC emails that production sends, so use email addresses you can read. Merchants created in production are real merchants.

Build and test against the test hosts, then switch both hosts to production together.

Example

curl "https://api.valpay.dev/v1/brands?limit=100&page=0" \
-H "X-API-KEY: YOUR_API_KEY"
Did this answer your question?