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
StatusHTTP status code returned by the API. See Response codes.
x-viva-eventIdEvent identifier corresponding to the event. See Rejection reasons.
Response messageReason phrase of status code, usually contains a description of x-viva-eventId. See Rejection reasons.

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.

StatusMeaningMessage
200OKThe request has succeeded. The meaning of the success depends on the HTTP method:
  • GET
    The resource has been fetched and is transmitted in the message body.
  • PUT or POST
    The resource describing the result of the action is transmitted in the message body.
400Bad requestThe server could not understand the request due to invalid syntax.
401UnauthorizedAlthough the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response.
403ForbiddenThe client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401, the client's identity is known to the server.
404Not foundThe server can not find requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist.
405Method not allowedThe request method is known by the server but has been disabled and cannot be used.
406Not acceptableYou requested a format that isn't JSON.
409ConflictThis response is sent when a request conflicts with the current state of the server.
410GoneThis response is sent when the requested content has been permanently deleted from server, with no forwarding address.
429Too many requestsThe user has sent too many requests in a given amount of time ('rate limiting').
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 contain either an explanation of why the request could not be completed successfuly, or, an event ID corresponding to a sub-status.

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):

Rejection reasons

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

The table below applies to Visa and Mastercard transactions only. AMEX payments are excluded currently.

x-viva-eventId Reason Explanation Type
10001 Refer to card issuer The issuing bank prevented the transaction. Issuer
10003 Invalid merchant number Security violation (source is not correct issuer). Issuer
10004 Pick up card The card has been designated as lost or stolen. Issuer
10005 Do not honor The issuing bank declined the transaction without an explanation. Issuer
10006 General error The card issuer has declined the transaction as there is a problem with the card number. Issuer
10012 Invalid transaction The bank has declined the transaction because of an invalid format or field. This indicates the card details were incorrect. Issuer
10013 Invalid amount The card issuer has declined the transaction because of an invalid format or field. System
10014 Invalid card number The card issuer has declined the transaction as the credit card number is incorrectly entered or does not exist. User
10030 Format error The card issuer does not recognise the transaction details being entered. This is due to a format error. System
10041 Lost card The card issuer has declined the transaction as the card has been reported lost. Issuer
10043 Stolen card The card has been designated as lost or stolen. User
10051 Insufficient funds The card has insufficient funds to cover the cost of the transaction. Issuer
10054 Expired card The payment gateway declined the transaction because the expiration date is expired or does not match. User
10055 Incorrect PIN Incorrect PIN. User
10057 Function not permitted to cardholder The card issuer has declined the transaction as the credit card cannot be used for this type of transaction. Issuer
10058 Function not permitted to terminal The card issuer has declined the transaction as the credit card cannot be used for this type of transaction. Issuer
10061 Withdrawal limit exceeded Exceeds withdrawal amount limit. Issuer
10062 Restricted card The customer's bank has declined their card. Issuer
10065 Activity count limit exceeded The customer is over their credit limit or this transaction would put them over it. Issuer
10070 Call issuer Contact card issuer. Issuer
10075 PIN entry tries exceeded Allowable number of PIN tries exceeded. User
10076 Invalid / non-existent "to account" specified Invalid / non-existent OR Invalid / non-existent specified. System
10096 System malfunction A temporary error occurred during the transaction. System