FAQs and common issues

We have many customers calling the API and most of the time everything works just as you would expect, but sometimes things go wrong and the following contains a few examples of things you can try to determine the cause of the issue.

If you are having problems we suggest the use of two tools that can be invaluable in debugging HTTP requests :-

The first is Fiddler which acts as a proxy for your web requests - it can record what's being sent to our API and what is returned.

The second is a plug-in for Google Chrome called Postman which is invaluable in making API calls.

What environment are you calling?

When calling the Staging environment you need a token that was created for staging, so need to login to here to generate that token.

When calling the Live environment, you not only need a token that was created for Live, but you also need to have provided us with the IP address(es) of any server(s) you are using to call our system. For security reasons we maintain an IP whitelist in Live, and if the machine you are calling from is not on this list, you will receive no response at all. This is by design.

What HTTP error code are you receiving?

If you are receiving a 4xx error code then it's likely that that the request being sent is at issue, double check that everything is correct. The JSON view in Fiddler is useful here, you may have omitted a brace - { or }.

The most common error message is 401 Unauthorized which simply means that the request you are making does not contain a valid token. Please check that the token contains the appropriate Role to call the given endpoint. Each of our API definitions in the documentation contains details of the Role required to call it. You can use a 3rd party tool such as http://jwt.io to look at your token to see what role(s) it contains.

What error message are you receiving?

We’ve tried to be as specific as possible with error messages, from describing issues with tokens to describing mandatory/optional requirements and lengths on fields. It’s uncommon that we won’t have come across your issue and added a specific error message for it – but if we haven’t, please send us the request you are sending (as a trace from Fiddler) and the response (again copied from the Raw view in Fiddler) and we’ll take a look.

Can you manually call the API?

If you’ve written code to integrate with the API and it’s not working, try the same request in Postman.

We found an issue recently with someone calling our API from Node.js that was tracked down to a bug in Node – so even if you think your code is correct (it might be!) there’s often a layer beneath your code that errors could be lurking in.

We have an extensive set of automated tests that call our API, and a number of other customers calling it too, so we find that issues calling the API are generally code related - by using a tool such as Postman it's often possible to work out the issue isn't our API but the code that's calling it.

If all else fails...

• Is the API token valid? These can be invalidated in MAS so it’s worth checking. Tokens have a built in expiration date so it's worth checking that you are using a token that has not expired. You need to obtain new tokens from us periodically. This is a security feature, you don’t want tokens to be valid indefinitely. Tokens can expire automatically (i.e. they go past their end date) or manually (by someone revoking the token in MAS).

{
  "Code": "TokenRevoked",
  "Message": "The token presented to the API has been revoked and can no longer be used. Please use another token.",
  "MoreInfo": "https://docs.vitessepsp.com/reference#section-tokenrevoked"
}

• Does the token you are using contain the appropriate roles? You can copy the token to http://jwt.io and that will show the content of the token and each role it contains. You’ll get a “401 Unauthorized” response if you call an API with a token that does not contain the correct role for that particular API. Please check out the documentation on the individual API's as each specifies the necessary Role your token needs to possess in order to call that API.
• Have you specified the correct headers in the call? We need need Authorization: Bearer xxx.yyy.zzz and ContentType: application/json. Anything else is unnecessary.
• Are you specifying the correct URL for the API? Our staging API is at https://staging-api.vitessepsp.com/api/xxxx - where xxxx is replaced with the endpoint you want to call, such as transactionRequests or accounBalances.
• Are you using a token for the correct environment? Tokens are environment specific - so you cannot use a Live token for Staging and vice-versa. To check which environment a token is valid for, please post it into https://jwt.io and look at the iss claim. This should be https://staging-api.vitessepsp.com for Staging, and https://api.vitessepsp.com for Live. If you use a token for the incorrect environment you will receive an error such as as the following.

{
  "Code": "TokenInvalidSignature",
  "Message": "The signature of the token is missing or invalid",
  "MoreInfo": "https://docs.vitessepsp.com/reference#section-tokeninvalidsignature"
}

• Are you calling from the right environment?

The API is designed to be called from another server, not from a client (such as Javascript running in a browser). If you are attempting to call directly from a browser you'll receive some CORS errors such as "The Same Origin Policy disallows reading the remote resource at XXXX".

Calling our API from a browser isn't supported for security reasons, as you'd need to include the API token with any request and this could be hijacked from the browser. In addition, in our Live environment we lock down access using IP Addresses, and only add addresses of your servers to this whitelist. So, please ensure you're calling us from a "back-end" environment rather than from the browser.

• Are you specifying https?

If you have tried all of the above and it's still not working please contact us - we're here to help.  [email protected]