For AI agents: the complete documentation index is at /llms.txt, and the full text of every page is at /llms-full.txt. Most pages are also available as Markdown by adding .md to the URL.

eRaty Guide

Implement BNPL with our API

In this guide, we will set up the request, which gives you access to the eRaty service. This allows you to initialize a call for your customer's choice of either the 0% APR eRaty payment option, or the non-0% APR option.

At a high level, the majority of Alternative Payment Methods work like this:

APM Integration

After a successful API call to the PKO BP form (along with the selected eRaty offer), your customer will be redirected to a secure PKO BP form where your customer’s data will be collected, their identity confirmed by the bank, the credit scoring will be analysed, and the contract between your customer and PKO BP will be signed if the loan is granted. In the case of a rejection by the bank, your customer will be redirected to a payment page, where other payment options may be selected.

Any refunds or cancellations will be handled solely between the PKO BP bank and your customer, as these are the only parties involved at a contractual level.

Prerequisites

Before starting, you must perform the following steps:

Step 1: Initiate the payment

In an eRaty transaction, the first request is a transaction creation. This is used to provide the payment method the details of a new transaction and to retrieve the necessary information required to facilitate authentication.

In this example, we set up a eRaty transaction. Use the mode parameter to specify the selected eRaty option and to distinguish between bank-interest-bearing plans and non-bank-interest (0% APR) plans.

Request example with 0% APR

{
    "merchant_id": "MER_20c2b3fcfedd484e9c3723347dsefb11",
    "account_name": "Transaction_Processing",
    "channel": "CNP",
    "capture_mode": "AUTO",
    "type": "SALE",
    "amount": "40000",
    "currency": "PLN",
    "country": "PL",
    "reference": "REF-1234223ttk333344ffdd344f",
    "payment_method": {
        "name": "John Doe",
        "entry_mode": "ECOM",
        "apm": {
            "provider": "ERATY",
            "category":"BNPL",
            "terms": {
                "time_unit": "MONTH",
                "count": "10",
                "mode": "NO_INTEREST"
            }
        }
    },
    "payer": {
        "reference": "B8J9KSQA5M6S2",
        "country": "PL",
        "email": "abc@ccc.com"
    },
    "notifications": {
        "cancel_url": "https://webhook.site/1a9fd3b4-dc6b-4db6-b2a4-4b230f185cb5",
        "return_url": "https://webhook.site/1a9fd3b4-dc6b-4db6-b2a4-4b230f185cb5",
        "status_url": "https://webhook.site/1a9fd3b4-dc6b-4db6-b2a4-4b230f185cb5"
    }
}

Request example with non-0% APR (With Interest)

{
    "merchant_id": "MER_20c2b3fcfedd484e9c3723347dsefb11",
    "account_name": "Transaction_Processing",
    "channel": "CNP",
    "capture_mode": "AUTO",
    "type": "SALE",
    "amount": "40000",
    "currency": "PLN",
    "country": "PL",
    "reference": "REF-1234223ttk333344ffdd344f",
    "payment_method": {
        "name": "John Doe",
        "entry_mode": "ECOM",
        "apm": {
            "provider": "ERATY",
            "category":"BNPL",
            "terms": {
                "time_unit": "MONTH",
                "count": "14",
                "mode": "BANK_INTEREST"
            }
        }
    },
    "payer": {
        "reference": "B8J9KSQA5M6S2",
        "country": "PL",
        "email": "abc@ccc.com"
    },
    "notifications": {
        "cancel_url": "https://webhook.site/1a9fd3b4-dc6b-4db6-b2a4-4b230f185cb5",
        "return_url": "https://webhook.site/1a9fd3b4-dc6b-4db6-b2a4-4b230f185cb5",
        "status_url": "https://webhook.site/1a9fd3b4-dc6b-4db6-b2a4-4b230f185cb5"
    }
}

Please use the below table as a reference for understanding No Interest (0% APR) vs Interest (non-0% APR) use cases.

Request fields
time_unit	count	mode
MONTH	3	NO_INTEREST
MONTH	5	NO_INTEREST
MONTH	10	NO_INTEREST
MONTH	Any (except 3, 5, 10)	BANK_INTEREST

Sample response (for 0% APR)

{
    "id": "TRN_mB3ManRvvwWnGEfhpNcfL3c9BYgp_3344ffdd344f",
    "time_created": "2025-12-19T12:52:45.797Z",
    "type": "SALE",
    "status": "INITIATED",
    "channel": "CNP",
    "capture_mode": "AUTO",
    "amount": "40000",
    "currency": "PLN",
    "country": "PL",
    "merchant_id": "MER_20c2b3fcfedd484e9c3723347dsefb11",
    "merchant_name": "UCP_Test_Merchant",
    "account_id": "TRA_f7e775f0a2ce4cedb36a2d8887232a",
    "account_name": "Transaction_Processing",
    "reference": "REF-1234223ttk333344ffdd344f",
    "payment_method": {
        "result": "01",
        "message": "PENDING",
        "entry_mode": "ECOM",
        "redirect_url": "https://sandbox.apis.globalpay.com/ucp/transactions/redirect/f6b33eda-9b62-4287-bf20-bb19be0d3e54",
        "apm": {
            "provider": "ERATY",
            "category":"BNPL",
            "provider_redirect_url": "https://test.apm.gpwebpay.com/apm-simulator/public/test-payment-method/payments/f6b33eda-9b62-4287-bf20-bb19be0d3e54",
            "terms": {
                "time_unit": "MONTH",
                "count": "10",
                "mode": "NO_INTEREST"
            },
            "provider_payer_name": "John Doe"
        }
    },
    "payer": {
        "reference": "B8J9KSQA5M6S2",
        "country": "PL",
        "email": "abc@ccc.com"
    },
    "action": {
        "id": "ACT_0mmB3ManRvvwWnGEfhpNcfL3c9Bygp",
        "type": "INITIATE",
        "time_created": "2025-12-19T12:52:45.797Z",
        "result_code": "SUCCESS",
        "app_id": "hkjrcsGDhWiDt8GEhoDMKy3pzFz5R0B",
        "app_name": "UCP_Test_App"
    }
}

Step 2: Redirect to the payment method

After a successful initiation of the transaction, the following step is to redirect the customer to the eRaty to facilitate authentication and authorization. One way of achieving this is by using, for example, a simple JavaScript redirect. You could also use a HTTP GET (302 redirect).

<!DOCTYPE html>
<html>

<head>
  <title>Sample APM Redirect</title>
  <meta charset="UTF-8">
</head>

<body>
  <script>
    window.location = "https://www.paymentMethodUrl.com/pay";
  </script>
</body>

</html>

Once the customer completes the authentication and processes the transaction using a payment method, they are redirected to the Return URL of the initial request. The current status of the transaction will also be returned.

https://webhook.site/b628afed-2245-49f2-8a87-39286b26e0ef?X-GP-Signature=9983e0f8349058a8353574df3e5790e27da8bb071eebdd83b961ebca70c821bb4a9abcd412bf01c0bcf9255eb27306e28bd011c6e0e4f9ebde8a4770a72e17d4&id=TRN_GAxizPo0xxxxxYF1WJoBInxzWiAf_41xxxxxx2769&status=PENDING&reference=202412191212769&payment_method.result=01&payment_method.message=PENDING&provider=eraty3inst&apm.wait_notification=&apm.optional_redirect=&apm.fund_status=&apm.payment_description=&apm.confirmed_accountholder=&apm.account_number=&country=PL&apm.bank.iban=&apm.bank.identifier_code=&apm.bank.name=&apm.bank.code=&action.id=ACT_cuWxjbLLD8S0ftIUndasYYYsTE9qNK&action.type=RETURN_NOTIFICATION&action.time_created=2025-07-02T11%3A08%3A18.975Z

Your application might take a few seconds while it checks to see if the Status URL was sent a final update. You can then redirect the customer to a final success or failure page.

Step 3: Receive the final status

The final status will appear on the URL specified in the Status URL element in the initial request. Depending on the payment method used, this can happen at the same time that the customer is redirected to your Return URL moments after, or potentially, the final status update might come days later.

You may want to inform the customer at this point that their payment was accepted. You can also initiate the dispatch of items to the customer.

Sample status update:

{
    "id": "TRN_zC4Ah6njMEH0VaWE4kAxEuxvaXtU57_3344ffdd344f",
    "time_created": "2025-12-18T12:07:41.241Z",
    "type": "SALE",
    "status": "CAPTURED",
    "channel": "CNP",
    "capture_mode": "AUTO",
    "amount": "40000",
    "currency": "PLN",
    "country": "PL",
    "merchant_id": "MER_20c2b3fcfedd484e9c3723347dsefb11",
    "merchant_name": "UCP_Test_Merchant",
    "account_id": "TRA_f7e775f0a2ce4cedb36a2d8887232a",
    "account_name": "Transaction_Processing",
    "reference": "REF-1234223ttk333344ffdd344f",
    "payment_method": {
        "result": "00", 
        "message": "SUCCEEDED", 
        "entry_mode": "ECOM",
        "apm": {
            "terms": {
                "time_unit": "MONTH",
                "count": "3",
                "mode": "NO_INTEREST"
            },
            "provider": {
                "name":"ERATY",
                "confirmed_account_holder": "John Doe",
                "wait_notification": "",
                "fund_status": "",
                "payment_description": "",     
                "optional_redirect": ""
            },
            "bank": {
                "name": "",
                "iban": "",
                "identifier_code": "",
                "account_number": "95258",
            }
        }
    },
    "batch_id": "",
    "action": {
        "id": "ACT_vvwMzxwgeV6ZI4q4yyafzac7YRxq",
        "type": "STATUS_NOTIFICATION",
        "time_created": "2025-12-18T12:08:14.152Z",
        "result_code": "SUCCESS",
        "app_id": "hkjrcsGDhWiDt8GEhoDMKy3pzFz5R0B",
        "app_name": "UCP_Test_App"
    }
}

Status Handling

Endpoints

Once you have a Global Payments Client ID, the URL endpoints for where to send transactions are as follows:

Environment	URL
Sandbox	https://apis.sandbox.eservicegateway.com/ucp/transactions
Production	https://apis.eservicegateway.com/ucp/transactions

For Production, we only accept transactions from IP addresses on your account's allow list. Your Global Payments account manager can assist you with setting this up.

Even if your Client ID has been set to Live, you can still send transactions to the Sandbox environment – just target the Sandbox URL.

Result Codes

Code	Description	Status
200	OK	This represents a successful API action.
400	Bad Request	Error: The API request has an error in it.
401	Not Authenticated	Error: Can’t authenticate with those credentials. Need to get a new access token.
403	Forbidden	Error: Don’t have permission to execute that API action.
404	Resource Not Found	Error: the resource referenced in the request cannot be found.
405	Method Not Allowed	Error: The HTTP request method is not supported for the requested resource.
409	Duplicate	Error: The API request was blocked as it is seen as a duplicate action that must not be processed.
500	Internal Server Error	Error: Something unexpected happened.
502	Bad Gateway	Error: Something unexpected happened when communicating with another system.
504	Timeout	Error: API did not get a response from another system in the expected timeframe.

eRaty Guide | Global Payments