Partner API documentation
Technical reference for the ValyutaMobile Partner API: endpoints, authentication and response formats.
https://valyutamobile.com/wp-json/valyutamobile/v1Authentication
Protected requests require a Bearer token and HMAC SHA-256 signature.
- Use a vm_test_ token for testing.
- Send a unique nonce with each request.
- Keep live tokens server-side only.
TOKEN='vm_test_YOUR_TOKEN'
TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
METHOD='GET'
TARGET='/wp-json/valyutamobile/v1/catalog?page=1&per_page=20'
BODY=''
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 | awk '{print $2}')
CANONICAL=$(printf '%s\n%s\n%s\n%s' "$TS" "$METHOD" "$TARGET" "$BODY_HASH")
SIGNATURE=$(printf '%s' "$CANONICAL" | openssl dgst -sha256 -hmac "$TOKEN" | awk '{print $2}')
curl "https://valyutamobile.com$TARGET" \
-H "Authorization: Bearer $TOKEN" \
-H "X-VM-Timestamp: $TS" \
-H "X-VM-Nonce: $NONCE" \
-H "X-VM-Signature: $SIGNATURE"{
"success": true,
"data": {
"items": [],
"page": 1,
"per_page": 20,
"total": 0,
"total_pages": 0
}
}Sandbox
A vm_test_ token runs in the test environment and does not change the live balance.
test_scenario | Result |
|---|---|
completed | Successful test response |
processing | Processing test response |
failed | Failed test response |
insufficient_balance | Balance error test |
POST /sandbox/reset resets the test balance.
Catalog
/catalog?page=1&per_page=100&search=&category=Read product and category data from the API. Use product id and fields values when creating orders. API v1 supports fixed denominations. Variable-amount top-ups are unavailable through the API; previously synced IDs are rejected before charging.
Respect each field type. If dynamic_options=true, fetch current choices via GET /products/{id} before checkout. For select fields submit options.value, not options.label. Do not accept orders with unavailable fields or empty required lists. Send numbers as strings too; number_format specifies integer or decimal.
GET /catalog?page=1&per_page=100
GET /categories
GET /products/{vm_prod_id}{
"success": true,
"data": {
"items": [{
"id": "vm_prod_a1b2c3",
"name": "Example product",
"price": 9.50,
"currency": "AZN",
"stock_status": "in_stock",
"fields": [{"key":"user_id","label":"User ID","type":"text","required":true}]
}],
"page": 1,
"total": 1
}
}Create order
/ordersSend product data and a unique Idempotency-Key with POST /orders.
The example test_scenario is for vm_test_ tokens only; omit it from live orders.
{
"external_order_id": "shop-1058-line-1",
"product_id": "vm_prod_a1b2c3",
"quantity": 1,
"fields": {"user_id": "123456", "server_id": "EU"},
"test_scenario": "completed"
}{
"success": true,
"data": {
"id": "vm_order_8f2d1c",
"external_order_id": "shop-1058-line-1",
"status": "completed",
"amount": 9.50,
"currency": "AZN",
"environment": "sandbox",
"delivery": {"text": "TEST-CODE-1234", "images": []}
}
}Order status
/orders/{vm_order_id}GET /orders/{id} returns the current status and available delivery data.
GET /orders/vm_order_8f2d1c{
"success": true,
"data": {"id":"vm_order_8f2d1c","status":"completed","refunded":false}
}Balance
/balanceGET /balance returns the balance for the current token environment.
GET /balance
GET /wallet/transactions?page=1&per_page=50{
"success": true,
"data": {"balance":1000.00,"currency":"AZN","environment":"sandbox"}
}Webhook
order.updated events can be sent as signed webhook requests. Verify the signature and return 2xx.
X-VM-Webhook-SignatureAPI console
Use only a vm_test_ token when testing requests.
Response will appear here.
Errors & limits
| HTTP | Meaning |
|---|---|
400/422 | Invalid request or data |
401/403 | Authentication or access error |
402 | Insufficient balance |
409 | Conflict or unavailable resource |
429 | Request limit exceeded |
5xx | Temporary server error |