Getting started
To access the API, you’ll need a token – and to get a token you’ll need to tell us the application you’re using to access the API and which data you’re trying to access. You can get both sets of credentials from Fuzebox.
We use the industry-standard oAuth2.0 protocol to authenticate, and you’ll need…
Note for PSPs
You should use your own client ID and secret, with the specific credentials (API username and password) of the individual merchant data you wish to access.
Generate an access token
To generate a token, you’ll need send a POST request to the /oauth
API endpoint with the following details:
Request location
We recommend using the Sandbox environment for testing your end-to-end process.
- Sandbox
- Production
POST https://api.sandbox.volt.io/oauth
POST https://api.volt.io/oauth
Request headers
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Request parameters
client_id |
Client ID for your application (from Applications in Fuzebox) |
client_secret |
Client secret for your application (from Applications in Fuzebox) |
username |
From credentials (from Customers in Fuzebox) |
password |
From credentials in Customers in Fuzebox) |
grant_type |
Must be set to password |
Successful authentication
If you’ve successfully authenticated, the response should look like this :
{
"token_type": "Bearer",
"expires_in": 3600,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijc2MGEwNDRkMDkwZmUxNmE0YzRkMWRjMWE5NDU1MTgxMzgxZDRkNDIyZGUyNDY5NjQ0NDI4NWNkZjk1NWJkMzBjMjcxYzYxNjE0MzkyMmI0In0.eyJhdWQiOiI2NjIzODRhMC05NzE0LTQ2NTYtYTNiZC0zZjFlNzc0ZTJhM2MiLCJqdGkiOiI3NjBhMDQ0ZDA5MGZlMTZhNGM0ZDFkYzFhOTQ1NTE4MTM4MWQ0ZDQyMmRlMjQ2OTY0NDQyODVjZGY5NTViZDMwYzI3MWM2MTYxNDM5MjJiNCIsImlhdCI6MTU2MjA0MzA1OSwibmJmIjoxNTYyMDQzMDU5LCJleHAiOjE1NjIwNDY2NTksInN1YiI6IjQyMzc5YjQ5LWJjYTItNDhkNy05ZmQ4LTRlNTMwYzliM2VkNyIsInNjb3BlcyI6WyJiYW5rcyIsInBheW1lbnRzIiwiYWRtaW4iXX0.Twey0UPvEfx2ITbPEW2ATlsYYwRB_Ts_Hl2kBiHv0mP42jNB7B5xdftjvr4JzMVUzbXmv7161L7gvcrTMHEZvqcqppcLYsFzbVLViZsxT8oktrQdX6wjx5f2OYkG1Cbrxgc8fR4BBh84kSYwfHMoPEWVdTJTb27nmyWSIqxmpUX6U-8ZKzu2eHZ2YnyDD-aS4PGv6bDKBZXsC369hBmQY6mpvLKhv67mT52E1MFhTv8kI7ALiQx5BUW6IOuuqUQ_6f5mIBu_9Dzul_2cqhVFVOGw-hmoXlEr0cehfPI7UoDk70icozKjpfEiNuqAMwddsPHUdC_F_n1hAeBoplzOfQ",
"refresh_token": "def50200fd32e987655dbdbfa15b0acb5b9e9b6f56c245fc4d92db02a0f60a8fbd664249959aff1f311109a26305fb4f26417db1f318203505172830f9a1db170e9affd0890dcc77f1db713993b9de26680d86127b4320b160fc477827d34103997847ac65d505a34b4d9183fd54c619171de4f4b32cba1bbff9f4eac8131a26b9b8aa666ca0adb79ce23a5e23f4f89a9e537d9379796655803160c04977ea1cbb8f2bd534a500f64a5f66b6763c30268eb8064a9957f4fadd39e478cd64b24b252516b23b55615a581b989dbc5eee36f378a40405de7285a199cb8dfc1446a1851ea73c7b6ed3cdeca7055a09a600f9a7b72a6c4240e0ce3a31de85c0f791a6babc765bf6c94661892a18e338412115b1a397bd814738f08e9ae0f7dbadcab0f419f68b9275d643a99c7ffe3e6c2f3eb66ed16114d3d6dd0fb7f219dc3cb77011ef2f0080beff8f89e7f2ebf9e83356181cb7ff4bf6fcdd0592a9f773866be50aae6713319f8dca4eb454d84affbaf24eb2af0009e67f68ceb4c1188aae0809f010fb5b271ca33723c67f8e3dd8ab99ac1508985e43ba03e30cecff766b9354b38d98e911b5883319e031389703d19e62d826a79456d17801b48c197aef9c11a29ed2"
}
Unsuccessful authentication
If your authentication was not successful, you’ll receive an HTTP 401
code in the response. Please check that both sets of credentials are being supplied correctly, and that you’ve set the grant_type
to password in the request.
Using your access token
An access_token
is valid for one hour once authenticated, as indicated by the expires_in
value in the response. You were also supplied a refresh_token
in the authentication response, which will be valid for 24 hours, and which allows you to obtain a new access_token.
To access the other endpoints in our API, you’ll need to send the access_token
in an HTTP header called “Authorization” in the format “Bearer {access_token}”. Note that Authorization must be spelled the American way and there’s a single space between Bearer and your access token.
Using the access_token
from our successful authentication above, you would send an http header :-
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijc2MGEwNDRkMDkwZmUxNmE0YzRkMWRjMWE5NDU1MTgxMzgxZDRkNDIyZGUyNDY5NjQ0NDI4NWNkZjk1NWJkMzBjMjcxYzYxNjE0MzkyMmI0In0
Refreshing your token
For security reasons an access_token
expires after one hour. If your application needs to access our API beyond that time, you can generate a new one using the refresh_token that you received when you authenticated.
To do this, send a POST request to the /token/refresh
endpoint with the following:
grant_type
: should be set to refresh_tokenrefresh_token
: will be the contents of the refresh_token you received when you authenticated
You’ll be issued a new access_token
which will provide access to the API for another hour, as well as an updated refresh_token
(you can now discard the original refresh_token
).
Please note that each refresh_token
expires after 24 hours. If you need another, simply repeat the steps for generating an access token.
Need help?
If you’re unable to authenticate, or need help implementing any feature of our API, we’re here to help. Please send an email to our support team and we’ll get back to you as soon as we can.