Parameters
Updated
FUNCTIONALITY AND CONSTRAINTS
Teya´s Secure Payment Page can be configured to require the cardholder to insert email, mobile number and home address.
If parameter skipreceiptpage is set to 1 then the receipt page is not displayed and the buyer is redirected to the URL in parameter returlursuccess upon successful payment. In this setup the merchant must display receipt information.
Merchant logo can be displayed by setting a valid URL in parameter merchantlogo. The logo will then be displayed in the left corner, above the merchant name. Note that the image needs to be stored under https to avoid browser warning message.
SecurePay uses unicode (UTF-8) characters set. If the web shop is in another character set, f.ex. iso8859, then character conversion is needed. A conversion code example in .Net is here
public static string iso8859ToUnicode(string src)
{
Encoding iso = Encoding.GetEncoding("iso8859-1");
Encoding unicode = Encoding.UTF8;
byte[] isoBytes = iso.GetBytes(src);
byte[] unibytes = Encoding.Convert(iso,unicode,isoBytes);
char[] unichars = newchar[iso.GetCharCount(unibytes,0,unibytes.Length)];
unicode.GetChars(unibytes,0,unibytes.Length,unichars,0);
returnnewstring(unichars);
}SecurePay supports Verified By Visa (VbyV) and MasterCard SecureCode, no technical changes are needed to activate enhanced security. Please send request of activation to: podrska@sTeya.co, stating the website and the merchant ID.
Decimal numbers can be sent in with either , or . to differentiate between whole numbers and cents.
Each pair of MerchantId/PaymentGatewayId can only support one currency. If support is needed for more than one currency then the webshop must be able to change the MerchantId/PaymentGatewayId pair depending on currency. There is no additional charge for multiple MerchantId/PaymentGatewayId´s.
FROM WEB SHOP TO PAYMENT PAGE
Name | Value |
Merchantid Required | MerchantId issued by Teya that identifies the merchant |
paymentgatewayid Required | Payment Gateway Id issued by Teya that identifies the payment method |
Orders Required | Order number created by webshop, it will be a part of the creditcard transaction. 12 alphanumeric characters, extended characters sets can not be used. |
reference Optional | Reference can be any string, it is returned with the same value as is sent in. It‘s main function is to simplify adaptation to merchant system by containing an external orderid number. |
checkhash Required | Signature that is created by joining together the following parameters with | as separator and using HMAC SHA256 with the merchant secret key to create the checkhash. MerchantId|ReturnUrlSuccess|ReturnUrlSuccessServer|OrderId|Amount|Currency (Secret key is issued by Teya and known only to merchant and Teya) See HMAC value creation appendix. |
amount Required | Total amount, can be with up to two cent numbers. Examples of legal values, 350 and 54,43 and 12.34 |
currency Required | Currency code, allowed values are GBP, USD, EUR, DKK, NOK, SEK, CHF, CAD, HUF, BHD, AUD, RUB, PLN, RON, HRK, CZK and ISK. Default value is ISK. |
language Required | Language on webpages displayed to users. Supported langages are Icelandic (IS), English (IN), German (OF), French (FR), Russian (RU), Spanish (IS) Italian (IT), Portuguese (PT), Slovenian (AND), Hungarian (HU), Swedish (SE), Dutch (NL), Polish (PL), Norwegian (NO), Czech (CZ), Slovak (SK), Croatian (HR), Serbian (SR), Romanian (RO), Danish (DK), Finnish (BE) and Faroese (FO). |
buyername Optional | Buyers name. If left empty then the buyer can insert it on the payment page.. |
returnurlsuccess Required | Buyer will be sent to this page after a successful payment. |
returnurlsuccessserver Conditional | A notification of successful payment is sent to this URL by the server. If this parameter is not present, the value of the returnurlsuccess parameter is used instead.* |
returnurlcancel Optional | Buyer will be sent to this page if he pushes the Cancel button instead of finalizing the payment. |
returnurlerror Optional | Buyer will be sent to this page if an unexpected error occurs. |
pagetype Optional | If set as 1 then cardholder is required to insert email, mobile number and home address. Merchantemail parameter must be set since cardholder information is returned through email to merchant. |
merchantlogo Optional | If merchantlogo contains a url address of an image (100width x 100 height) then it is displayed on left side of the page, above the merchant name. Note that IE displayes warning if image is not stored on SSL. |
skipreceiptpage Optional | If set to 1 then the page displaying the purchase receipt to the cardholder is skipped and browser redirected to the url in returnurlsuccess. Thewebshop must then display a receipt to the cardholder in this setup. |
merchantemail Optional | If present, an e-mail is sent to the merchant upon successful payment. The message contains information about the merchant and buyer, along with the contents of the shopping cart. |
buyeremail Optional | If present, an e-mail is sent to the buyer upon successful payment. The message contains information about the merchang and buyer, along with the contents of the shopping cart. |
displaymode Optional | Can be set as "iframe" to make the payment page use a more compact layout suitable for display in iframes. Minimum supported width is 370px and maximum supported width is 755px. |
showadditionalbrands Optional | Can be set as "false" to hide brand logos other than VISA and MasterCard. |
| Cart as seen by the payment page consists of one or more items, each type of item creates one line. Each line contains one type of item along with number of items, unit amount and total amount for each line. Cart is sent by parameters with running number that start with 0 and are sequential. Each set of parameters represent one line in cart. Required |
Itemdescription_x Required | Item description, maximum length is 80 characters |
Itemcount_x Required | Number of items of this type |
Itemunitamount_x Required | Price of a single unit |
Itemamount_x Required | Total prices of this line. itemamount = itemcount * itemunitamount |
FROM PAYMENT PAGE TO WEB SHOP
The payment page can end its processing in three different stages:
Successful payment, buyer is redirected to the url in the parameter returnurlsuccess
Buyer cancels and is redirected to the url in the parameter returnurlcancel
Unexpected error occurred, buyer is redirected to the url in the parameter returnurlerror
Successful payment
NOTE: It is strongly recommended that the merchant verifies the order hash returned in the server-to-server (returnurlsuccessserver) response from Teya to avoid fraud attempts.
If payment is successful then the buyer is redirected to the url in parameter returnurlsuccess with the following HTTP POST parameters. It‘s usage is up to the web shop but it is important to verify the orderhash to validate that the success message is from Teya.
Name | Value |
status | Contains „Ok“ |
order hash | Signature that is created by joining together the following parameters with | as separator and using HMAC SHA256 with the merchant secret key to create the checkhash. orderid|amount|Currency (Secret key is issued by Teya and known only to merchant and Teya) See HMAC value creation appendix |
warrants | Order number created by webshop and sent to payment page during payment initiation |
authorizationcode | Payment authorization from Teya |
creditcardnumber | Masked creditcard number (1234-**-1234) |
step | Success message is sent on two occations from Teya to the webshop. First time is after buyer has successfully paid and is being shown a receipt by Teya. Note that this url request comes from the Teya server and is not redirected thorugh the buyer browser, it is thus not in the same active session. Second time is when the buyer pushes the optional Back to shop button. The steps are identified by the following values: „Payment”: Payment has been completed. „Confirmation”: Buyer is sent from the payment page back to the webshop. |
ticket | Included if payment page was accessed using a ticket. This parameter will contain the ticket used.. |
buyername | Included if registration was required (pagetype = 1) |
buyeraddress | Included if registration was required (pagetype = 1) |
buyerzip | Included if registration was required (pagetype = 1) |
buyercity | Included if registration was required (pagetype = 1) |
buyercountry | Included if registration was required (pagetype = 1) |
buyerphone | Included if registration was required (pagetype = 1) |
buyeremail | Included if registration was required (pagetype = 1) |
buyerreferral | Included if registration was required (pagetype = 1) |
buyercomment | Included if registration was required (pagetype = 1) |
Cancel
If buyer pushes the Cancel button the he is redirected to the url in the parameter returnurlcancel
Name | Value |
Status | Contains "Cancel" |
Unexpected error
Buyer is redirected to the url in the parameter returnurlerror if unexpected error occurrs.
Name | Value |
Status | Contains „Error“ |
errordescription | Error description suitable for displaying to buyer |
error code | Error code |
Additional codes are returned from the payment-page test-site:
Name | Value |
errordetailx | Details about the error |
auditlogx | Records from the audit log |
Payment notification response
If the step parameter is ’Payment’, then the preferred response from the webshop to the server-to-server notification should be an XML document, which indicates that the webshop has successfully received the notification.
The structure of the XML should be as follows:
<PaymentNotification>Accepted</PaymentNotification>If this response is received from the web shop, an audit log entry is created which states that the payment notification was successfully received by the web shop. Otherwise, the audit log entry will only state that the payment notification was sent to the web shop.