Response information
You can refer below for information about the responses you get when using our API methods. Each response includes:
- Response query string parameters (Smart Checkout only): upon completion of a payment by the customer on our Smart Checkout, the customer is redirected back to your website, and certain query string parameters are appended to the redirect URL.
- Transaction feedback parameters (all API methods): when the call of the API method results in a response by Viva Wallet that includes information about a transaction / payment, certain transaction feedback parameters are returned in the response.
- HTTP response code (all API methods): you may occasionally refer to the HTTP response code to determine whether the API call has been completed successfully.
When troubleshooting any technical problems you might have, please refer also to our page on Debugging errors which contains additional guidance.
Response query string parameters
The following response query string parameters are appended to the redirect URL upon completion of the payment order payment on our Smart Checkout.
| Parameter | Description |
|---|---|
| EventId | Code corresponding to the outcome of the payment. See Event ID codes below for full details. **This is the most reliable indicator of the outcome of a payment, and overrides any HTTP response code or ErrorCode that may indicate an error**. |
| ECI | ECI code. See Electronic Commerce Indicator below for full details. |
| ErrorCode | Typically corresponds to the HTTP response code returned by the API. In cases where it does not correspond to the HTTP response code, it should be ignored. |
| ErrorText | Reason phrase of error code. |
Event ID codes
During a payment attempt, any of the following EventId codes can be appended to the Success / Failure URL as query string parameters.
| EventId | Reason | Explanation | Type |
|---|---|---|---|
| 0 | Payment successful | The issuer has accepted the card payment. | Issuer |
| 2061 | 3DS flow incomplete | Browser closed before authentication finished. | User |
| 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 |
| 10200 | Generic error | 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 |
Electronic Commerce Indicator
The Electronic Commerce Indicator (ECI) is a code appended to the Success / Failure URL as a query string parameter in addition to Event ID (above). The following values are possible:
| ECI code | Meaning |
|---|---|
| 0 | Unspecified |
| 1 | Authenticated |
| 2 | No 3DS |
| 3 | Attempt or not enrolled |
Transaction feedback parameters
When receiving information about a transaction / payment via the call of an API method, certain transaction feedback parameters are returned in the response. In particular, the StatusId parameter is used to return information relating to payment success / failure, while the TransactionTypeId parameter is used to return information about the type of the transaction.
StatusId parameter
The result of a transaction is identified by the StatusId parameter in the response body. It applies to the following API calls:
It can have any one of the values outlined in the table below.
| StatusId | Description |
|---|---|
| E | The transaction was not completed because of an error (PAYMENT UNSUCCESSFUL) |
| A | The transaction is in progress (PAYMENT PENDING) |
| M | The cardholder has disputed the transaction with the issuing Bank |
| MA | Dispute Awaiting Response |
| MI | Dispute in Progress |
| ML | A disputed transaction has been refunded (Dispute Lost) |
| MW | Dispute Won |
| MS | Suspected Dispute |
| X | The transaction was cancelled by the merchant |
| R | The transaction has been fully or partially refunded |
| F | The transaction has been completed successfully (PAYMENT SUCCESSFUL) |
TransactionTypeId parameter
The transaction type is identified by the TransactionTypeId parameter returned in the response body. It is relevant in the context of the Retrieve transactions API call and webhooks for payments only.
| TransactionTypeId | Description |
|---|---|
| 0 | Card capture |
| 1 | Card pre-auth |
| 4 | Card refund* |
| 5 | Card charge |
| 6 | Card charge (installments) |
| 7 | Card void |
| 8 | Card Original Credit (refund, betting MCC only)* |
| 9 | Wallet charge |
| 11 | Wallet refund |
| 13 | Card refund claimed |
| 15 | Dias |
| 16 | Cash |
| 17 | Cash refund |
| 18 | Card refund (installments)* |
| 19 | Card payout |
| 20 | Alipay charge |
| 21 | Alipay refund |
| 22 | Card manual cash disbursement |
| 23 | iDEAL charge |
| 24 | iDEAL refund |
| 25 | P24 charge |
| 26 | P24 refund |
| 27 | BLIK charge |
| 28 | BLIK refund |
| 29 | PayU charge |
| 30 | PayU refund |
| 31 | Card withdrawal |
| 32 | MULTIBANCO charge |
| 33 | MULTIBANCO refund |
| 34 | giropay charge |
| 35 | giropay refund |
| 36 | Sofort charge |
| 37 | Sofort refund |
| 38 | EPS charge |
| 39 | EPS refund |
| 40 | WeChat Pay charge |
| 41 | WeChat Pay refund |
| 42 | BitPay charge |
| 43 | BitPay refund |
| 44 | SEPA Direct Debit |
| 45 | SEPA Direct Debit refund |
| 46 | SEPA Direct Debit refund claimed |
| 47 | SEPA Direct Debit void |
| 48 | PayPal charge |
| 49 | PayPal refund |
| 50 | Klarna charge |
| 51 | Klarna refund |
| 52 | Verkkopankki charge |
| 53 | Verkkopankki refund |
| 54 | Trustly charge |
| 55 | Trustly refund |
*The transactions that reverse previous payments have always a negative amount.
HTTP 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, while 400 codes indicate a client-side error, and 500 codes indicate an error with Viva Wallet’s servers.
| Response code | 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 cannot 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. |
| 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. |