MERCHANT INTEGRATION MANUAL

Version: 1.7.2 <April 27, 2012 >

TrustPay Merchant Integration Manual Version: 1.7.2 <April 27, 2012 >

Versions
Version 1.0 1.1 1.2 Date June 21, 2010 August 3, 2010 January 26, 2011 Changes Initial revision Changed method in HTTP notification from POST to GET Added TYP and OID to notification, updated default URLs Added testing instructions Changed sender Notification E-mail address Changed URL of payment service Added paysafecard option Appendix VII Updated UI screenshots Added value 2 authorized to result codes table Added cancel URL Added parameters RURL, CURL, EURL Added new supported countries, languages and currencies see Appendices II, III,IV Updated Appendix VI Testing Added Appendix VIII Internal transfers, which are no longer available from standard payment service Corrected informations in appendices VII,VIII Added Appendix IX - Entering the PRODUCTION state (LIVE environment) Added new supported countries, languages and currencies see Appendices II, III,IV Value A for FLG parameter is no longer supported REF parameter supports 512 characters Added Appendix X - FAQ Added parameter NURL Changed result code 2 to "Announced" for all bank payments, you will receive this code Added result code 3 for "Authorized" Changed key value for sample in Appendix I Updated Appendix II Payment page changed to paymentservice.aspx that includes landing intro page (calling pay.aspx is fully backward compatible)

1.3 1.4 1.5

June 9, 2011 August 22, 2011 November 22, 2011

1.6

December 14, 2011

1.6.1

February 9, 2012

1.7.

March 13, 2012

1.7.1 1.7.2

April 25, 2012 April 27, 2012

Unclassified

TrustPay, a.s.

Page 2 / 17

TrustPay Merchant Integration Manual Version: 1.7.2 <April 27, 2012 >

Table of contents
Versions ................................................................................................................................................................... 2 Introduction ............................................................................................................................................................ 4 Payment process ..................................................................................................................................................... 6 Merchant redirects client to TrustPay ................................................................................................................ 7 TrustPay notifies Merchant about payment ...................................................................................................... 9 TrustPay redirects client to Merchant .............................................................................................................. 10 Appendix I - Creating data sign ............................................................................................................................. 11 Code samples ................................................................................................................................................... 11 .NET framework 2.0 (C#) ............................................................................................................................. 11 PHP .............................................................................................................................................................. 11 JAVA ............................................................................................................................................................. 11 Appendix II - Result codes ..................................................................................................................................... 13 Appendix III Supported currencies ...................................................................................................................... 13 Appendix IV Supported languages ..................................................................................................................... 14 Appendix V Supported countries ....................................................................................................................... 14 Appendix VI Testing ............................................................................................................................................ 15 Appendix VII Paysafecard* ................................................................................................................................. 16 Appendix VIII Internal Transfer .......................................................................................................................... 16 Appendix IX FAQ ................................................................................................................................................. 16

Unclassified

TrustPay, a.s.

Page 3 / 17

TrustPay Merchant Integration Manual Version: 1.7.2 <April 27, 2012 >

Introduction
The TrustPay (TP) Merchant API (payment service) is an internet based payment tool that Merchants can use to receive payments from clients. This manual should help implement and integrate the TrustPay Merchant API into Merchants pages and ensure a functional and secure connection between TrustPays server and the Merchants server. It is intended to be used by technical staff maintaining the Merchant's website. When a Merchant wants to implement the TP payment service on his page, the following required procedure must be followed: 1. 2. Merchant must sign an agreement with TrustPay. Merchant must provide the necessary data for the TEST environment: o Success Return URL (required) default address of page, where client will be redirected after a successful payment. o Error Return URL (required) default address of page, where client will be redirected when an error has occurred. o Cancel Return URL (required) default address of page, where client will be redirected if user cancels the payment. o Notification URL (optional) address of page where the Merchant wants to receive payment notifications through the HTTP protocol. o Notification E-mail address (required) e-mail address where the Merchant wants to receive payment notifications by e-mails. Merchant receives test data. These accounts are created exclusively for integration testing purposes and work only under the test environment: o One test environment PID required to log in to TrustPay's internet banking on the test environment o Test account numbers for each requested currency IDs of accounts enabled for payments (used as AID parameter). o A single secret key used for signing data (needed in order to build the SIG parameter). Merchant implements the necessary changes on his website, according to this document. Merchant must execute a few API payments on these test accounts in order to verify the integration. Upon successful completion of the previous step, the Merchant contacts TrustPay with a request to enter the production state. TrustPay verifies that the integration was successful and asks the merchant to provide the following data prior to entering the PRODUCTION state: o Success Return URL (required) o Error Return URL (required) o Cancel Return URL (required) o Notification URL (optional) o Notification E-mail address (optional) TrustPay processes the received data and provides the following production environment data to the merchant: o Production environment PID required to log in to TrustPay's internet banking on the production environment

3.

4. 5. 6. 7.

8.

Unclassified

TrustPay, a.s.

Page 4 / 17

TrustPay Merchant Integration Manual Version: 1.7.2 <April 27, 2012 > Requested account numbers IDs of accounts enabled for payments (used as AID parameter). o Production environment secret key used for signing data (needed in order to build the SIG parameter). Merchant can now enter the production (LIVE) environment by applying new settings based on the production environment data received from TrustPay see Appendix IX o

9.

Unclassified

TrustPay, a.s.

Page 5 / 17

TrustPay Merchant Integration Manual Version: 1.7.2 <April 27, 2012 >

Payment process
TrustPay requires the Merchant to modify their payment/checkout page to contain TrustPay as a payment provider option. When the customer selects TrustPay as a payment method he is actually sending data to TrustPays secure web servers. Sent data contains information about the payment, such as the Merchant's account, amount to be paid and several other fields that control the behavior of TrustPays Payment Gateway. Here is a simple sequence diagram of the payment process flow.
Client Merchant application TrustPay

Show deposit/payment page [HTTP POST (GET) with payment details] Select TP as payment option [request no OK]

[request OK]

Show error page

[error URL]

Redirect to error URL

Show payment possibilities

Choose payment method

Show payment

Cancel payment

Redirect to cancel URL [cancel URL]

Show cancel page

Confirm payment

Execute payment

Show result

Click Return to merchant [success URL or error URL]

Redirect to URL

Show success or error page

Accept and process notification

[notification URL, e-mail]

Create and send notification

Unclassified

TrustPay, a.s.

Page 6 / 17

TrustPay Merchant Integration Manual Version: 1.7.2 <April 27, 2012 >

Merchant redirects client to TrustPay

Using the SIG parameter allows the Merchant to verify data integrity. Based on the SIG parameter presence the requests can be categorized as follows: Normal request SIG parameter is not present. In this case parameters REF and AMT are treated specially. a. REF If REF is present (sent from Merchant) it cannot be changed. If REF is not present, user must fill in the Reference field at the TrustPay site. b. AMT If AMT is present (sent from Merchant) it cannot be changed. If AMT is not present, user must fill in AMT at TrustPay site. Secure request SIG parameter is present - no changes in the AMT and REF parameter values are possible.

Merchant's implementation has to redirect the client to the Merchant API with the following parameters. Name AID AMT CUR Description Merchant account ID ID of account assigned by TrustPay Amount of the payment exactly 2 decimal places Currency of the payment same as currency of merchant account See Appendix III Reference Merchants payment identification Flags (obsolete) Controls behavior of TrustPay Return URL overrides any default Return URL, can be overridden further by RURL,CURL,EURL Return URL overrides default Success Return URL Return URL overrides default Cancel Return URL Return URL overrides default Error Return URL Notification URL overrides default Notification URL Data sign see Appendix I Format Varchar(10) Decimal(13, 2) en-US format Char(3) Required Yes For secure requests Yes Example 1234567890 1234.00 EUR

REF FLG URL

Char(500) Varchar(32) Varchar(256)

For secure requests No No

INV9876543210

RURL

Varchar(256)

No

CURL

Varchar(256)

No

EURL

Varchar(256)

No

NURL

Varchar(256)

No

SIG

Char(64)

For secure requests

LNG

Language default language for TrustPay site see Appendix IV

Char(2)

No

http://www.mercha nt.com/TrustPayRet urn.html http://www.mercha nt.com/TrustPayRet urn.html http://www.mercha nt.com/TrustPayCan cel.html http://www.mercha nt.com/TrustPayErr or.html https://www.merch ant.com/TrustPayNo tification.html F3E74F2204C2D187 DD303CF0C5B22CE4 1DEB8FA0C1F18356 C05DA0F8DAFF5B69 en

Unclassified

TrustPay, a.s.

Page 7 / 17

TrustPay Merchant Integration Manual Version: 1.7.2 <April 27, 2012 > CNT Country default country of client see Appendix V Description free text that will be displayed to the user Char(2) No SK

DSC

Varchar(256)

No

Payment for Order XYZ

The base Production URL for client redirect is: https://ib.trustpay.eu/mapi/paymentservice.aspx The base TEST URL for client redirect is: https://test.trustpay.eu/mapi/paymentservice.aspx There are 2 types of redirect: LINK parameters are sent directly in link as a query string FORM parameters are sent using FORM

LINK All parameters are sent in a query string and must be URL encoded (according to RFC 1738). Example of the LINK:
<A href="https://ib.trustpay.eu/mapi/paymentservice.aspx?AID=9876543210&AMT=100.50&C UR=EUR&REF=1234567890&SIG=F3E74F2204C2D187DD303CF0C5B22CE41DEB8FA0C1F18356C05DA0F 8DAFF5B69">Pay with TrustPay</A>

FORM The parameters should be inserted on the merchant page as INPUT fields with type HIDDEN. The form can have set the METHOD parameter to POST or GET. Encoding of form should be set to default application/x-wwwform-urlencoded. Example of the FORM with the hidden parameters:
<FORM name="form1" action="https://ib.trustpay.eu/mapi/paymentservice.aspx " method="POST"> <INPUT type="hidden" name="AID" value="9876543210" /> <INPUT type="hidden" name="AMT" value="100.50" /> <INPUT type="hidden" name="CUR" value="EUR" /> <INPUT type="hidden" name="REF" value="1234567890" /> <INPUT type="hidden" name="SIG" value="F3E74F2204C2D187DD303CF0C5B22CE41DEB8FA0C1F18356C05DA0F8DAFF5B69"/> <INPUT type="submit" name="Pay with TrustPay" /> </FORM>

Unclassified

TrustPay, a.s.

Page 8 / 17

TrustPay Merchant Integration Manual Version: 1.7.2 <April 27, 2012 >

TrustPay notifies Merchant about payment

For each announced, authorized, or successfully finished payment on the Merchants account, TrustPay sends the result of the payment to the Merchant using the following parameters: Name AID TYP AMT CUR REF RES TID OID TSS Description Merchant account ID ID of account assigned by TrustPay Type of transaction CRDT or DBIT Amount of the payment Max. 2 decimal places Currency of the payment See Appendix III Reference Merchants payment identification Result code See Appendix II TrustPay Transaction ID unique ID used for any enquiries TrustPay Order ID ID of payment order (0 if no order available) Transaction signed If request from merchant was signed, this value determines, whether real payment was done with same signed values as specfified by merchant. Data sign see Appendix I Format Varchar(10) Char(4) Decimal(13, 2) Char(3) Number(10) Number(4) Number(10) Number(10) Char(1) Example 1234567890 CRDT 123.45 EUR 9876543210 0 9876543210 1122334455 Y Yes, N No

SIG

Char(64)

F3E74F2204C2D187 DD303CF0C5B22CE4 1DEB8FA0C1F18356 C05DA0F8DAFF5B69

All parameters are always present. NOTE: VERIFY PARAMETERS TSS AND AMOUNT. In some cases (such as offline payment) user can send different amount. Trustpay will process such payment to your account and will send notification with amount processed to your account. Notifications can be sent to the Merchant using the following channels: HTTP all parameters are sent as a HTTP query string to Notification URL provided by the Merchant. Script at this URL should return HTTP status 200 OK on success or 500 Internal error otherwise. TrustPay will repeat notification every hour until 200 OK is received or 10 attempts were made. Sample: http://www.merchant.com/result.html?AID=1234567890&AMT=123.45&CUR=EUR&REF=9876543210 &RES=0&TID=11111&TSS=Y&SIG=F3E74F2204C2D187DD303CF0C5B22CE41DEB8FA0C1F18356C05DA 0F8DAFF5B69 E-mail an e-mail in text/plain format is sent to email provided by merchant. The message consists of: o From TrustPay IB [tpnotify@trustpay.eu] o Subject Notification Reference: {REF} o Body all parameters in format parameter name: value, each parameter on new row

After signing an agreement, the Merchant can choose through which of the channels he would like to receive payment notifications. Notifications are not sent for failed payments. Unclassified TrustPay, a.s. Page 9 / 17

TrustPay Merchant Integration Manual Version: 1.7.2 <April 27, 2012 >

TrustPay redirects client to Merchant

After finishing this process, the customer is redirected (according to the result), to one of the return URLs provided by the Merchant. Success Return URL user is redirected here in case of an authorized or a successful payment with RES = 0 or in case of a timed out pending payment with RES=1. Cancel Return URL user is redirected here in case he decides to cancel the payment with RES=1005. Error Return URL user is redirected here in case of a failed or refused payment with RES >= 1000 and RES!=1005.

The following parameters are always being sent with the redirects: Name REF RES PID Description Reference Merchants payment identification Result code See Appendix II Processing ID (optional) Sent when available, can be used for inquiries Format Number(10) Number(4) Number(10) Example 9876543210 0 1234568790

NOTE: DO NOT PERFORM ANY ACTION ON THIS REDIRECT. Data is not signed and therefore cannot be considered as a verified payment result, such as the signed results sent to Notification URL or Notification Email. In case of result 1(PENDING) in redirection to merchant, notification will come only if user really makes the payment.

Unclassified

TrustPay, a.s.

Page 10 / 17

TrustPay Merchant Integration Manual Version: 1.7.2 <April 27, 2012 >

Appendix I - Creating data sign

HMAC-SHA-256 (RFC 2104) code is used for checking the integrity of the data sent between TrustPay and Merchant. Sign creation flow: A message is created as concatenation of parameter values in this specified order: o Merchant redirect to TrustPay: AID, AMT, CUR, and REF o TrustPay notification to Merchant: AID, TYP, AMT, CUR, REF, RES, TID, OID and TSS HMAC-SHA-256 code (32 bytes) is generated using a key obtained from TrustPay Then the code is converted to a string to be a hexadecimal representation of the code (64 upper chars).

The key used for signing data is obtained by Merchant when the agreement with TrustPay is signed.

Code samples
Test your sign computing implementation using the following data: key AID AMT CUR REF SIG abcd1234 9876543210 123.45 EUR 1234567890 DF174E635DABBFF7897A82822521DD739AE8CC2F83D65F6448DD2FF991481EA3

Here we provide examples of code computing SIG in some major programming languages. .NET framework 2.0 (C#)
public static string GetSign(string key, string message) { System.Security.Cryptography.HMAC hmac = System.Security.Cryptography.HMAC.Create("HMACSHA256"); hmac.Key = System.Text.Encoding.UTF8.GetBytes(key); byte[] hash = hmac.ComputeHash(System.Text.Encoding.UTF8.GetBytes(message)); return BitConverter.ToString(hash).Replace("-", "").ToUpperInvariant(); }

PHP
function GetSign($key, $message) { return strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*', $key))); }

JAVA
public static String GetSign(String key, String message) throws Exception { javax.crypto.Mac mac = javax.crypto.Mac.getInstance("HmacSHA256"); byte[] keyBytes = key.getBytes("UTF-8"); System.out.println("Key bytes: " + ByteArray2HexString(keyBytes)); byte[] messageBytes = message.getBytes("UTF-8"); System.out.println("Message bytes: " + ByteArray2HexString(messageBytes)); mac.init(new javax.crypto.spec.SecretKeySpec(keyBytes, mac.getAlgorithm())); return ByteArray2HexString(mac.doFinal(messageBytes));

Unclassified

TrustPay, a.s.

Page 11 / 17

TrustPay Merchant Integration Manual Version: 1.7.2 <April 27, 2012 >
} public static String ByteArray2HexString(byte[] b) { java.math.BigInteger bi = new java.math.BigInteger(1, b); return String.format("%0" + (b.length << 1) + "X", bi); }

Unclassified

TrustPay, a.s.

Page 12 / 17

TrustPay Merchant Integration Manual Version: 1.7.2 <April 27, 2012 >

Appendix II - Result codes

List of result codes returned by TrustPay to Merchant (either to Error Return URL or Notification URL). Please be informed that only Reason code 0 can be treated as sucessful payment which has been credited to Merchants account in TrustPay. Code 0 Description Success Payment was successfully processed Pending Payment is pending (offline payment) Announced TrustPay has been notified that the the client placed a payment order or rd has made payment, but further confirmation from 3 party is needed. Another notification (with result code 0 - success) will be sent when rd TrustPay receives and processes payment from 3 party. Authorized Payment was successfully authorized. Another notification (with result code 0 - success) will be sent when TrustPay receives and processes rd payment from 3 party. Invalid request data sent is not properly formatted Unknown account Account with specified ID was not found Merchant disabled Merchant account has been disabled Invalid sign sign of message is invalid User cancel user has cancelled payment Invalid authentication request was not properly authenticated General Error internal error has occurred Returned via redirect email notification http notification redirect redirect email notification http notification

1 2

redirect email notification http notification redirect redirect redirect redirect redirect redirect redirect

1001 1002 1003 1004 1005 1006 1100

Appendix III Supported currencies

The following is a list of currencies (according to ISO 4217) supported by TrustPay. Code CZK EUR GBP HUF PLN USD RON BAM BGN HRK ID 203 978 826 348 985 840 946 977 975 191 Name Czech koruna Euro Pound Sterling Forint Zloty US Dollar Romanian new leu Bosnia and Herzegovina convertible mark Bulgarian lev Croatian Kuna

Unclassified

TrustPay, a.s.

Page 13 / 17

TrustPay Merchant Integration Manual Version: 1.7.2 <April 27, 2012 > RSD 941 Serbian dinar

Appendix IV Supported languages

The following is a list of languages (according to ISO 639-1) supported by TrustPay. Code en sk cs pl hu bg hr ro ru sr bs lv lt et sl Language English Slovak Czech Polish Hungarian Bulgarian Croatian Romanian Russian Serbian Bosnian Latvian Lithuanian Estonian Slovene

Appendix V Supported countries

The following is a list of countries (according to ISO 3166-1 alpha-2) supported by TrustPay. Code CZ HU PL SK EE BG RO BA HR RS Country Czech Republic Hungary Poland Slovak Republic Estonia Bulgaria Romania Bosnia and Herzegovina Croatia Serbia

Unclassified

TrustPay, a.s.

Page 14 / 17

TrustPay Merchant Integration Manual Version: 1.7.2 <April 27, 2012 >

Appendix VI Testing
After successful implementation of the TrustPay API, the Merchant needs to test all return values depending on the results of the payment transactions. Redirecting the clients browser to https://test.trustpay.eu/mapi/paymentservice.aspx will display TrustPays following page.

On the Bank Transfer page select the country Slovakia for EUR test account in dropdown with available countries. For tests on accounts in currency different then EUR, select country for currency according appendix III. Then click on the TestPay Banka bank under the online payment options and click on the "Confirm" button. Note: TestPay is a virtual instant payment used only for testing purposes. You will then be redirected to the TestPay page where you can choose one of these actions:

OK Payment from Instant transfer will be paid and client will be redirected to SUCCESS RETURN URL with result RES=0. TrustPay then call NOTIFICATION URL or send NOTIFICATION EMAIL, depending on Merchants configuration. TrustPay, a.s. Page 15 / 17

Unclassified

TrustPay Merchant Integration Manual Version: 1.7.2 <April 27, 2012 > ANNOUNCED This emulates situation when Trustpay receives notification about payment from 3 party but payment was not processed yet. If Redirect to MAPI checkbox is checked, you will be redirected to SUCCESS RETURN URL and you will received only one notification with result 2. You can uncheck this checkbox, click AUTH button to receive authorization notification. Later, you can clik OK button to receive another notification for same payment with result 0. This emulates production environment scenario for some gateways. FAIL Payment from Instant transfer will be failed and client will be redirected to ERROR RETURN URL with result value RES defined in error code table Appendix II. PENDING Payment from Instant transfer will be pending. Client will be redirected to SUCCESS RETURN URL with result RES=1 which means Payment pending. TrustPay will wait for acknowledgment from Bank or third-party payment system and then call NOTIFICATION URL or send NOTIFICATION EMAIL, depending on Merchants configuration.
rd

Note: The Reference value in the TestPay gateway is for Trustpays internal use only.

Appendix VII Paysafecard*

The Paysafecard option is not reachable from the payment service site in TrustPay. It needs to be called directly using these URLs: The base Production URL for client redirect, direct for the payment option Paysafecard is: https://ib.trustpay.eu/mapi/paysafecard.aspx All other parameters work as described above. The Paysafecard payment option cannot be tested on the test environment. Instead, merchants have to pass the online bank payment test as described in Appendix VI Testing. *The Paysafecard URLs work only for those merchants, who have Paysafecard payment option enabled in their agreements with TrustPay. An error message will be shown to all other merchants.

Appendix VIII Internal Transfer

Internal transfers (from TrustPay account) are not reachable from the payment service site in TrustPay. It needs to be called directly using these URLs: The base Production URL for client redirect, direct for the internal payment option is: https://ib.trustpay.eu/mapi/internaltransfer.aspx The base TEST URL for client redirect, direct for the internal payment option is: https://test.trustpay.eu/mapi/internaltransfer.aspx All other parameters work as described above. It is not required to test the Internal payment option. Passing the online bank payment test as described in Appendix VI Testing is sufficient to enter the production environment.

Appendix IX Entering the PRODUCTION state (LIVE environment)

In order to test the implementation of TrustPay on merchant's site, each merchant receives access to the TEST environment. After the process of implementation is over, the merchant contacts TrustPay and requests access to the PRODUCTION (Live) environment. After TrustPay verifies that the implementation was successful, the

Unclassified

TrustPay, a.s.

Page 16 / 17

TrustPay Merchant Integration Manual Version: 1.7.2 <April 27, 2012 > merchant will receive new production state data. The previously received data, was valid for the TEST environment only. The production state data includes: PID AIDs Secret Key

Please, do not forget to change the base URL for client redirect to the PRODUCTION URL and make sure the implementation is configured with production state data after entering the Live environment. Using data valid for the TEST environment will cause payment failures or unexpected payment results (payments not being signed) in the Live environment.

Appendix X FAQ
In case you need further assistance with the integration of TrustPay's payment methods please refer to the FAQ available at http://trustpay.eu/home/top-left-menu/services/merchants/documents/mapi-faq.aspx If your questions were not answered by the FAQ, feel free to contact TrustPay's support at support@trustpay.eu In order for us to help you solve your problem, please provide the following information in your inquiry: Live or Test environment which en AID account ID your are testing on Company / Account owner name Detailed problem description - describe the problem in detail, provide relevant input data and procedures that you use, step by step instructions that you followed and also state your expected outcome / result

Unclassified

TrustPay, a.s.

Page 17 / 17