TatraPayPlus SDK and API Documentation

website·Indexed 39 days ago

https://sdk.tatrabanka.sk

Developer documentation for the TatraPayPlus payment gateway, including API references for payment intents, direct transactions, and appearance customization. Provides SDK libraries for Node.js, Python, and PHP to handle payment processing, chargebacks, pre-authorizations, and loan precalculations.

Tokens: 17.9K
Snippets: 89
Records: 105
Agent score: 49%

What's inside TatraPayPlus

Extract error details from ApiException

When a Tatrapayplus\TatrapayplusApiClient\ApiException is caught, you can use the following methods to retrieve diagnostic information about the failed request and the server's response:

use Tatrapayplus\TatrapayplusApiClient\ApiException;

try {
    $tatrapayplus_api->getAvailableMethods();
} catch (ApiException $e) {
    $body = $e->getResponseBody();      // HTTP body of the server response (JSON or string)
    $headers = $e->getResponseHeaders(); // HTTP response headers
    $request = $e->getRequestBody();    // The HTTP request body that caused the exception
    $errorObj = $e->getResponseObject(); // Deserialized response object of type \Tatrapayplus\TatrapayplusApiClient\Model\Model400ErrorBody
}

Retrieve available payment methods using the PHP SDK
v2
In the TatraPayPlus payment gateway, users select their preferred payment option within the gateway itself rather than in the e-shop. To inform customers about available payment options before they enter the gateway, use the getAvailableMethods helper. This allows you to determine which payment methods to display based on the transaction's currency, total amount, and the customer's country.
```
<?php
use Tatrapayplus\TatrapayplusApiClient\Api\TatraPayPlusAPIApi;

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

$available_methods = $tatrapayplus_api->getAvailableMethods(
    total_amount: 100,
    currency: "EUR",
    country: "SK"
);
```
https://sdk.tatrabanka.sk/docs/libraries/php/v2/available_methods

Update the payment gateway logo

Use the set_appearance_logo method to upload a custom logo for the payment gateway. The logo must be provided as a base64 encoded image string within an AppearanceLogoRequest object. Note that appearance changes are only applicable in PRODUCTION mode and only affect new payments.

from tatrapayplus.client import TBPlusSDK
from tatrapayplus.models import *

client = TBPlusSDK(
    "your-client-id",
    "your-client-secret"
)

logo_data = AppearanceLogoRequest(
    logo_image="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII",
)

response = client.set_appearance_logo(logo_data)

Perform a full or partial return (chargeback) of a transaction

Merchants can perform a full or partial return of a transaction using the update_payment method. Returns are only permitted for successful payments (including completed pre-authorisations) or payments that have already undergone a partial return. The total return amount cannot exceed the original payment amount (or the confirmed pre-authorisation amount).

from tatrapayplus.client import TBPlusSDK
from tatrapayplus.models import *

# Initialize the SDK client
client = TBPlusSDK(
    "your-client-id",
    "your-client-secret"
)

# The ID of the payment to be returned
payment_id = "b54afd37-5bb9-4080-9416-5ec450779087"

# Define the chargeback instruction
chargeback_data = CardPayUpdateInstruction(
    operation_type=CardPayUpdateInstructionOperationType.CHARGEBACK,
    amount=120,
)

# Execute the update to perform the chargeback
chargeback_response = client.update_payment(payment_id, chargeback_data)

Cancel payment constraints and requirements
v1
A payment can be cancelled under the following conditions:
1. For any payment method: authorization_status must be NEW.
2. For the PAY_LATER payment method: Can be cancelled if authorization_status is AUTH_DONE AND status is CUSTOMER_CREATION_IN_PROGRESS.
https://sdk.tatrabanka.sk/docs/libraries/python/v1/cancel_payment

Confirm or cancel a pre-authorization payment in PHP

Merchants must either confirm or cancel a pre-authorization by calling the online interface within 7 days of the transaction. Use the updatePaymentIntent method with the CardPayUpdateInstruction model to specify the operation type.

use Tatrapayplus\TatrapayplusApiClient\Api\TatraPayPlusAPIApi;
use Tatrapayplus\TatrapayplusApiClient\Model\CardPayUpdateInstruction;

$tatrapayplus_api = new TatraPayPlusAPIApi(
    "your-client-id",
    "your-client-secret",
);
$payment_id = 'b54afd37-5bb9-4080-9416-5ec450779087';

// To CANCEL the pre-authorization
$cancel_data = new CardPayUpdateInstruction([
    "operation_type" => CardPayUpdateInstruction::OPERATION_TYPE_CANCEL_PRE_AUTHORIZATION,
]);
$response_cancel = $tatrapayplus_api->updatePaymentIntent($payment_id, $cancel_data);

// To CONFIRM the pre-authorization
$confirm_data = new CardPayUpdateInstruction([
    "operation_type" => CardPayUpdateInstruction::OPERATION_TYPE_CONFIRM_PRE_AUTHORIZATION,
]);
$response_confirm = $tatrapayplus_api->updatePaymentIntent($payment_id, $confirm_data);

Retrieve and verify payment status after redirection
v1
Upon receiving the paymentId from the redirect URL, use the SDK to retrieve the actual payment status.
Important Notes:
- Sandbox: Status may take 2–5 minutes to move from PENDING to the final status.
- Production: Status is usually updated by the time of redirection, but may occasionally remain PENDING briefly.
The simpleStatus attribute maps complex payment method statuses into four simplified values: AUTHORIZED, CAPTURE, REJECTED, or PENDING.
```
const paymentId = req.query.paymentId; // Extract from request query
const { simpleStatus, data, error } = await sdk.getPaymentStatus(paymentId);

// Handle based on simpleStatus: AUTHORIZED, CAPTURE, REJECTED, or PENDING
```
https://sdk.tatrabanka.sk/docs/libraries/node/v1/process_payment
Handle API errors using ApiException
v2
All requests made via TatraPayPlusAPIApi are wrapped in internal error handling. If the API returns an error, the SDK throws a Tatrapayplus\TatrapayplusApiClient\ApiException. Developers should wrap client calls in a try/catch block to handle these failures.
```
use Tatrapayplus\TatrapayplusApiClient\ApiException;

try {
    $tatrapayplus_api->getAvailableMethods();
} catch (ApiException $e) {
    sprintf('Fetching methods failed: %s', $e);
    // Handle error
}
```
https://sdk.tatrabanka.sk/docs/libraries/php/v2/errors_handling
Retrieve available payment methods using the Node.js SDK
v1
Use the getAvailablePaymentMethods helper to determine which payment options are available to a customer. This is necessary because users select their preferred payment method within the payment gateway rather than the e-shop. You can filter available methods based on the customer's country code, total amount, and currency code, or call the method without arguments to retrieve all available options.
```
// Retrieve filtered payment methods based on specific conditions
const { data: availablePaymentMethods } = await sdk.getAvailablePaymentMethods({
  countryCode: "HU",
  totalAmount: 50,
  currencyCode: "USD",
});

// Retrieve all available payment methods without restrictions
const { data: allPaymentMethods } = await sdk.getAvailablePaymentMethods();
```
https://sdk.tatrabanka.sk/docs/libraries/node/v1/available_methods
Handle API errors using TatrapayPlusApiException
v1
All API requests in the TBPlusSDK are wrapped in internal error handling logic. If an API request fails, the SDK raises a TatrapayPlusApiException. To ensure application stability, wrap client calls in a try/except block to catch this specific exception.
```
from tatrapayplus.errors import TatrapayPlusApiException

try:
    payment_response = client.create_payment(
        request=payment_data,
        redirect_uri="https://tatrabanka.sk/",
        ip_address="127.0.0.1"
    )
except TatrapayPlusApiException as e:
    print("Payment failed:", e)
    # Handle error
```
https://sdk.tatrabanka.sk/docs/libraries/python/v1/errors_handling
Authenticate with TatraPayPlus API using OAuth 2.0
The TatraPayPlus API (Version 0.0.1_2024-05-27v1) uses the OAuth 2.0 Client Credentials flow for authentication. To obtain an access token, requests must be sent to the token endpoint. The required scope for accessing the API is TATRAPAYPLUS.
```
POST /tatrapayplus/sandbox/auth/oauth/v2/token
Host: api.tatrabanka.sk
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=TATRAPAYPLUS
```
https://sdk.tatrabanka.sk/docs/api/tatrapayplus-api

Requirements for PayLater (Na splátkyTB)

PayLater requires detailed order information, including a list of items. A critical constraint is that the instructed_amount.amount_value must exactly match the sum of all total_item_price values in the order items, otherwise the API will reject the request.

$payLater = 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",
                    ]),
                ]),
            ]),
        ],
    ]),
]);