When merchant SuccessUrl is https://somedomain.com/success
Then redirect url will https://somedomain.com/success?PaymentRequestId=123456&Reference=MerchhantReference
When merchant CancelUrl is https://somedomain.com/cancel
Then redirect url will https://somedomain.com/cancel?PaymentRequestId=123456&Reference=MerchhantReference
When merchant ErrorUrl is https://somedomain.com/error
Then redirect url will https://somedomain.com/error?PaymentRequestId=123456&Reference=MerchhantReference
After payment initiate, merchant is redirected to Callback Url filled in request or in project's settings depended of result of process. When result is Success or Processed, merchant will redirect to SuccessUrl. For Canceled result, CancelUrl will use. And ErrorUrl for Error, Timeout or Rejected results.
Callback Url
Description
SuccessUrl
Payment initiation was successful, now you can finish order process.
CancelUrl
Customer cancels payment process.
ErrorUrl
Error occurred during payment initiation, eg. card provider rejects the payment or request timed out, because of customer long time inactivity.
For easier payment identification, there are appended these two parameters:
Parameter
Type
Description
PaymentRequestId
Numeric
This is parameter returned in first API call's response or in notification
Reference
Varchar(35)
This is parameter contains string chose by merchant
Code lists
Supported currencies
The list of currencies (according to ISO 4217) supported by TrustPay.
Code
ID
Name
AUD
036
Australian Dollar
BAM
977
Bosnia and Herzegovina convertible mark
BGN
975
Bulgarian lev
CAD
124
Canadian Dollar
CHF
756
Swiss Franc
CNY
156
Yuan Renminbi
CZK
203
Czech koruna
DKK
208
Danish Krone
EUR
978
Euro
GBP
826
Pound sterling
HKD
344
Hong Kong Dollar
HUF
348
Hungarian forint
ILS
376
Israeli new shekel
JPY
392
Japanese yen
NOK
578
Norwegian Krone
PLN
985
Polish zloty
RON
946
Romanian leu
RSD
941
Serbian dinar
SEK
752
Swedish Krona
TRY
949
Turkish Lira
USD
840
United States dollar
Supported languages
The list of languages (according to ISO 639-1) supported by TrustPay.
Code
Language
Supported Payment Methods
en
English
All payment methods
sk
Slovak
Card Payments, Instant Bank Transfer, Instant Bank Transfer(PL), SEPA Direct Debit, SEPA Credit Transfer, IDeal, MyBank, Blik, Satispay, AircashPay, WeChatPay, Payconiq, OpenBanking
bg
Bulgarian
Card Payments
cs
Czech
Card Payments, Instant Bank Transfer, SEPA Direct Debit, IDeal, MyBank, SEPA Credit Transfer
hr
Croatian
Card Payments, Aircash
da
Danish
Card Payments
nl
Dutch
Card Payments, SEPA Direct Debit, IDeal
et
Estonian
Card Payments
fi
Finnish
Card Payments, Instant Bank Transfer (FI)
fr
French
Card Payments, SEPA Direct Debit, IDeal, MyBank
de
German
Card Payments, SEPA Direct Debit, IDeal, MyBank, OpenBanking
el
Greek
Card Payments
hu
Hungarian
Card Payments
it
Italian
Card Payments, SEPA Direct Debit, MyBank
ja
Japanese
Card Payments
lv
Latvian
Card Payments
lt
Lithuanian
Card Payments
nb
Norwegian, Bokmål
Card Payments
pl
Polish
Card Payments, Instant Bank Transfer(PL), Blik
pt
Portuguese
Card Payments, Multibanco, MbWay
ro
Romanian
Card Payments
ru
Russian
Card Payments
sl
Slovene
Card Payments
es
Spanish
Card Payments, SEPA Direct Debit, MyBank
sv
Swedish
Card Payments, Instant Bank Transfer (FI)
uk
Ukrainian
Card Payments
Result codes
The Result code provides the result of the payment request's processing. Its value is returned in response of all APIs for creating/refunding a payment of any method and in error response of any our API.
The list of Result codes
ResultCode
Description
1001000
Success
1092002
TooManyTransactions. Change the request to select less transactions.
1112002
AlreadyCanceledReversed
1112003
CancelReversalAlreadyProcessing
1112004
CutoffTimeExceeded
1112005
CancelReversalNotAllowed
1112008
InvalidPaymentState
1112009
RefundRejected
1122006
AccountCurrencyNotAllowed
1130000
MapiSuccess
1130001
MapiPending
1130002
MapiAnnounced
1130003
MapiAuthorized
1130004
MapiProcessing
1130005
MapiAuthorizedOnly
1132000
InvalidMapiRequest
1132001
UnknownAccount
1132002
MerchantAccountDisabled
1132003
InvalidSign
1132004
DisposableBalance
1132005
TransactionNotFound
1132006
UnsupportedTransaction
1132007
GeneralMapiError
1132008
UnsupportedCurrencyConversion
1132009
UnknownMandate
1132010
CanceledMandate
1132011
MissingCid
1132012
MandateAlreadyPaid
1132013
AccountIsTesting
1132014
RequestThrottled
1133000
InvalidAuthentication
1133001
ServiceNotAllowed
1133002
PaymentRequestNotFound
1133003
UnexpectedGateway
1133004
MissingExternalId
1133005
ApiDomainNotAllowed
1152000
RiskDecline
Reason codes
Value of the Reason code specifies why the payment request was rejected. Its value is available for unsuccessful payment requests in Notifications and via Get Payment State API.
The list of Reason codes
Code
Description
000.000.000
Transaction succeeded
000.000.100
Successful request
000.100.105
Chargeback Representment is successful
000.100.106
Chargeback Representment cancellation is successful
000.100.110
Request successfully processed in 'Merchant in Integrator Test Mode'
000.100.111
Request successfully processed in 'Merchant in Validator Test Mode'
000.100.112
Request successfully processed in 'Merchant in Connector Test Mode'
000.100.200
Reason not Specified
000.100.201
Account or Bank Details Incorrect
000.100.202
Account Closed
000.100.203
Insufficient Funds
000.100.204
Mandate not Valid
000.100.205
Mandate Cancelled
000.100.206
Revocation or Dispute
000.100.207
Cancellation in Clearing Network
000.100.208
Account Blocked
000.100.209
Account does not exist
000.100.210
Invalid Amount
000.100.211
Transaction succeeded (amount of transaction is smaller then amount of pre-authorization)
000.100.212
Transaction succeeded (amount of transaction is greater then amount of pre-authorization)
000.100.220
Fraudulent Transaction
000.100.221
Merchandise Not Received
000.100.222
Transaction Not Recognized By Cardholder
000.100.223
Service Not Rendered
000.100.224
Duplicate Processing
000.100.225
Credit Not Processed
000.100.226
Cannot be settled
000.100.227
Configuration Issue
000.100.228
Temporary Communication Error - Retry
000.100.229
Incorrect Instructions
000.100.230
Unauthorised Charge
000.100.231
Late Representment
000.100.232
Liability Shift
000.100.233
Authorization-Related Chargeback
000.100.234
Non receipt of merchandise
000.100.299
Unspecified (Technical)
000.200.000
Transaction pending
000.200.001
Transaction pending for acquirer, the consumer is not present
000.200.100
Successfully created checkout
000.200.101
Successfully updated checkout
000.200.102
Successfully deleted checkout
000.200.103
Checkout is pending
000.200.200
Transaction initialized
000.200.201
QR Scanned/Link Clicked, waiting for the final authentication result
000.300.000
Two-step transaction succeeded
000.300.100
Risk check successful
000.300.101
Risk bank account check successful
000.300.102
Risk report successful
000.300.103
Exemption check successful
000.310.100
Account updated
000.310.101
Account updated (Credit card expired)
000.310.110
No updates found, but account is valid
000.400.000
Transaction succeeded (please review manually due to fraud suspicion)
000.400.010
Transaction succeeded (please review manually due to AVS return code)
000.400.020
Transaction succeeded (please review manually due to CVV return code)
000.400.030
Transaction partially failed (please reverse manually due to failed automatic reversal)
000.400.040
Transaction succeeded (please review manually due to amount mismatch)
000.400.050
Transaction succeeded (please review manually because transaction is pending)
000.400.060
Transaction succeeded (approved at merchant's risk)
000.400.070
Transaction succeeded (waiting for external risk review)
000.400.080
Transaction succeeded (please review manually because the service was unavailable)
000.400.081
Transaction succeeded (please review manually, as the risk status not available yet due network timeout)
000.400.082
Transaction succeeded (please review manually, as the risk status not available yet due processing timeout)
000.400.090
Transaction succeeded (please review manually due to external risk check)
000.400.100
Transaction succeeded, risk after payment rejected
000.400.101
Card not participating/authentication unavailable
000.400.102
User not enrolled
000.400.103
Technical Error in 3D system
000.400.104
Missing or malformed 3DSecure Configuration for Channel
000.400.105
Unsupported User Device - Authentication not possible
000.400.106
Invalid payer authentication response(PARes) in 3DSecure Transaction
000.400.107
Communication Error to Scheme Directory Server
000.400.108
Cardholder Not Found - card number provided is not found in the ranges of the issuer
000.400.109
Card is not enrolled for 3DS version 2
000.400.110
Authentication successful (frictionless flow)
000.400.111
Data Only request failed
000.400.112
3RI transaction not permitted
000.400.120
Authentication successful (data only flow)
000.400.200
Risk management check communication error
000.500.000
Transaction succeeded - very good rating
000.500.100
Transaction succeeded (address corrected)
000.600.000
Transaction succeeded due to external update
100.100.100
Request contains no creditcard, bank account number or bank name
100.100.101
Invalid creditcard, bank account number or bank name
100.100.104
Invalid unique id / root unique id
100.100.200
Request contains no month
100.100.201
Invalid month
100.100.300
Request contains no year
100.100.301
Invalid year
100.100.303
Card expired
100.100.304
Card not yet valid
100.100.305
Invalid expiration date format
100.100.400
Request contains no cc/bank account holder
100.100.401
Cc/bank account holder too short or too long
100.100.402
Cc/bank account holder not valid
100.100.500
Request contains no credit card brand
100.100.501
Invalid credit card brand
100.100.600
Empty CVV for VISA, MASTER, AMEX not allowed
100.100.601
Invalid CVV/brand combination
100.100.650
Empty CreditCardIssueNumber for MAESTRO not allowed
100.100.651
Invalid CreditCardIssueNumber
100.100.700
Invalid cc number/brand combination
100.100.701
Blacklist Validation (50) suspecting fraud, this card may not be processed
100.150.100
Request contains no Account data and no registration id
100.150.101
Invalid length for specified registration id (must be 32 chars)
100.150.200
Registration does not exist
100.150.201
Registration is not confirmed yet
100.150.202
Registration is already deregistered
100.150.203
Registration is not valid, probably initially rejected
100.150.204
Account registration reference pointed to no registration transaction
100.150.205
Referenced registration does not contain an account
100.150.300
Payment only allowed with valid initial registration
100.200.100
Bank account contains no or invalid country
100.200.103
Bank account has invalid bankcode/name account number combination
100.200.104
Bank account has invalid acccount number format
100.200.200
Bank account needs to be registered and confirmed first. Country is mandate based.
100.210.101
Virtual account contains no or invalid Id
100.210.102
Virtual account contains no or invalid brand
100.211.101
User account contains no or invalid Id
100.211.102
User account contains no or invalid brand
100.211.103
No password defined for user account
100.211.104
Password does not meet safety requirements (needs 8 digits at least and must contain letters and numbers)
100.211.105
Wallet id has to be a valid email address
100.211.106
Voucher ids have 32 digits always
100.212.101
Wallet account registration must not have an initial balance
100.212.102
Wallet account contains no or invalid brand
100.212.103
Wallet account payment transaction needs to reference a registration
100.250.100
Job contains no execution information
100.250.105
Invalid or missing action type
100.250.106
Invalid or missing duration unit
100.250.107
Invalid or missing notice unit
100.250.110
Missing job execution
100.250.111
Missing job expression
100.250.120
Invalid execution parameters, combination does not conform to standard
100.250.121
Invalid execution parameters, hour must be between 0 and 23
100.250.122
Invalid execution parameters, minute and seconds must be between 0 and 59
100.250.123
Invalid execution parameters, Day of month must be between 1 and 31
100.250.124
Invalid execution parameters, month must be between 1 and 12
100.250.125
Invalid execution parameters, Day of week must be between 1 and 7
100.250.250
Job tag missing
100.300.101
Invalid test mode (please use LIVE or INTEGRATOR_TEST or CONNECTOR_TEST)
100.300.200
Transaction id too long
100.300.300
Invalid reference id
100.300.400
Missing or invalid channel id
100.300.401
Missing or invalid sender id
100.300.402
Missing or invalid version
100.300.501
Invalid response id
100.300.600
Invalid or missing user login
100.300.601
Invalid or missing user pwd
100.300.700
Invalid relevance
100.300.701
Invalid relevance for given payment type
100.310.401
Account management type not supported
100.310.402
Account management transaction not allowed in current state
100.350.100
Referenced session is REJECTED (no action possible).
100.350.101
Referenced session is CLOSED (no action possible)
100.350.200
Undefined session state
100.350.201
Referencing a registration through reference id is not applicable for this payment type
Transaction declined (transaction in wrong state on aquirer side)
800.100.192
Transaction declined (invalid CVV, Amount has still been reserved on the customer's card and will be released in a few business days. Please ensure the CVV code is accurate before retrying the transaction)
Transaction declined (revocation of authorisation order)
800.100.500
Card holder has advised his bank to stop this recurring payment
800.100.501
Card holder has advised his bank to stop all recurring payments for this merchant
800.110.100
Duplicate transaction
800.120.100
Rejected by throttling
800.120.101
Maximum number of transactions per account already exceeded
800.120.102
Maximum number of transactions per ip already exceeded
800.120.103
Maximum number of transactions per email already exceeded
800.120.200
Maximum total volume of transactions already exceeded
800.120.201
Maximum total volume of transactions per account already exceeded
800.120.202
Maximum total volume of transactions per ip already exceeded
800.120.203
Maximum total volume of transactions per email already exceeded
800.120.300
Chargeback rate per bin exceeded
800.120.401
Maximum number of transactions or total volume for configured MIDs or CIs exceeded
800.121.100
Channel not configured for given source type. Please contact your account manager.
800.121.200
Secure Query is not enabled for this entity. Please contact your account manager.
800.121.300
SMS is not enabled for this entity. Please contact your account manager.
800.130.100
Transaction with same TransactionId already exists
800.140.100
Maximum number of registrations per mobile number exceeded
800.140.101
Maximum number of registrations per email address exceeded
800.140.110
Maximum number of registrations of mobile per credit card number exceeded
800.140.111
Maximum number of registrations of credit card number per mobile exceeded
800.140.112
Maximum number of registrations of email per credit card number exceeded
800.140.113
Maximum number of registrations of credit card number per email exceeded
800.150.100
Account Holder does not match Customer Name
800.160.100
Invalid payment data for configured Shopper Dispatching Type
800.160.110
Invalid payment data for configured Payment Dispatching Type
800.160.120
Invalid payment data for configured Recurring Transaction Dispatching Type
800.160.130
Invalid payment data for configured TicketSize Dispatching Type
800.190.999
Unknown risk error
800.200.159
Account or user is blacklisted (card stolen)
800.200.160
Account or user is blacklisted (card blocked)
800.200.165
Account or user is blacklisted (card lost)
800.200.202
Account or user is blacklisted (account closed)
800.200.208
Account or user is blacklisted (account blocked)
800.200.220
Account or user is blacklisted (fraudulent transaction)
800.300.101
Account or user is blacklisted
800.300.102
Country blacklisted
800.300.200
Email is blacklisted
800.300.301
Ip blacklisted
800.300.302
Ip is anonymous proxy
800.300.401
Bin blacklisted
800.300.499
Card scheme blacklisted
800.300.500
Transaction temporary blacklisted (too many tries invalid CVV)
800.300.501
Transaction temporary blacklisted (too many tries invalid expire date)
800.310.200
Account closed
800.310.210
Account not found
800.310.211
Account not found (BIN/issuer not participating)
800.400.100
AVS Check Failed
800.400.101
Mismatch of AVS street value
800.400.102
Mismatch of AVS street number
800.400.103
Mismatch of AVS PO box value fatal
800.400.104
Mismatch of AVS zip code value fatal
800.400.105
Mismatch of AVS settings (AVSkip, AVIgnore, AVSRejectPolicy) value
800.400.110
AVS Check Failed. Amount has still been reserved on the customer's card and will be released in a few business days. Please ensure the billing address is accurate before retrying the transaction.
800.400.150
Location validation (37), Implausible address data
800.400.151
Implausible address state data
800.400.200
Invalid Payer Authentication in 3DSecure transaction
800.400.500
Waiting for confirmation of non-instant payment. Denied for now.
800.400.501
Waiting for confirmation of non-instant debit. Denied for now.
800.400.502
Waiting for confirmation of non-instant refund. Denied for now.
800.500.100
Direct debit transaction declined for unknown reason
800.500.110
Unable to process transaction - ran out of terminalIds - please contact acquirer
800.600.100
Transaction is being already processed
800.700.100
Transaction for the same session is currently being processed, please try again later
800.700.101
Family name too long
800.700.201
Given name too long
800.700.500
Company name too long
800.800.102
Invalid street
800.800.202
Invalid zip
800.800.302
Invalid city
800.800.400
Connector/acquirer system is under maintenance
800.800.800
The payment system is currenty unavailable, please contact support in case this happens again.
800.800.801
The payment system is currenty unter maintenance. Please apologize for the inconvenience this may cause. If you were not informed of this maintenance window in advance, contact your sales representative.
800.900.100
Sender authorization failed
800.900.101
Invalid email address (probably invalid syntax)
800.900.200
Invalid phone number (has to start with a digit or a '+', at least 7 and max 25 chars long)
800.900.201
Unknown channel
800.900.300
User authorization failed
800.900.301
User authorization failed, user has no sufficient rights to process transaction
800.900.302
Authorization failed
800.900.303
No token created
800.900.399
Secure Registration Problem
800.900.401
Invalid IP number
800.900.450
Invalid birthdate
900.100.100
Unexpected communication error with connector/acquirer
900.100.200
Error response from connector/acquirer
900.100.201
Error on the external gateway (e.g. on the part of the bank, acquirer,...)
900.100.202
Invalid transaction flow, the requested function is not applicable for the referenced transaction.
900.100.203
Error on the internal gateway
900.100.204
Error during message parsing
900.100.205
Error response from token vault
900.100.300
No response from connector/acquirer [uncertain result]
900.100.301
Transaction timed out without response from connector/acquirer. It was reversed.
900.100.310
Transaction timed out due to internal system misconfiguration. Request to acquirer has not been sent.
900.100.400
Timeout at connectors/acquirer side
900.100.500
Timeout at connectors/acquirer side (try later)
900.100.600
Connector/acquirer currently down
900.100.700
Error on the external service provider
900.200.100
Message Sequence Number of Connector out of sync
900.300.600
User session timeout
900.400.100
Unexpected communication error with external risk provider
999.999.888
Undefined platform database error
999.999.999
Undefined connector/acquirer error
Notifications
Notification Signature
Creating a secret key
You can view the project's secret key in TrustPay Merchant Portal under Technical Settings – Secret Key.
You can view your secret key any time. You are also able to see the history of secret keys and generate a new key if required.
Creating a Notification signature
using System;
using System.Security.Cryptography;
using System.Text;
public static string GetSignature(string key, string message)
{
using (var hmac = HMAC.Create("HMACSHA256"))
{
hmac.Key = Encoding.UTF8.GetBytes(key);
byte[] signature = hmac.ComputeHash(Encoding.UTF8.GetBytes(message));
return BitConverter.ToString(signature).Replace("-", "").ToUpperInvariant();
}
}
function GetSignature($key, $message){
return strtoupper(hash_hmac('sha256', pack('A*', $message), pack('A*', $key)));
}
public static String GetSignature(String key, String message) throws Exception
{
byte[] keyBytes = key.getBytes("UTF-8");
byte[] messageBytes = message.getBytes("UTF-8");
javax.crypto.Mac mac = javax.crypto.Mac.getInstance("HmacSHA256");
mac.init(new javax.crypto.spec.SecretKeySpec(keyBytes, mac.getAlgorithm()));
return ByteArrayToHexString(mac.doFinal(messageBytes));
}
public static String ByteArrayToHexString(byte[] b)
{
java.math.BigInteger bi = new java.math.BigInteger(1, b);
return String.format("%0" + (b.length << 1) + "X", bi);
}
HMAC-SHA-256 (RFC 2104) code is used for checking the integrity of the data sent between TrustPay and Merchant.
This Notification signature is created using the secret key and message data.
Data signature calculated from concatenated values of all values (in ASCII sorted order) in the notification.
Slash character ('/') is used as separator. Not empty values are sorted in ascending order and then concatenated using the separator.
After computing the signature, it needs to be converted to hexadecimal uppercase string.
Functions for creating the signature in .NET C#, PHP and JAVA are provided by TrustPay.
Verification of Notification signature
Transaction notifications
In MerchantPortal you can enable notifications not only about succeeded transactions but rejected, authorized and chargebacked too. These notifications differs from common ones by they Status property.
Format of notifications is same for URL and email notifications.
This function allows refunding or canceling (if it is possible) a transaction.
You can cancel SEPA Direct Debits with separate API request.
Request
Parameters are the same as for standard Purchase with more optional parameters, but endpoint url is different and these additional parameters have to be added to the request:
Refund example:
using System.Net;
using System.Text;
using System.Web.Script.Serialization;
public string RefundPayment(string token)
{
string url = "https://aapi.trustpay.eu/api/Payments/Payment/[PaymentRequestId]/Refund";
using (var client = new WebClient())
{
client.Headers = new WebHeaderCollection
{
"Authorization: Bearer " + token,
"Content-Type: application/json"
};
var request = new
{
MerchantIdentification = new
{
ProjectId = 4107123456
},
PaymentInformation = new
{
Amount = new
{
Amount = 1.50,
Currency = "EUR",
},
References = new
{
MerchantReference = "Order 12345"
},
},
};
JavaScriptSerializer serializer = new JavaScriptSerializer();
var requestdata = Encoding.UTF8.GetBytes(serializer.Serialize(request));
var responseData = client.UploadData(url, requestdata);
var response = serializer.Deserialize<dynamic>(Encoding.UTF8.GetString(responseData));
if (Encoding.UTF8.GetString(responseData) == "{}")
{
return "Refund was successful";
}
return response["ResultInfo"];
}
}
Description of result that occurred during the service call.
Varchar(235)
Payment Methods
Card Payments PopUp
Merchant's implementation has to include link to Merchant API JavaScript on it's page and load the TrustPay payment gateway inside an IFrame. Url to payment gateway is filled in response on initiate request. (Initiate request is json object, sent on API endpoint, as you can see in Payment example) The included JavaScript will style the IFrame so that it is hidden. It also contains the code necessary to show the payment gateway from the hidden IFrame as a popup overlaid over the merchant's e-shop. To allow users to show the payment gateway popup, the merchant needs to include some link/button/etc. with CSS class "show-popup" somewhere on the page. Onclick event handler that shows the popup will be automatically added to this element. Please see the example to the right.
Payment
API endpoints:
Live - https://aapi.trustpay.eu/api/Payments/Payment
<scripttype="text/javascript"src="https://mapi.trustpay.eu/mapi5/Scripts/TrustPay/popup.js"></script><iframeid="TrustPayFrame"src="https://aapi.trustpay.eu/Payments/Gateway?paymentRequestId=123123&sig=58B2FA9C45AEE707FFB6A4A0749D2"></iframe><ahref="#"class="show-popup">Pay via TrustPay</a>
This functionality allows merchant to perform preauthorization followed by a later capture.
It is suitable in scenarios where reservation is required earlier than delivery of goods or services is possible.
When the merchant performs a preauthorization, the amount on the card is only reserved. This works in a similar way to standard transaction.
Capture is performed later in the background by the merchant's system.
Once a transaction has been authorized, you can request a capture to complete the transaction.
This is done by a background call using parameters received in the notification of the preauthorization.
In References parameter set OriginalPaymentRequestId to payment request ID from 1. response or from notification
Numeric(10)
Yes
Card On File
Card on file functionality allows merchants to store card tokens in their systems, without storing any sensitive card data (card number, expiry date, CVV code) and to subsequently use such tokens to process payments, without any need for the client (cardholder) to enter any card details during subsequent purchases.
Parameters of request and response for card on file are the same as for standard payment, but these additional parameters have to be added to the request:
To register card for later card on file purchases, a first purchase must be made that works similar to standard purchase, but this
additional parameter is required:
Parameters of request and response for card on file authorization are the same as for standard payment, but these additional parameters have to be added to the request:
Parameters of request and response for card on file authorization are the same as for standard payment, but these additional parameters have to be added to the request:
Recurring transactions allow repetition of card payments. For instance, this allows merchant to implement auto-recharge payments or scheduled payments.
Merchants responsibilities:
Save the payment request ID (PaymentRequestId) of the initial payment
Once an initial transaction was made, you can make repeated transactions.
This is done by a background call using the parameters received in the notification of initial transaction.
In References parameter set OriginalPaymentRequestId to payment request ID from Recurring Initial response or from notification
Boolean
Yes
Check required and optional parameters in Refunds section.
Recurring Initial Preauthorization
Recurring Initial Preauthorization allows Recurring Subsequent or later Capture of card payments.
For instance, this allows merchant to implement auto-recharge payments or scheduled payments.
Note that 0.00 Amount is acceptable for Recurring Initial Preauthorization so that only recurring subsequent payments are available for later processing.
Merchants responsibilities:
Save the payment request ID (PaymentRequestId) of the initial payment
Payment fails with result failed 3DS authentication
4200 0000 0000 0004
Payment fails with result insufficient funds
4200 0000 0000 0005
Payment fails with result invalid CVV
4200 0000 0000 0006
Payment fails with result invalid expiry date
4200 0000 0000 0007
Payment fails with result too many invalid tries
Any other card number
Payment fails with result invalid card number
Card Payments EmbeddedFields
TrustPay Gateway Embedded Fields API is a web-based payment widget that the merchants can use
to receive payments from their customers.
Together with TP.js it enables a simple, customizable and secure way to integrate payment forms into a website.
TrustPay Gateway supports the following payment methods:
Payment Card
Google Pay
Apple Pay
Embedded Fields API endpoint:
Live - https://tpgw.trustpay.eu/client/v1/
Overview of the payment process:
Customer creates an order on the merchant's site.
(Server side) Merchant uses the order details and an API key to create a payment intent.
As a result, the merchant receives a unique identifier instanceId and a set of secrets:
The instanceId represents TrustPay's payment reference. It can be used to (re)obtain a
payment's status or in some requests (capture, refund, reverse) to reference a previous payment.
The set of secrets are used by the TP.js client to communicate with TrustPay services.
(Merchant's site) HTML placeholder elements are placed on the website into which the payment components will be loaded.
(Server side) The merchant checks the payment status through a Transaction status call.
Prerequisites:
Include TrustPay's v1.js file on the merchant's webpage.
Initialization
Every TrustPay payment using Embedded Fields must start with the server side
Create Intent call.
The merchant uses the Create Intent call to create a payment instance.
The payment instance is a unique TrustPay entity that represents the intent to execute a payment.
Its id (instanceId) can be used later to (re)obtain a payment's status or in some requests
to reference a previous payment (applies to capture, reverse and refund).
Create Intent
Create Intent endpoint:
Live - https://tpgw.trustpay.eu/api/v1/intent
An authentication header X-API-KEY needs to be present this request.
Request
Name
Description
Format
Required
X-API-KEY
The merchant's TrustPay API key, this parameter is supplied via HTTP header
3.1. Combined Card Component Layout
A card component layout that displays all three card data inputs (PAN, Expiration date and CVV) combined in a single joint input.
You can style the card inputs, but you can't reorder them.
Example of this layout:
To create your own layout with the combined card component:
Card component placeholder:
<div id="card-element"></div>
3.1.1. Place a card placeholder HTML element on your webpage
Card component creation:
var cardComponent = trustPayApi.createComponent("card", {
style: {
// style properties to apply to the joint card data input and to the placeholder (see available properties)
}
});
3.1.2. Create TrustPay's card component using TrustPayApi object in your JavaScript code
Mount your card component to a placeholder:
cardComponent.mount("#card-element"});
3.1.3. Mount the card component created to the placeholder HTML element
3.2. Custom Card Component Layout
Instead of creating one card component with a pre-built layout, you
can arrange all the card components (Cardholder, PAN, Expiration date, CVV) separately
and lay them out as needed.
Example of a custom layout:
To create your own layout with separate card components:
3.2.1. Place HTML placeholders on your webpage for each of the card components (Cardholder, PAN, Expiration date, CVV)
Card components placeholders:
var cardHolderComponent = trustPayApi.createComponent("cardHolder", {
style: {
// style properties to apply to the card holder input and the placeholder (see available properties)
}
});
var cardPanComponent = trustPayApi.createComponent("cardNumber", {
style: {
// style properties to apply to the card number input and the placeholder (see available properties)
}
});
var cardExpComponent = trustPayApi.createComponent("cardExpirationDate", {
style: {
// style properties to apply to the card pan input and the placeholder (see available properties)
}
});
var cardCvvComponent = trustPayApi.createComponent("cardVerificationCode", {
style: {
// style properties to apply to the card cvv input and the placeholder (see available properties)
}
});
3.2.2. Create the TrustPay's card components using TrustPayApi object in your JavaScript code
3.2.3. Mount the card components created to the placeholder corresponding HTML elements
4.
Create a Pay button on your webpage
Example of a pay button's click handler:
document.getElementById("button-pay").addEventListener("click", function(){
// send card data to TrustPay and execute payment
// payment secret can be found in secrets object you have received from server
trustPayApi.finishCardPayment(paymentSecret, { card: cardComponent}).then(function(result) {
if (result.status >= 0) {
// the payment has completed successfully
// execute additional payment status check on your server
// show success to your customer
} else {
// the payment has failed
// execute additional payment status check on your server
// show error to your customer
}
})
.catch(function(result) {
// the payment has failed
// show error to your customer
});
});
Only a selected subset of the css styling properties are accepted by the TrustPayApi's card data input components.
They are color, border, border-width, font-family, font-size, font-weight, outline, text-align, and letter-spacing.
Checking Payment Status
After you receive a payment status on the client-side, we recommend to do an additional
payment status check on your backend using a Get Transaction Status call.
Use paymentStatus property to determine whether the payment was successful.
The paymentStatus has the following format: nnn.nnn.nnn,
where n is a number from the interval <0, 9>.
The payment is considered successful if the paymentStatus:
starts with 000.000.
starts with 000.100.1
starts with 000.3
starts with 000.6
equals 000.400.110
equals 000.400.120
Get Transaction Status call
Get Transaction Status call can be used to retrieve information about the operation.
Get Transaction Status endpoint:
Live - https://tpgw.trustpay.eu/api/v1/Instance/{instanceId}
Request
The instanceId needs to be provided as a GET parameter.
This API call is an HTTP GET request.
An authentication header X-API-KEY needs to be present in this request.
This functionality allows merchants to perform preauthorization
followed by a later capture. It is suitable in scenarios where
reservation is required earlier than delivery of goods or services is possible.
When the merchant performs a preauthorization, the amount on the card is
only reserved. This works in a similar way as a standard transaction.
Capture is performed later as a backend call by the merchant's system.
Once a transaction has been authorized, you can either request a capture
to complete the transaction or reverse to revert the transaction. This is
done by the merchant using a backend call.
Integration
1.
Initialize a payment request with a Create Intent call
This is the same process as with a standard Card Payment operation,
but there is one additional PaymentAction parameter required:
Capture or Reverse the payment using our backend S2S API call
Recurring Payment
Recurring transactions allow repetition of card payments. For instance, this allows merchant to implement auto-recharge payments or scheduled payments.
Once the customers give permission to the merchant, the amount can be deducted at predefined intervals until the customer retracts their permission or the subscription expires.
Once an initial transaction was made, you can make repeated transactions.
This is done by a backend call using the parameters received in the
Create Intent call.
Integration
1.
Initialize a payment request with a Create Intent call
Use the same parameters as you would with standard
Create Intent, but there is one additional
parameter PaymentType required:
Card on file functionality allows merchants to store card tokens in their systems, without storing any sensitive card data (card number, expiry date, CVV code) and to subsequently use such tokens to process payments, without any need for the client (cardholder) to enter any card details during subsequent purchases.
Once an initial transaction was made, you can make repeated transactions.
This is done by a backend call using the parameters received in the
Create Intent call.
Integration
1.
Initialize a payment request with a Create Intent call
Use the same parameters as you would with standard
Create Intent, but there is one additional
parameter PaymentType required:
The first payment of a card on file payment request
CardOnFileSubsequent
Subsequent payment of a card on file payment request
PaymentAction
PaymentAction is an enumeration type.
Value
Description
Purchase
Ordinary purchase request, implicit
Preauthorization
Reserve amount on customer's credit card, must be release later by Capture/Reverse
Currency
Use ISO-4217 alphabetical code as a currency, e.g. EUR.
List of commonly used currencies:
Code
ID
Name
CZK
203
Czech koruna
EUR
978
Euro
HUF
348
Hungarian forint
USD
840
United States dollar
Response
Status
Status is an integer type that represents server call status.
Value
Description
0
Call succeeded
1
Call succeeded, pending operation
< 0
Failure
Secrets
Object that holds client secrets, consisting of:
Property
Description
display
Used internally by TrustPay API to load widgets
payment
Used by the customer to execute payment
Card Payments ServerToServer
TrustPay Gateway API (TPGW API) allows for a direct communication with payment provider.
API endpoints:
Live - https://tpgw.trustpay.eu/api/v1
Requests to TPGW API are made as HTTP POST requests with parameters sent as form data if not specified otherwise.
All parameter names are case-insensitive.
Most of the requests to TPGW API return a unique operation identifier - InstanceId. This can be used to (re)obtain a payment's status or in some requests to reference a previous payment.
Authentication
An authentication header X-API-KEY needs to be present in all TPGW API requests.
Purchase
Represents a basic payment request.
Purchase endpoint:
Live - https://tpgw.trustpay.eu/api/v1/purchase
A recurring payment is subsequent to some initial payment which it must reference in some way.
You may reference to an initial TPGW payment by its InstanceId while not providing the card data, or you may reference to any initial payment by its CardSchemeTxId while providing the card data.
Initial recurring
To set up new recurring payments via TPGW you need first to create an initial recurring payment.
A successful response includes its InstanceId required for future reference.
To relay a subsequent recurring payment without the initial recurring payment executed via TPGW reference to it with its CardSchemeTxId and provide the card data.
In response to a recurring request a Merchant Advice Code can be present.
These codes offer guidance to merchants on action that can be taken.
MAC can be as follows:
Response Code
Description
00
Others
01
New/ Updated Account Information is available
02
Try again later
03
Do not try again
21
Recurring Payment Cancellation Service
Scheme Response Code
In response to a recurring request a Scheme Response Code can be present.
This code indicates an issuer’s reason for approving or declining a transaction.
Scheme Response Code can be as follows:
Scheme Response Code
Description
00
Approved or completed successfully
01
Refer to card issuer
03
Invalid merchant
04
Capture card
05
Do not honor
08
Honor with ID
10
Partial Approval
12
Invalid transaction
13
Invalid amount
14
Invalid card number
15
Invalid issuer
30
Format error
41
Lost card
43
Stolen card
51
Insufficient funds/over credit limit
54
Expired card
55
Invalid PIN
57
Transaction not permitted to issuer/cardholder
58
Transaction not permitted to acquirer/terminal
61
Exceeds withdrawal amount limit
62
Restricted card
63
Security violation
65
Exceeds withdrawal count limit
70
Contact Card Issuer
71
PIN Not Changed
75
Allowable number of PIN tries exceeded
76
Invalid/nonexistent “To Account” specified
77
Invalid/nonexistent “From Account” specified
78
Invalid/nonexistent account specified (general)
79
Life cycle (Mastercard use only)
80
System not available
81
Domestic Debit Transaction Not Allowed (Regional use only)
82
Policy (Mastercard use only)
83
Fraud/Security (Mastercard use only)
84
Invalid Authorization Life Cycle
85
Not declined
86
PIN Validation not possible
87
Purchase Amount Only, No Cash Back Allowed
88
Cryptographic failure
89
Unacceptable PIN—Transaction Declined—Retry
90
Cutoff is in progress
91
Authorization System or issuer system inoperative
92
Unable to route transaction
94
Duplication transaction detected
96
System error
1Z
Authorization System or issuer system inoperative
Card on File Purchase
A basic purchase may be requested to store the card data.
Such purchase shall generate a unique handle for the end consumer of the service.
You may register a card within TPGW and reference to it with the provided CardId or you may relay a subsequent Card on File transaction with providing the card data on your own.
Initial Card on File
A basic purchase can be marked as an initial card on file purchase in order to store the card data.
Successful request returns the card's unique CardId which can be later used to reference to the card data without actually providing it.
{
"status": 0,
"description": "Request successfully processed in 'Merchant in Connector Test Mode'",
"instanceId": "fhtK20BZvLa8o2Chlrq44w",
"paymentStatus": "000.100.112",
"paymentDescription": "Request successfully processed in 'Merchant in Connector Test Mode'"
}
Refund
A refund is performed against a previous payment, referencing its InstanceId.
Refund can be used to return full or partial amount.
Refund endpoint:
Live - https://tpgw.trustpay.eu/api/v1/refund
{
"status": 0,
"description": "Request successfully processed in 'Merchant in Connector Test Mode'",
"instanceId": "fhtK20BZvLa8o2Chlrq44w",
"paymentStatus": "000.100.112",
"paymentDescription": "Request successfully processed in 'Merchant in Connector Test Mode'"
}
Reversal
A reversal is performed against an already processed Preauthorization (PA) or Purchase (DB), referencing its InstanceId.
A Reversal is only possible until specific cut-off time.
Reversal endpoint:
Live - https://tpgw.trustpay.eu/api/v1/reverse
{
"status": 0,
"description": "Request successfully processed in 'Merchant in Connector Test Mode'",
"instanceId": "fhtK20BZvLa8o2Chlrq44w",
"paymentStatus": "000.100.112",
"paymentDescription": "Request successfully processed in 'Merchant in Connector Test Mode'"
}
Transaction status
Transaction status endpoint:
Live - https://tpgw.trustpay.eu/api/v1/instance/{instanceId}
This call is used to query status of an instance/transaction.
Use InstanceId as a query parameter.
This API call is an HTTP GET request.
Electronic Commerce Indicator (ECI)
ECI value
Flow type
Brand
Description
00
Non-3DS
MasterCard
3DS authentication is either failed or could not be attempted. Possible reasons being both card and Issuing Bank are not secured by 3DS, technical errors, or improper configuration.
01
Partial 3DS
MasterCard
3DS authentication was attempted but was not or could not be completed. Possible reasons being either the card or its Issuing Bank has yet to participate in 3DS, or cardholder ran out of time to authorize.
02
Fully 3DS
MasterCard
3DS authentication is successful and both card and Issuing Bank are secured by 3DS.
05
Fully 3DS flow
VISA
3DS authentication was successful. Transactions are secured by 3DS.
06
Partial 3DS
VISA
3DS authentication was attempted but was not or could not be completed. Possible reasons being either the card or its Issuing Bank has yet to participate in 3DS.
07
Non-3DS
VISA
3DS authentication is either failed or could not be attempted. Possible reasons being both card and Issuing Bank are not secured by 3DS, technical errors, or improper configuration.
Customer parameter names are prefixed with Customer.
Name
Description
Format
Required
IpAddress
Customer's IP address (IPv4 / IPv6)
Varchar(45)
Yes
Email
Customer's email address
Varchar(128)
Yes2
Phone
Customer's phone number1
Varchar(16)
Yes2
Surname
Customer's last name or surname
Varchar(48)
No3
Birthdate
Customer's birthday in ISO 8601 YYYY-MM-DD format
Varchar(10)
No3
1 Phone number in ITU E.164 CountryCode-Subscriber format, e.g. 421-123456789 2 At least one of the parameters is required (email or phone) 3 Required for some risk checks and payment providers
Request/BrowserData
Browser parameter names are prefixed with Browser.
Name
Description
Format
Required
AcceptHeader
Exact content of the HTTP accept headers from the cardholder's browser
Varchar(2048)
Yes
Language
Value representing the browser language as defined in IETF BCP47
Varchar(8)
Yes
ScreenHeight
Total height of the cardholder's screen in pixels
Numeric(6)
Yes
ScreenWidth
Total width of the cardholder's screen in pixels
Numeric(6)
Yes
Timezone
Time-zone offset in minutes between UTC and the cardholder browser local time, note that the offset is positive if the local time zone is behind UTC and negative if it is ahead
Numeric(5)
Yes
UserAgent
Exact content of the HTTP user-agent header
Varchar(2048)
Yes
JavaEnabled
Boolean that represents the ability of the cardholder browser to execute Java
Bool
Yes
JavaScriptEnabled
Boolean that represents the ability of the cardholder browser to execute JavaScript
Bool
Yes
ScreenColorDepth
Value representing the bit depth of the colour palette for displaying images, in bits per pixel
Varchar(2)
Yes
ChallengeWindow
Dimensions of the challenge window that has been displayed to the cardholder
TD1 Top-level parameters (Billing.*, Customer.*, Browser.*, ...) are not required, but all structure's sub-parameters are required if any of the sub-parameters are present.
Request/ChallengeWindow
ChallengeWindow is an enumeration type that represents size of the authentication iframe which will render the ACS authentication front-end to the shopper for interaction.
Value
Description
1
250 x 400
2
390 x 400
3
500 x 600
4
600 x 400
5
Full screen
Request/3DsData
3DS parameter names are prefixed with threeDSecure.
Name
Description
Format
Required
EnrollmentStatus
The enrollment status for the 3D secure request
Varchar (1)
Yes
Eci
The ECI for the 3D secure request
Numeric (2)
Yes
AuthenticationStatus
The authentication status for the 3D secure request
Varchar (1)
Yes
VerificationId
The 3D secure CAVV or AAV. Must be Base64 encoded
Varchar (28)
Yes
Xid
The 3D secure xid. Must be Base64 encoded
Varchar (64)
No
Version
Version of the 3D Secure that was used for authentication
Varchar (5)
No
MerchantName
Merchant name as defined by the Scheme Directory Server
Provides information on why the Transaction Status field has the specified value
Numeric (2)
No
AcsTransactionId
This field contains a universally unique transaction identifier assigned by the ACS to identify a single transaction
String
No
Request/3DsData/ChallengeIndicator
ChallengeIndicator indicates whether a challenge is requested for this transaction. For example: a 3DS Requestor may have concerns about the transaction, and request a challenge. Allows 3DS Requestor to request a challenge such as to follow local/regional mandates or other variables.
Value
Description
01
No preference
02
No challenge requested
03
Challenge requested: 3D Secure Requestor Preference
04
Challenge requested: Mandate
Request/3DsData/AuthenticationType
AuthType. The type of authentication that was requested by the ACS.
Value
Description
01
Static
02
Dynamic
03
OOB
04
Decoupled
Request/3DsData/ExemptionFlag
ExemptionFlag. Flags the transaction as exemption during authorization. Can be used for 3D Secure version 2.2 or higher.
Value
Description
01
Low value exemption
02
TRA exemption
03
Trusted beneficiary exemption
04
Corporate card payment exemption
Request/Instructions
Instruction parameters are prefixed with Instructions.
1 Field present for successful operations 2 Field present for operations with asynchronous process 3 Field present for operations that were sent to payment provider
During transaction processing an asynchronous process may be required to complete the transaction.
Most pending transactions with an asynchronous process contain a redirectUrl field together with a set of parameters in redirectParams parameter block.
Optionally, some transactions might contain also a set of parameters in preconditions parameter block.
In case of asynchronous process proceed as follows:
Open a hidden iframe and post data to the preconditions.url URL.
This applies only if preconditions parameters block is present in the response.
This should not redirect the shopper. Data is posted on the background.
Redirect the shopper to redirectUrl with redirectParams posted as a form.
If preconditions block is present in the response, the redirect step should take place after onLoad event from step 1. completes.
If the onLoad event is not triggered within 10 seconds of submitting - continue with the redirect step.
After the asynchronous process is completed, the customer is redirected to RedirectUrl
that the merchant used as a request parameter.
Open a hidden iframe and post data to the Preconditions URL
<form name="methodForm" action="preconditions.url" method="POST" target="preconditions_frame">
<!-- iterate through all 'preconditions.parameters': (key,value) => name = key, value = value -->
<input type="hidden" name="threeDSMethodData" value="methodData">
</form>
<!-- hidden iframe for preconditions -->
<iframe name="preconditions_frame" style="display:none;"></iframe>
<script>
window.onload=methodForm;
function submitForm() { methodForm.submit(); }
</script>
Redirect the shopper to the Redirect URL using a form to submit data
<form name="redirectForm" action="redirectUrl" method="POST">
<!-- iterate through all 'redirectParams': (key,value) => name = key, value = value -->
<input type="hidden" name="MD" value="8ac7a4a27a2c1670017a2d7f1b09WYXZ">
<input type="hidden" name="TermUrl" value="https://test.trustpay.eu/..">
<input type="hidden" name="PaReq" value="IT0ubu...">
<input type="hidden" name="connector" value="THREEDSECURE">
</form>
<script>
// if preconditions are present, wait for them to load (via onload event, wait at most 10 seconds)
window.onload=redirectForm;
function submitForm() { redirectForm.submit(); }
</script>
Wallet Payments EmbeddedFields
Embedded Fields for Wallet Payments
Embedded fields are convenience components that the merchant can easily include in his solution.
For this embedded field to be available, you need to register your project. Please refer to the relevant documentation or reach out to our support team.
Every Merchant that wants to integrate MobilePay payments with our platform needs to provide:
Merchant’s Name (official company name), this name is used to identify payments for the MobilePay app
VAT number
Country - MobilePay supports all countries in the EU/EEA and DKK, EUR, SEK, NOK currencies
Logo - preferable size 250x250 pixels, PNG or JPG format
Please contact our support to assist you with the onboarding process.
Prerequisites
Include TrustPay's v1.js file on the merchant's webpage.
Setup
Before you set up the components, you should issue a CreateIntent request if you have not done so yet.
To minimize the amount of background calls, it is preferable that you use parts of the response during the setup of the components.
After receiving the response, you need to initialize an instance of the TrustPayApi class.
Initialize TP.js object:
var trustpayApi = new TrustPayApi(createIntentResponse.secrets, {});
All the embedded fields follow the same scheme:
Add a placeholder to your page
Create an instance of the field
Check if the customer's environment supports the relevant payment method and mount the component
Handle the payment result
Setup Apple Pay
1. Add a placeholder
Example of an Apple Pay placeholder:
<div id="apple-pay-element"></div>
2. Create an instance of the component
Create an instance of the component:
interface IPaymentResult {
status:number;
description:string;
}
apButton = trustpayApi.createComponent("applePay", {
initiativeContext: "my.lovely.site.co.uk",
style: {
"--apple-pay-button-width": "140px;",
"--apple-pay-button-height": "30px;"
"--apple-pay-button-border-radius": "5px;",
"--apple-pay-button-padding": "5px 0px;",
},
buttonStyle: "black",
buttonType: "buy",
buttonType: "en-US",
onPaymentProcessed: (result: IPaymentResult) => { console.log(result); }
// define your callback function
// - this will be called after the transaction is resolved (either synchronously or asynchronously)
paymentRequest: createIntentResponse.appleInitResultData,
// if this is not supplied the component will fetch it from the server
// - supplying the parameter is however encouraged since it saves a backend call
});
Parameter
Required
Value
initiativeContext
yes
For this required parameter provide the fully qualified domain name of your website from which the payment is initiated. In the case a payment is initiated from a subdomain it is not enough to provide only the top-level domain.
If you initiate payments from multiple subdomains then each one has to be registered and verified under your account in the Merchant Portal.
For possible values, please refer to Apple's documentation
If you omit this parameter, the component will try to infer the value based on the placeholder component
The supplied handler function will trigger once the payment process is completed
paymentRequest
recommended
It is strongly recommended you supply this parameter with the value of createIntentResponse.appleInitResultData to prevent unnecessary initialization calls
apButton.isSupported()
.then(result => {
if (result) {
console.log("[Integration] Apple Pay Supported");
// mount the embedded field to its placeholder
apButton.mount("#apple-pay-element");
}
else {
console.log("[Integration] Apple Pay NOT supported");
}
})
.catch(error => {
console.log("[Integration] Apple Pay NOT supported", error);
})
4. Handle the result
If you attached a handler function via setting the onPaymentProcessed parameter, it will receive an IPaymentResult object with a specific status code.
Setup Google Pay
1. Add a placeholder
Example of a Google Pay placeholder:
<div id="google-pay-element"></div>
2. Create an instance of the component
Create an instance of the component:
interface IPaymentResult {
status:number;
description:string;
}
var gpButton = trustpayApi.createComponent("googlePay", {
buttonColor: "black",
buttonType: "plain",
buttonLocale: "en",
buttonSizeMode: "static",
onPaymentProcessed: (result: IPaymentResult) => { console.log(result); }
// define your callback function -
// this will be called after the transaction is resolved (either synchronously or asynchronously)
paymentRequest: createIntentResponse.googleInitResultData,
// if this is not supplied the component will fetch it from the server
// - supplying the parameter is however encouraged since it saves a backend call
placement: "trustpay",
});
Parameter
Required
Value
buttonColor
no
For possible values, please refer to Google's documentation
If you omit this parameter, the component will try to infer the value based on the placeholder component
The supplied handler function will trigger once the payment process is completed
paymentRequest
recommended
It is strongly recommended you supply this parameter with the value of createIntentResponse.googleInitResultData to prevent unnecessary backend calls
placement
no
The default value is trustpay, which is suitable for most use cases. If you would like to use your own Google Pay merchant ID with it's registered domain, the value should be set to merchant. Please contact our support team to make sure if this option is available for you
gpButton.isSupported()
.then(result => {
if (result) {
console.log("[Integration] Google Pay Supported");
// mount the embedded field to its placeholder
gpButton.mount("#google-pay-element");
}
else {
console.log("[Integration] Google Pay NOT supported");
})
.catch(error => {
},
console.log("[Integration] Google Pay NOT supported", error);
})
4. Handle the result
If you attached a handler function via setting the onPaymentProcessed parameter, it will receive an IPaymentResult object with a specific status code.
Setup MobilePay
1. Add a placeholder
Example of a MobilePay placeholder:
<div id="mobile-pay-element"></div>
2. Create an instance of the component
Create an instance of the component:
interface IPaymentResult {
status:number;
description:string;
}
var mpButton = trustpayApi.createComponent("mobilePay", {
buttonVerb: "pay",
buttonLanguage: "en-uk",
branded: true,
onPaymentProcessed: (result: IPaymentResult) => { console.log(result); },
// define your callback function -
// this will be called after the transaction is resolved (either synchronously or asynchronously)
});
The supplied handler function will trigger once the payment process is completed
3. Check availability and mount
Mount the component:
mpButton.isSupported()
.then(result => {
if (result) {
console.log("[Integration] MobilePay Supported");
// mount the embedded field to its placeholder
mpButton.mount("#mobile-pay-element");
}
else {
console.log("[Integration] MobilePay NOT supported");
})
.catch(error => {
},
console.log("[Integration] MobilePay NOT supported", error);
})
4. Handle the result
If you attached a handler function via setting the onPaymentProcessed parameter, it will receive an IPaymentResult object with a specific status code.
The possible codes are listed below:
Value
Explanation
0
Success
1
Pending
-1
Expired
-2
Error
-3
Server call failed
-4
Aborted by user
-255
Failure
The result code will be accompanied by a user readable description.
Customer Metadata
Components for Apple Pay and Google Pay support customer metadata extraction.
Setup
To retrieve metadata, set up your component as described in the relevant documentation
and add the requestCustomerMetadata preference to the preferences array.
Add the requestCustomerMetadata preference to the preferences array:
You can access the data by via the component's customerMetadata getter.
Data, if successfully gathered, will be populated after the payment has been processed.
Limitations
Customer metadata are extracted after the customer authorizes the transaction
(i.e. after customer confirms the payment via the native Apple or Google payment sheet).
Customer metadata are undefined until gathered successfully.
Modal Window Events
The TrustPayApi class uses modals to display and handle some workflows
(e.g. 3DS challenge redirects) necessary to complete a payment.
You can subscribe to following events to provide a better experience for your customers: modalopen, modalload, modalclose.
Modal Opened
This event is raised when the modal window starts to display content (e.g. 3DS challenge redirect).
The content of the modal window is loaded in an iframe placed in a div element
which is appended to document.body with the following properties:
Property
Value
div.style.width
100%
div.style.height
100%
div.style.position
absolute
div.style.top
0
div.style.left
0
div.style.backgroundColor
white
div.style.zIndex
999
Modal Loaded
This event is raised when content is loaded within the modal window (i.e. onLoad of the modal's iframe).
Please note this event may be raised multiple times based on the flow being executed
- e.g. 3DS authentication may require multiple URL redirects within the modal's iframe element.
Modal Closed
This event is raised when the current flow handled by the modal window finishes and
the content is stopped being displayed.
Subscribe to the events by calling addEventListener
Component Event Handling
You can subscribe to following events triggered by instances of
ApplePayComponent, GooglePayComponent and MobilePayComponent.
click - raised when the component's button is clicked
Example of registering the click event for the GooglePayComponent:
let gpButton = trustpayApi.createComponent("googlePay", {
...
});
gpButton.on("click", (event) => {
console.log("[Integration] Google Pay button CLICKED!", event);
})//hook up click event
Component Removal
Example of component removal:
// create your instance of TrustPayApi
trustpayApi = new TrustPayApi(...);
...
// add your GooglePay component
let gpButton = trustpayApi.createComponent("googlePay", {
...
});
...
// remove your GooglePay component
trustpayApi.removeComponent(gpButton);
If necessary, you can remove components you added to your TrustPayApi
instance by calling removeComponent.
AircashPay
Payment process
Merchant's site makes a Payment request with purchase order reference to the TrustPay's API.
The response from TrustPay's API will contain a URL for the payment page.
Merchant's site redirects customer to the provided URL which will generate AircashPay's QR code that the customer can scan and use with AircashPay application.
After the customer finishes the payment in AircashPay app, the customer is then redirected to Merchant's URL provided in the original Payment request.
Payment
API endpoints:
Live - https://aapi.trustpay.eu/api/Payments/Payment
Initiates new AircashPay payment request.
Request
Payment example:
using System.Net;
using System.Text;
using System.Web.Script.Serialization;
public string Payment(string token)
{
string url = "https://aapi.trustpay.eu/api/Payments/Payment";
using (var client = new WebClient())
{
client.Headers = new WebHeaderCollection
{
"Authorization: Bearer " + token,
"Content-Type: application/json"
};
var request = new
{
PaymentMethod = "AircashPay",
MerchantIdentification = new
{
ProjectId = "1234567"
},
PaymentInformation = new
{
Amount = new
{
Amount = 1.50,
Currency = "EUR"
},
Localization = "en",
References = new
{
MerchantReference = "Order 12345"
}
},
CallbackUrls = new
{
Success = "https://somedomain.eu/success",
Cancel = "https://somedomain.eu/cancel",
Error = "https://somedomain.eu/error",
Notification = "https://somedomain.eu/notification_handler"
}
};
JavaScriptSerializer serializer = new JavaScriptSerializer();
var requestData = Encoding.UTF8.GetBytes(serializer.Serialize(request));
var responseData = client.UploadData(url, requestData);
var response = serializer.Deserialize<dynamic>(Encoding.UTF8.GetString(responseData));
return response["GatewayUrl"];
}
}
<scripttype="text/javascript"src="https://mapi.trustpay.eu/mapi5/Scripts/TrustPay/popup.js"></script><iframeid="TrustPayFrame"src="https://aapi.trustpay.eu/Payments/Gateway?paymentRequestId=123123&sig=58B2FA9C45AEE707FFB6A4A0749D2"></iframe><ahref="#"class="show-popup">Pay via TrustPay</a>
This code is using external library Jackson to parse text from and to json format
import org.codehaus.jackson.map.ObjectMapper;
import javax.net.ssl.HttpsURLConnection;
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.URL;
import java.util.Map;
public String CapturePayment(String token){
try {
URL obj = new URL("https://aapi.trustpay.eu/api/Payments/Payment");
HttpsURLConnection con = (HttpsURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Authorization", "Bearer " + token);
con.setRequestProperty("Content-type", "application/json");
Object request = new Object() {
public String PaymentMethod = "Blik";
public Object MerchantIdentification = new Object(){
public long ProjectId = 4107123456;
};
public Object PaymentInformation = new Object(){
public Object Amount = new Object(){
public double Amount = 12.50;
public String Currency = "PLN";
};
public Object Debtor = new Object(){
public String Name = "John Doe";
public String Email = "email@example.com";
};
public String Localization = "en";
public Object References = new Object(){
public String MerchantReference = "merch ref. no. #555";
};
};
public Object CallbackUrls = new Object(){
public String Success = "https://somedomain.eu/success";
public String Cancel = "https://somedomain.eu/cancel";
public String Error = "https://somedomain.eu/error";
public String Notification = "https://somedomain.eu/notification_handler";
};
};
ObjectMapper JsonParser = new ObjectMapper();
String jsonrequest = JsonParser.writeValueAsString(request);
con.setDoOutput(true);
try (DataOutputStream wr = new DataOutputStream(con.getOutputStream())) {
wr.writeBytes(jsonrequest);
wr.flush();
}
String response = "";
try (BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()))) {
String inputLine;
while ((inputLine = in.readLine()) != null) {
response += inputLine;
}
}
Map<String,String> deserialized = JsonParser.readValue(response, Map.class);
return String.valueOf(deserialized.get("GatewayUrl"));
}
catch (Exception ex){
throw new RuntimeException(ex.getMessage());
}
}
This code is using external library Jackson to parse text from and to json format
import org.codehaus.jackson.map.ObjectMapper;
import javax.net.ssl.HttpsURLConnection;
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.URL;
import java.util.Map;
public String CapturePayment(String token){
try {
URL obj = new URL("https://aapi.trustpay.eu/api/Payments/Payment");
HttpsURLConnection con = (HttpsURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Authorization", "Bearer " + token);
con.setRequestProperty("Content-type", "application/json");
Object request = new Object() {
public String PaymentMethod = "CashtoCode";
public Object MerchantIdentification = new Object(){
public long ProjectId = 4107123456;
};
public Object PaymentInformation = new Object(){
public Object Amount = new Object(){
public double Amount = 1.50;
public String Currency = "EUR";
};
public String Localization = "SK";
public String Country = "SK"
public Object References = new Object(){
public String MerchantReference = "merch ref. no. #555";
};
public Object Debtor = new Object(){
public Object Address = new Object(){
public String CountryCode = "DE";
},
public Object Identification = new Object(){
public String Id = "123456";
};
};
};
public Object CallbackUrls = new Object(){
public String Success = "https://somedomain.eu/success";
public String Error = "https://somedomain.eu/error";
public String Notification = "https://somedomain.eu/notification_handler";
};
};
ObjectMapper JsonParser = new ObjectMapper();
String jsonrequest = JsonParser.writeValueAsString(request);
con.setDoOutput(true);
try (DataOutputStream wr = new DataOutputStream(con.getOutputStream())) {
wr.writeBytes(jsonrequest);
wr.flush();
}
String response = "";
try (BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()))) {
String inputLine;
while ((inputLine = in.readLine()) != null) {
response += inputLine;
}
}
Map<String,String> deserialized = JsonParser.readValue(response, Map.class);
return String.valueOf(deserialized.get("GatewayUrl"));
}
catch (Exception ex){
throw new RuntimeException(ex.getMessage());
}
}
This code is using external library Jackson to parse text from and to json format
import org.codehaus.jackson.map.ObjectMapper;
import javax.net.ssl.HttpsURLConnection;
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.URL;
import java.util.Map;
public String CapturePayment(String token){
try {
URL obj = new URL("https://aapi.trustpay.eu/api/Payments/Payment");
HttpsURLConnection con = (HttpsURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Authorization", "Bearer " + token);
con.setRequestProperty("Content-type", "application/json");
Object request = new Object() {
public String PaymentMethod = "CashToCodeEVoucher";
public Object MerchantIdentification = new Object(){
public long ProjectId = 4107123456;
};
public Object PaymentInformation = new Object(){
public Object Amount = new Object(){
public double Amount = 1.50;
public String Currency = "USD";
};
public String Localization = "SK";
public String Country = "SK"
public Object References = new Object(){
public String MerchantReference = "merch ref. no. #555";
};
public Object Debtor = new Object(){
public Object Address = new Object(){
public String CountryCode = "DE";
},
public Object Identification = new Object(){
public String Id = "123456";
};
};
};
public Object CallbackUrls = new Object(){
public String Success = "https://somedomain.eu/success";
public String Error = "https://somedomain.eu/error";
public String Notification = "https://somedomain.eu/notification_handler";
};
};
ObjectMapper JsonParser = new ObjectMapper();
String jsonrequest = JsonParser.writeValueAsString(request);
con.setDoOutput(true);
try (DataOutputStream wr = new DataOutputStream(con.getOutputStream())) {
wr.writeBytes(jsonrequest);
wr.flush();
}
String response = "";
try (BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()))) {
String inputLine;
while ((inputLine = in.readLine()) != null) {
response += inputLine;
}
}
Map<String,String> deserialized = JsonParser.readValue(response, Map.class);
return String.valueOf(deserialized.get("GatewayUrl"));
}
catch (Exception ex){
throw new RuntimeException(ex.getMessage());
}
}
At first the GetBankList API request is made. After receiving the bank list, the customer can choose a bank. After that the merchant sends a SetupPayment request. After receiving the SetupPayment result, the merchant/customer chooses between an online or offline payment. For an online payment an additional ExecutePayment redirect has to be made. After redirection, the standart payment process flow follows.
Get bank list
API endpoints:
Live - https://aapi.trustpay.eu/api/gateway/gateways
The GetBankList request is used to aquire a list of currently supported banks. If the country and/or merchant account ID parameter is specified, only banks available for that country/merchant account are returned.
This code is using external library Jackson to parse text from and to json format
import org.codehaus.jackson.map.ObjectMapper;
import javax.net.ssl.HttpsURLConnection;
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.URL;
import java.util.Map;
public String CapturePayment(String token){
try {
URL obj = new URL("https://aapi.trustpay.eu/api/Payments/Payment");
HttpsURLConnection con = (HttpsURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Authorization", "Bearer " + token);
con.setRequestProperty("Content-type", "application/json");
Object request = new Object() {
public String PaymentMethod = "SepaCreditTransfer";
public Object MerchantIdentification = new Object(){
public long ProjectId = 4107123456;
};
public Object PaymentInformation = new Object(){
public Object Amount = new Object(){
public double Amount = 1.50;
public String Currency = "EUR";
};
public String Localization = "en";
public Object References = new Object(){
public String MerchantReference = "merch ref. no. #555";
};
public Object DebtorAgent = new Object(){
public long ProprietaryId = 1000001;
};
};
public Object CallbackUrls = new Object(){
public String Notification = "https://somedomain.eu/notification_handler";
};
};
ObjectMapper JsonParser = new ObjectMapper();
String jsonrequest = JsonParser.writeValueAsString(request);
con.setDoOutput(true);
try (DataOutputStream wr = new DataOutputStream(con.getOutputStream())) {
wr.writeBytes(jsonrequest);
wr.flush();
}
String response = "";
try (BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()))) {
String inputLine;
while ((inputLine = in.readLine()) != null) {
response += inputLine;
}
}
Map<String,String> deserialized = JsonParser.readValue(response, Map.class);
return String.valueOf(deserialized.get("GatewayUrl"));
}
catch (Exception ex){
throw new RuntimeException(ex.getMessage());
}
}
Description of result that occurred during the service call.
Varchar(235)
CorrelationId
Correlation Id is only shown when an error occurs. It's a GUID of the error log in our internal system.
Varchar(36)
Payment (recurring)
API endpoints:
Live - https://aapi.trustpay.eu/api/Payments/Payment
Initiates new EPS recurring payment request using direct debit.
The debtor's name and IBAN from the original EPS payment request will be used to initiate the direct debit.
Request
Payment example:
using System.Net;
using System.Text;
using System.Web.Script.Serialization;
public string Payment(string token)
{
string url = "https://aapi.trustpay.eu/api/Payments/Payment";
using (var client = new WebClient())
{
client.Headers = new WebHeaderCollection
{
"Authorization: Bearer " + token,
"Content-Type: application/json"
};
var request = new
{
PaymentMethod = "SepaDirectDebit",
MerchantIdentification = new
{
ProjectId = "1234567"
},
PaymentInformation = new
{
DueDate = "2022-05-25",
Amount = new
{
Amount = 1.50,
Currency = "EUR"
},
Localization = "en",
References = new
{
MerchantReference = "Order 12345",
OriginalPaymentRequestId = 73807
}
Debtor = new
{
Email = "example@example.org",
IpAddress = "1.2.3.4",
},
},
CallbackUrls = new
{
Success = "https://somedomain.eu/success",
Cancel = "https://somedomain.eu/cancel",
Error = "https://somedomain.eu/error",
Notification = "https://somedomain.eu/notification_handler"
}
};
JavaScriptSerializer serializer = new JavaScriptSerializer();
var requestData = Encoding.UTF8.GetBytes(serializer.Serialize(request));
var responseData = client.UploadData(url, requestData);
var response = serializer.Deserialize<dynamic>(Encoding.UTF8.GetString(responseData));
return response["GatewayUrl"];
}
}
This code is using external library Jackson to parse text from and to json format
import org.codehaus.jackson.map.ObjectMapper;
import javax.net.ssl.HttpsURLConnection;
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.URL;
import java.util.Map;
public String CapturePayment(String token){
try {
URL obj = new URL("https://aapi.trustpay.eu/api/Payments/Payment");
HttpsURLConnection con = (HttpsURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Authorization", "Bearer " + token);
con.setRequestProperty("Content-type", "application/json");
Object request = new Object() {
public String PaymentMethod = "SepaDirectDebit";
public String DueDate = "2022-05-25";
public Object MerchantIdentification = new Object(){
public long ProjectId = 4107123456;
};
public Object PaymentInformation = new Object(){
public Object Amount = new Object(){
public double Amount = 1.50;
public String Currency = "EUR";
};
public String Localization = "en";
public Object References = new Object(){
public String MerchantReference = "merch ref. no. #555";
public long OriginalPaymentRequestId = 73807;
};
public Object Debtor = new Object(){
public String Email = "example@example.org";
public String IpAddress = "1.2.3.4";
};
};
public Object CallbackUrls = new Object(){
public String Success = "https://somedomain.eu/success";
public String Cancel = "https://somedomain.eu/cancel";
public String Error = "https://somedomain.eu/error";
public String Notification = "https://somedomain.eu/notification_handler";
};
};
ObjectMapper JsonParser = new ObjectMapper();
String jsonrequest = JsonParser.writeValueAsString(request);
con.setDoOutput(true);
try (DataOutputStream wr = new DataOutputStream(con.getOutputStream())) {
wr.writeBytes(jsonrequest);
wr.flush();
}
String response = "";
try (BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()))) {
String inputLine;
while ((inputLine = in.readLine()) != null) {
response += inputLine;
}
}
Map<String,String> deserialized = JsonParser.readValue(response, Map.class);
return String.valueOf(deserialized.get("GatewayUrl"));
}
catch (Exception ex){
throw new RuntimeException(ex.getMessage());
}
}
Description of result that occurred during the service call.
Varchar(235)
CorrelationId
Correlation Id is only shown when an error occurs. It's a GUID of the error log in our internal system.
Varchar(36)
Payment (recurring)
API endpoints:
Live - https://aapi.trustpay.eu/api/Payments/Payment
Initiates new Giropay recurring payment request using direct debit.
The debtor's name and IBAN from the original Giropay payment request will be used to initiate the direct debit.
Request
Payment example:
using System.Net;
using System.Text;
using System.Web.Script.Serialization;
public string Payment(string token)
{
string url = "https://aapi.trustpay.eu/api/Payments/Payment";
using (var client = new WebClient())
{
client.Headers = new WebHeaderCollection
{
"Authorization: Bearer " + token,
"Content-Type: application/json"
};
var request = new
{
PaymentMethod = "SepaDirectDebit",
MerchantIdentification = new
{
ProjectId = "1234567"
},
PaymentInformation = new
{
DueDate = "2022-05-25",
Amount = new
{
Amount = 1.50,
Currency = "EUR"
},
Localization = "en",
References = new
{
MerchantReference = "Order 12345",
OriginalPaymentRequestId = 73807
}
Debtor = new
{
Email = "example@example.org",
IpAddress = "1.2.3.4",
},
},
CallbackUrls = new
{
Success = "https://somedomain.eu/success",
Cancel = "https://somedomain.eu/cancel",
Error = "https://somedomain.eu/error",
Notification = "https://somedomain.eu/notification_handler"
}
};
JavaScriptSerializer serializer = new JavaScriptSerializer();
var requestData = Encoding.UTF8.GetBytes(serializer.Serialize(request));
var responseData = client.UploadData(url, requestData);
var response = serializer.Deserialize<dynamic>(Encoding.UTF8.GetString(responseData));
return response["GatewayUrl"];
}
}
This code is using external library Jackson to parse text from and to json format
import org.codehaus.jackson.map.ObjectMapper;
import javax.net.ssl.HttpsURLConnection;
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.URL;
import java.util.Map;
public String CapturePayment(String token){
try {
URL obj = new URL("https://aapi.trustpay.eu/api/Payments/Payment");
HttpsURLConnection con = (HttpsURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Authorization", "Bearer " + token);
con.setRequestProperty("Content-type", "application/json");
Object request = new Object() {
public String PaymentMethod = "SepaDirectDebit";
public String DueDate = "2022-05-25";
public Object MerchantIdentification = new Object(){
public long ProjectId = 4107123456;
};
public Object PaymentInformation = new Object(){
public Object Amount = new Object(){
public double Amount = 1.50;
public String Currency = "EUR";
};
public String Localization = "en";
public Object References = new Object(){
public String MerchantReference = "merch ref. no. #555";
public long OriginalPaymentRequestId = 73807;
};
public Object Debtor = new Object(){
public String Email = "example@example.org";
public String IpAddress = "1.2.3.4";
};
};
public Object CallbackUrls = new Object(){
public String Success = "https://somedomain.eu/success";
public String Cancel = "https://somedomain.eu/cancel";
public String Error = "https://somedomain.eu/error";
public String Notification = "https://somedomain.eu/notification_handler";
};
};
ObjectMapper JsonParser = new ObjectMapper();
String jsonrequest = JsonParser.writeValueAsString(request);
con.setDoOutput(true);
try (DataOutputStream wr = new DataOutputStream(con.getOutputStream())) {
wr.writeBytes(jsonrequest);
wr.flush();
}
String response = "";
try (BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()))) {
String inputLine;
while ((inputLine = in.readLine()) != null) {
response += inputLine;
}
}
Map<String,String> deserialized = JsonParser.readValue(response, Map.class);
return String.valueOf(deserialized.get("GatewayUrl"));
}
catch (Exception ex){
throw new RuntimeException(ex.getMessage());
}
}
<scripttype="text/javascript"src="https://mapi.trustpay.eu/mapi5/Scripts/TrustPay/popup.js"></script><iframeid="TrustPayFrame"src="https://aapi.trustpay.eu/Payments/Gateway?paymentRequestId=123123&sig=58B2FA9C45AEE707FFB6A4A0749D2"></iframe><ahref="#"class="show-popup">Pay via TrustPay</a>
<scripttype="text/javascript"src="https://mapi.trustpay.eu/mapi5/Scripts/TrustPay/popup.js"></script><iframeid="TrustPayFrame"src="https://aapi.trustpay.eu/Payments/Gateway?paymentRequestId=123123&sig=58B2FA9C45AEE707FFB6A4A0749D2"></iframe><ahref="#"class="show-popup">Pay via TrustPay</a>
Description of result that occurred during the service call.
Varchar(235)
CorrelationId
Correlation Id is only shown when an error occurs. It's a GUID of the error log in our internal system.
Varchar(36)
Payment (recurring)
API endpoints:
Live - https://aapi.trustpay.eu/api/Payments/Payment
Initiates new iDEAL recurring payment request using direct debit.
The debtor's name and IBAN from the original iDEAL payment request will be used to initiate the direct debit.
Request
Payment example:
using System.Net;
using System.Text;
using System.Web.Script.Serialization;
public string Payment(string token)
{
string url = "https://aapi.trustpay.eu/api/Payments/Payment";
using (var client = new WebClient())
{
client.Headers = new WebHeaderCollection
{
"Authorization: Bearer " + token,
"Content-Type: application/json"
};
var request = new
{
PaymentMethod = "SepaDirectDebit",
MerchantIdentification = new
{
ProjectId = "1234567"
},
PaymentInformation = new
{
DueDate = "2022-05-25",
Amount = new
{
Amount = 1.50,
Currency = "EUR"
},
Localization = "en",
References = new
{
MerchantReference = "Order 12345",
OriginalPaymentRequestId = 73807
}
Debtor = new
{
Email = "example@example.org",
IpAddress = "1.2.3.4",
},
},
CallbackUrls = new
{
Success = "https://somedomain.eu/success",
Cancel = "https://somedomain.eu/cancel",
Error = "https://somedomain.eu/error",
Notification = "https://somedomain.eu/notification_handler"
}
};
JavaScriptSerializer serializer = new JavaScriptSerializer();
var requestData = Encoding.UTF8.GetBytes(serializer.Serialize(request));
var responseData = client.UploadData(url, requestData);
var response = serializer.Deserialize<dynamic>(Encoding.UTF8.GetString(responseData));
return response["GatewayUrl"];
}
}
This code is using external library Jackson to parse text from and to json format
import org.codehaus.jackson.map.ObjectMapper;
import javax.net.ssl.HttpsURLConnection;
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.URL;
import java.util.Map;
public String CapturePayment(String token){
try {
URL obj = new URL("https://aapi.trustpay.eu/api/Payments/Payment");
HttpsURLConnection con = (HttpsURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Authorization", "Bearer " + token);
con.setRequestProperty("Content-type", "application/json");
Object request = new Object() {
public String PaymentMethod = "SepaDirectDebit";
public String DueDate = "2022-05-25";
public Object MerchantIdentification = new Object(){
public long ProjectId = 4107123456;
};
public Object PaymentInformation = new Object(){
public Object Amount = new Object(){
public double Amount = 1.50;
public String Currency = "EUR";
};
public String Localization = "en";
public Object References = new Object(){
public String MerchantReference = "merch ref. no. #555";
public long OriginalPaymentRequestId = 73807;
};
public Object Debtor = new Object(){
public String Email = "example@example.org";
public String IpAddress = "1.2.3.4";
};
};
public Object CallbackUrls = new Object(){
public String Success = "https://somedomain.eu/success";
public String Cancel = "https://somedomain.eu/cancel";
public String Error = "https://somedomain.eu/error";
public String Notification = "https://somedomain.eu/notification_handler";
};
};
ObjectMapper JsonParser = new ObjectMapper();
String jsonrequest = JsonParser.writeValueAsString(request);
con.setDoOutput(true);
try (DataOutputStream wr = new DataOutputStream(con.getOutputStream())) {
wr.writeBytes(jsonrequest);
wr.flush();
}
String response = "";
try (BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()))) {
String inputLine;
while ((inputLine = in.readLine()) != null) {
response += inputLine;
}
}
Map<String,String> deserialized = JsonParser.readValue(response, Map.class);
return String.valueOf(deserialized.get("GatewayUrl"));
}
catch (Exception ex){
throw new RuntimeException(ex.getMessage());
}
}
API endpoints:
Live - https://aapi.trustpay.eu/api/Payments/Payment
Merchant's implementation has to include link to Merchant API JavaScript on it's page and load the TrustPay payment gateway inside an IFrame. Url to payment gateway is filled in response on initiate request. (Initiate request is json object, sent on API endpoint, as you can see in Payment example) The included JavaScript will style the IFrame so that it is hidden. It also contains the code necessary to show the payment gateway from the hidden IFrame as a popup overlaid over the merchant's e-shop. To allow users to show the payment gateway popup, the merchant needs to include some link/button/etc. with CSS class "show-popup" somewhere on the page. Onclick event handler that shows the popup will be automatically added to this element. Please see the example to the right.
Initiates new bank transfer payment request.
Request
Payment example:
using System.Net;
using System.Text;
using System.Web.Script.Serialization;
public string Payment(string token)
{
string url = "https://aapi.trustpay.eu/api/Payments/Payment";
using (var client = new WebClient())
{
client.Headers = new WebHeaderCollection
{
"Authorization: Bearer " + token,
"Content-Type: application/json"
};
var request = new
{
PaymentMethod = "Wire",
MerchantIdentification = new
{
ProjectId = "1234567"
},
PaymentInformation = new
{
Amount = new
{
Amount = 1.50,
Currency = "EUR",
},
Localization = "en",
References = new
{
MerchantReference = "Order 12345"
}
},
CallbackUrls = new
{
Notification = "https://somedomain.eu/notification_handler"
}
};
JavaScriptSerializer serializer = new JavaScriptSerializer();
var requestData = Encoding.UTF8.GetBytes(serializer.Serialize(request));
var responseData = client.UploadData(url, requestData);
var response = serializer.Deserialize<dynamic>(Encoding.UTF8.GetString(responseData));
return response["GatewayUrl"];
}
}
<scripttype="text/javascript"src="https://mapi.trustpay.eu/mapi5/Scripts/TrustPay/popup.js"></script><iframeid="TrustPayFrame"src="https://aapi.trustpay.eu/Payments/Gateway?paymentRequestId=123123&sig=58B2FA9C45AEE707FFB6A4A0749D2"></iframe><ahref="#"class="show-popup">Pay via TrustPay</a>
Merchant's site makes a Payment request with purchase order reference to the TrustPay's API.
The response from TrustPay's API will contain a URL for the payment page.
Merchant's site redirects customer to the provided URL in which a list of Finnish banks will be displayed.
The banks selection form can be displayed as a popup overlaid over the merchant's site using IFrame element.
The customer selects his preferred bank and presses the submit button.
Page will be redirect to the bank's secure environment.
Customer fills up data on the site and confirms the payment.
After the data is confirmed customer is redirected to Merchant's URL provided in the original Payment request.
Payment
API endpoints:
Live - https://aapi.trustpay.eu/api/Payments/Payment
Initiates new Instant Bank Transfers (FI) payment request.
Request
Payment example:
using System.Net;
using System.Text;
using System.Web.Script.Serialization;
public string Payment(string token)
{
string url = "https://aapi.trustpay.eu/api/Payments/Payment";
using (var client = new WebClient())
{
client.Headers = new WebHeaderCollection
{
"Authorization: Bearer " + token,
"Content-Type: application/json"
};
var request = new
{
PaymentMethod = "InstantBankTransferFI",
MerchantIdentification = new
{
ProjectId = "1234567"
},
PaymentInformation = new
{
Amount = new
{
Amount = 1.50,
Currency = "EUR"
},
Debtor = new
{
Email = "email@example.com"
},
Localization = "en",
References = new
{
MerchantReference = "Order 12345"
}
},
CallbackUrls = new
{
Success = "https://somedomain.eu/success",
Cancel = "https://somedomain.eu/cancel",
Error = "https://somedomain.eu/error",
Notification = "https://somedomain.eu/notification_handler"
}
};
JavaScriptSerializer serializer = new JavaScriptSerializer();
var requestData = Encoding.UTF8.GetBytes(serializer.Serialize(request));
var responseData = client.UploadData(url, requestData);
var response = serializer.Deserialize<dynamic>(Encoding.UTF8.GetString(responseData));
return response["GatewayUrl"];
}
}
<scripttype="text/javascript"src="https://mapi.trustpay.eu/mapi5/Scripts/TrustPay/popup.js"></script><iframeid="TrustPayFrame"src="https://aapi.trustpay.eu/Payments/Gateway?paymentRequestId=123123&sig=58B2FA9C45AEE707FFB6A4A0749D2"></iframe><ahref="#"class="show-popup">Pay via TrustPay</a>
Data signature calculated from concatenated values of all values (in ASCII sorted order) in the notification. Slash character ('/') is used as separator. Not empty values are sorted in ascending order and then concatenated using the separator.
This code is using external library Jackson to parse text from and to json format
import org.codehaus.jackson.map.ObjectMapper;
import javax.net.ssl.HttpsURLConnection;
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.URL;
import java.util.Map;
public String CapturePayment(String token){
try {
URL obj = new URL("https://aapi.trustpay.eu/api/Payments/Payment");
HttpsURLConnection con = (HttpsURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Authorization", "Bearer " + token);
con.setRequestProperty("Content-type", "application/json");
Object request = new Object() {
public String PaymentMethod = "InstantBankTransferPL";
public Object MerchantIdentification = new Object(){
public long ProjectId = 4107123456;
};
public Object PaymentInformation = new Object(){
public Object Amount = new Object(){
public double Amount = 12.50;
public String Currency = "PLN";
};
public Object Debtor = new Object(){
public String Name = "John Doe";
public String Email = "email@example.com";
};
public String Localization = "en";
public Object References = new Object(){
public String MerchantReference = "merch ref. no. #555";
};
};
public Object CallbackUrls = new Object(){
public String Success = "https://somedomain.eu/success";
public String Cancel = "https://somedomain.eu/cancel";
public String Error = "https://somedomain.eu/error";
public String Notification = "https://somedomain.eu/notification_handler";
};
};
ObjectMapper JsonParser = new ObjectMapper();
String jsonrequest = JsonParser.writeValueAsString(request);
con.setDoOutput(true);
try (DataOutputStream wr = new DataOutputStream(con.getOutputStream())) {
wr.writeBytes(jsonrequest);
wr.flush();
}
String response = "";
try (BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()))) {
String inputLine;
while ((inputLine = in.readLine()) != null) {
response += inputLine;
}
}
Map<String,String> deserialized = JsonParser.readValue(response, Map.class);
return String.valueOf(deserialized.get("GatewayUrl"));
}
catch (Exception ex){
throw new RuntimeException(ex.getMessage());
}
}
Merchant's site makes a Payment request with purchase order reference to the TrustPay's API.
The response from TrustPay's API will contain a URL for the payment page.
Merchant's site redirects customer to the provided URL which will generate request in MbWay application that the customer need to confirm in MbWay application.
After the customer finishes the payment in MbWay app, the customer is then redirected to Merchant's URL provided in the original Payment request.
Payment
API endpoints:
Live - https://aapi.trustpay.eu/api/Payments/Payment
Initiates new MbWay payment request.
Request
Payment example:
using System.Net;
using System.Text;
using System.Web.Script.Serialization;
public string Payment(string token)
{
string url = "https://aapi.trustpay.eu/api/Payments/Payment";
using (var client = new WebClient())
{
client.Headers = new WebHeaderCollection
{
"Authorization: Bearer " + token,
"Content-Type: application/json"
};
var request = new
{
PaymentMethod = "MbWayId",
MerchantIdentification = new
{
ProjectId = "1234567"
},
PaymentInformation = new
{
Amount = new
{
Amount = 1.50,
Currency = "EUR"
},
Debtor = new
{
Phone = "+421 XXXXXXXXX"
},
Localization = "en",
References = new
{
MerchantReference = "Order 12345"
}
},
CallbackUrls = new
{
Success = "https://somedomain.eu/success",
Cancel = "https://somedomain.eu/cancel",
Error = "https://somedomain.eu/error",
Notification = "https://somedomain.eu/notification_handler"
}
};
JavaScriptSerializer serializer = new JavaScriptSerializer();
var requestData = Encoding.UTF8.GetBytes(serializer.Serialize(request));
var responseData = client.UploadData(url, requestData);
var response = serializer.Deserialize<dynamic>(Encoding.UTF8.GetString(responseData));
return response["GatewayUrl"];
}
}
<scripttype="text/javascript"src="https://mapi.trustpay.eu/mapi5/Scripts/TrustPay/popup.js"></script><iframeid="TrustPayFrame"src="https://aapi.trustpay.eu/Payments/Gateway?paymentRequestId=123123&sig=58B2FA9C45AEE707FFB6A4A0749D2"></iframe><ahref="#"class="show-popup">Pay via TrustPay</a>
Merchant's site makes a Payment request with purchase order reference to the TrustPay's API.
The response from TrustPay's API will contain a URL for the payment page.
Merchant's site redirects customer to the provided URL which we will provides Multibanco's payment details that the customer can make this payment at a Multibanco ATM, internet banking or mobile phone.
Once the payment is complete, the customer will be redirected to the merchant URL provided in the original payment request.
Payment
API endpoints:
Live - https://aapi.trustpay.eu/api/Payments/Payment
Initiates new Multibanco payment request.
Request
Payment example:
using System.Net;
using System.Text;
using System.Web.Script.Serialization;
public string Payment(string token)
{
string url = "https://aapi.trustpay.eu/api/Payments/Payment";
using (var client = new WebClient())
{
client.Headers = new WebHeaderCollection
{
"Authorization: Bearer " + token,
"Content-Type: application/json"
};
var request = new
{
PaymentMethod = "Multibanco",
MerchantIdentification = new
{
ProjectId = "1234567"
},
PaymentInformation = new
{
Amount = new
{
Amount = 1.50,
Currency = "EUR"
},
Localization = "en",
References = new
{
MerchantReference = "Order 12345"
},
DueDate = "2023-04-28",
},
CallbackUrls = new
{
Success = "https://somedomain.eu/success",
Cancel = "https://somedomain.eu/cancel",
Error = "https://somedomain.eu/error",
Notification = "https://somedomain.eu/notification_handler"
}
};
JavaScriptSerializer serializer = new JavaScriptSerializer();
var requestData = Encoding.UTF8.GetBytes(serializer.Serialize(request));
var responseData = client.UploadData(url, requestData);
var response = serializer.Deserialize<dynamic>(Encoding.UTF8.GetString(responseData));
return response["GatewayUrl"];
}
}
<scripttype="text/javascript"src="https://mapi.trustpay.eu/mapi5/Scripts/TrustPay/popup.js"></script><iframeid="TrustPayFrame"src="https://aapi.trustpay.eu/Payments/Gateway?paymentRequestId=123123&sig=58B2FA9C45AEE707FFB6A4A0749D2"></iframe><ahref="#"class="show-popup">Pay via TrustPay</a>
Merchant's site makes a Payment request with purchase order reference to the TrustPay's API.
The response from TrustPay's API will contain a URL for the payment page.
Merchant's site redirects customer to the provided URL in which the Issuer's payment gateway will be loaded.
When no Issuer's ProprietaryId was specified in the Payment request default Issuer selection form will be loaded instead.
The Issuer selection form can be displayed as a popup overlaid over the merchant's site using IFrame, details in the Payment request.
Optionally, custom Issuer selection form can be implemented in the merchant's system using the Issuers data that can be
programmatically loaded using the Issuers request.
Customer fills up the payment details on the Issuers's payment site and confirms the data.
After the data is confirmed customer is redirected to Merchant's URL provided in the original Payment request.
Payment
API endpoints:
Live - https://aapi.trustpay.eu/api/Payments/Payment
Initiates new MyBank payment request.
When no Issuer's ProprietaryId is specified in the Payment request the default Issuer selection form can be displayed as a popup overlaid over the merchant's site using IFrame.
The Merchant's site has to include link to Merchant API JavaScript popup.js on it's page and load the TrustPay payment gateway url inside an IFrame.
The included JavaScript will style the IFrame so that it is hidden. It also contains the code necessary to show the Issuer selection form from the hidden IFrame as a popup overlaid
over the merchant's e-shop. To allow users to show the Issuer selection popup, the merchant needs to include some link/button/etc. with CSS class "show-popup" somewhere on the
page. Onclick event handler that shows the popup will be automatically added to this element. Please see the HTML code example to the right.
Request
Payment example:
using System.Net;
using System.Text;
using System.Web.Script.Serialization;
public string Payment(string token)
{
string url = "https://aapi.trustpay.eu/api/Payments/Payment";
using (var client = new WebClient())
{
client.Headers = new WebHeaderCollection
{
"Authorization: Bearer " + token,
"Content-Type: application/json"
};
var request = new
{
PaymentMethod = "MyBank",
MerchantIdentification = new
{
ProjectId = "1234567"
},
PaymentInformation = new
{
Amount = new
{
Amount = 1.50,
Currency = "EUR"
},
DebtorAgent = new
{
ProprietaryId = "CT000005:it"
},
Localization = "en",
References = new
{
MerchantReference = "Order 12345"
}
},
CallbackUrls = new
{
Success = "https://somedomain.eu/success",
Cancel = "https://somedomain.eu/cancel",
Error = "https://somedomain.eu/error",
Notification = "https://somedomain.eu/notification_handler"
}
};
JavaScriptSerializer serializer = new JavaScriptSerializer();
var requestData = Encoding.UTF8.GetBytes(serializer.Serialize(request));
var responseData = client.UploadData(url, requestData);
var response = serializer.Deserialize<dynamic>(Encoding.UTF8.GetString(responseData));
return response["GatewayUrl"];
}
}
<scripttype="text/javascript"src="https://mapi.trustpay.eu/mapi5/Scripts/TrustPay/popup.js"></script><iframeid="TrustPayFrame"src="https://aapi.trustpay.eu/Payments/Gateway?paymentRequestId=123123&sig=58B2FA9C45AEE707FFB6A4A0749D2"></iframe><ahref="#"class="show-popup">Pay via TrustPay</a>
Description of result that occurred during the service call.
Varchar(235)
CorrelationId
Correlation Id is only shown when an error occurs. It's a GUID of the error log in our internal system.
Varchar(36)
Payment (recurring)
API endpoints:
Live - https://aapi.trustpay.eu/api/Payments/Payment
Initiates new MyBank recurring payment request using direct debit.
The debtor's name and IBAN from the original MyBank payment request will be used to initiate the direct debit.
Request
Payment example:
using System.Net;
using System.Text;
using System.Web.Script.Serialization;
public string Payment(string token)
{
string url = "https://aapi.trustpay.eu/api/Payments/Payment";
using (var client = new WebClient())
{
client.Headers = new WebHeaderCollection
{
"Authorization: Bearer " + token,
"Content-Type: application/json"
};
var request = new
{
PaymentMethod = "SepaDirectDebit",
MerchantIdentification = new
{
ProjectId = "1234567"
},
PaymentInformation = new
{
DueDate = "2022-05-25",
Amount = new
{
Amount = 1.50,
Currency = "EUR"
},
Localization = "en",
References = new
{
MerchantReference = "Order 12345",
OriginalPaymentRequestId = 73807
}
Debtor = new
{
Email = "example@example.org",
IpAddress = "1.2.3.4",
},
},
CallbackUrls = new
{
Success = "https://somedomain.eu/success",
Cancel = "https://somedomain.eu/cancel",
Error = "https://somedomain.eu/error",
Notification = "https://somedomain.eu/notification_handler"
}
};
JavaScriptSerializer serializer = new JavaScriptSerializer();
var requestData = Encoding.UTF8.GetBytes(serializer.Serialize(request));
var responseData = client.UploadData(url, requestData);
var response = serializer.Deserialize<dynamic>(Encoding.UTF8.GetString(responseData));
return response["GatewayUrl"];
}
}
This code is using external library Jackson to parse text from and to json format
import org.codehaus.jackson.map.ObjectMapper;
import javax.net.ssl.HttpsURLConnection;
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.URL;
import java.util.Map;
public String CapturePayment(String token){
try {
URL obj = new URL("https://aapi.trustpay.eu/api/Payments/Payment");
HttpsURLConnection con = (HttpsURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Authorization", "Bearer " + token);
con.setRequestProperty("Content-type", "application/json");
Object request = new Object() {
public String PaymentMethod = "SepaDirectDebit";
public String DueDate = "2022-05-25";
public Object MerchantIdentification = new Object(){
public long ProjectId = 4107123456;
};
public Object PaymentInformation = new Object(){
public Object Amount = new Object(){
public double Amount = 1.50;
public String Currency = "EUR";
};
public String Localization = "en";
public Object References = new Object(){
public String MerchantReference = "merch ref. no. #555";
public long OriginalPaymentRequestId = 73807;
};
public Object Debtor = new Object(){
public String Email = "example@example.org";
public String IpAddress = "1.2.3.4";
};
};
public Object CallbackUrls = new Object(){
public String Success = "https://somedomain.eu/success";
public String Cancel = "https://somedomain.eu/cancel";
public String Error = "https://somedomain.eu/error";
public String Notification = "https://somedomain.eu/notification_handler";
};
};
ObjectMapper JsonParser = new ObjectMapper();
String jsonrequest = JsonParser.writeValueAsString(request);
con.setDoOutput(true);
try (DataOutputStream wr = new DataOutputStream(con.getOutputStream())) {
wr.writeBytes(jsonrequest);
wr.flush();
}
String response = "";
try (BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()))) {
String inputLine;
while ((inputLine = in.readLine()) != null) {
response += inputLine;
}
}
Map<String,String> deserialized = JsonParser.readValue(response, Map.class);
return String.valueOf(deserialized.get("GatewayUrl"));
}
catch (Exception ex){
throw new RuntimeException(ex.getMessage());
}
}
Description of result that occurred during the service call.
Varchar(235)
CorrelationId
Correlation Id is only shown when an error occurs. It's a GUID of the error log in our internal system.
Varchar(36)
Issuers
API endpoints:
Live - https://aapi.trustpay.eu/api/Issuers/Issuers/MyBank
Retrieve MyBank Issuers list using GET request.
Request
Request example:
using System.Net;
using System.Text;
public string ListIssuers()
{
string url = "https://aapi.trustpay.eu/api/Issuers/Issuers/MyBank";
using (var client = new WebClient())
{
return client.DownloadString(url);
}
}
This code is using external library Jackson to parse text from and to json format
import org.codehaus.jackson.map.ObjectMapper;
import javax.net.ssl.HttpsURLConnection;
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.URL;
import java.util.Map;
public String CapturePayment(String token){
try {
URL obj = new URL("https://aapi.trustpay.eu/api/Payments/Payment");
HttpsURLConnection con = (HttpsURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Authorization", "Bearer " + token);
con.setRequestProperty("Content-type", "application/json");
Object request = new Object() {
public String PaymentMethod = "NasplatkyTB";
public Object MerchantIdentification = new Object(){
public long ProjectId = 4107123456;
};
public Object PaymentInformation = new Object(){
public Object Amount = new Object(){
public double Amount = 1.50;
public String Currency = "EUR";
};
public String Localization = "SK";
public Object References = new Object(){
public String MerchantReference = "merch ref. no. #555";
};
public Object Debtor = new Object(){
public String FirstName = "John";
public String LastName = "Doe";
public String Email = "email@example.com";
};
public Object[] OrderedItems = new Object[]{
new Object(){
public String Name = "Item1";
public int Quantity = 1;
public double Price = 1.50;
};
};
};
public Object CallbackUrls = new Object(){
public String Success = "https://somedomain.eu/success";
public String Cancel = "https://somedomain.eu/cancel";
public String Error = "https://somedomain.eu/error";
public String Notification = "https://somedomain.eu/notification_handler";
};
};
ObjectMapper JsonParser = new ObjectMapper();
String jsonrequest = JsonParser.writeValueAsString(request);
con.setDoOutput(true);
try (DataOutputStream wr = new DataOutputStream(con.getOutputStream())) {
wr.writeBytes(jsonrequest);
wr.flush();
}
String response = "";
try (BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()))) {
String inputLine;
while ((inputLine = in.readLine()) != null) {
response += inputLine;
}
}
Map<String,String> deserialized = JsonParser.readValue(response, Map.class);
return String.valueOf(deserialized.get("GatewayUrl"));
}
catch (Exception ex){
throw new RuntimeException(ex.getMessage());
}
}
<scripttype="text/javascript"src="https://mapi.trustpay.eu/mapi5/Scripts/TrustPay/popup.js"></script><iframeid="TrustPayFrame"src="https://aapi.trustpay.eu/Payments/Gateway?paymentRequestId=123123&sig=58B2FA9C45AEE707FFB6A4A0749D2"></iframe><ahref="#"class="show-popup">Pay via TrustPay</a>
Merchant's site makes a Payment request with purchase order reference to the TrustPay's API.
The response from TrustPay's API will contain a URL for the payment page.
Merchant's site redirects customer to the provided URL in which a country and bank selection form will be loaded.
The countries and banks selection form can be displayed as a popup overlaid over the merchant's site using IFrame.
Customer fills up the payment details on the bank's payment site and confirms the data.
After the data is confirmed customer is redirected to Merchant's URL provided in the original Payment request.
Payment
API endpoints:
Live - https://aapi.trustpay.eu/api/Payments/Payment
Initiates new OpenBanking payment request.
Request
Payment example:
using System.Net;
using System.Text;
using System.Web.Script.Serialization;
public string Payment(string token)
{
string url = "https://aapi.trustpay.eu/api/Payments/Payment";
using (var client = new WebClient())
{
client.Headers = new WebHeaderCollection
{
"Authorization: Bearer " + token,
"Content-Type: application/json"
};
var request = new
{
PaymentMethod = "OpenBanking",
MerchantIdentification = new
{
ProjectId = "1234567"
},
PaymentInformation = new
{
Amount = new
{
Amount = 1.50,
Currency = "EUR"
},
Localization = "SK",
Country = "DE",
References = new
{
MerchantReference = "Order 12345"
}
},
CallbackUrls = new
{
Success = "https://somedomain.eu/success",
Cancel = "https://somedomain.eu/cancel",
Error = "https://somedomain.eu/error",
Notification = "https://somedomain.eu/notification_handler"
}
};
JavaScriptSerializer serializer = new JavaScriptSerializer();
var requestData = Encoding.UTF8.GetBytes(serializer.Serialize(request));
var responseData = client.UploadData(url, requestData);
var response = serializer.Deserialize<dynamic>(Encoding.UTF8.GetString(responseData));
return response["GatewayUrl"];
}
}
This code is using external library Jackson to parse text from and to json format
import org.codehaus.jackson.map.ObjectMapper;
import javax.net.ssl.HttpsURLConnection;
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.URL;
import java.util.Map;
public String CapturePayment(String token){
try {
URL obj = new URL("https://aapi.trustpay.eu/api/Payments/Payment");
HttpsURLConnection con = (HttpsURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Authorization", "Bearer " + token);
con.setRequestProperty("Content-type", "application/json");
Object request = new Object() {
public String PaymentMethod = "OpenBanking";
public Object MerchantIdentification = new Object(){
public long ProjectId = 4107123456;
};
public Object PaymentInformation = new Object(){
public Object Amount = new Object(){
public double Amount = 1.50;
public String Currency = "EUR";
};
public String Localization = "SK";
public String Country = "DE"
public Object References = new Object(){
public String MerchantReference = "merch ref. no. #555";
};
};
public Object CallbackUrls = new Object(){
public String Success = "https://somedomain.eu/success";
public String Cancel = "https://somedomain.eu/cancel";
public String Error = "https://somedomain.eu/error";
public String Notification = "https://somedomain.eu/notification_handler";
};
};
ObjectMapper JsonParser = new ObjectMapper();
String jsonrequest = JsonParser.writeValueAsString(request);
con.setDoOutput(true);
try (DataOutputStream wr = new DataOutputStream(con.getOutputStream())) {
wr.writeBytes(jsonrequest);
wr.flush();
}
String response = "";
try (BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()))) {
String inputLine;
while ((inputLine = in.readLine()) != null) {
response += inputLine;
}
}
Map<String,String> deserialized = JsonParser.readValue(response, Map.class);
return String.valueOf(deserialized.get("GatewayUrl"));
}
catch (Exception ex){
throw new RuntimeException(ex.getMessage());
}
}
Merchant's site makes a Payment request with purchase order reference to the TrustPay's API.
The response from TrustPay's API will contain a URL for the payment page.
Merchant's site redirects customer to the provided URL which will generate Payconiq's QR code that the customer can scan and use with Payconiq application.
After the customer finishes the payment in Payconiq app, the customer is then redirected to Merchant's URL provided in the original Payment request.
Payment
API endpoints:
Live - https://aapi.trustpay.eu/api/Payments/Payment
Initiates new Payconiq payment request.
Request
Payment example:
using System.Net;
using System.Text;
using System.Web.Script.Serialization;
public string Payment(string token)
{
string url = "https://aapi.trustpay.eu/api/Payments/Payment";
using (var client = new WebClient())
{
client.Headers = new WebHeaderCollection
{
"Authorization: Bearer " + token,
"Content-Type: application/json"
};
var request = new
{
PaymentMethod = "Payconiq",
MerchantIdentification = new
{
ProjectId = "1234567"
},
PaymentInformation = new
{
Amount = new
{
Amount = 1.50,
Currency = "EUR"
},
Localization = "en",
References = new
{
MerchantReference = "Order 12345"
}
},
CallbackUrls = new
{
Success = "https://somedomain.eu/success",
Cancel = "https://somedomain.eu/cancel",
Error = "https://somedomain.eu/error",
Notification = "https://somedomain.eu/notification_handler"
}
};
JavaScriptSerializer serializer = new JavaScriptSerializer();
var requestData = Encoding.UTF8.GetBytes(serializer.Serialize(request));
var responseData = client.UploadData(url, requestData);
var response = serializer.Deserialize<dynamic>(Encoding.UTF8.GetString(responseData));
return response["GatewayUrl"];
}
}
<scripttype="text/javascript"src="https://mapi.trustpay.eu/mapi5/Scripts/TrustPay/popup.js"></script><iframeid="TrustPayFrame"src="https://aapi.trustpay.eu/Payments/Gateway?paymentRequestId=123123&sig=58B2FA9C45AEE707FFB6A4A0749D2"></iframe><ahref="#"class="show-popup">Pay via TrustPay</a>
Merchant's site makes a Payment request with purchase order reference to the TrustPay's API.
The response from TrustPay's API will contain a URL for the payment page.
Merchant's site redirects customer to the provided URL which will generate Satispay's QR code that the customer can scan and use with Satispay application.
After the customer finishes the payment in Satispay app, the customer is then redirected to Merchant's URL provided in the original Payment request.
Payment
API endpoints:
Live - https://aapi.trustpay.eu/api/Payments/Payment
<scripttype="text/javascript"src="https://mapi.trustpay.eu/mapi5/Scripts/TrustPay/popup.js"></script><iframeid="TrustPayFrame"src="https://aapi.trustpay.eu/Payments/Gateway?paymentRequestId=123123&sig=58B2FA9C45AEE707FFB6A4A0749D2"></iframe><ahref="#"class="show-popup">Pay via TrustPay</a>
This code is using external library Jackson to parse text from and to json format
import org.codehaus.jackson.map.ObjectMapper;
import javax.net.ssl.HttpsURLConnection;
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.URL;
import java.util.Map;
public String CapturePayment(String token){
try {
URL obj = new URL("https://aapi.trustpay.eu/api/Payments/Payment");
HttpsURLConnection con = (HttpsURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-type", "application/json");
Object request = new Object() {
public String PaymentMethod = "SepaCreditTransfer";
public Object MerchantIdentification = new Object(){
public long ProjectId = 4107123456;
};
public Object PaymentInformation = new Object(){
public Object Amount = new Object(){
public double Amount = 1.50;
public String Currency = "EUR";
public boolean RequireExact = true;
};
public String DueDate = "2021-04-27";
public String Localization = "en";
public Object References = new Object(){
public String MerchantReference = "merch ref. no. #555";
};
};
public Object CallbackUrls = new Object(){
public String Notification = "https://somedomain.eu/notification_handler";
};
};
ObjectMapper JsonParser = new ObjectMapper();
String jsonrequest = JsonParser.writeValueAsString(request);
con.setDoOutput(true);
try (DataOutputStream wr = new DataOutputStream(con.getOutputStream())) {
wr.writeBytes(jsonrequest);
wr.flush();
}
String response = "";
try (BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()))) {
String inputLine;
while ((inputLine = in.readLine()) != null) {
response += inputLine;
}
}
Map<String,String> deserialized = JsonParser.readValue(response, Map.class);
return String.valueOf(deserialized.get("GatewayUrl"));
}
catch (Exception ex){
throw new RuntimeException(ex.getMessage());
}
}
Merchant's site makes a Prepare mandate request with purchase order reference and mandate details to the TrustPay's API.
The response from TrustPay's API will contain a URL for the payment iFrame.
Merchant's site includes an IFrame with the provided URL in which TrustPay's payment gateway will be loaded.
Customer fills up the SEPA Direct Debit mandate form in the IFrame loaded on the merchant's site and confirms the data.
After the data is confirmed customer can download a PDF file with details of the mandate.
After this information is submited, the mandate will start being processed by TrustPay together with possible payment (if pay now was chosen)
Prepare mandate
API endpoints:
Live - https://aapi.trustpay.eu/api/SepaDirectDebitMandates/Mandate
Prepares the mandate and returns the URL of the form in which the customer needs to fill some additional information. After this information is submitted,
the mandate will start being processed by TrustPay together with possible payment (if pay now was chosen).
Request
Prepare mandate example:
using System;
using System.Net;
using System.Text;
using System.Web.Script.Serialization;
public string PrepareMandate(string token)
{
string url = "https://aapi.trustpay.eu/api/SepaDirectDebitMandates/Mandate";
using (var client = new WebClient())
{
client.Headers = new WebHeaderCollection
{
"Authorization: Bearer " + token,
"Content-Type: application/json"
};
var request = new
{
PayNow = true,
ReducedPeriod = 4,
MerchantIdentification = new
{
ProjectId = "1234567",
},
PaymentInformation = new
{
DueDate = "2017-07-28",
RemittanceInformation = "test123",
Amount = new
{
Amount = 1.50,
Currency = "EUR",
},
References = new
{
MerchantReference = "Order 12345",
EndToEnd = "e2e",
},
SepaDirectDebitInformation = new
{
SequenceType = "RCUR",
},
},
CallbackUrls = new
{
Notification = "https://somedomain.eu/notification_handler",
}
};
JavaScriptSerializer serializer = new JavaScriptSerializer();
var requestData = Encoding.UTF8.GetBytes(serializer.Serialize(request));
var responseData = client.UploadData(url, requestData);
var response = serializer.Deserialize<dynamic>(Encoding.UTF8.GetString(responseData));
return response["GatewayUrl"];
}
}
This code is using external library Jackson to parse text from and to json format
import org.codehaus.jackson.map.ObjectMapper;
import javax.net.ssl.HttpsURLConnection;
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.URL;
import java.util.Map;
public String PrepareMandate(String token){
try{
URL obj = new URL("https://aapi.trustpay.eu/api/SepaDirectDebitMandates/Mandate");
HttpsURLConnection con = (HttpsURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Authorization", "Bearer " + token);
con.setRequestProperty("Content-type", "application/json");
Object request = new Object() {
public boolean PayNow = true;
public Byte ReducedPeriod = null;
public Object MerchantIdentification = new Object(){
public long ProjectId = 4107123456;
};
public Object PaymentInformation = new Object(){
public String DueDate = "2017-03-27";
public String RemittanceInformation = "test";
public Object Amount = new Object(){
public double Amount = 1.50;
public String Currency = "EUR";
};
public Object References = new Object(){
public String MerchantReference = "merch ref. no. #555";
public String EndToEnd = "e2e";
};
public Object SepaDirectDebitInformation = new Object(){
public String SequenceType = "RCUR";
};
};
public Object CallbackUrls = new Object(){
public String Notification = "https://somedomain.eu/notification_handler";
};
};
ObjectMapper JsonParser = new ObjectMapper();
String jsonrequest = JsonParser.writeValueAsString(request);
con.setDoOutput(true);
try (DataOutputStream wr = new DataOutputStream(con.getOutputStream())) {
wr.writeBytes(jsonrequest);
wr.flush();
}
String response = "";
try (BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()))) {
String inputLine;
while ((inputLine = in.readLine()) != null) {
response += inputLine;
}
}
Map<String,String> deserialized = JsonParser.readValue(response, Map.class);
return deserialized.get("PreparedMandateUrl");
}
catch(Exception ex){
throw new RuntimeException(ex.getMessage());
}
}
Description of result that occurred during the service call.
Varchar(235)
CorrelationId
Correlation Id is only shown when an error occurs. It's a GUID of the error log in our internal system.
Varchar(36)
Cancel mandate
API endpoints:
Live - https://aapi.trustpay.eu/api/SepaDirectDebitMandates/Mandate/[UMR]/Cancel
This function allows you to cancel an active mandate.
Request
Cancel mandate example:
using System.Net;
using System.Text;
using System.Web.Script.Serialization;
public void CancelMandate(string token)
{
string url = "https://aapi.trustpay.eu/api/SepaDirectDebitMandates/Mandate/[UMR]/Cancel";
using (var client = new WebClient())
{
client.Headers = new WebHeaderCollection
{
"Authorization: Bearer " + token,
"Content-Type: application/json"
};
var request = new
{
Umr = "12345678901234567890"
};
JavaScriptSerializer serializer = new JavaScriptSerializer();
var requestData = Encoding.UTF8.GetBytes(serializer.Serialize(request));
var responseData = client.UploadData(url, requestData);
var response = Encoding.UTF8.GetString(responseData);
if (response == "{}")
{
return;
}
throw new Exception(serializer.Deserialize<dynamic>(response)["ResultMessage"]);
}
}
This code is using external library Jackson to parse text from and to json format
import org.codehaus.jackson.map.ObjectMapper;
import javax.net.ssl.HttpsURLConnection;
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.URL;
import java.util.Map;
public String CapturePayment(String token){
try {
URL obj = new URL("https://aapi.trustpay.eu/api/Payments/Payment");
HttpsURLConnection con = (HttpsURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Authorization", "Bearer " + token);
con.setRequestProperty("Content-type", "application/json");
Object request = new Object() {
public String PaymentMethod = "SepaDirectDebit";
public Object MerchantIdentification = new Object(){
public long ProjectId = 4107123456;
};
public Object PaymentInformation = new Object(){
public String DueDate = "2017-03-27";
public String RemittanceInformation = "test";
public Object Amount = new Object(){
public double Amount = 1.50;
public String Currency = "EUR";
};
public Object References = new Object(){
public String MerchantReference = "merch ref. no. #555";
public String EndToEnd = "e2e";
};
public Object SepaDirectDebitInformation = new Object(){
public Object MandateInformation = new Object(){
public String Umr = "12345678901234567890";
};
};
};
public Object CallbackUrls = new Object(){
public String Notification = "https://somedomain.eu/notification_handler";
};
};
ObjectMapper JsonParser = new ObjectMapper();
String jsonrequest = JsonParser.writeValueAsString(request);
con.setDoOutput(true);
try (DataOutputStream wr = new DataOutputStream(con.getOutputStream())) {
wr.writeBytes(jsonrequest);
wr.flush();
}
String response = "";
try (BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()))) {
String inputLine;
while ((inputLine = in.readLine()) != null) {
response += inputLine;
}
}
Map<String,String> deserialized = JsonParser.readValue(response, Map.class);
return String.valueOf(deserialized.get("PaymentRequestId"));
}
catch (Exception ex){
throw new RuntimeException(ex.getMessage());
}
}
Description of result that occurred during the service call.
Varchar(235)
CorrelationId
Correlation Id is only shown when an error occurs. It's a GUID of the error log in our internal system.
Varchar(36)
Capture payment with external mandate
API endpoints:
Live - https://aapi.trustpay.eu/api/Payments/Payment
Creates new direct debit without previously creating a mandate in TrustPay. This API has the same request and response as Capture payment, with these additional parameters in the request:
Request
Capture payment with external mandate example:
using System.Net;
using System.Text;
using System.Web.Script.Serialization;
public int CapturePayment(string token)
{
string url = "https://aapi.trustpay.eu/api/Payments/Payment";
using (var client = new WebClient())
{
client.Headers = new WebHeaderCollection
{
"Authorization: Bearer " + token,
"Content-Type: application/json"
};
var request = new
{
PaymentMethod = "SepaDirectDebit",
MerchantIdentification = new
{
ProjectId = "1234567",
},
PaymentInformation = new
{
DueDate = "2017-07-28",
RemittanceInformation = "test123",
Amount = new
{
Amount = 1.50,
Currency = "EUR",
},
References = new
{
MerchantReference = "Order 12345",
EndToEnd = "e2e",
},
SepaDirectDebitInformation = new
{
SequenceType = "FRST",
MandateInformation = new
{
Umr = "12345678901234567890",
SignatureCity = "Bratislava",
SignatureDate = "2017-07-28",
},
},
Debtor = new
{
Name = "John Doe",
Email = "client@somedomain.eu",
IpAddress = "1.2.3.4",
Address = new
{
PostCode = "12345",
City = "Bratislava",
CountryCode = "SK",
Lines = new[]
{
"Street 1/A",
},
},
},
DebtorAccount = new
{
Iban = "SK3112000000198742637541",
},
DebtorAgent = new
{
Bic = "TPAYSKBX",
},
},
CallbackUrls = new
{
Notification = "https://somedomain.eu/notification_handler",
}
};
JavaScriptSerializer serializer = new JavaScriptSerializer();
var requestData = Encoding.UTF8.GetBytes(serializer.Serialize(request));
var responseData = client.UploadData(url, requestData);
var response = serializer.Deserialize<dynamic>(Encoding.UTF8.GetString(responseData));
return response["PaymentRequestId"];
}
}
This code is using external library Jackson to parse text from and to json format
import org.codehaus.jackson.map.ObjectMapper;
import javax.net.ssl.HttpsURLConnection;
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.URL;
import java.util.Map;
public String CapturePayment(String token){
try {
URL obj = new URL("https://aapi.trustpay.eu/api/Payments/Payment");
HttpsURLConnection con = (HttpsURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Authorization", "Bearer " + token);
con.setRequestProperty("Content-type", "application/json");
Object request = new Object() {
public String PaymentMethod = "SepaDirectDebit";
public Object MerchantIdentification = new Object(){
public long ProjectId = 4107123456;
public String Currency = "EUR";
};
public Object PaymentInformation = new Object(){
public String DueDate = "2017-03-27";
public String RemittanceInformation = "test";
public Object Amount = new Object(){
public double Amount = 1.50;
};
public Object References = new Object(){
public String MerchantReference = "merch ref. no. #555";
public String EndToEnd = "e2e";
};
public Object SepaDirectDebitInformation = new Object(){
public String SequenceType = "FRST";
public Object MandateInformation = new Object(){
public String Umr = "12345678901234567890";
public String SignatureDate = "2020-06-01";
public String SignatureCity = "Bratislava";
};
};
public Object Debtor = new Object(){
public String Name = "John Doe";
public String Email = "client@somedomain.eu";
public String IpAddress = "1.2.3.4";
public Object Address = new Object(){
public String PostCode = "12345";
public String City = "Bratislava";
public String CountryCode = "SK";
public String[] Lines = {"Street 1/A"};
};
};
public Object DebtorAccount = new Object(){
public String Iban = "SK3112000000198742637541";
};
public Object DebtorAgent = new Object(){
public String Bic = "TPAYSKBX";
};
};
public Object CallbackUrls = new Object(){
public String Notification = "https://somedomain.eu/notification_handler";
};
};
ObjectMapper JsonParser = new ObjectMapper();
String jsonrequest = JsonParser.writeValueAsString(request);
con.setDoOutput(true);
try (DataOutputStream wr = new DataOutputStream(con.getOutputStream())) {
wr.writeBytes(jsonrequest);
wr.flush();
}
String response = "";
try (BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()))) {
String inputLine;
while ((inputLine = in.readLine()) != null) {
response += inputLine;
}
}
Map<String,String> deserialized = JsonParser.readValue(response, Map.class);
return String.valueOf(deserialized.get("PaymentRequestId"));
}
catch (Exception ex){
throw new RuntimeException(ex.getMessage());
}
}