Create Payment

To create a payment using the PHP SDK, call the TatraPayPlusAPIApi->initiatePayment() method.

Click to see example for all payment methods

<?php
use Tatrapayplus\TatrapayplusApiClient\Api\TatraPayPlusAPIApi;

$tatrapayplus_api = new TatraPayPlusAPIApi(
    "your-client-id",
    "your-client-secret",
);

$address = new Tatrapayplus\TatrapayplusApiClient\Model\Address([
    "street_name" => "TestStreet",
    "building_number" => "12",
    "town_name" => "Town",
    "post_code" => "97405",
    "country" => "SK",
]);
$initiate_payment_request = new Tatrapayplus\TatrapayplusApiClient\Model\InitiatePaymentRequest([
    "base_payment" => new Tatrapayplus\TatrapayplusApiClient\Model\BasePayment([
        "instructed_amount" => new Tatrapayplus\TatrapayplusApiClient\Model\Amount([
            "amount_value" => 10.0,
            "currency" => "EUR",
        ]),
        "end_to_end" => new Tatrapayplus\TatrapayplusApiClient\Model\E2e([
            "variable_symbol" => "1",
            "specific_symbol" => "2",
            "constant_symbol" => "3",
        ]),
    ]),
    "bank_transfer" => new Tatrapayplus\TatrapayplusApiClient\Model\BankTransfer(),
    "user_data" => new Tatrapayplus\TatrapayplusApiClient\Model\UserData([
        "first_name" => "Janko",
        "last_name" => "Hrasko",
        "email" => "janko.hrasko@example.com",
    ]),
    "card_detail" => new Tatrapayplus\TatrapayplusApiClient\Model\CardDetail([
        "card_holder" => "Janko Hrasko",
        "billing_address" => $address,
        "shipping_address" => $address,
    ]),
    "pay_later" => new Tatrapayplus\TatrapayplusApiClient\Model\PayLater([
        "order" => new Tatrapayplus\TatrapayplusApiClient\Model\Order([
            "order_no" => "ORDER123456",
            "order_items" => [
                new Tatrapayplus\TatrapayplusApiClient\Model\OrderItem([
                    "quantity" => 1.0,
                    "total_item_price" => 10.0,
                    "item_detail" => new Tatrapayplus\TatrapayplusApiClient\Model\ItemDetail([
                        "item_detail_en" => new Tatrapayplus\TatrapayplusApiClient\Model\ItemDetailLangUnit([
                            "item_name" => "Product 1",
                        ]),
                        "item_detail_sk" => new Tatrapayplus\TatrapayplusApiClient\Model\ItemDetailLangUnit([
                            "item_name" => "Produkt 1",
                        ]),
                    ]),
                ]),
            ],
        ]),
    ]),
]);

$response = $tatrapayplus_api->initiatePayment(
    "redirect uri",
    $initiate_payment_request,
);
$response["object"]->getPaymentId(); // newly created payment ID

Common Data

Tatrapay Plus supports multiple payment methods. Depending on the selected method, you can include additional optional fields. However, some data is mandatory for all payment types:

$base_payment = new BasePayment([
    "instructed_amount" => new Amount([
        "amount_value" => 10.0,
        "currency" => "EUR",
    ]),
    "end_to_end" => new E2e([
        "variable_symbol" => "ORDER123456",
    ]),
]);

warning

Most common issue is that value in instructed_amount.amount_value field is not rounded properly and API will reject such a data. Please round your data to 2 decimals places.

Modify language and preferred method

By default, tatrapay+ gateway will show all available payment methods and payment gateway is shown in default Slovak language. If you want to change this behaviour you can pass language and preferred_method param to create_payment.

If preferred_method is available user will be directly navigated to this method.

Show gateway in English with bank transfer method

$response = $tatrapayplus_api->initiatePayment(
    "http://localhost",
    $initiate_payment_request,
    preferred_method: "BANK_TRANSFER",
    accept_language: "en"
);

Redirect URI

Redirect URI is used as return address after customer finishes payment. This URI is necessary and is used to process result of the payment.

If your application serves multiple locales with distinct URIs for example:

• https://example.com for one locale
• https://example.com/de/ for German users

you must register both URIs in the developer portal. Then, when making a create_payment request, be sure to include the redirect URI that matches the user's locale.

warning

This URI must exactly match the URI defined in the Developer Portal

Specific payment method data

Bank transfer and QR pay

For this payment method you need to define attribute bank_transfer. It can be empty or contain additional information. If you omit this attribute, bank transfer wouldn't be shown.

$bank_transfer = new BankTransfer("Additional information");

Card pay

This payment method requires card_detail.card_holder, user_data.first_name and user_data.last_name. One of user_data.email or user_data.phone is required, notifications to customers will be sent based on these.

tip

The SDK automatically strips diacritical marks from characters in the card_detail.card_holder field, so you don't need to handle this conversion yourself.

$userData = new UserData([
    "first_name" => "Janko",
    "last_name" => "Hrasko",
    "email" => "janko.hrasko@example.com",
]);

$cardDetail = new CardDetail([
    "card_holder" => "Janko Hrasko",
]);

PayLater (Na splátky^TB)

This payment method requires information about items that were bought by customer. This structure is more complex and description of all fields can be found in API reference.

warning

The API will reject requests where instructed_amount.amount_value doesn't match the sum of all total_item_price values.

$payLater = new PayLater([
    "order" => new Order([
        "order_no" => "ORDER123456",
        "order_items" => [
            new OrderItem([
                "quantity" => 1.0,
                "total_item_price" => 10.0,
                "item_detail" => new ItemDetail([
                    "item_detail_en" => new ItemDetailLangUnit([
                        "item_name" => "Product 1",
                    ]),
                    "item_detail_sk" => new ItemDetailLangUnit([
                        "item_name" => "Produkt 1",
                    ]),
                ]),
            ]),
        ],
    ]),
]);

Response

After you create request to initiate payment, you will receive InitiatePaymentResponse with following data:

new InitiatePaymentResponse([
    "payment_id" => 'd7ec77c6-39d8-4011-a462-1a0f1b23f65f',
    "tatra_pay_plus_url" => 'https://api.tatrabanka.sk/tatrapayplus/sandbox/v1/auth?paymentId=d7ec77c6-39d8-4011-a462-1a0f1b23f65f&client_id=l7ba7ffa0bf66b49b88d17dfe144955f54&hmac=7043761cb4cff51d1d084f90cd25d370b89515a1c43c39e6ea459dd504059834',
    "available_payment_methods" => [
        new AvailablePaymentMethod([
            "payment_method" => PaymentMethod::BANK_TRANSFER,
            "is_available" => true,
        ]),
        new AvailablePaymentMethod([
            "payment_method" => PaymentMethod::CARD_PAY,
            "is_available" => true,
        ]),
    ]
]);

Example usage:

$response = $tatrapayplus_api->initiatePayment(
    "redirect uri",
    $initiate_payment_request, // instance of InitiatePaymentRequest
);
$response_obj = $response['object'];

$payment_id = $response_obj->getPaymentId();
$tatra_pay_plus_url = $response_obj->getTatraPayPlusUrl();

You should save $payment_id to your order associated with this payment. You will later need it to retrieve status of payment. Then you have two options of displaying payment gateway:

1. Simply redirect user to gateway, field $tatra_pay_plus_url.
2. Show payme