NAV
.NET (C#) PHP JAVA curl HTTP form
English

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.

Payment process

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.

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)1 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 Bool2 No

1 The reference can not contain characters < and >
2 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:

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>

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.

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)1 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)1 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)2 No
IsRedirect Allows to make a redirect from merchant's e-shop Bool3 No

1 Only alphanumeric characters are allowed. Other characters may be lost or changed during payment process.
2 Only alphanumeric and space characters are allowed. Other characters may not be displayed correctly.
3 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:

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:

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

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'
}

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:

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.






























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)
Reference1 Reference (merchant’s payment identification) Varchar(35)
ResultCode Result code Numeric(4)
PaymentId Payment ID Numeric(10)
OrderId1 TrustPay Order ID (ID of payment order) Numeric(10)
CounterAccount1 Counter account Varchar(34)
CounterAccountName1 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)

1 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:

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)
CardId1 Card ID. This can be used to make card-on-file payments Varchar(64)
CardMask1 Masked card number or last 4 digits of the card Varchar(19)
CardExpiration1 Card expiration in MMYY format Number(4)
AuthNumber1 Authorization number Varchar(7)

1 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
enEnglishYesYes
skSlovakYesYes
csCzechYesYes
bgBulgarianNoYes
hrCroatianNoYes
daDanishNoYes
nlDutchNoYes
etEstonianNoYes
fiFinnishNoYes
frFrenchNoYes
deGermanNoYes
elGreekNoYes
huHungarianNoYes
itItalianNoYes
jaJapaneseNoYes
lvLatvianNoYes
ltLithuanianNoYes
nbNorwegian BokmålNoYes
plPolishNoYes
ptPortugueseNoYes
roRomanianNoYes
ruRussianNoYes
slSloveneNoYes
esSpanishNoYes
svSwedishNoYes
ukUkrainianNoYes

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)1
BillingCountry The country of customer's billing address Char(2)
Email Customer email Varchar(254)

1 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.

This site uses cookies to provide you with a better browsing experience. By browsing TrustPay websites, you agree with using cookies. Find out more on how we use cookies here.