Technical specification
Request data fields
The HTTP POST request consists of a set of data fields that must obey some syntactical and semantical rules. If one or more data fields does not comply with these rules, it will result in an error. Furthermore, any data fields that are not part of the protocol will be discarded.
 |
Note |
| Name | Regular expression | Description |
|---|---|---|
| *protocol | /^4$/ | Defines the version of the protocol. 4 is the latest |
| *msgtype | /^(authorize|subscribe)$/`` | Defines wether the transaction should be a standard payment or a subscription payment. |
| *merchant | /^[0-9]{8}$/ | The QuickPayId |
| *language | /^[a-z]{2}$/ | The language to use in the HTML pages as 2-letter ISO 639-1 alphabetical code. See http://quickpay.net/features/languages/ for supported languages. |
| *ordernumber | /^[a-zA-Z0-9]{4,20}$/ | A value by merchant's own choise. Must be unique for each transaction. Usually an incrementing sequence. The value may be reflected in the your bank account list. |
| *amount | /^[0-9]{1,9}$/ | The transaction amount in its smallest unit. In example, 1 EUR is written 100. |
| *currency | /^[A-Z]{3}$/ | The transaction currency as the 3-letter ISO 4217 alphabetical code. See http://quickpay.net/features/multi-currency/ for more info |
| *continueurl | !^https?://! | QuickPay will redirect to this URL upon a succesful transaction. |
| *cancelurl | !^https?://! | QuickPay will redirect to this URL if transaction is cancelled. |
| callbackurl | !^https?://! | QuickPay will make a call back to this URL with the result of the transaction. See http://quickpay.net/faq/callbackurl/ for more information. |
| autocapture | /^[0-1]{,1}$/ | If set to 1, the transaction will be captured automatically. See http://quickpay.net/features/autocapture/ for more information. Note: autocapture is only valid for message type 'authorize' |
| autofee | /^[0-1]{,1}$/ | If set to 1, the fee charged by the acquirer will be calculated and added to the transaction amount. See http://quickpay.net/features/transaction-fees/ for more information. |
| cardtypelock | /^[a-zA-Z,-]{0,}$/ | Lock to card type. Multiple card types allowed by comma separation. See http://quickpay.net/features/cardtypelock/ for available values. From V4 cardtypelock=creditcard is default |
| description | /^[\w _-.]{,20}$/ | A value by the merchant's own choise. Used for identifying a subscription payment. Note: Required for message type 'subscribe'. |
| group | /^[0-9]{0,9}$/ | Add subscription to this subscription group - (API v4 only) |
| testmode | /^[0-1]{,1}$/ | Enables inline testing. If set to '1', QuickPay will handle this and only this transaction in test-mode, while QuickPay is in production-mode. |
| splitpayment | /^[0-1]{0,1}$/ | Enable split payment on transaction - (API v4 only) |
| *md5check | /^[a-z0-9]{32}$/ | A MD5 checksum to ensure data integrity. See http://quickpay.net/faq/md5check/ for more information. |
MD5 checksum calculation for a Form Request
The field values must be concatenated in the following order:
cstr = concatenate(
'protocol',
'msgtype',
'merchant',
'language',
'ordernumber',
'amount',
'currency',
'continueurl',
'cancelurl',
'callbackurl',
'autocapture',
'autofee',
'cardtypelock',
'description',
'group',
'testmode',
'splitpayment',
'secret'
)
md5check = md5(cstr)
Response data fields
Though not required, it is highly recommended that you make use of the callback functionality. This way you can check that the transaction status etc.
If a callback URL is provided in the request, QuickPay will send the result of the transaction to that URL as a HTTP POST request. Table 2 lists the variables that will be send to the callback URL.
| Name | Regular expression | Description |
|---|---|---|
| msgtype | /^[a-z]$/ | Defines which action was performed - Each message type is described in detail later |
| ordernumber | /^[a-zA-Z0-9]{4,20}$/ | A value specified by merchant in the initial request. |
| amount | /^[0-9]{1,10}$/ | The amount defined in the request in its smallest unit. In example, 1 EUR is written 100. |
| currency | /^[A-Z]{3}$/ | The transaction currency as the 3-letter ISO 4217 alphabetical code. |
| time | /^[0-9]{12}$/ | The time of which the message was handled. Format is YYMMDDHHIISS. |
| state | /^[1-9]{1,2}$/ | The current state of the transaction. See http://quickpay.net/faq/transaction-states/ |
| qpstat | /^[0-9]{3}$/ | Return code from QuickPay. See http://quickpay.net/faq/status-codes/ |
| qpstatmsg | /^[\w -.]{1,}$/ | A message detailing errors and warnings if any. |
| chstat | /^[0-9]{3}$/ | Return code from the clearing house. Please refer to the clearing house documentation. |
| chstatmsg | /^[\w -.]{1,}$/ | A message from the clearing house detailing errors and warnings if any. |
| merchant | /^[\w -.]{1,100}$/ | The QuickPay merchant name |
| merchantemail | /^[\w_-.\@]{6,}$/ | The QuickPay merchant email/username |
| transaction | /^[0-9]{1,32}$/ | The id assigned to the current transaction. |
| cardtype | /^[\w-]{1,32}$/ | The card type used to authorize the transaction. |
| cardnumber | /^[\w\s]{,32}$/ | A truncated version of the card number - eg. 'XXXX XXXX XXXX 1234'. Note: This field will be empty for other message types than 'authorize' and 'subscribe'. |
| cardexpire | /^[\w\s]{,4}$/ | Expire date on the card used in a 'subscribe'. Notation is 'yymm'. Note: This field will be empty for other message types than 'subscribe'. |
| splitpayment | /^[0|1]$/ | Spitpayment enabled on transaction. See http://quickpay.net/features/split-payment/ for more information. (API v4 only) |
| fraudprobability | /^[low|medium|high]?$/ | Fraud probability if fraudcheck was performed. (API v4 only) |
| fraudremarks | /^.*?$/ | Fraud remarks if fraudcheck was performed. (API v4 only) |
| fraudreport | /^.*?$/ | Fraud report if given. (API v4 only) |
| fee | /^[0-9]{,10}$/ | Will contain the calculated fee, if autofee was activated in request. See http://quickpay.net/features/transaction-fees/ for more information. |
| md5check | /^[a-z0-9]{32}$/ | A MD5 checksum to ensure data integrity. See http://quickpay.net/faq/md5check/ for more information. |
MD5 checksum calculation for a Form callback
The field values must be concatenated in the following order:
cstr = concatenate(
'msgtype',
'ordernumber',
'amount',
'currency',
'time',
'state',
'qpstat',
'qpstatmsg',
'chstat',
'chstatmsg',
'merchant',
'merchantemail',
'transaction',
'cardtype',
'cardnumber',
'cardexpire (if subscribe)',
'splitpayment',
'fraudprobability',
'fraudremarks',
'fraudreport',
'fee',
'secret'
)
md5check = md5(cstr)