Overview of payment process

Intro

The TrustPay Merchant API (payment service) is an internet based payment tool that merchants can use to receive payments from clients. By integrating this service, merchants are able to process both instant bank transfer and card payments.

API endpoint:
Live - https://amapi.trustpay.eu/
For testing purposes please use the same API endpoint with your testing credentials.

The live API endpoint is https://amapi.trustpay.eu/.

Payment process

Merchant's site includes an IFrame in which TrustPay's payment gateway will be loaded. This will also set up the payment in TrustPay. After user decides to pay with TrustPay, the payment gateway will be shown as a popup.
For instant bank transfer payments the client choses their bank on the TrustPay payment gateway and makes a payment in their bank. In case of card payments the client pays directly on TrustPay payment gateway by entering their card details.
After the payment is finished, TrustPay redirects the client to merchant's success, error or cancel URL accordingly. These URLs can be configured in TrustPay Merchant Portal in Technical settings.
TrustPay notifies the merchant of successful payment using merchant's notification URL and/or e-mail address configured in TrustPay Merchant Portal in Technical settings.

Payment processing

Instant Bank transfers

Payment setup v02

API endpoint:

Live - https://amapi.trustpay.eu/mapi5/wire/paypopup
For testing purposes please use the same API endpoint with your testing credentials.

Example HTML code:


        <script type="text/javascript" src="https://mapi.trustpay.eu/mapi5/Scripts/TrustPay/popup.js"></script>
<iframe id="TrustPayFrame" src="https://amapi.trustpay.eu/mapi5/wire/paypopup?accountId=4107111111..."></iframe>
<a href="#" class="show-popup">Pay via TrustPay</a>

Merchant's implementation has to include link to Merchant API JavaScript on it's page and load the TrustPay payment gateway inside an IFrame. 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.

If your web page needs to be notified that the Payments PopUp has been loaded, create a parameterless JavaScript function with the name onTrustPayPopupLoaded() before including the link to the Merchant API JavaScript.

The IFrame URL should contain the following parameters:

Payment setup example:


public string GetSetUpPaymentUrl() 
{
    string baseUrl = "https://amapi.trustpay.eu/mapi5/wire/paypopup";
    long accountId = 4107111111;
    decimal amount = 1.5M;
    string currency = "EUR";
    string reference = "123456789";
    string notificationUrl = "https://example.handler.com/result.php";
    int paymentType = 0;
        
    string secretKey = "123456";
    string sigData = string.Format(
        CultureInfo.InvariantCulture,
        "{0}/{1:0.00}/{2}/{3}/{4}", accountId, amount, currency, reference, paymentType);
    string signature = GetSignature(secretKey, sigData);

    string url = string.Format(
    CultureInfo.InvariantCulture,
        "{0}?AccountId={1}&Amount={2:0.00}&Currency={3}&Reference={4}&NotificationUrl={5}&PaymentType={6}&Signature={7}",
        baseUrl, accountId, amount, currency, HttpUtility.UrlEncode(reference),
        HttpUtility.UrlEncode(notificationUrl), paymentType, signature);

    Response.Redirect(url);
}


function getSetUpPaymentUrl()
{
    $baseUrl = "https://amapi.trustpay.eu/mapi5/wire/paypopup";
    $accountId = 4107111111;
    $amount = 1.5;
    $currency = "EUR";
    $reference = "123456789";
    $notificationUrl = "https://example.handler.com/result.php";
    $paymentType = 0;

    $secretKey = "123456";
    $sigData = sprintf("%d/%s/%s/%s/%d", $accountId, number_format($amount, 2, '.', ''), $currency, $reference, $paymentType);
    $signature = GetSignature($secretKey, $sigData);

    $url = sprintf(
        "%s?AccountId=%d&Amount=%s&Currency=%s&Reference=%s&NotificationUrl=%s&PaymentType=%d&Signature=%s",
        $baseUrl, $accountId, number_format($amount, 2, '.', ''), $currency,
        urlencode($reference), urlencode($notificationUrl), $paymentType, $signature);
    return $url;
}


import java.util.Locale;
import java.net.URLEncoder;

public String GetSetUpPaymentUrl()
{
    String baseUrl = "https://amapi.trustpay.eu/mapi5/wire/paypopup";
    long accountId = 4107111111;
    double amount = 1.5d;
    String currency = "EUR";
    String reference = "123456789";
    String notificationUrl = "https://example.handler.com/result.php";
    int paymentType = 0;

    try
    {
        String secretKey = "123456";
        String sigData = String.format(Locale.ROOT, "%d/%.2f/%s/%s/%d", accountId, amount, currency, reference, paymentType);
        String signature = GetSignature(secretKey, sigData);

        String url = String.format(
            Locale.ROOT,"%s?AccountId=%d&Amount=%.2f&Currency=%s&Reference=%s&NotificationUrl=%s&PaymentType=%d&Signature=%s", 
            baseUrl, accountId, amount, currency, URLEncoder.encode(reference, "UTF-8"), 
            URLEncoder.encode(notificationUrl, "UTF-8"), paymentType, signature);
        return url;
    }catch(Exception ex){}
}

Name	Description	Format	Required
AccountId	Merchant account or project ID (ID of account or project assigned by TrustPay)	Numeric(10)	Yes
Amount	Amount of the payment (exactly 2 decimal places)	Numeric(13,2) en-US format	Yes
Currency	Currency of the payment (same as currency of merchant account)	Char(3)	Yes
Reference	Reference (merchant’s payment identification)	Varchar(35)¹	Yes
PaymentType	Payment type For purchase must be set to 0	Numeric(1)	Yes
Signature	Data signature calculated from concatenated values of AccountId, Amount, Currency, Reference and PaymentType parameters, if these parameters are present. Slash character ('/') is used as separator.	Char(64)	Yes
Url	Return URL (overrides any default Return URL, can be overridden further by Return URL, Cancel URL, Error URL)	Varchar(256)	No
ReturnUrl	Return URL (overrides default Success Return URL)	Varchar(256)	No
CancelUrl	Cancel URL (overrides default Cancel Return URL)	Varchar(256)	No
ErrorUrl	Error URL (overrides default Error Return URL)	Varchar(256)	No
NotificationUrl	Notification URL (overrides default Notification URL)	Varchar(256)	No
Localization	Default language for TrustPay site	Char(2)	No
Country	Default country of client	Char(2)	No
Description	Description (payment description text that will be displayed to the user)	Varchar(140)	No
Email	Customer email	Varchar(254)	No
IsRedirect	Allows to make a redirect from merchant's e-shop	Bool²	No

¹ The reference can not contain characters < and >
² Only values True and False are allowed.

Payment result v02

After paying, the customer is redirected to one of the return URLs provided by the Merchant:

Success Return URL

Customer is redirected here in case of an announced, authorized or a successful payment with Result=0, or in case of a timed out pending payment with Result=1
Cancel Return URL

Customer is redirected here in case he decides to cancel the payment with Result=1005.
Error Return URL

Customer is redirected here in case of a failed or refused payment with Result >= 1000 and Result!=1005.

The following parameters are always being sent with the redirects:

Payment result example:
https://example.handler.com/result.php?Reference=1234567890&ResultCode=0&PaymentRequestId=4337417657

Name	Description	Format
Reference	Reference (merchant’s payment identification)	Varchar(500)
ResultCode	Result code	Numeric(4)
PaymentRequestId	Payment request ID (sent when available, can be used for inquiries regarding failed payments)	Numeric(10)

Refund v02

API endpoint:
Live - https://amapi.trustpay.eu/mapi5/wire/paypopup
For testing purposes please use the same API endpoint with your testing credentials.

Refund example:


string baseUrl = "https://amapi.trustpay.eu/mapi5/Wire/PayPopup";
long accountId = 4107111111;
decimal amount = 1.5M;
string currency = "EUR";
string reference = "123456789";
int paymentType = 8;
int paymentRequestId = 555;
        
string secretKey = "123456";
string sigData = string.Format(
    CultureInfo.InvariantCulture,
    "{0}/{1:0.00}/{2}/{3}/{4}/{5}/{6}", accountId, amount, currency, reference, paymentType, paymentRequestId);
string signature = GetSignature(secretKey, sigData);

string url = string.Format(
    CultureInfo.InvariantCulture,
    "{0}?AccountId={1}&Amount={2:0.00}&Currency={3}&Reference={4}&Signature={5}&PaymentType={6}&PaymentRequestId={7}",
    baseUrl, accountId, amount, currency, HttpUtility.UrlEncode(reference), signature, paymentType, paymentRequestId);

Response.Redirect(url);


$baseUrl = "https://amapi.trustpay.eu/mapi5/Wire/PayPopup";
$accountId = 4107111111;
$amount = 1.5;
$currency = "EUR";
$reference = "123456789";
$paymentType = 8;
$paymentRequestId = 555;
        
$secretKey = "123456";
$sigData = sprintf("%d/%s/%s/%s/%d/%d", $accountId, number_format($amount, 2, '.', ''), $currency, $reference, $paymentType, $paymentRequestId);
$signature = GetSignature($secretKey, $sigData);

$url = sprintf(
    "%s?AccountId=%d&Amount=%s&Currency=%s&Reference=%s&Signature=%s&PaymentType=%d&PaymentRequestId=%s", 
    $baseUrl, $accountId, number_format($amount, 2, '.', ''), $currency, urlencode($reference), $signature, $paymentType, $paymentRequestId);
header("Location: $url");
exit();


import java.util.Locale;
import java.net.URLEncoder;

String  baseUrl = "https://amapi.trustpay.eu/mapi5/Wire/PayPopup";
long accountId = 4107111111;
double amount = 1.5d;
String  currency = "EUR";
String  reference = "123456789";
int paymentType = 8;
int paymentRequestId = 555;

try
{
    String secretKey = "123456";
    String sigData = String.format(Locale.ROOT, "%d/%.2f/%s/%s/%d/%d", accountId, amount, currency, reference, paymentType, paymentRequestId);
    String signature = GetSignature(secretKey, sigData);

    String url = String.format(
        Locale.ROOT,"%s?AccountId=%d&Amount=%.2f&Currency=%s&Reference=%s&Signature=%s&PaymentType=%d&PaymentRequestId=%s", 
        baseUrl, accountId, amount, currency, URLEncoder.encode(reference, "UTF-8"), signature, paymentType, paymentRequestId);
    response.sendRedirect(url);
}catch(Exception ex){}

This function allows refunding a transaction.

Parameters are the same as for standard Purchase, but these additional parameters have to be added to the request:

Name	Description	Format	Required
PaymentType	Payment type For refund must be set to 8	Numeric(1)	Yes
PaymentRequestId	Payment request ID from notification	Numeric(10)	Yes
Signature	Data signature calculated from concatenated values of AccountId, Amount, Currency, Reference, PaymentType and PaymentRequestId parameters, if these parameters are present. Slash character ('/') is used as separator.	Char(64)	Yes

Body of HTTP response will contain a result code (see example response to the right).

Example response:
{
    "ResultCode": 0
}

Card payments

Visa and MasterCard card payments work in a similar way to instant bank transfers, with the differences described in this chapter.

Successful notifications are sent with result code 3 – authorized, which also means that the payment has been captured. All payments in an agreed period will be settled to your TrustPay account later in a single transaction. You will not receive any further notifications for the individual card transactions.

Test cards v02

When you are testing your implementation on the mapi endpoint with your testing credentials, you can use these test cards to make simulated payments:

Card number	Result when using this card
4200 0000 0000 0000 4200 0000 0000 1234 4200 0000 0000 5555	Payment is successful
4200 0000 0000 0001	Payment fails with result card expired
4200 0000 0000 0002	Payment fails with result card limit exceeded
4200 0000 0000 0003	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

Purchase v02

API endpoint:
Live - https://amapi.trustpay.eu/mapi5/Card/PayPopup
For testing purposes please use the same API endpoint with your testing credentials.

Example HTML code:


<script type="text/javascript" src="https://mapi.trustpay.eu/mapi5/Scripts/TrustPay/popup.js"></script>
<iframe id="TrustPayFrame" src="https://amapi.trustpay.eu/mapi5/Card/PayPopup?accountId=4107111111..."></iframe>
<a href="#" class="show-popup">Pay via TrustPay</a>

The IFrame URL should contain the following parameters:

Payment setup example:


public string GetPurchaseUrl() 
{
    string baseUrl = "https://amapi.trustpay.eu/mapi5/Card/PayPopup";
    long accountId = 4107111111;
    decimal amount = 1.5M;
    string billingcity = "Bratislava";
    string billingcountry = "SK";
    string billingpostcode = "83103";
    string billingstreet = "Za kasarnou 1";
    string cardholder = "TrustPay";
    string currency = "EUR";
    string email = "info@trustpay.eu";
    string reference = "123456789";
    int paymentType = 0;

    string secretKey = "123456";
    string sigData = string.Format(
        CultureInfo.InvariantCulture,
        "{0}/{1:0.00}/{2}/{3}/{4}/{5}/{6}/{7}/{8}/{9}/{10}", accountId, amount, currency, reference, paymentType, billingcity, billingcountry, billingpostcode, billingstreet, cardholder, email);
        string signature = GetSignature(secretKey, sigData);

    string url = string.Format(
        CultureInfo.InvariantCulture,
        "{0}?AccountId={1}&Amount={2:0.00}&Currency={3}&Reference={4}&PaymentType={5}&Signature={6}&BillingCity={7}&BillingCountry={8}&BillingPostcode={9}&BillingStreet={10}&CardHolder={11}&Email={12}",
        baseUrl, accountId, amount, currency, HttpUtility.UrlEncode(reference), paymentType, signature, billingcity, billingcountry, billingpostcode, billingstreet, cardholder, email);

    return url;
}


function getPurchaseUrl()
{
    $baseUrl = "https://amapi.trustpay.eu/mapi5/Card/PayPopup";
    $accountId = 4107111111;
    $amount = 1.5;
    $billingcity = "Bratislava";
    $billingcountry = "SK";
    $billingpostcode = "83103";
    $billingstreet = "Za kasarnou 1";
    $cardholder = "TrustPay";
    $currency = "EUR";
    $email = "info@trustpay.eu";
    $reference = "123456789";
    $paymentType = 0;
        
    $secretKey = "123456";
    $sigData = sprintf("%d/%s/%s/%s/%d/%s/%s/%s/%s/%s/%s", $accountId, number_format($amount, 2, '.', ''), $currency, $reference, $paymentType, $billingcity, $billingcountry, $billingpostcode, $billingstreet, $cardholder, $email);
    $signature = GetSignature($secretKey, $sigData);

    $url = sprintf(
        "%s?AccountId=%d&Amount=%s&Currency=%s&Reference=%s&PaymentType=%d&Signature=%s&BillingCity=%s&BillingCountry=%s&BillingPostcode=%s&BillingStreet=%s&CardHolder=%s&Email=%s", 
        $baseUrl, $accountId, number_format($amount, 2, '.', ''), $currency, urlencode($reference), $paymentType, $signature, $billingcity, $billingcountry, $billingpostcode, $billingstreet, $cardholder, $email);

    return $url;
}


import java.util.Locale;
import java.net.URLEncoder;

public String GetPurchaseUrl()
{
    String  baseUrl = "https://amapi.trustpay.eu/mapi5/Card/PayPopup";
    long accountId = 4107111111;
    double amount = 1.5d;
    String billingcity = "Bratislava";
    String billingcountry = "SK";
    String billingpostcode = "83103";
    String billingstreet = "Za kasarnou 1";
    String cardholder = "TrustPay";
    String currency = "EUR";
    String email = "info@trustpay.eu";
    String reference = "123456789";
    int paymentType = 0;

    try
    {
        String secretKey = "123456";
        String sigData = String.format(Locale.ROOT, "%d/%.2f/%s/%s/%d/%s/%s/%s/%s/%s/%s", accountId, amount, currency, reference, paymentType, billingcity, billingcountry, billingpostcode, billingstreet, cardholder, email);
        String signature = GetSignature(secretKey, sigData);

        String url = String.format(
            Locale.ROOT,"%s?AccountId=%d&Amount=%.2f&Currency=%s&Reference=%s&PaymentType=%d&Signature=%s&BillingCity=%s&BillingCountry=%s&BillingPostcode=%s&BillingStreet=%s&CardHolder=%s&Email=%s", 
            baseUrl, accountId, amount, currency, URLEncoder.encode(reference, "UTF-8"), paymentType, signature, billingcity, billingcountry, billingpostcode, billingstreet, cardholder, email);
        return url;
    }catch(Exception ex){}
}

Name	Description	Format	Required
AccountId	Merchant account or project ID (ID of account or project assigned by TrustPay)	Numeric(10)	Yes
Amount	Amount of the payment (exactly 2 decimal places)	Numeric(13,2) en-US format	Yes
BillingCity	The town, district or city of customer's billing address	Varchar(80)	Yes, from 1.10.2020
BillingCountry	The country of customer's billing address (in ISO-3166 format)	Char(2)	Yes, from 1.10.2020
BillingPostcode	The postal code or zip code of customer's billing address	Varchar(30)¹	Yes, from 1.10.2020
BillingStreet	The street name and number of customer's billing address	Varchar(100)	Yes, from 1.10.2020
CardHolder	The cardholder name (at least 3 characters)	Varchar(3-140)	Yes, from 1.10.2020
Currency	Currency of the payment	Char(3)	Yes
Email	Customer email	Varchar(254)	Yes, from 1.10.2020
PaymentType	Payment type For purchase must be set to 0	Numeric(1)	Yes
Reference	Reference (merchant’s payment identification)	Varchar(35)¹	Yes
Signature	Data signature calculated from concatenated values of AccountId, Amount, Currency, Reference, PaymentType, BillingCity, BillingCountry, BillingPostcode, BillingStreet, CardHolder and Email parameters, if these parameters are present. Slash character ('/') is used as separator. Email parameter in the signature is optional until 1. 10. 2020.	Char(64)	Yes
Url	Return URL (overrides any default Return URL, can be overridden further by Return URL, Cancel URL, Error URL)	Varchar(256)	No
ReturnUrl	Return URL (overrides default Success Return URL)	Varchar(256)	No
CancelUrl	Cancel URL (overrides default Cancel Return URL)	Varchar(256)	No
ErrorUrl	Error URL (overrides default Error Return URL)	Varchar(256)	No
NotificationUrl	Notification URL (overrides default Notification URL)	Varchar(256)	No
Localization	Default language for TrustPay site	Char(2)	No
Country	Default country of client	Char(2)	No
Description	Description (payment description text that will be displayed to the user)	Varchar(140)²	No
IsRedirect	Allows to make a redirect from merchant's e-shop	Bool³	No

¹ Only alphanumeric characters are allowed. Other characters may be lost or changed during payment process.
² Only alphanumeric and space characters are allowed. Other characters may not be displayed correctly.
³ Only values True and False are allowed.

Card on file v02

API endpoint:
Live - https://amapi.trustpay.eu/mapi5/Card/PayPopup
For testing purposes please use the same API endpoint with your testing credentials.

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.

Register

Card on file registration example:


public string GetRegisterUrl() 
{
    string baseUrl = "https://amapi.trustpay.eu/mapi5/Card/PayPopup";
    long accountId = 4107111111;
    decimal amount = 1.5M;
    string currency = "EUR";
    string reference = "123456789";
    int paymentType = 1;
        
    string secretKey = "123456";
    string sigData = string.Format(
        CultureInfo.InvariantCulture,
        "{0}/{1:0.00}/{2}/{3}/{4}", accountId, amount, currency, reference, paymentType);
    string signature = GetSignature(secretKey, sigData);

    string url = string.Format(
        CultureInfo.InvariantCulture,
        "{0}?AccountId={1}&Amount={2:0.00}&Currency={3}&Reference={4}&Signature={5}&PaymentType={6}",
        baseUrl, accountId, amount, currency, HttpUtility.UrlEncode(reference), signature, paymentType);

    return url;
}


function getRegisterUrl() 
{
    $baseUrl = "https://amapi.trustpay.eu/mapi5/Card/PayPopup";
    $accountId = 4107111111;
    $amount = 1.5;
    $currency = "EUR";
    $reference = "123456789";
    $paymentType = 1;
        
    $secretKey = "123456";
    $sigData = sprintf("%d/%s/%s/%s/%d", $accountId, number_format($amount, 2, '.', ''), $currency, $reference, $paymentType);
    $signature = GetSignature($secretKey, $sigData);

    $url = sprintf(
        "%s?AccountId=%d&Amount=%s&Currency=%s&Reference=%s&Signature=%s&PaymentType=%d", 
        $baseUrl, $accountId, number_format($amount, 2, '.', ''), $currency, urlencode($reference), $signature, $paymentType);

    return $url;
}


import java.util.Locale;
import java.net.URLEncoder;

public String GetRegisterUrl()
{
    String  baseUrl = "https://amapi.trustpay.eu/mapi5/Card/PayPopup";
    long accountId = 4107111111;
    double amount = 1.5d;
    String  currency = "EUR";
    String  reference = "123456789";
    int paymentType = 1;

    try
    {
        String secretKey = "123456";
        String sigData = String.format(Locale.ROOT, "%d/%.2f/%s/%s/%d", accountId, amount, currency, reference, paymentType);
        String signature = GetSignature(secretKey, sigData);

        String url = String.format(
            Locale.ROOT,"%s?AccountId=%d&Amount=%.2f&Currency=%s&Reference=%s&Signature=%s&PaymentType=%d", 
            baseUrl, accountId, amount, currency, URLEncoder.encode(reference, "UTF-8"), signature, paymentType);
        return url;
    }catch(Exception ex){}
}

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:

Name	Description	Format	Required
PaymentType	Payment type For card on file registration must be set to 1	Numeric(1)	Yes

CardID parameter will be present in notification after client completes a purchase. Value of this parameter needs to be used to make subsequent card on file purchases.

Card on file purchase

Card on file purchase example:


public string GetCardOnFilePurchaseUrl()
{
    string baseUrl = "https://amapi.trustpay.eu/mapi5/Card/PayPopup";
    long accountId = 4107111111;
    decimal amount = 1.5M;
    string currency = "EUR";
    string reference = "123456789";
    int paymentType = 2;
    string cardId = "8a8394855cfd3692015d0dc3f793355b";
        
    string secretKey = "123456";
    string sigData = string.Format(
        CultureInfo.InvariantCulture,
        "{0}/{1:0.00}/{2}/{3}/{4}/{5}/{6}", accountId, amount, currency, reference, paymentType, cardId);
    string signature = GetSignature(secretKey, sigData);

    string url = string.Format(
        CultureInfo.InvariantCulture,
        "{0}?AccountId={1}&Amount={2:0.00}&Currency={3}&Reference={4}&Signature={5}&PaymentType={6}&CardId={7}",
        baseUrl, accountId, amount, currency, HttpUtility.UrlEncode(reference), signature, paymentType, cardId);

    return url;
}


function getCardOnFilePurchaseUrl()
{
    $baseUrl = "https://amapi.trustpay.eu/mapi5/Card/PayPopup";
    $accountId = 4107111111;
    $amount = 1.5;
    $currency = "EUR";
    $reference = "123456789";
    $paymentType = 2;
    $cardId = "8a8394855cfd3692015d0dc3f793355b";
        
    $secretKey = "123456";
    $sigData = sprintf("%d/%s/%s/%s/%d/%s", $accountId, number_format($amount, 2, '.', ''), $currency, $reference, $paymentType, $cardId);
    $signature = GetSignature($secretKey, $sigData);

    $url = sprintf(
        "%s?AccountId=%d&Amount=%s&Currency=%s&Reference=%s&Signature=%s&PaymentType=%d&CardId=%s", 
        $baseUrl, $accountId, number_format($amount, 2, '.', ''), $currency, urlencode($reference), $signature, $paymentType, $cardId);

    return $url;
}


import java.util.Locale;
import java.net.URLEncoder;

public String GetCardOnFilePurchaseUrl()
{
    String  baseUrl = "https://amapi.trustpay.eu/mapi5/Card/PayPopup";
    long accountId = 4107111111;
    double amount = 1.5d;
    String  currency = "EUR";
    String  reference = "123456789";
    int paymentType = 2;
    String cardId = "8a8394855cfd3692015d0dc3f793355b";

    try
    {
        String secretKey = "123456";
        String sigData = String.format(Locale.ROOT, "%d/%.2f/%s/%s/%d/%s", accountId, amount, currency, reference, paymentType, cardId);
        String signature = GetSignature(secretKey, sigData);

        String url = String.format(
            Locale.ROOT,"%s?AccountId=%d&Amount=%.2f&Currency=%s&Reference=%s&Signature=%s&PaymentType=%d&CardId=%s", 
            baseUrl, accountId, amount, currency, URLEncoder.encode(reference, "UTF-8"), signature, paymentType, cardId);
        return url;
    }catch(Exception ex){}
}

Parameters for card on file purchase are the same as for standard payment, but these additional parameters have to be added to the request:

Name	Description	Format	Required
PaymentType	Payment type For card on file purchase must be set to 2	Numeric(1)	Yes
CardId	Card ID from notification	Varchar(64)	No
Signature	Data signature calculated from concatenated values of AccountId, Amount, Currency, Reference, PaymentType, BillingCity, BillingCountry, BillingPostcode, BillingStreet, CardHolder, Email and CardId parameters, if these parameters are present. Slash character ('/') is used as separator.	Char(64)	Yes

Card on file preauthorization

Card on file preauthorization example:


public string GetCardOnFilePreauthorizationUrl() 
{
    string baseUrl = "https://amapi.trustpay.eu/mapi5/Card/PayPopup";
    long accountId = 4107111111;
    decimal amount = 1.5M;
    string currency = "EUR";
    string reference = "123456789";
    int paymentType = 9;
    string cardId = "8a8394855cfd3692015d0dc3f793355b";

    string secretKey = "123456";
    string sigData = string.Format(
        CultureInfo.InvariantCulture,
        "{0}/{1:0.00}/{2}/{3}/{4}/{5}/{6}", accountId, amount, currency, reference, paymentType, cardId);
    string signature = GetSignature(secretKey, sigData);

    string url = string.Format(
        CultureInfo.InvariantCulture,
        "{0}?AccountId={1}&Amount={2:0.00}&Currency={3}&Reference={4}&Signature={5}&PaymentType={6}&CardId={7}",
        baseUrl, accountId, amount, currency, HttpUtility.UrlEncode(reference), signature, paymentType, cardId);

    return url;
}


function getCardOnFilePreauthorizationUrl()
{
    $baseUrl = "https://amapi.trustpay.eu/mapi5/Card/PayPopup";
    $accountId = 4107111111;
    $amount = 1.5;
    $currency = "EUR";
    $reference = "123456789";
    $paymentType = 9;
    $cardId = "8a8394855cfd3692015d0dc3f793355b";
        
    $secretKey = "123456";
    $sigData = sprintf("%d/%s/%s/%s/%d/%s", $accountId, number_format($amount, 2, '.', ''), $currency, $reference, $paymentType, $cardId);
    $signature = GetSignature($secretKey, $sigData);

    $url = sprintf(
        "%s?AccountId=%d&Amount=%s&Currency=%s&Reference=%s&Signature=%s&PaymentType=%d&CardId=%s", 
        $baseUrl, $accountId, number_format($amount, 2, '.', ''), $currency, urlencode($reference), $signature, $paymentType, $cardId);

    return $url;
}


import java.util.Locale;
import java.net.URLEncoder;

public String GetCardOnFilePreauthorizationUrl()
{
    String  baseUrl = "https://amapi.trustpay.eu/mapi5/Card/PayPopup";
    long accountId = 4107111111;
    double amount = 1.5d;
    String  currency = "EUR";
    String  reference = "123456789";
    int paymentType = 9;
    String cardId = "8a8394855cfd3692015d0dc3f793355b";

    try
    {
        String secretKey = "123456";
        String sigData = String.format(Locale.ROOT, "%d/%.2f/%s/%s/%d/%s", accountId, amount, currency, reference, paymentType, cardId);
        String signature = GetSignature(secretKey, sigData);

        String url = String.format(
            Locale.ROOT,"%s?AccountId=%d&Amount=%.2f&Currency=%s&Reference=%s&Signature=%s&PaymentType=%d&CardId=%s", 
            baseUrl, accountId, amount, currency, URLEncoder.encode(reference, "UTF-8"), signature, paymentType, cardId);
        return url;
    }catch(Exception ex){}
}

Parameters for card on file preauthorization are the same as for standard payment, but these additional parameters have to be added to the request:

Name	Description	Format	Required
PaymentType	Payment type For card on file preauthorization must be set to 9	Numeric(1)	Yes
CardId	Card ID from notification	Varchar(64)	Yes
Signature	Data signature calculated from concatenated values of AccountId, Amount, Currency, Reference, PaymentType, BillingCity, BillingCountry, BillingPostcode, BillingStreet, CardHolder, Email and CardId parameters, if these parameters are present. Slash character ('/') is used as separator.	Char(64)	Yes

Recurring v02

API endpoint:
Live - https://amapi.trustpay.eu/mapi5/Card/PayPopup
For testing purposes please use the same API endpoint with your testing credentials.

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
Maintain the payment schedule

Initial payment

Initial payment example:


public string GetInitialPaymentUrl()
{
    string baseUrl = "https://amapi.trustpay.eu/mapi5/Card/PayPopup";
    long accountId = 4107111111;
    decimal amount = 1.5M;
    string currency = "EUR";
    string reference = "123456789";
    int paymentType = 3;
        
    string secretKey = "123456";
    string sigData = string.Format(
        CultureInfo.InvariantCulture,
        "{0}/{1:0.00}/{2}/{3}/{4}", accountId, amount, currency, reference, paymentType);
    string signature = GetSignature(secretKey, sigData);

    string url = string.Format(
        CultureInfo.InvariantCulture,
        "{0}?AccountId={1}&Amount={2:0.00}&Currency={3}&Reference={4}&Signature={5}&PaymentType={6}",
        baseUrl, accountId, amount, currency, HttpUtility.UrlEncode(reference), signature, paymentType);

    return url;
}


function getInitialPaymentUrl()
{
    $baseUrl = "https://amapi.trustpay.eu/mapi5/Card/PayPopup";
    $accountId = 4107111111;
    $amount = 1.5;
    $currency = "EUR";
    $reference = "123456789";
    $paymentType = 3;
        
    $secretKey = "123456";
    $sigData = sprintf("%d/%s/%s/%s/%d", $accountId, number_format($amount, 2, '.', ''), $currency, $reference, $paymentType);
    $signature = GetSignature($secretKey, $sigData);

    $url = sprintf(
        "%s?AccountId=%d&Amount=%s&Currency=%s&Reference=%s&Signature=%s&PaymentType=%d", 
        $baseUrl, $accountId, number_format($amount, 2, '.', ''), $currency, urlencode($reference), $signature, $paymentType);
    
    return $url;
}


import java.util.Locale;
import java.net.URLEncoder;

public String GetInitialPaymentUrl()
{
    String  baseUrl = "https://amapi.trustpay.eu/mapi5/Card/PayPopup";
    long accountId = 4107111111;
    double amount = 1.5d;
    String  currency = "EUR";
    String  reference = "123456789";
    int paymentType = 3;

    try
    {
        String secretKey = "123456";
        String sigData = String.format(Locale.ROOT, "%d/%.2f/%s/%s/%d", accountId, amount, currency, reference, paymentType);
        String signature = GetSignature(secretKey, sigData);

        String url = String.format(
            Locale.ROOT,"%s?AccountId=%d&Amount=%.2f&Currency=%s&Reference=%s&Signature=%s&PaymentType=%d", 
            baseUrl, accountId, amount, currency, URLEncoder.encode(reference, "UTF-8"), signature, paymentType);
        return url;
    }catch(Exception ex){}
}

Parameters are the same as for standard Purchase, but there is one additional parameter required:

Name	Description	Format	Required
PaymentType	Payment type For initial recurring payment must be set to 3	Numeric(1)	Yes

Subsequent payment

Subsequent payment example:


string baseUrl = "https://amapi.trustpay.eu/mapi5/Card/PayPopup";
long accountId = 4107111111;
decimal amount = 1.5M;
string currency = "EUR";
string reference = "123456789";
int paymentType = 4;
int paymentRequestId = 555;
        
string secretKey = "123456";
string sigData = string.Format(
    CultureInfo.InvariantCulture,
    "{0}/{1:0.00}/{2}/{3}/{4}/{5}/{6}", accountId, amount, currency, reference, paymentType, paymentRequestId);
string signature = GetSignature(secretKey, sigData);

string url = string.Format(
    CultureInfo.InvariantCulture,
    "{0}?AccountId={1}&Amount={2:0.00}&Currency={3}&Reference={4}&Signature={5}&PaymentType={6}&PaymentRequestId={7}",
    baseUrl, accountId, amount, currency, HttpUtility.UrlEncode(reference), signature, paymentType, paymentRequestId);

Response.Redirect(url);


$baseUrl = "https://amapi.trustpay.eu/mapi5/Card/PayPopup";
$accountId = 4107111111;
$amount = 1.5;
$currency = "EUR";
$reference = "123456789";
$paymentType = 4;
$paymentRequestId = 555;
        
$secretKey = "123456";
$sigData = sprintf("%d/%s/%s/%s/%d/%d", $accountId, number_format($amount, 2, '.', ''), $currency, $reference, $paymentType, $paymentRequestId);
$signature = GetSignature($secretKey, $sigData);

$url = sprintf(
    "%s?AccountId=%d&Amount=%s&Currency=%s&Reference=%s&Signature=%s&PaymentType=%d&PaymentRequestId=%s", 
    $baseUrl, $accountId, number_format($amount, 2, '.', ''), $currency, urlencode($reference), $signature, $paymentType, $paymentRequestId);
header("Location: $url");
exit();


import java.util.Locale;
import java.net.URLEncoder;

String  baseUrl = "https://amapi.trustpay.eu/mapi5/Card/PayPopup";
long accountId = 4107111111;
double amount = 1.5d;
String  currency = "EUR";
String  reference = "123456789";
int paymentType = 4;
int paymentRequestId = 555;

try
{
    String secretKey = "123456";
    String sigData = String.format(Locale.ROOT, "%d/%.2f/%s/%s/%d/%d", accountId, amount, currency, reference, paymentType, paymentRequestId);
    String signature = GetSignature(secretKey, sigData);

    String url = String.format(
        Locale.ROOT,"%s?AccountId=%d&Amount=%.2f&Currency=%s&Reference=%s&Signature=%s&PaymentType=%d&PaymentRequestId=%s", 
        baseUrl, accountId, amount, currency, URLEncoder.encode(reference, "UTF-8"), signature, paymentType, paymentRequestId);
    response.sendRedirect(url);
}catch(Exception ex){}

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.

Parameters are the same as for standard Purchase, but these additional parameters have to be added to the request:

Name	Description	Format	Required
PaymentType	Payment type For subsequent recurring payments must be set to 4	Numeric(1)	Yes
PaymentRequestId	Payment request ID from notification	Numeric(10)	Yes
Signature	Data signature calculated from concatenated values of AccountId, Amount, Currency, Reference, PaymentType, BillingCity, BillingCountry, BillingPostcode, BillingStreet, CardHolder, Email and PaymentRequestId parameters, if these parameters are present. Slash character ('/') is used as separator.	Char(64)	Yes

Body of HTTP response will contain a result code (see example response to the right).

Example response:


{
    'ResultCode':3,
    'AcquirerResponseId':'000.000.000'
}

Recurring Initial Preauthorization v02

API endpoint:
Live - https://amapi.trustpay.eu/mapi5/Card/PayPopup
For testing purposes please use the same API endpoint with your testing credentials.

Recurring 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

Initial payment

Initial payment example:


public string GetInitialPaymentUrl()
{
    string baseUrl = "https://amapi.trustpay.eu/mapi5/Card/PayPopup";
    long accountId = 4107111111;
    decimal amount = 1.5M;
    string currency = "EUR";
    string reference = "123456789";
    int paymentType = 12;
        
    string secretKey = "123456";
    string sigData = string.Format(
        CultureInfo.InvariantCulture,
        "{0}/{1:0.00}/{2}/{3}/{4}", accountId, amount, currency, reference, paymentType);
    string signature = GetSignature(secretKey, sigData);

    string url = string.Format(
        CultureInfo.InvariantCulture,
        "{0}?AccountId={1}&Amount={2:0.00}&Currency={3}&Reference={4}&Signature={5}&PaymentType={6}",
        baseUrl, accountId, amount, currency, HttpUtility.UrlEncode(reference), signature, paymentType);

    return url;
}


function getInitialPaymentUrl()
{
    $baseUrl = "https://amapi.trustpay.eu/mapi5/Card/PayPopup";
    $accountId = 4107111111;
    $amount = 1.5;
    $currency = "EUR";
    $reference = "123456789";
    $paymentType = 12;
        
    $secretKey = "123456";
    $sigData = sprintf("%d/%s/%s/%s/%d", $accountId, number_format($amount, 2, '.', ''), $currency, $reference, $paymentType);
    $signature = GetSignature($secretKey, $sigData);

    $url = sprintf(
        "%s?AccountId=%d&Amount=%s&Currency=%s&Reference=%s&Signature=%s&PaymentType=%d", 
        $baseUrl, $accountId, number_format($amount, 2, '.', ''), $currency, urlencode($reference), $signature, $paymentType);
    
    return $url;
}


import java.util.Locale;
import java.net.URLEncoder;

public String GetInitialPaymentUrl()
{
    String  baseUrl = "https://amapi.trustpay.eu/mapi5/Card/PayPopup";
    long accountId = 4107111111;
    double amount = 1.5d;
    String  currency = "EUR";
    String  reference = "123456789";
    int paymentType = 12;

    try
    {
        String secretKey = "123456";
        String sigData = String.format(Locale.ROOT, "%d/%.2f/%s/%s/%d", accountId, amount, currency, reference, paymentType);
        String signature = GetSignature(secretKey, sigData);

        String url = String.format(
            Locale.ROOT,"%s?AccountId=%d&Amount=%.2f&Currency=%s&Reference=%s&Signature=%s&PaymentType=%d", 
            baseUrl, accountId, amount, currency, URLEncoder.encode(reference, "UTF-8"), signature, paymentType);
        return url;
    }catch(Exception ex){}
}

Parameters are the same as for standard Purchase, but there is one additional parameter required:

Name	Description	Format	Required
PaymentType	Payment type For initial recurring preauthorization payment must be set to 12	Numeric(2)	Yes

Preauthorization

API endpoint:
Live - https://amapi.trustpay.eu/mapi5/Card/PayPopup
For testing purposes please use the same API endpoint with your testing credentials.

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.

Setup

Preauthorization setup example:


public string GetPreauthorizationSetupUrl() 
{
    string baseUrl = "https://amapi.trustpay.eu/mapi5/Card/PayPopup";
    long accountId = 4107111111;
    decimal amount = 1.5M;
    string currency = "EUR";
    string reference = "123456789";
    int paymentType = 5;
        
    string secretKey = "123456";
    string sigData = string.Format(
        CultureInfo.InvariantCulture,
        "{0}/{1:0.00}/{2}/{3}/{4}", accountId, amount, currency, reference, paymentType);
    string signature = GetSignature(secretKey, sigData);

    string url = string.Format(
        CultureInfo.InvariantCulture,
        "{0}?AccountId={1}&Amount={2:0.00}&Currency={3}&Reference={4}&Signature={5}&PaymentType={6}",
        baseUrl, accountId, amount, currency, HttpUtility.UrlEncode(reference), signature, paymentType);

    return url;
}


function getPreauthorizationSetupUrl()
{
    $baseUrl = "https://amapi.trustpay.eu/mapi5/Card/PayPopup";
    $accountId = 4107111111;
    $amount = 1.5;
    $currency = "EUR";
    $reference = "123456789";
    $paymentType = 5;
        
    $secretKey = "123456";
    $sigData = sprintf("%d/%s/%s/%s/%d", $accountId, number_format($amount, 2, '.', ''), $currency, $reference, $paymentType);
    $signature = GetSignature($secretKey, $sigData);

    $url = sprintf(
        "%s?AccountId=%d&Amount=%s&Currency=%s&Reference=%s&Signature=%s&PaymentType=%d", 
        $baseUrl, $accountId, number_format($amount, 2, '.', ''), $currency, urlencode($reference), $signature, $paymentType);

    return $url;
}


import java.util.Locale;
import java.net.URLEncoder;

public String GetPreauthorizationSetupUrl()
{
    String  baseUrl = "https://amapi.trustpay.eu/mapi5/Card/PayPopup";
    long accountId = 4107111111;
    double amount = 1.5d;
    String  currency = "EUR";
    String  reference = "123456789";
    int paymentType = 5;

    try
    {
        String secretKey = "123456";
        String sigData = String.format(Locale.ROOT, "%d/%.2f/%s/%s/%d", accountId, amount, currency, reference, paymentType);
        String signature = GetSignature(secretKey, sigData);

        String url = String.format(
            Locale.ROOT,"%s?AccountId=%d&Amount=%.2f&Currency=%s&Reference=%s&Signature=%s&PaymentType=%d", 
            baseUrl, accountId, amount, currency, URLEncoder.encode(reference, "UTF-8"), signature, paymentType);
        return url;
    }catch(Exception ex){}
}

Parameters are the same as for standard Purchase, but there is one additional parameter required:

Name	Description	Format	Required
PaymentType	Payment type For preauthorization of standard purchase must be set to 5	Numeric(1)	Yes

You will receive result code 5 – Authorization only in the notification, if an authorization was successful.

Capture

Capture example:


string baseUrl = "https://amapi.trustpay.eu/mapi5/Card/PayPopup";
long accountId = 4107111111;
decimal amount = 1.5M;
string currency = "EUR";
string reference = "123456789";
int paymentType = 6;
int paymentRequestId = 555;
        
string secretKey = "123456";
string sigData = string.Format(
    CultureInfo.InvariantCulture,
    "{0}/{1:0.00}/{2}/{3}/{4}/{5}/{6}", accountId, amount, currency, reference, paymentType, paymentRequestId);
string signature = GetSignature(secretKey, sigData);

string url = string.Format(
    CultureInfo.InvariantCulture,
    "{0}?AccountId={1}&Amount={2:0.00}&Currency={3}&Reference={4}&Signature={5}&PaymentType={6}&PaymentRequestId={7}",
    baseUrl, accountId, amount, currency, HttpUtility.UrlEncode(reference), signature, paymentType, paymentRequestId);

Response.Redirect(url);


$baseUrl = "https://amapi.trustpay.eu/mapi5/Card/PayPopup";
$accountId = 4107111111;
$amount = 1.5;
$currency = "EUR";
$reference = "123456789";
$paymentType = 6;
$paymentRequestId = 555;
        
$secretKey = "123456";
$sigData = sprintf("%d/%s/%s/%s/%d/%d", $accountId, number_format($amount, 2, '.', ''), $currency, $reference, $paymentType, $paymentRequestId);
$signature = GetSignature($secretKey, $sigData);

$url = sprintf(
    "%s?AccountId=%d&Amount=%s&Currency=%s&Reference=%s&Signature=%s&PaymentType=%d&PaymentRequestId=%s", 
    $baseUrl, $accountId, number_format($amount, 2, '.', ''), $currency, urlencode($reference), $signature, $paymentType, $paymentRequestId);
header("Location: $url");
exit();


import java.util.Locale;
import java.net.URLEncoder;

String  baseUrl = "https://amapi.trustpay.eu/mapi5/Card/PayPopup";
long accountId = 4107111111;
double amount = 1.5d;
String  currency = "EUR";
String  reference = "123456789";
int paymentType = 6;
int paymentRequestId = 555;

try
{
    String secretKey = "123456";
    String sigData = String.format(Locale.ROOT, "%d/%.2f/%s/%s/%d/%d", accountId, amount, currency, reference, paymentType, paymentRequestId);
    String signature = GetSignature(secretKey, sigData);

    String url = String.format(
        Locale.ROOT,"%s?AccountId=%d&Amount=%.2f&Currency=%s&Reference=%s&Signature=%s&PaymentType=%d&PaymentRequestId=%s", 
        baseUrl, accountId, amount, currency, URLEncoder.encode(reference, "UTF-8"), signature, paymentType, paymentRequestId);
    response.sendRedirect(url);
}catch(Exception ex){}

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.

Parameters are the same as for standard Purchase, but these additional parameters have to be added to the request:

Name	Description	Format	Required
PaymentType	Payment type For capture must be set to 6	Numeric(1)	Yes
PaymentRequestId	Payment request ID from notification	Numeric(10)	Yes
Signature	Data signature calculated from concatenated values of AccountId, Amount, Currency, Reference, PaymentType and PaymentRequestId parameters, if these parameters are present. Slash character ('/') is used as separator.	Char(64)	Yes

Body of HTTP response will contain a result code (see example response to the right).

Example response:


{
    'ResultCode':3,
    'AcquirerResponseId':'000.000.000'
}

If capture was successful, a new notification with result code 3 - Authorized will be sent.

Refund v02

API endpoint:
Live - https://amapi.trustpay.eu/mapi5/Card/PayPopup
For testing purposes please use the same API endpoint with your testing credentials.

Refund example:


string baseUrl = "https://amapi.trustpay.eu/mapi5/Card/PayPopup";
long accountId = 4107111111;
decimal amount = 1.5M;
string currency = "EUR";
string reference = "123456789";
int paymentType = 8;
int paymentRequestId = 555;
        
string secretKey = "123456";
string sigData = string.Format(
    CultureInfo.InvariantCulture,
    "{0}/{1:0.00}/{2}/{3}/{4}/{5}/{6}", accountId, amount, currency, reference, paymentType, paymentRequestId);
string signature = GetSignature(secretKey, sigData);

string url = string.Format(
    CultureInfo.InvariantCulture,
    "{0}?AccountId={1}&Amount={2:0.00}&Currency={3}&Reference={4}&Signature={5}&PaymentType={6}&PaymentRequestId={7}",
    baseUrl, accountId, amount, currency, HttpUtility.UrlEncode(reference), signature, paymentType, paymentRequestId);

Response.Redirect(url);


$baseUrl = "https://amapi.trustpay.eu/mapi5/Card/PayPopup";
$accountId = 4107111111;
$amount = 1.5;
$currency = "EUR";
$reference = "123456789";
$paymentType = 8;
$paymentRequestId = 555;
        
$secretKey = "123456";
$sigData = sprintf("%d/%s/%s/%s/%d/%d", $accountId, number_format($amount, 2, '.', ''), $currency, $reference, $paymentType, $paymentRequestId);
$signature = GetSignature($secretKey, $sigData);

$url = sprintf(
    "%s?AccountId=%d&Amount=%s&Currency=%s&Reference=%s&Signature=%s&PaymentType=%d&PaymentRequestId=%s", 
    $baseUrl, $accountId, number_format($amount, 2, '.', ''), $currency, urlencode($reference), $signature, $paymentType, $paymentRequestId);
header("Location: $url");
exit();


import java.util.Locale;
import java.net.URLEncoder;

String  baseUrl = "https://amapi.trustpay.eu/mapi5/Card/PayPopup";
long accountId = 4107111111;
double amount = 1.5d;
String  currency = "EUR";
String  reference = "123456789";
int paymentType = 8;
int paymentRequestId = 555;

try
{
    String secretKey = "123456";
    String sigData = String.format(Locale.ROOT, "%d/%.2f/%s/%s/%d/%d", accountId, amount, currency, reference, paymentType, paymentRequestId);
    String signature = GetSignature(secretKey, sigData);

    String url = String.format(
        Locale.ROOT,"%s?AccountId=%d&Amount=%.2f&Currency=%s&Reference=%s&Signature=%s&PaymentType=%d&PaymentRequestId=%s", 
        baseUrl, accountId, amount, currency, URLEncoder.encode(reference, "UTF-8"), signature, paymentType, paymentRequestId);
    response.sendRedirect(url);
}catch(Exception ex){}

This function allows refunding or cancelling a transaction that was authorized or preauthorized.

Parameters are the same as for standard Purchase, but these additional parameters have to be added to the request:

Name	Description	Format	Required
PaymentType	Payment type For refund must be set to 8	Numeric(1)	Yes
PaymentRequestId	Payment request ID from notification	Numeric(10)	Yes
Signature	Data signature calculated from concatenated values of AccountId, Amount, Currency, Reference, PaymentType and PaymentRequestId parameters, if these parameters are present. Slash character ('/') is used as separator.	Char(64)	Yes

Body of HTTP response will contain a result code (see example response to the right).

Example response:


{
    'ResultCode':0,
    'AcquirerResponseId':'000.000.000'
}

Payment result v02

After paying, the customer is redirected to one of the return URLs provided by the Merchant:

Success Return URL
Customer is redirected here in case of an announced, authorized or a successful payment with Result=0, or in case of a timed out pending payment with Result=1
Cancel Return URL
Customer is redirected here in case he decides to cancel the payment with Result=1005.
Error Return URL
Customer is redirected here in case of a failed or refused payment with Result >= 1000 and Result!=1005.

The following parameters are always being sent with the redirects:

Payment result example:
https://example.handler.com/result.php?Reference=1234567890&ResultCode=0&AcquirerResponseId=000.100.110&PaymentRequestId=4337417657

Name	Description	Format
Reference	Reference (merchant’s payment identification)	Varchar(35)
ResultCode	Result code	Numeric(4)
AcquirerResponseId	Card acquirer result code	Varchar(128)
PaymentRequestId	Payment request ID (sent when available, can be used for inquiries regarding failed payments)	Numeric(10)

Signature

Creating a secret key

For live environment, a different secret key is automatically generated for every merchant account. You can view this secret key in your TrustPay Merchant Portal in Technical settings. 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 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 signature is created using secret key and message data. Message data is obtained by concatenating request parameters and details are explained in documentation for specific operations. 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 a signature v02

Here you can verify your implementation of TrustPay signature. Just enter your parameters and the signature you calculated and our tool will check whether the signature is valid or not.

Environment:

Signature:

Account:

Amount:

Currency:

Reference:

PaymentType:

BillingCity:

BillingCountry:

BillingPostcode:

BillingStreet:

CardHolder:

Email:

PaymentRequestId:

CardId:

Payment notifications

Wire notification v02

For each announced, authorized, or successfully finished payment on the merchant’s account, TrustPay sends the result of the payment to the Merchant in notification URL and/or e-mail using the following parameters:

Payment URL notification example:
https://example.handler.com/result.php?AccountId=4107111111&Type=CRDT&Amount=6.00&Currency=EUR&ResultCode=0&PaymentId=177561&Reference=1234567890&CounterAccount=SK3399520000002107425307&CounterAccountName=TestAccount&Signature=C4FFA5F7B57A0F5E6DD105197C8B7D7B9214509F3618CDC0F527C9B4E57F0334
Payment E-mail notification example:
{
    "AccountId":4107111111,
    "Type":"CRDT",
    "Amount":6.00,
    "Currency":"EUR",
    "Reference":"1234567890",
    "ResultCode":0,
    "PaymentId":"177561",
    "Signature":"C4FFA5F7B57A0F5E6DD105197C8B7D7B9214509F3618CDC0F527C9B4E57F0334",
    "CounterAccount":"SK3399520000002107425307",
    "CounterAccountName":"TestAccount"
}

Name	Description	Format
AccountId	Merchant account or project ID (ID of account or project assigned by TrustPay)	Numeric(10)
Type	Type of transaction (CRDT or DBIT)	Char(4)
Amount	Amount of the payment (exactly 2 decimal places)	Numeric(13,2), en-US format
Currency	Currency of the payment (same as currency of merchant account)	Char(3)
Reference¹	Reference (merchant’s payment identification)	Varchar(35)
ResultCode	Result code	Numeric(4)
PaymentId	Payment ID	Numeric(10)
OrderId¹	TrustPay Order ID (ID of payment order)	Numeric(10)
CounterAccount¹	Counter account	Varchar(34)
CounterAccountName¹	Counter account name	Varchar(140)
Signature	Data signature calculated from concatenated values of AccountId, Amount, Currency, Type, ResultCode, CounterAccount, CounterAccountName, OrderId, PaymentId, Reference and RefuseReason parameters, if these parameters are present. Slash character ('/') is used as separator.	Char(64)

¹ These parameters might not be present depending on the request and/or payment gateway used.

Notifications can be sent to the Merchant using the following channels:

HTTP request
All parameters are sent as a HTTP query string to Notification URL. Script at this URL should return HTTP status 200 OK on success or 500 Internal server error otherwise.
TrustPay will repeat notification every 10 minutes until HTTP status 200 OK is received within 75 hours (450 attempts).
E-mail
An e-mail in text/plain format is sent to the e-mail address configured by the merchant in TrustPay Merchant Portal in technical settings.

Card notification v02

Payment URL notification example:
https://example.handler.com/result.php?AccountId=4107111111&Type=CRDT&Amount=6.00&Currency=EUR&Reference=1234567890&ResultCode=0&PaymentRequestId=177561&Signature=C4FFA5F7B57A0F5E6DD105197C8B7D7B9214509F3618CDC0F527C9B4E57F0334&CardId=8a8294495c589aa3015c63bd6d237e46&CardMask=0162&CardExpiration=1020&AuthNumber=198159
Payment E-mail notification example:
{
    "AccountId":"4107111111",
    "Type":"CRDT",
    "Amount":"6.00",
    "Currency":"EUR",
    "PaymentRequestId":"177561",
    "CardId":"8a8294495c589aa3015c63bd6d237e46",
    "CardMask":"0162",
    "CardExpiration":"1020",
    "AuthNumber":"198159",
    "Signature":"51541600BDED4230304D5E20DB96730181E7C34886DF00D82650C6F0C28424A2",
    "ResultCode":"3",
    "Reference":"1234567890"
}

Card URL and e-mail notifications contain following parameters:

Name	Description	Format
AccountId	Merchant account or project ID (ID of account or project assigned by TrustPay)	Numeric(10)
Type	Type of transaction (CRDT or DBIT)	Char(4)
Amount	Amount of the payment (exactly 2 decimal places)	Numeric(13,2), en-US format
Currency	Currency of the payment (same as currency of merchant account)	Char(3)
Reference	Reference (merchant’s payment identification)	Varchar(35)
ResultCode	Result code	Numeric(4)
PaymentRequestId	Payment request ID (sent when available, can be used for inquiries regarding failed payments)	Numeric(10)
Signature	Data signature calculated from concatenated values of AccountId, Amount, Currency, Reference, Type, ResultCode, PaymentRequestId, CardId, CardMask, CardExpiration and AuthNumber parameters, if these parameters are present. Slash character ('/') is used as separator.	Char(64)
CardId¹	Card ID. This can be used to make card-on-file payments	Varchar(64)
CardMask¹	Masked card number or last 4 digits of the card	Varchar(19)
CardExpiration¹	Card expiration in MMYY format	Number(4)
AuthNumber¹	Authorization number	Varchar(7)

¹ These parameters might not be present depending on the request.

Code lists

Supported currencies

The list of currencies (according to ISO 4217) supported by TrustPay for instant bank transfers.

Code	ID	Name
CZK	203	Czech koruna
EUR	978	Euro

Supported countries

The list of customer countries (according to ISO 3166-1 alpha-2) supported by TrustPay for instant bank transfers.

Code	Country
CZ	Czech Republic
SK	Slovak Republic

Supported languages

The list of languages (according to ISO 639-1) supported by TrustPay.

Code	Language	Supported for wire payments	Supported for card payments
en	English	Yes	Yes
sk	Slovak	Yes	Yes
cs	Czech	Yes	Yes
bg	Bulgarian	No	Yes
hr	Croatian	No	Yes
da	Danish	No	Yes
nl	Dutch	No	Yes
et	Estonian	No	Yes
fi	Finnish	No	Yes
fr	French	No	Yes
de	German	No	Yes
el	Greek	No	Yes
hu	Hungarian	No	Yes
it	Italian	No	Yes
ja	Japanese	No	Yes
lv	Latvian	No	Yes
lt	Lithuanian	No	Yes
nb	Norwegian Bokmål	No	Yes
pl	Polish	No	Yes
pt	Portuguese	No	Yes
ro	Romanian	No	Yes
ru	Russian	No	Yes
sl	Slovene	No	Yes
es	Spanish	No	Yes
sv	Swedish	No	Yes
uk	Ukrainian	No	Yes

Result codes

Code	Name	Description	Returned via
0	Success	Payment was successfully processed. When received in notification, funds have been credited to the merchant account - merchant can provide goods or services without delay	client redirects, merchant notifications
1	Pending	Payment may have been payed, but the real result is not known yet (for example client made offline payment or TrustPay still waits for notification from bank).	client redirects
2	Announced	TrustPay has been notified that the client placed a payment order or has made payment, but further confirmation from 3rd party is needed. Another notification (with result code 0 - success) will be sent when TrustPay receives and processes payment from 3rd party. Funds have not been credited to the merchant account and there is no guarantee they will be.	merchant notifications
3	Authorized	Payment was successfully authorized. Another notification (with result code 0 - success) will be sent when TrustPay receives and processes payment from 3rd party. For card payments, no further notification will be sent and funds will be credited to the merchant's account in a bulk payment on the next settlement day. Merchant can provide goods or services without delay.	merchant notifications
4	Processing	TrustPay has received the payment, but it must be internally processed before it is settled on the merchant's account. When the payment is successfully processed, another notification (with the result code 0 – success) will be sent. Funds will be credited to merchant's account at a later date.	merchant notifications
5	AuthorizedOnly	Card payment was successfully authorized, but not captured. Subsequent MAPI calls are required to capture the payment.	client redirects, merchant notifications
1001	Invalid request	Some of the parameters in request are missing or have invalid format.	client redirects
1002	Unknown account	Account with specified ID was not found. Please check that you are using correct AID for live environment.	client redirects
1003	Merchant account disabled	Merchant account has been disabled.	client redirects
1004	Invalid signature	Verification of request signature has failed.	client redirects
1005	User cancel	Customer has cancelled the payment.	client redirects
1006	Invalid authentication	Request was not properly authenticated.	client redirects
1007	Insufficient balance	Requested transaction amount is greater than disposable balance.	client redirects
1008	Service not allowed	Service cannot be used or permission to use given service has not been granted. If you receive this code, please contact TrustPay for more information.	client redirects
1009	Processing ID used	Specified processing ID was already used. Please generate a new PID using Setup payment service call.	client redirects
1010	Transaction not found	Transaction with specified ID was not found.	client redirects, API responses
1011	Unsupported transaction	The requested action is not supported for the transaction.	client redirects, API responses
1014	Rejected transaction	Transaction was rejected by issuer or gateway.	client redirects
1015	Declined by risk	Transaction was rejected by risk department.	client redirects, API responses
1100	General Error	Internal error has occurred. Please contact TrustPay to resolve this issue.	client redirects, API responses
1101	Unsupported currency conversion	Currency conversion for requested currencies is not supported.	client redirects

Card acquirer result code

Code	Description
100.100.303	Rejected - card expired
100.100.600	Rejected - invalid CVV
100.100.601	Rejected - invalid CVV
100.100.700	Rejected - invalid card number
100.380.401	Rejected - failed 3DS authentication
100.380.501	Rejected - failed 3DS authentication
800.100.151	Rejected - invalid card number
800.100.153	Rejected - invalid CVV
800.100.155	Rejected - insufficient funds
800.100.157	Rejected - invalid expiry date
800.100.161	Rejected - too many invalid tries
800.100.162	Rejected - card limit exceeded
800.100.163	Rejected - card limit exceeded
800.120.101	Rejected - card limit exceeded
800.120.200	Rejected - card limit exceeded
800.120.201	Rejected - card limit exceeded

Payment type

Code	Description
0	Purchase
1	Card on file - Register
2	Card on file - Purchase
3	Recurring - Initial payment
4	Recurring - Subsequent payment
5	Preauthorization
6	Capture
9	Card on file - Preauthorization
8	Refund

API update 2020 - SCA

What is SCA?

Strong Customer Authentication (SCA), as part of the Payment Services Directive (PSD2) in the European Economic Area, requires changes to customer authentication of online payments. In order to increase the security of online payments, a new version of customer verification will be required.

What SCA means for you?

TrustPay amended its payments gateway to meet the new regulatory requirements of SCA in a way that will require as few changes from the merchant´s side as possible. You will be required to send us some additional information about your customer in the payment requests for card payments and the rest will be done by TrustPay.

What changes do you have to make in your integration?

You have to send us the following additional fields in your payment requests for card payments:

Name	Description	Format
CardHolder	The cardholder name (at least 3 characters)	Varchar(100)
BillingStreet	The street name and number of customer's billing address	Varchar(100)
BillingCity	The town, district or city of customer's billing address	Varchar(80)
BillingPostcode	The postal code or zip code of customer's billing address	Varchar(30)¹
BillingCountry	The country of customer's billing address	Char(2)
Email	Customer email	Varchar(254)

¹ Only alphanumeric characters are allowed. Other characters may be lost or changed during payment process.

For more information please check this section of our integration manual: Cards

What is the deadline to update the integration?

You should ensure that your systems will comply with the above-mentioned changes by October 1st,2020. If you fail to update your integration, your transactions missing the new mandatory elements may be rejected by the issuing banks.