Balance by id
GET /api/v1/external/customers/:id/wallet
Returns the current balance of the customer's wallet. Requires scope wallet:read.
Request
curl https://api.nuvlyx.com/api/v1/external/customers/9f8e…/wallet \
-H "Authorization: Bearer nvl_live_YOUR_TOKEN"Response 200
{
"id": "wallet_…",
"balance": "25000.00",
"currency": "COP",
"updatedAt": "2026-05-18T10:21:00.000Z"
}Balance by phone
GET /api/v1/external/customers/by-phone/:phone/wallet
Returns the customer's balance identifying them by their WhatsApp number.
The customer must have linked their WhatsApp beforehand from their
profile in the store. Otherwise the API returns 404 with an explicit
message.
Path parameters
| Parameter | Format | Example |
|---|---|---|
phone | E.164 (with +) | %2B573001234567 (URL-encoded) |
Request
curl "https://api.nuvlyx.com/api/v1/external/customers/by-phone/%2B573001234567/wallet" \
-H "Authorization: Bearer nvl_live_YOUR_TOKEN"Recharge wallet (by id)
POST /api/v1/external/customers/:id/wallet/recharge
Credits the given amount to the customer's wallet. Internally creates a
WalletTransaction of type MANUAL_ADJUSTMENT — equivalent to a manual
recharge approval. Requires scope wallet:write.
Body
| Field | Type | Description |
|---|---|---|
amount | number | Positive amount to credit (1 – 100,000,000). Max 2 decimal places. |
reference | string | Readable reference (e.g. "Bot WhatsApp - sale #..."). Stored in the ledger. Optional. |
Request
curl -X POST https://api.nuvlyx.com/api/v1/external/customers/9f8e…/wallet/recharge \
-H "Authorization: Bearer nvl_live_YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "amount": 50000, "reference": "Nequi payment #PAGO-0042" }'Recharge wallet (by phone)
POST /api/v1/external/customers/by-phone/:phone/wallet/recharge
Same operation, identifying the customer by their linked phone.
Why customers must link their WhatsApp
For security and customer consent, the API does not auto-create customers
from a phone number received via API. The customer confirms their number from
their profile in the store by receiving a code over WhatsApp. Once linked,
the number is bound to the tenant (phone_verified_at is timestamped).
This prevents mass creation of phantom customers via external integrations and keeps a clear opt-in flow.