Authentication | Volt Docs

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…

Your client ID and secret – identifies the application you’re using. Find them here in Fuzebox.
Your username and password – identifies the data you want to access. Find them here in Fuzebox.

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 :

200 OK

{
  "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_token
refresh_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.