merchant api integration manual

merchant api integration manual
MERCHANT API INTEGRATION MANUAL
Version: 2.15 <January 2016 >
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>
Versions
Version
2.3
Date
January, 2014
2.4
2.5
February, 2014
April, 2014
2.6
May, 2014
2.7
June, 2014
2.8
August, 2014
2.9
November 21,
2014
2.9.1
2.10
December 4,
2014
January 12, 2015
2.11
March 9, 2015
2.12
April 21, 2015
2.13
May 25, 2015
2.14
November 11,
2015
2.15
January 27, 2016
Changes
Updated sequence diagram of the payment process flow
New testing page screenshot – Appendix VI
Added notification sample for Paysafecard payment –
Appendix VII
Added notification sample for Card payment – Appendix XI
Added Finland into supported countries – Appendix V
Updated format of REF parameter (Char(500) except “<”,
“>”)
Added note regarding CZK and HUF currencies – Appendix
III
Manual updated due to changes in the distribution of
secret key
Added new secret key appendix - Appendix XII
Added Greece into supported countries – Appendix V
Updated information regarding successful payment result
codes
– Appendix II
Changed base “TEST” URL for test environment – see
Appendix VI,
Transaction country of origin identification – see page 16.
and new Appendix XIII – GetTransactionOrigin,
Updated Appendix II – added result codes 1010 and 1011,
chapters numbering changed.
Typo in Appendix XIII corrected – GetTrasnactionOrigin
renamed to GetTransactionOrigin
Appendix III - PLN currency removed
Appendix V - country Poland removed
Appendix III – changed supported currencies: added DKK,
removed HRK
Appendix V – changed supported countries: added DK,
removed HR
Appendix VI – info about unsupported self-signed
certificates added.
Payment process, Appendix VI & Appendix VIII - Removed
old URLs for test environment.
Updated notification IP addresses for test and live
environment
Appendix III – changed supported currencies: added SEK
Appendix V – changed supported countries: added SE
Updated email notification IP adresses
Removed Appendix Paysafecard
Removed Appendix Internal Transfer
Removed Appendix FAQ
Appendix III – GBP currency removed
Appendix IV – Turkish language added
Appendix II – removed result code 1009 PaySafeCard
timeout
Removed supported currencies: BGN,RON,DKK,SEK,NOK
TrustPay, a.s.
Page 2 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>
Removed supported countries: Bulgaria, Romania,
Denmark, Sweden, Norway, Finland, Greece
TrustPay, a.s.
Page 3 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>
Table of contents
Versions .......................................................................................................................................................... 2
Table of contents ......................................................................................................................................... 4
Introduction .................................................................................................................................................. 5
Payment process ......................................................................................................................................... 7
Merchant redirects client to Trust Pay ..................................................................................................... 9
TrustPay notifies Merchant about payment ........................................................................................ 12
TrustPay redirects client to Merchant .................................................................................................... 13
Additional information for merchants Transaction country of origin identification .................. 15
1.
Internet Protocol address ............................................................................................................. 15
2.
Bank details ...................................................................................................................................... 15
Appendix I - Creating data sign ............................................................................................................. 16
Code samples .............................................................................................................................................. 16
.NET framework 2.0 (C#) ....................................................................................................................... 17
PHP ............................................................................................................................................................. 17
JAVA .......................................................................................................................................................... 17
Appendix II - Result codes........................................................................................................................ 18
Appendix III – Supported currencies ...................................................................................................... 20
Appendix IV – Supported languages .................................................................................................... 21
Appendix V – Supported countries ........................................................................................................ 22
Appendix VI – Testing of bank payments ............................................................................................. 23
Appendix VII – Card payments* ............................................................................................................. 25
Requests......................................................................................................................................................... 25
Notification.................................................................................................................................................... 25
Appendix VIII – Entering the PRODUCTION state (LIVE environment) ............................................. 27
Appendix IX – Secret key ......................................................................................................................... 28
Appendix X – GetTransactionOrigin....................................................................................................... 31
Merchant request: ...................................................................................................................................... 31
MAPI response: ............................................................................................................................................ 31
TrustPay, a.s.
Page 4 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>
Introduction
The Trust Pay (TP) Merchant API (payment service) is an internet based payment tool that
Merchants can use to receive payments from clients. This tool includes four basic payment
methods:
1. Card payments via VISA and MasterCard branded cards.
2. Bank transfers
This manual should help implement and integrate the Trust Pay Merchant API into Merchants’
e-commerce portal and ensure a functional and secure connection between Trust Pay’s server
and the Merchant’s 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. Merchant must sign an agreement with Trust Pay and fulfill all other legal and
business requirements, details of which are out of scope of this document.
2. 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 (required)
address of page where the Merchant wants to receive payment
notifications through the HTTP protocol.
o Notification E-mail address (optional)
e-mail address where the Merchant wants to receive payment
notifications by e-mails.
3. Merchant receives test data. This data is created exclusively for integration testing
purposes and works only in the test environment, not the production environment:
o One test environment PID
required to log in to Trust Pay’s internet banking on the test environment in
order to generate a secret key for your test environment accounts. For
more information - see Appendix XII
o Test account numbers for one currency (EUR)
IDs of accounts on the test environment enabled for payments (used as
AID parameter).
4. Merchant implements the necessary changes on his website, according to this
document.
5. Merchant must execute a few API payments on these test accounts in order to
verify the integration.
6. Upon successful completion of the previous step, the Merchant contacts Trust Pay
with a request to enter the production state.
TrustPay, a.s.
Page 5 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>
7. Trust Pay 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 (required)
o Notification E-mail address (optional)
8. Trust Pay processes the received data and provides the following production
environment data to the merchant:
o Production environment PID
required to log in to Trust Pay’s internet banking on the production
environment in order to generate secret keys for your production
environment accounts. For more information - see Appendix XII
o Requested account numbers
IDs of accounts enabled for payments (used as AID parameter).
9. Merchant can now enter the production (LIVE) environment by applying new
settings based on the production environment data received from Trust Pay – see
Appendix X
TrustPay, a.s.
Page 6 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>
Payment process
Trust Pay requires the Merchant to modify their payment/checkout page to include payment
options offered by Trust Pay. When the customer selects Trust Pay as a payment method, he is
actually sending data to Trust Pay’s 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 Trust Pay’s Payment Gateway.
The following chapter describes primarily the “bank transfer” solution of Trust Pay, however it
also provides a common base for all other payment options available through Trust Pay.
Payment option selection (Card payment / Bank transfer / … ) needs to be implemented on
merchant’s site / application. Once the customer is redirected to Trust Pay, he is not able to
change the payment option without returning to the merchant’s site.
Here is a simple sequence diagram of the payment process flow.
TrustPay, a.s.
Page 7 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>
TrustPay, a.s.
Page 8 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>
Merchant redirects client to Trust Pay
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 Trust Pay 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 Trust Pay 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
REF
URL
RURL
CURL
EURL
NURL
SIG
Description
Merchant account ID
ID of account assigned by Trust
Pay
Amount of the payment
exactly 2 decimal places
Currency of the payment
same as currency of merchant
account
See Appendix III
Reference
Merchant’s payment
identification
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
Format
Varchar(10)
Required
Yes
Example
1234567890
Decimal(13, 2)
en-US format
Char(3)
For secure
requests
Yes
1234.00
Char(500)
except “<”, “>”
For secure
requests
ORDER987654321
0
Varchar(256)
No
http://www.merc
hant.com/TrustP
ayReturn.html
Varchar(256)
No
Varchar(256)
No
Varchar(256)
No
Varchar(256)
No
Data sign
see Appendix I
Char(64)
For secure
requests
http://www.merc
hant.com/TrustP
ayReturn.html
http://www.merc
hant.com/TrustP
ayCancel.html
http://www.merc
hant.com/TrustP
ayError.html
https://www.mer
chant.com/Trust
PayNotification.h
tml
F3E74F2204C2D1
87
TrustPay, a.s.
EUR
Page 9 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>
LNG
CNT
DSC
EMA
Language
default language for Trust Pay
site
see Appendix IV
Country
default country of client
see Appendix V
Description
free text that will be displayed
to the user
Customer email
prefills the email address fields
for the customer when
redirected to Trust Pay
Char(2)
No
DD303CF0C5B22
CE4
1DEB8FA0C1F183
56
C05DA0F8DAFF5
B69
en
Char(2)
No
SK
Varchar(256)
No
Payment for
Order XYZ
Varchar(254)
No
email@gmail.co
m
The base “Production” URL for client redirect is: https://ib.trustpay.eu/mapi/pay.aspx
The new base “TEST” URL for client redirect is: https://ib.test.trustpay.eu/mapi/pay.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 their values must be URL encoded (according to
RFC 1738).
Example of the LINK:
<A
href="https://ib.trustpay.eu/mapi/pay.aspx?AID=9876543210&AMT=100.50&CUR=EUR&REF=1234567890
&SIG=F3E74F2204C2D187DD303CF0C5B22CE41DEB8FA0C1F18356C05DA0F8DAFF5B69">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-www-form-urlencoded.
Example of the FORM with the hidden parameters:
TrustPay, a.s.
Page 10 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>
<FORM name="form1"
action="https://ib.trustpay.eu/mapi/pay.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>
NOTE: In case your request parameter values are not being decoded correctly on the
payment site, make sure you are using UTF-8 encoding.
TrustPay, a.s.
Page 11 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>
TrustPay notifies Merchant about payment
For each announced, authorized, or successfully finished payment on the Merchant’s account,
TrustPay sends the result of the payment to the Merchant in notification URL (email) using the
following parameters:
Name
AID
TYP
AMT
CUR
REF
RES
TID
OID
TSS
SIG
Description
Merchant account ID
ID of account assigned by TrustPay
Type of transaction
CRDT or DBIT
Amount of the payment
Exactly 2 decimal places
Currency of the payment
See Appendix III
Reference
Merchant’s 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
specified by merchant.
Data sign
see Appendix I
Format
Varchar(10)
Example
1234567890
Char(4)
CRDT
Decimal(13, 2)
123.45
Char(3)
EUR
Char(500)
except “<”,
“>”
Number(4)
9876543210
Number(10)
9876543210
Number(10)
1122334455
Char(1)
Y – Yes, N – No
Char(64)
F3E74F2204C2D187
DD303CF0C5B22C
E4
1DEB8FA0C1F1835
6
C05DA0F8DAFF5B6
9
0
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 5 minute until 200 OK is received
within 75 hours (900 attempts).
Notification requests from Production environment are sent from IP 176.31.175.45
Notification requests from Test environment are sent from IP 151.80.116.200
Sample:
TrustPay, a.s.
Page 12 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>

http://www.merchant.com/result.html?AID=1234567890&TYP=CRDT&AMT=123.45&CUR=EUR&REF=
9876543210&RES=0&TID=11111&OID=1122334455&TSS=Y&SIG=F3E74F2204C2D187DD303CF0C5B22
CE41DEB8FA0C1F18356C05DA0F8DAFF5B69
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
E-mails delivered from Production environment are sent from one of the following IPs:
81.89.63.10, 46.229.226.247
E-mails delivered from Test environment are sent from IP: 217.73.23.110
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.
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 announced or authorized or a successful
payment with RES = 0
or in case of a timed out pending payment with RES=1.
Redirect to the success return URL – does not mean that merchant has received the
payment. Only the notification URL (or email if defined) is used for informing the
merchants about realized payment.

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
Description
Reference
Merchant’s payment identification
RES
Result code
See Appendix II
Processing ID (optional)
Sent when available, can be used for inquiries
regarding failed payments
PID
TrustPay, a.s.
Format
Char(500)
except “<”,
“>”
Number(4)
Example
9876543210
Number(10)
1234568790
0
Page 13 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>
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.
TrustPay, a.s.
Page 14 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>
Additional information for merchants
Transaction country of origin identification
From the 1st of January 2015, the European Union VAT changes to the place of supply of
electronic services will enter into force. The place of taxation for natural persons (non-taxable
customers) will be determined by the location of the end consumer, and digital supplies will
be taxed at the VAT rate applicable in the consumer’s member state.
For the purpose of applying the rules in Article 58 of Directive 2006/112/EC and fulfilling the
requirements of point (d) of Article 24b or Article 24d(1) of the COUNCIL IMPLEMENTING
REGULATION (EU) No 1042/2013, the following evidence shall be provided by TrustPay where
available:
 the Internet Protocol (IP) address of the device used by the customer or any method of
geolocation;
 bank details such as the location of the bank account used for payment or the billing
address of the customer held by that bank;
1. Internet Protocol address
Based on regularly updated GeoIP data the country is derived from the IP address of the
customer visiting Trust Pay’s payment site located at https://ib.trustpay.eu/mapi/...
This information is only available for payments executed through Trust Pay’s payment site. Direct
payments, white-label solutions and customer repeated payments avoid the payment site,
thus the IP is unknown to TrustPay in these scenarios. For payments made through Trust Pay’s
payment site, this evidence is available instantly.
2. Bank details
TrustPay provides two evidences (where available) regarding the banks used for payments,
those being country based on payer’s account and country based on the account where
TrustPay has been credited with the transaction.
Two of the following evidences can only be taken to constitute a single item of evidence as
they are all related to the bank location. In case both are available and should they differ,
adhere to the following rule when determining the country.
In order to determine the country based on bank, use the first available in the following order:
1. Payer’s bank country
2. Payee’s bank country
2.1. Payer’s bank country
By being able to identify the counterparty account, TrustPay can provide the evidence based
on the location of the bank where the account is open.
This information is available if provided by counterparty. This information may not be available
instantly upon receiving a payment.
2.2. Payee’s bank country
In some cases however, TrustPay does not have access to information regarding the
counterparty account. In order to provide at least some information to be able to determine
the customer’s country, TrustPay will provide the country where the funds have been received.
As the aim of the involved parties (merchant, customer, TrustPay) is to execute a payment that
TrustPay, a.s.
Page 15 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>
is credited without any delay to the merchant, one can assume that the customer will be
making an intra-bank or at least a domestic payment.
This information is available for each received payment instantly.
For technical solution see Appendix XIII - GetTransactionOrigin.
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
o
Transaction country of origin identification request: AID, TID
o
Transaction country of origin identification response: whole xml without
Signature tag with redundant white-spaces removed.

HMAC-SHA-256 code (32 bytes) is generated using a key obtained from TrustPay
(please see Appendix XII.)

Then the code is converted to a string to be a hexadecimal representation of the code
(64 upper chars)..
Code samples
Test your sign computing implementation using the following data:
key
AID
AMT
CUR
REF
SIG
abcd1234
9876543210
123.45
EUR
1234567890
DF174E635DABBFF7897A82822521DD739AE8CC2F83D65F6448DD2FF991481EA3
TrustPay, a.s.
Page 16 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>
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));
}
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);
}
TrustPay, a.s.
Page 17 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>
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 Result codes 0, 3 or 4 can be treated as a successfully executed
payment which has been or is guaranteed to be credited to Merchant’s account in TrustPay.
For card payments result codes, please see Appendix IX
Code
0
1
2
3
4
5
1001
1002
1003
1004
Description
Success
Payment was successfully processed.
When received in notification, funds have been credited to the
merchant account.
Merchant can provide goods or services without delay.
Pending
Payment is pending (offline payment)
Announced
TrustPay has been notified that the client placed a payment
order or has made payment, but further confirmation from 3 rd
party is needed. Another notification (with result code 0 success) will be sent when TrustPay receives and processes
payment from 3rd party.
Funds have not been credited to the merchant account and
there is no guarantee they will be.
Authorized
Payment was successfully authorized. Another notification
(with result code 0 - success) will be sent when TrustPay
receives and processes payment from 3rd party.
For card payments (see Appendix IX), funds will be credited to
the merchant account of the merchant in a bulk payment on
the next settlement day.
For other payments, funds will be credited to the merchant
account, at a later date.
Merchant can provide goods or services without delay.
Processing
TrustPay has received the payment, but it must be internally
processed before it is settled on the merchant‘s account.
When the payment is successfully processed, another
notification (with the result code 0 – success) will be sent.
Funds will be credited to the merchant account, at a later
date.
AuthorizedOnly – reserved for future use
Card payment was successfully authorized, but not captured.
Subsequent MAPI call(s) is (are) required to capture payment.
Invalid request
Data sent is not properly formatted
Unknown account
Account with specified ID was not found.
Please check if you are using correct account number – AID.
Merchant account disabled
Merchant account has been disabled
Invalid sign
The message is not signed correctly
TrustPay, a.s.
Returned via
redirect
email notification
http notification
redirect
email notification
http notification
email notification
http notification
email notification
http notification
redirect
email notification
http notification
redirect
redirect
redirect
redirect
Page 18 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>
1005
User cancel
Customer has cancelled the payment
Invalid authentication
request was not properly authenticated
Disposable balance
Requested transaction amount is greater than disposable
balance
redirect
1008
Service not allowed
Service cannot be used or permission to use given service has
not been granted. If you receive current code, please
contact TrustPay for more information.
redirect
1010
Transaction not found
Transaction with specified ID was not found
Unsupported transaction
The requested action is not supported for the transaction
General Error
Internal error has occurred
Unsupported currency conversion
Currency conversion for requested currencies is not supported
redirect
1006
1007
1011
1100
1101
redirect
redirect
redirect
redirect
redirect
If there is a need to contact TrustPay because some error occurred, please send to TrustPay
printscreens and URL link with parameters (GET or POST).
TrustPay, a.s.
Page 19 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>
Appendix III – Supported currencies
The following is a list of currencies (according to ISO 4217) supported by TrustPay.
Code
CZK
EUR
HUF
TRY
USD
ID
203
978
348
949
840
Name
Czech koruna
Euro
Forint
Turkish lira
US Dollar
NOTE: For the currencies CZK and HUF remember to use integers only in payment requests
(but they still have to be formatted with exactly two decimal places, e.g. “1234.00”). Using
fractional parts might result in the inability of your customers to pay the amount you
requested.
TrustPay, a.s.
Page 20 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>
Appendix IV – Supported languages
The following is a list of languages (according to ISO 639-1) supported by TrustPay.
Code
Language
bg
bs
cs
de
en
es
et
hr
hu
it
lt
lv
pl
ro
ru
sk
sl
sr
tr
uk
Bulgarian
Bosnian
Czech
German
English
Spanish
Estonian
Croatian
Hungarian
Italian
Lithuanian
Latvian
Polish
Romanian
Russian
Slovak
Slovene
Serbian
Turkish
Ukrainian
Supported for
bank
payments
Yes
Yes
Yes
No
Yes
No
Yes
Yes
Yes
No
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
No
Supported for
card
payments
No
No
Yes
Yes
Yes
Yes
No
Yes
Yes
Yes
No
No
Yes
Yes
Yes
Yes
Yes
No
No
Yes
TrustPay, a.s.
Page 21 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>
Appendix V – Supported countries
The following is a list of customer countries (according to ISO 3166-1 alpha-2) supported by
TrustPay.
Code
CZ
EE
HU
LT
LV
SI
SK
TR
Country
Czech Republic
Estonia
Hungary
Lithuania
Latvia
Slovenia
Slovak Republic
Turkey
TrustPay, a.s.
Page 22 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>
Appendix VI – Testing of bank payments
After successful implementation of the TrustPay API, the Merchant needs to test all return values
depending on the results of the payment transactions.
Secure communication using self-signed certificates isn’t supported by Trust pay. Please use
certificates issued by a certification authority.
Redirecting the client’s browser to https://ib.test.trustpay.eu/mapi/pay.aspx will display Trust
Pay’s following page.
On the second step select the country “Slovakia” in the “Currently listing banks for” field when
using a EUR test account. For tests with accounts in currencies different then EUR, select a
country with the account currency as domestic currency. Then click on the “TrustPay” bank. In
the third step, click the “Pay now” button.
Note: The TrustPay bank is a virtual instant payment Gateway used only for testing purposes.
You will then be redirected to the “TestPay” gateway page where you can choose one of
the following actions:
TrustPay, a.s.
Page 23 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>




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 (required)
or send NOTIFICATION EMAIL (optional), depending on Merchant’s configuration.
ANNOUNCED – This emulates situation when TrustPay receives notification about
payment from 3rd 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
ANNOUNCED button to receive announced notification. Later, you can click 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 Merchant’s
configuration.
Note: The Reference value in the TestPay gateway is for Trust Pay’s internal use only.
TrustPay, a.s.
Page 24 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>
Appendix VII – Card payments*
Visa and MasterCard card payments work in a way similar to bank transfers (Chapter
Payment process), with the differences described in this appendix.
Successful notifications are sent with the result code 3 – authorized, which also mean that the
payment has been captured. All payments in an agreed period will be settled later with a
single transaction; therefore you will not receive any further notifications for the individual
card transactions.
Requests
The base “Production” URL for client redirect for the card payment is:
https://ib.trustpay.eu/mapi/cardpayments.aspx
All other parameters work as described in the chapter Payment process with the following
limitations:




Only characters a-z, A-Z, 0-9 and space character of parameter DSC (description) are
displayed to a customer (payer) on the payment page. Other characters are changed
to ‘ ‘ (space). Max DSC length is Char(256)
REF allowed format is Alphanumeric(19) - only first 19 characters of the REF parameter
are stored by TrustPay for later support inquiries.
AMT allowed format is Decimal(6, 2)
EMA allowed format is Char(32)
In the return redirect URL the result code 0 is passed for successful authorization, otherwise you
will receive error codes in the ranges 600-700 and 2000-3000. These error codes are reserved for
card payments. Please contact TrustPay support at support@trustpay.eu if you received an
error.
Notification
Card payment notifications have following parameters in addition to the bank transfer
notification:
Name
CardID
CardMask
CardExp
AuthNumber
CardRecTxSec
AcqResId
SIG2
Description
ID of card payment, reserved
for future versions
Masked card number
Card expiration as MMYY
Authorization number
blank, reserved for future
versions
Card Acquirer Response ID
signature containing standard
notification data and card
payment specific data
TrustPay, a.s.
Format
Number (36)
Example
1234567892221111
Char (19)
Number(4)
Char(7)
Char(1)
444433******1111
1215
0123456
J
Char(128)
Char(64)
8418184894
FC5C07FC0340DC
10EA7F5AF4CB677
07B5F401240E00D7
821DA8681A1A9D7
22B4
Page 25 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>
SIG2 is computed from the following values:
AID, TYP, AMT, CUR, REF, RES, TID, OID, TSS, CardID, CardMask, CardExp, AuthNumber,
CardRecTxSec, AcqResId
NOTE: parameter SIG is also send for the backward compatibility as described in appendix I.
Sample:
http://www.merchant.com/result.html?type=notification&AID=2107425307&TYP=CRDT&AMT=
33.00&CUR=EUR&REF=1234567890&RES=3&TID=140344&OID=0&TSS=N&CardID=1030241464051
111&CardMask=444433******1111&CardExp=0313&AuthNumber=0548393&AcqResId=3065141
40344&CardRecTxSec=&SIG=59DD8954B7372B6BCB627264E770875B13DD68201699FA92B99DE
91D666645D4&SIG2=5FBBBE81D7F1A29133C40F94333F1D21F71D6CBBEC1BFA919164C7727B8A
E0A2
Testing of card payments can be done on the bank transfer test page (as described in
Appendix VI.) and is limited only to testing of the authorization notification by using of the
TrustPay Authorization gateway (with OK button).
*This option is enabled only for those merchants, who have an agreement with TrustPay for
card payments (stated as TrustCard service in the agreement). An error message will be
shown to all other merchants.
There is additional API manual available for card payments “Merchant API Integration
manual Card Payments Extension”, which describes card-on-file transactions, recurring card
transactions, refunds and preauthorization.
TrustPay, a.s.
Page 26 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>
Appendix VIII – 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.
The base “Production” URL for client redirect is: https://ib.trustpay.eu/mapi/pay.aspx
After TrustPay verifies that the implementation was successful, the 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
It is necessary to use the live Secret keys for the PRODUCTION (Live) environment in order to
generate correct signs. Secret key is available and can be generated by merchant in Trust
Pay’s Internet banking under Settings / Accounts settings – for more information see Appendix
XII.
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.
Please, make sure you use the test secret keys in the test environment.
Please, make sure you use the live secret keys in the production (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.
TrustPay, a.s.
Page 27 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>
Appendix IX – Secret key
A secret key is required for signing of payment data (used when generating the SIG
parameter).
Each merchant’s account ID in TrustPay has its own secret key. A new secret key can be
generated for a given account by an active disponent.
To access or generate a new secret key, follow the steps below:
1. Log in to TrustPay Internet banking with your PID and password
2. Go to Settings / Accounts settings. Under Accounts settings two action buttons are
available for each account:
“Set as default”
“Secret key” - button is displayed only for accounts where user is an active disponent
3. Click on the secret key action button
TrustPay, a.s.
Page 28 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>
The secret key will be displayed in the field “Secret key” (it is a 32 characters long random
string consisting of small letters, large letters and numbers). Apart from the secret key, also
change history details with information about who and when generated a new secret key is
displayed.
In case the merchant needs to generate a new secret key, click on the button “Generate”.
After clicking on the button a confirmation dialog is displayed in order to warn the merchant
(or his active disponent) to consider the impact of a new secret key on his integration.
TrustPay, a.s.
Page 29 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>
If dialog is confirmed, confirmation window will be closed and new secret key will be
generated. Change history will be updated with user name and actual date and time and a
new Secret key will be displayed in field Secret key.
If dialog is declined, confirmation window will be closed without generating a new secret key.
In case the generation of secret key fails, the system will display an error message. Press the
button “Generate” again and try to generate a new secret key.
Remember to update the new secret key value in your integration configuration as soon as
possible, otherwise your customers might not be able to pay and you will not be able to
process received payment notifications.
TrustPay, a.s.
Page 30 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>
Appendix X – GetTransactionOrigin
Service GetTransactionOrigin returns evidences of transaction country of origin by TransferID.
Service is available only for incoming transactions.
Merchant request:
Parameters for request are sent via method GET or POST.



AID
TID
SIG
ID of merchant account
ID of transaction
Signature
All parmeters are required. SIG is computed from AID and TID in this order. Usage of Signature
is completely described in Appendix I. in this document.
The base “Production” URL for transaction country of origin identification is:
https://ib.trustpay.eu/mapi/GetTransactionOrigin.aspx
This service will be available in the production environment from the 1st of January 2015.
The base “TEST” URL for transaction country of origin identification is:
https://ib.test.trustpay.eu/mapi/GetTransactionOrigin.aspx.
This service will be available in the test environment from the 12th of December 2014.
MAPI response:
Response is XML document with structure specified lower contains following evidences about
transaction country of payment origin:

CustomerIPCountry

PayerAccountCountry

PayeeAccountCountry
Country from IP address, from which MAPI client was
logged. Available only for MAPI payments.
Country from IBAN/BIC of debtor’s account.
Available only if provided by bank.
Country of creditor’s account.
Available for every transaction.
TrustPay, a.s.
Page 31 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>
Element
Parent
GetTransaction
OriginResponse
TransferID
ResultCode
Children
ResultCode [1]
Items [1]
Signature [1]
GetTransaction
OriginResponse
GetTransaction
OriginResponse
Items
GetTransaction
OriginResponse
Signature
GetTransaction
OriginResponse
ItemOfEvidence
Items
Name
ItemOfEvidence
Evidences
Evidence
ItemOfEvidence
Evidences
Name
Evidence
Priority
Evidence
Country
Evidence
Description
Root element
ID of transaction, same
as TID from request.
Described in Appendix
II – Result codes.
ItemOfEvidence[0..n]
Computed from whole
xml without Signature
tag with redundant
white-spaces removed.
Provided only with
ResultCode 0 and 1011.
Name [1]
Evidences [1..n]
String. Following values
available:
CustomerIP
AccountCountries
Evidence [1..n]
Name [1]
Priority [1]
Country [1]
String. Following values
available:
CustomerIPCountry
PayerAccountCountry
PayeeAccountCountry
Priority of evidence
The lower value - the
higher priority
String(3)
Format defined in
ISO3166-1Alpha-3
Signature computed from GetTransactionOriginResponse xml without Signature tag,
with redundant white-spaces removed. Signature is provided only with result codes
0 - Success and 1011 - Transaction not supported.
Completely Described in Appendix I – Creating data sign.
TrustPay, a.s.
Page 32 / 33
TrustPay
Merchant API Integration Manual
Version: 2.15 <January 2016>
Example:
<GetTransactionOriginResponse>
<TransferID>171215</TransferID>
<ResultCode>0</ResultCode>
<Items>
<ItemOfEvidence>
<Name>CustomerIP</Name>
<Evidences>
<Evidence>
<Name>CustomerIPCountry</Name>
<Priority>1</Priority>
<Country>POL</Country>
</Evidence>
</Evidences>
</ItemOfEvidence>
<ItemOfEvidence>
<Name>AccountCountries</Name>
<Evidences>
<Evidence>
<Name>PayerAccountCountry</Name>
<Priority>1</Priority>
<Country>CZE</Country>
</Evidence>
<Evidence>
<Name>PayeeAccountCountry</Name>
<Priority>10</Priority>
<Country>SVK</Country>
</Evidence>
</Evidences>
</ItemOfEvidence>
</Items>
<Signature>
DF174E635DABBFF7897A82822521DD739AE8CC2F83D65F6448DD2FF991481EA3
</Signature>
</GetTransactionOriginResponse>
TrustPay, a.s.
Page 33 / 33
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertising