Error codes

The below error code information is important in the context of our APIs.


Response body

The following response body is consistent across API methods and signifies that an error has occurred. In addition, it provides a way to ensure that the error response was generated by the API method being accessed (for example, when the resource id provided does not correspond to any known system entity) and not by the web server (for example, when the supplied URL is undefined).

ParameterDescription
statusThe HTTP status code returned by the API
messageThe reason phrase of status code, usually contains a description of the eventId
eventIdThe event identifier corresponding to the event

Response codes

Viva Wallet uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 200 range indicate success. 400 codes indicate a client-side error. 500 codes indicate an error with Viva Wallet’s servers.

Common status codeMeaningReason phrase
200OKEverything worked as expected
400Bad requestThe request was unacceptable, often due to missing a required parameter.
401UnauthorizedNo valid API key provided.
403ForbiddenYou are not authorized to access the requested resource.
404Not foundThe requested resource doesn't exist.
405Method not allowedYou tried to access a resource using an invalid method.
406Not acceptableYou requested a format that isn't json.
409ConflictThe request could not be completed due to a conflict (usually during a PUT or POST)
410GoneThe resource you requested no longer exists.
429Too many requestsYou have reached the request threshold. The resource is temporarily locked.
500, 502, 504Server errorSomething went wrong at our end. Try again later.
503Service unavailableWe're temporarily offline for maintenance. Try again later.

The reason phrase will usually contain either a specific explanation on why the request could not be completed successfuly or, the definition of the eventId in the case that an event has occured.


Request format

There are several cases where a request parameter, either query param or body property, does map directly to a scalar value type or must be entered in a special format (ISO).

Country codes must conform to the ISO 3166-1 alpha-2 code.

Dates must conform to the ISO 8601 and specifically be entered in the following format 2018-11-12T14:31:58+00:00 in order for the time offset to be specified correctly.

Currency fields must conform to the ISO 4217 in numeric form.


Rejection reasons

Any of the following card issuer, system or user error messages can be returned during a transaction attempt.

The below table applies to Visa and Mastercard transactions only. AMEX does not use ISO response codes currently.

ISO response code x-viva-eventId Type Response message Further details if applicable
00 10000 Issuer Approved Transaction approved successfully.
01 10001 Issuer Refer to card issuer The issuing bank prevented the transaction.
03 10003 Issuer Invalid merchant Security violation (source is not correct issuer).
04 10004 Issuer Pickup card The card has been designated as lost or stolen.
05 10005 Issuer Do not honor The issuing bank declined the transaction without an explanation.
06 10006 Issuer General error The card issuer has declined the transaction as there is a problem with the card number.
12 10012 Issuer Invalid transaction The bank has declined the transaction because of an invalid format or field. This indicates the card details were incorrect.
13 10013 System Invalid amount The card issuer has declined the transaction because of an invalid format or field.
14 10014 User Invalid account number The card issuer has declined the transaction as the credit card number is incorrectly entered or does not exist.
30 10030 System Format error The card issuer does not recognise the transaction details being entered. This is due to a format error.
41 10041 issuer Lost card The card issuer has declined the transaction as the card has been reported lost.
43 10043 user Stolen card The card has been designated as lost or stolen.
51 10051 issuer Insufficient funds The card has insufficient funds to cover the cost of the transaction.
54 10054 user Expired card The payment gateway declined the transaction because the expiration date is expired or does not match.
55 10055 user Incorrect PIN Incorrect PIN.
57 10057 issuer Transaction not permitted to cardholder The card issuer has declined the transaction as the credit card cannot be used for this type of transaction.
58 10058 issuer Transaction not permitted to terminal The card issuer has declined the transaction as the credit card cannot be used for this type of transaction.
61 10061 issuer Activity amount limit exceeded Exceeds withdrawal amount limit.
62 10062 issuer Restricted card The customer's bank has declined their card.
65 10065 issuer Activity count limit exceeded The customer is over their credit limit or this transaction would put them over it.
70 10070 issuer Call issuer Contact card issuer.
75 10075 user PIN entry tries exceeded Allowable number of PIN tries exceeded.
76 10076 system Invalid/nonexistent "to account" specified Invalid/nonexistent OR Invalid/nonexistent specified.
96 10096 system System malfunction A temporary error occurred during the transaction.