Merchant API
Authentication and verification requests for websites and online stores.
The Merchant API lives under /api/v1/merchant/. Every call carries the organisation's API key in the X-Api-Key header. Keys are created in the business cabinet under API keys; a key is shown once, at creation.
Two key modes exist: va_test_… keys return every request as already approved and never reach real customers; va_live_… keys are for production.
Check the key
GET /api/v1/merchant/ping
X-Api-Key: va_live_…
Returns ok, your organisation name, the key mode and the public links (website and store pages).
Create a verification request
POST /api/v1/merchant/verify-requests
X-Api-Key: va_live_…
Content-Type: application/json
{ "external_reference": "order-10432", "callback_url": "https://shop.example/verifage/callback" }
Both fields are optional. The response contains:
| Field | Meaning |
|---|---|
id |
Public id of the request, used in GET and in the callback |
public_code |
Short code the customer can type in the app |
qr_url |
Image of the QR that opens the request in the app |
app_url |
Universal link for a button on a phone |
status |
pending, approved, denied or expired |
verified |
true once approved, otherwise false |
expires_at |
72 hours after creation |
Read a request
GET /api/v1/merchant/verify-requests/{id}
Poll this endpoint while the customer is approving, or rely on the callback. Polling is rate-limited; once every 2–3 seconds is plenty.
Errors
The API uses standard HTTP codes: 401 for a missing or revoked key, 404 for a request that belongs to another organisation, 422 for invalid fields, 429 when a rate limit is hit. The body is JSON with a message.