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).
| Parameter | Description |
|---|---|
| Status | HTTP status code returned by the API. See Response codes. |
| x-viva-eventId | Event identifier corresponding to the event. See Rejection reasons. |
| Response message | Reason 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.
| Status | Meaning | Message |
|---|---|---|
| 200 | OK | The request has succeeded. The meaning of the success depends on the HTTP method:
|
| 400 | Bad request | The server could not understand the request due to invalid syntax. |
| 401 | Unauthorized | Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. |
| 403 | Forbidden | The 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. |
| 404 | Not found | The server can not find requested resource. In the browser, this means the URL is not recognised. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. |
| 405 | Method not allowed | The request method is known by the server but has been disabled and cannot be used. |
| 406 | Not acceptable | You requested a format that isn't JSON. |
| 409 | Conflict | This response is sent when a request conflicts with the current state of the server. |
| 410 | Gone | This response is sent when the requested content has been permanently deleted from server, with no forwarding address. |
| 429 | Too many requests | The user has sent too many requests in a given amount of time ('rate limiting'). |
| 500, 502, 504 | Server error | Something went wrong at our end. Try again later. |
| 503 | Service unavailable | We're temporarily offline for maintenance. Try again later. |
The reason phrase will contain either an explanation of why the request could not be completed, 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):
- Country codes must conform to the ISO 3166-1 alpha-2 standard.
- Dates must conform to the ISO 8601 standard and 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 ISO 4217 in numeric form.
Rejection reasons
Any of the following card issuer, system or user error messages can be returned during a Visa / Mastercard payment attempt.
| x-viva-eventId | Reason | Explanation | Type |
|---|---|---|---|
| 2061 | 3DS flow incomplete | Browser closed before authentication finished. | User |
| 2062 | 3DS validation failed | Wrong password or two-factor auth code entered. | User |
| 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 |
| 10015 | Invalid issuer | The card issuer doesn't exist. | System |
| 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 |
| 10301 | Soft decline | The issuer requests Strong Customer Authentication; the merchant should retry the transaction after successfully authenticating customer with 3DS first. | Issuer |