Authentication
How to authenticate with all Volt APIs
All Volt APIs use the same authentication mechanism. Once authenticated, you can access Payments, Verify, and all other Volt services.
One authentication for all APIs. Whether you're using Payments, Verify, or any other Volt service, you authenticate the same way.
Prerequisites
Before you can authenticate, you need credentials from Fuzebox:
| Credential | Where to get it | Purpose |
|---|---|---|
| Client ID | Applications | Identifies your application |
| Client Secret | Applications | Authenticates your application |
| Username | Customer Credentials | Identifies your merchant account |
| Password | Customer Credentials | Authenticates your merchant account |
Quick start
curl -X POST https://api.volt.io/oauth \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=password" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET" \
-d "username=YOUR_USERNAME" \
-d "password=YOUR_PASSWORD"Response:
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 86400,
"refresh_token": "92y..."
}Using your access token
Include the token in the Authorization header for all API requests:
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...Example - Create a payment:
curl -X POST https://api.volt.io/payments \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ ... }'Token management
| Property | Value | Note |
|---|---|---|
| Access token lifetime | 24 hours | Use expires_in from response |
| Refresh token lifetime | 24 hours | Use to get new access token |
Best practice: Cache your access token and reuse it until it expires. Don't request a new token for every API call.
Refreshing tokens
Use the refresh_token to obtain a new access token without re-authenticating:
curl -X POST https://api.volt.io/oauth \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=refresh_token" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET" \
-d "refresh_token=YOUR_REFRESH_TOKEN"Environments
| Environment | OAuth URL | API URL |
|---|---|---|
| Sandbox | https://api.sandbox.volt.io/oauth | https://api.sandbox.volt.io |
| Production | https://api.volt.io/oauth | https://api.volt.io |
Always test in Sandbox first. Use the toggle in Fuzebox (top-right) to switch between environments. Generate separate credentials for each environment.
Customer types
Depending on your role, authentication works slightly differently:
Merchants
Standard authentication with your own credentials.
PSPs (Payment Service Providers)
Authenticate with your application credentials, then use merchant-specific username/password for each merchant you support.
TSPs (Technical Service Providers)
Similar to PSPs - your application credentials plus merchant-generated username/password.
Error handling
| HTTP Status | Meaning | Action |
|---|---|---|
401 Unauthorized | Invalid or expired token | Re-authenticate |
403 Forbidden | Valid token, insufficient permissions | Check scopes/permissions |
Next steps
How is this guide?
Last updated on