Introduction
Welcome to the OnPay integration documentation, this documentation is directed at anyone wanting to integrate OnPay in their ecommerce solution.
If you have any questions regarding the documentation, please contact the support where you have your OnPay solution.
Receiving payments
To receive payments you will need to integrate the orderflow with OnPay. This can be done in the following ways:
Payment creation API
The recommended way to initialize new payments.
Create new payments(transactions or subscriptions) through the API, and receive a URL directly to the payment.
Payment window v3
Initialize new payments(transactions or subscriptions), by a form post directly to the Payment window.
API (processing payments)
It is possible to automate most of the tasks achieved through the management panel, through the API.
v1 API specification
SDK (Software Development Kit)
PHP SDK
A PHP-SDK for developing against the OnPay.io platform.
Download and instructions here
.NET SDK
A .NET-SDK for developing against the OnPay.io platform.
Download and instructions here
JavaScript SDK
SDK providing tools for implementing interactivity on webpages.
Accepted currencies
OnPay accepts the following currencies. The list is based on the ISO4217 standard.
If you have any questions regarding the accepted currencies or proposals for other currencies, please contact the support where you have your OnPay solution.
| Number | Code | Name | Exponent |
|---|---|---|---|
| 36 | AUD | Australian dollar | 2 |
| 124 | CAD | Canadian dollar | 2 |
| 156 | CNY | Chinese yuan | 2 |
| 203 | CZK | Czech koruna | 2 |
| 208 | DKK | Danish krone | 2 |
| 352 | ISK | Icelandic króna | 0 |
| 356 | INR | Indian rupee | 2 |
| 392 | JPY | Japanese yen | 0 |
| 554 | NZD | New Zealand dollar | 2 |
| 578 | NOK | Norwegian krone | 2 |
| 643 | RUB | Russian ruble | 2 |
| 702 | SGD | Singapore dollar | 2 |
| 710 | ZAR | South African rand | 2 |
| 748 | SZL | Swazi lilangeni | 2 |
| 752 | SEK | Swedish krona | 2 |
| 756 | CHF | Swiss franc | 2 |
| 818 | EGP | Egyptian pound | 2 |
| 826 | GBP | Pound sterling | 2 |
| 840 | USD | United States dollar | 2 |
| 978 | EUR | Euro | 2 |
| 980 | UAH | Ukrainian hryvnia | 2 |
| 985 | PLN | Polish złoty | 2 |
| 986 | BRL | Brazilian real | 2 |
Test data
If test mode is activated on the merchant, it is possible to use the following test cards.
Any expiration date in the future will work, as well as any CVC.
Visa/Dankort
| PAN | Status |
|---|---|
| 4571 9900 2080 0010 | Accepted |
| 4571 9900 2080 0028 | Denied |
| 4571 9900 2080 0036 | Capture fails |
| 4571 9900 2080 0044 | Recurring fails |
Dankort
| PAN | Status |
|---|---|
| 5019 9900 2080 0017 | Accepted |
| 5019 9900 2080 0025 | Denied |
| 5019 9900 2080 0033 | Capture fails |
| 5019 9900 2080 0041 | Recurring fails |
Visa
| PAN | Status |
|---|---|
| 4687 3800 2080 0015 | Accepted |
| 4687 3800 2080 0023 | Denied |
| 4687 3800 2080 0031 | Capture fails |
| 4687 3800 2080 0049 | Recurring fails |
MasterCard
| PAN | Status |
|---|---|
| 5204 7400 2080 0011 | Accepted |
| 5204 7400 2080 0029 | Denied |
| 5204 7400 2080 0037 | Capture fails |
| 5204 7400 2080 0045 | Recurring fails |
Action/acquirer codes
Some codes returned are general, while others are acquirer specific.
General
Non acquirer specific errors are negative
| Action code | Description |
|---|---|
| -1 | Communication error, acquirer may not be available |
| -2 | Unknown error |
| -5 | ACS denied, 3DSecure verification failed |
Nets / Elavon / Worldline
The most common action codes are highlighted here
| Action Code | Description | Transaction status | Recommended action |
|---|---|---|---|
| 000 | Approved | Approved | Transaction approved. No action required |
| 001 | Requires ID | Decline | Do not try again. Contact card issuer or try with a different card. |
| 100 | Declined | Decline | Try again once a day. If no success after 4 days contact card issuer |
| 101 | Expired card | Decline/Expired card | Do not try again. Contact card issuer or try with a different card. |
| 102 | Suspected fraud | Decline | Do not try again. Contact card issuer or try with a different card. |
| 103 | Contact acquirer | Decline | Do not try again. Contact card issuer or try with a different card. |
| 104 | Restricted card | Decline | Do not try again. Contact card issuer or try with a different card. |
| 106 | Blocked due to excess PIN tries | Decline | Do not try again. Contact card issuer or try with a different card. |
| 107 | Contact issuer | Decline | Do not try again. Contact card issuer or try with a different card. |
| 108 | Contact issuer | Decline | Do not try again. Contact card issuer or try with a different card. |
| 109 | Invalid merchant | Decline | Contact Nets to verify acquirer data in OnPay |
| 110 | Invalid amount | Decline/Amount error | Data error in payment window request. Correct data before trying again. Contact support for help. |
| 111 | Invalid card number | Decline | Do not try again. Contact card issuer or try with a different card. |
| 114 | Closed account | Decline | Do not try again. Contact card issuer or try with a different card. |
| 116 | Not sufficient funds on card | Decline | Try again once a day. If no success after 4 days contact card issuer |
| 117 | Incorrect PIN | Decline | Transaction approved. No action required |
| 118 | Unknown card | Decline | Do not try again. Contact card issuer or try with a different card. |
| 119 | Payment method not allowed for card | Decline/Invalid transaction | Do not try again. Contact card issuer or try with a different card. |
| 120 | Transaction not permitted for merchant | Declined/Invalid transaction | Contact Nets to verify acquirer data in OnPay |
| 121 | Exceeds withdrawal limit | Decline | Data error in payment window request. Correct data before trying again. Contact support for help. |
| 122 | Security violation | Decline | Data error in payment window request. Correct data before trying again. Contact support for help. |
| 123 | Exceeds withdrawal frequency limit | Decline | Try again once a day. If no success after 4 days contact card issuer |
| 124 | Violation of law | Decline | Data error in payment window request. Correct data before trying again. Contact support for help. |
| 125 | Card not effective | Decline | Do not try again. Contact card issuer or try with a different card. |
| 132 | Strong Customer Authentication Required | Decline | Data error in payment window request. Correct data before trying again. Contact support for help. |
| 145 | Token cryptogram invalid | Retransmit | Try again once a day. If no success after 4 days contact card issuer |
| 164 | Card entry found, below low range | Decline | Do not try again. Contact card issuer or try with a different card. |
| 165 | Pan length not according to table | Decline | Do not try again. Contact card issuer or try with a different card. |
| 178 | Blocked, first used or special condition—new cardholder not activated or card is temporarily blocked | Decline | Do not try again. Contact card issuer or try with a different card. |
| 182 | Negative online CAM, dCVV, iCVV, CVV, or CAVV results Or Offline PIN authentication interrupted | Decline | Do not try again. Contact card issuer or try with a different card. |
| 190 | Life Cycle | Decline | Do not try again. Contact card issuer or try with a different card. |
| 192 | Policy | Decline | Do not try again. Contact card issuer or try with a different card. |
| 194 | Fraud/Security | Decline | Do not try again. Contact card issuer or try with a different card. |
| 200 | Declined | Decline | Do not try again. Contact card issuer or try with a different card. |
| 202 | Suspected fraud | Decline | Do not try again. Contact card issuer or try with a different card. |
| 207 | Special conditions | Decline | Do not try again. Contact card issuer or try with a different card. |
| 208 | Lost card | Decline | Do not try again. Contact card issuer or try with a different card. |
| 209 | Stolen card | Decline | Do not try again. Contact card issuer or try with a different card. |
| 210 | Suspected counterfeit | Decline | Do not try again. Contact card issuer or try with a different card. |
| 352 | Unknown error | Decline | Do not try again. Contact card issuer or try with a different card. |
| 900 | Approved | Approved | Transaction approved. No action required |
| 902 | Invalid transaction | Declined | Data error in payment window request. Correct data before trying again. Contact support for help. |
| 903 | Re-enter transaction | Declined | Try again once a day. If no success after 4 days contact card issuer |
| 904 | Format error | contact Nets | Data error in payment window request. Correct data before trying again. Contact support for help. |
| 907 | Card issuer or switch inoperative | Retransmit | Try again once a day. If no success after 4 days contact card issuer |
| 908 | Transaction destination cannot find routing | Declined | Try again once a day. If no success after 4 days contact card issuer |
| 909 | System malfunction | contact Nets | Try again once a day. If no success after 4 days contact card issuer |
| 913 | Duplicate transmission | contact Nets | Try again once a day. If no success after 4 days contact card issuer |
| 922 | Out of sequence, contact support | Contact Nets | Data error in payment window request. Correct data before trying again. Contact support for help. |
| 945 | Timeout | Retransmit | Try again once a day. If no success after 4 days contact card issuer |
| 946 | Communication error, contact support | Contact Nets | Due to communication error, the connection to the transaction has been lost. Contact Nets support for the correct status. |
| 984 | No valid conversion for a field | Declined | Data error in payment window request. Correct data before trying again. Contact support for help. |
Further explanation
We have tried to add explanations for the error codes, based upon previous encounters of the error. Be aware that an error code can mean multiple things, so the explanation may not be correct for the specific case.
001
This transaction requires further identification of the cardholder, but since it is a e-commerce transaction this is not possible.
119
Typically seen when a card is not allowed to be used for e-commerce, in some circumstances the cardholder need to enable e-commerce shopping in their bank. Alternatively the transaction may succeed if done with 3D-Secure
120
This error is seen when attempting to do recurring transactions, but where the merchant agreement with the issuer is not enabled for recurring transactions. Contact Nets to get it corrected
984
Has been seen where a issuer has subscribed for Visa Payment Stop Service, and exhibits that it is impossible to withdraw money on a recurring transaction.
Clearhaus
The most common action codes are highlighted here
| Action code | Description | Approved |
|---|---|---|
| 20000 | Approved | Yes |
| 40000 | General input error | No |
| 40110 | Invalid card number | No |
| 40111 | Unsupported card scheme | No |
| 40120 | Invalid CSC | No |
| 40130 | Invalid expire date | No |
| 40135 | Card expired | No |
| 40140 | Invalid currency | No |
| 40150 | Invalid text on statement | No |
| 40190 | Invalid transaction | No |
| 40200 | Clearhaus rule violation | No |
| 40300 | 3-D Secure problem | No |
| 40310 | 3-D Secure authentication failure | No |
| 40400 | Backend problem | No |
| 40410 | Declined by issuer or card scheme | No |
| 40411 | Card restricted | No |
| 40412 | Card lost or stolen | No |
| 40413 | Insufficient funds | No |
| 40414 | Suspected fraud | No |
| 40415 | Amount limit exceeded | No |
| 40416 | Additional authentication required | No |
| 40420 | Merchant blocked by cardholder | No |
| 50000 | Clearhaus error | No |
Shift4
The most common action codes are highlighted here
| action code | description | approved |
|---|---|---|
| -69 | Transaction has been declined. Invalid 3ds-version parameter. | No |
| -68 | Authentication process timed out. Please try again. | No |
| -66 | Invalid combination of 3ds-initiate and exemption-action values. | No |
| -65 | Gateway MID is not allowed for this exemption. | No |
| -64 | TRA exemption is not allowed for this transaction amount. | No |
| -63 | The requested gateway MID is not enrolled to 3d-secure service. | No |
| -50 | An error occurred during the 3D secure process. | No |
| -39 | You need to be registered with the 3D Adviser service to complete the request. | No |
| -38 | The transaction has been denied by the gateway because 3D secure authentication failed. Reason: {} Note: the "Reason" part is optional and may appear according to detected reason. | No |
| -37 | Transaction has been denied. Malformed or missing {} parameter. Originating component: {} | No |
| -36 | The selected processor does not support some of the transaction’s parameters. | No |
| -35 | The selected MID is not registered to your account. | No |
| -33 | You need to be registered with the routing service to complete the routing request. | No |
| -32 | You are not registered with the selected processor. | No |
| -30 | Transaction failed due to error in 3D Secure process. | No |
| -20 | Processor authentication error. Please contact Shift4 support. | No |
| -17 | Fraud-protection service is unavailable. | No |
| -16 | Rejected. Overriding the fraud threshold is not allowed. | No |
| -15 | Rejected. Bypassing the fraud service is not allowed. | No |
| -13 | The requested gateway MID is not enrolled in the 3D Secure Adviser service. | No |
| -12 | Transaction has been declined due to security restrictions. | No |
| -11 | Rejected. Format error. | No |
| -10 | Internal server error. Please contact Shift4 support | No |
| -9 | The parameter is malformed. | No |
| -8 | The package signature is malformed. | No |
| -7 | Incorrect gateway response. Connection is broken. | No |
| 0 | The transaction has been executed successfully. | Yes |
| 1 | The transaction has been denied by the Gateway. | No |
| 2 | The transaction has been denied by the Gateway due to its high fraud risk. | No |
| 03 | The transaction has been denied by the Gateway due to its high AVS risk. | No |
| 04 | The transaction has been denied by the Gateway due to an interchange timeout. | No |
| 05 | The transaction has been declined. | No |
| 06 | Transaction pending cardholder authentication. | Pending |
| 07 | The transaction was declined by the gateway and will not be processed due to retry optimization policy. | No |
| 9 | The transaction has been denied by the Gateway due to a LUHN check failure. | No |
| 10 | The transaction has been partially approved. | Partially |
| 11 | The queried transaction is currently being processed. Please try again. | Pending |
| 13 | Rejected. The fraud-protection service is unavailable. | No |
| 15 | Rejected. Risk score is above limit. | No |
Swedbank
The most common action codes are highlighted here
| Action Code | Description | Approved | Recommended action |
|---|---|---|---|
| 00 | Approved | Yes | Transaction approved. No action required |
| 03 | Invalid merchant | No | Contact Swedbank to verify acquirer data in OnPay |
| 05 | General Decline | No | Do not try again. Contact card issuer or try with a different card. |
| 12 | Invalid transaction | No | Data error in payment window request. Correct data before trying again. Contact support for help. |
| 13 | Invalid amount | No | Data error in payment window request. Correct data before trying again. Contact support for help. |
| 14 | Invalid card number | No | Data error in payment window request. Correct data before trying again. Contact support for help. |
| 30 | Format error | No | Data error in payment window request. Correct data before trying again. Contact support for help. |
| 43 | Stolen card | No | Do not try again. Contact card issuer or try with a different card. |
| 51 | Not sufficient fund | No | Do not try again. Contact card issuer or try with a different card. |
| 54 | Expired card | No | Do not try again. Contact card issuer or try with a different card. |
| 56 | CAF not found | No | Data error in payment window request. Correct data before trying again. Contact support for help. |
| 57 | Transaction not permitted | No | Do not try again. Contact card issuer or try with a different card. |
| 58 | Transaction not allowed at terminal | No | Contact Swedbank to verify acquirer data in OnPay |
| 61 | Exceeds withdrawal amt. limit | No | Do not try again. Contact card issuer or try with a different card. |
| 62 | Restricted card | No | Do not try again. Contact card issuer or try with a different card. |
| 65 | Exceeds withdrawal frequency limit | No | Do not try again. Contact card issuer or try with a different card. |
| 75 | Pin tries exceeded | No | Do not try again. Contact card issuer or try with a different card. |
| 87 | Bad track2 | No | Do not try again. Contact card issuer or try with a different card. |
| N0 | Unable to authorize | No | Data error in payment window request. Correct data before trying again. Contact support for help. |
| N7 | CVD2 failure | No | Data error in payment window request. Correct data before trying again. Contact support for help. |
| O5 | 3D secure challenge requested // Documented in final newsletter of 2019 | No | Data error in payment window request. Correct data before trying again. Contact support for help. |
| O6 | Mod 10 check | No | Data error in payment window request. Correct data before trying again. Contact support for help. |
| O8 | Cached decline encountered | No | Authentication error for saved card. Create a new payment or try with a different card. |
Error codes
Error codes are always returned on callbacks in the onpay_errorcode parameter.
| Error Code | Description |
|---|---|
| 0 | Transaction approved without issue |
| 1 | Reference supplied is already used |
| 2 | Wallet Service communication error |
| 3 | Transaction cancelled or rejected |
| 1000 | Unknown error |