Tpay
API
Changelog

Merchant Accounts

The Partner Program is a form of cooperation with companies offering various services, such as implementing e-commerce solutions for their clients or developing their own marketplace solutions. As part of the program, the Partner recommends Tpay services and earns a specified percentage from each invoice of a client they have referred.

To use the Tpay Marketplace you must be a part of the Tpay Partner Program. Not a partner yet? Learn how to join the Program.

The instructions to launch and manage the Tpay marketplace payments can be found in the Partner Panel: here.

Authorization

As a Partner, you can generate access credentials for registering merchants via API from your Partner Panel in the API > Partner API tab

This tab allows you to generate API access credentials that enable communication with the accounts method.

To generate API access keys, click the Add new key button.

The following will be generated:

  • Client ID.
  • Secret.

To authorize via the API, please refer to the following instructions: First steps > Authorization

Merchant account registration

In addition to generating affiliate links in the Partner Panel, which allows a new merchant to register independently via the Tpay registration form, the system also offers a registration API. Having the merchant’s email address and a previously generated offer code, you can send a POST request to the following address:

https://api.tpay.com/v1/accounts/merchant

The remaining fields are optional.

Check details in API Reference documentation: POST /v1/accounts/merchant

In the request, specify the following parameters:

offerCode
The offer code to which the account will be assigned.
email
The merchant’s email address.
taxId
Tax Identification Number (NIP for Polish entities).
regon
REGON number.
krs
KRS number.
legalForm
Type of business activity. see business activity list
categoryId
Category of conducted sales. see conducted sales category list.
address[].name
Company name.
address[].street
Street.
address[].houseNumber
House number.
address[].flatNumber
Flat number.
address[].postalCode
Postal code.
address[].city
City.
address[].country
Country.
address[].phone
Phone Number.
address[].isMain
The provided address is the primary address. If only the primary address is submitted, it will by default also be used for invoicing and correspondence. The data set may contain a maximum of one address of each type.
address[].isCorrespondence
The provided address is used for correspondence.
address[].isInvoice
The provided address is used for invoicing.
website[].url
Point of sale URL.
website[].name
Point of sale name.
contactPerson[].name
Name of the contact person.
contactPerson[].surname
Surname of the contact person.
contactPerson[].phone
Phone number of the contact person.
contactPerson[].email
Email address of the contact person.
merchantApiConsent
Consent to obtain API access credentials in response to the request. If the merchant has given consent, send true to receive the merchant’s API keys needed for automatic integration.

The basic request body should look as follows:

{
  "offerCode": "9u7UP",
  "email": "[email protected]"
}

After sending the request, you will receive the MerchantCreated schema in response.

{
  "result": "success",
  "id": "01JQ404XV7KJPRD5PHFFZ6R9YR",
  "offerCode": "9u7UP",
  "email": "[email protected]",
  "taxId": null,
  "regon": null,
  "krs": null,
  "legalForm": null,
  "categoryId": null,
  "verified": false,
  "activationLink": "https://panel.tpay.com/Auth/Account/Activate/xyz123",
  "website": [
    {
      "posId": "01JQ404XVJBPR066ZK1XX5A0A0",
      "accountId": "01JQ404XV7KJPRD5PHFFZ6R9YR",
      "name": "",
      "friendlyName": "",
      "description": "",
      "url": "",
      "date": {
        "create": "2025-03-24 12:56:00",
        "modification": null
      },
      "settings": {
        "confirmationCode": "i3DCcHbIA_81rI@FeP4$+LMScK2X#T_|",
        "isTestMode": true
      },
      "verificationScope": 0,
      "verificationDate": null,
      "verificationStatus": 0
    }
  ],
  "address": [
    {
      "addressId": "ar_8OqmRLlQoV9eXgdx",
      "friendlyName": "-",
      "name": "-",
      "street": "-",
      "houseNumber": "",
      "flatNumber": "",
      "postalCode": "-",
      "city": "-",
      "country": "PL",
      "phone": "",
      "isMain": true,
      "isCorrespondence": true,
      "isInvoice": true
    }
  ],
  "person": []
}
Note

In the test environment (Sandbox), some merchant data will be automatically filled in with random values to enable automatic account activation.

An example of an expanded registration request looks as follows:

{
  "offerCode": "9u7UP",
  "email": "[email protected]",
  "taxId": "7773061579",
  "regon": "30087843700000",
  "krs": "0000412357",
  "legalForm": 36,
  "categoryId": 60,
  "address": [
    {
      "name": "Example Sp. z o.o.",
      "street": "ul. Przykładowa",
      "houseNumber": "44b",
      "flatNumber": "1",
      "postalCode": "11-111",
      "city": "Warszawa",
      "country": "PL",
      "phone": "123123123",
      "isMain": true,
      "isCorrespondence": true,
      "isInvoice": true
    }
  ],
  "website": [
    {
      "url": "http://przykladowezakupy.pl",
      "name": "Przykładowe zakupy online"
    }
  ],
  "contactPerson": [
    {
      "name": "Jan",
      "surname": "Kowalski",
      "phone": "123123123",
      "email": "[email protected]"
    }
  ],
  "merchantApiConsent": true
}

After sending the request, you will receive the MerchantCreated schema in response.

{
  "result": "success",
  "id": "01JVVCFMWT0QCGDFM7HB9SJXWT",
  "offerCode": "9u7UP",
  "email": "[email protected]",
  "taxId": "7773061579",
  "regon": "30087843700000",
  "krs": "0000412357",
  "legalForm": 36,
  "categoryId": 60,
  "verified": false,
  "activationLink": "http://docker.pop.com:81/Auth/Account/Activate/7a86870f6ab05385ddcae991a8e5e831",
  "website": [
    {
      "posId": "01JVVCFMX8ZGGV4E33ZYSXZMT8",
      "accountId": "01JVVCFMWT0QCGDFM7HB9SJXWT",
      "name": "Przykładowe zakupy online",
      "friendlyName": "",
      "description": "",
      "url": "http://przykladowezakupy.pl",
      "date": {
        "create": "2025-05-22 08:56:53",
        "modification": null
      },
      "settings": {
        "confirmationCode": "M6(d5QU+3P!57N2(C294#J^XN$2=WgZl",
        "isTestMode": true
      },
      "verificationScope": 0,
      "verificationDate": null,
      "verificationStatus": 0
    }
  ],
  "address": [
    {
      "addressId": "ar_vM9jQLGqBVK01aAp",
      "friendlyName": "Example Sp. z o.o.",
      "name": "Example Sp. z o.o.",
      "street": "ul. Przykładowa",
      "houseNumber": "44b",
      "flatNumber": "1",
      "postalCode": "11-111",
      "city": "Warszawa",
      "country": "PL",
      "phone": "123123123",
      "isMain": true,
      "isCorrespondence": true,
      "isInvoice": true
    }
  ],
  "person": [
    {
      "personId": "pr_P0jrvklnKGxgDZye",
      "name": "Jan",
      "surname": "Kowalski",
      "contacts": [
        {
          "contact": "123123123",
          "type": 2
        },
        {
          "contact": "[email protected]",
          "type": 1
        }
      ],
      "isBeneficiary": false,
      "isRepresentative": false,
      "isContactPerson": true,
      "isAuthorizedPerson": false
    }
  ],
  "transactionApiCredentials": {
    "apiKey": "string",
    "apiPassword": "string",
    "merchantId": 12345
  },
  "apiCredentials": [
    {
      "clientId": "string",
      "clientSecret": "string"
    }
  ]
}

API Access Keys for Merchants

If the merchantApiConsent parameter is set to true in the request that registers a new merchant account, the Tpay system will automatically generate the merchant’s API credentials and return them in the response. These credentials are required for integration with most e-commerce systems, and providing them in this form enables automated integration of the merchant account with your sales platform.

{
  "apiCredentials": [
    {
      "clientId": "string",
      "clientSecret": "string"
    }
  ],
  "transactionApiCredentials": {
    "merchantId": "12345",
    "apiKey": "string",
    "apiPassword": "string"
  }
}

Business activity list

You can expand the data scope during merchant registration by including the merchant’s type of business activity. To do so, present a selection list to the user or map your available data to the business activity types defined in the Tpay system.

To obtain the list, you can send a GET request to the following address:

https://api.tpay.com/accounts/legalForm

Check details in API Reference documentation: GET /accounts/legalForm

After sending the request, you will receive the LegalFormListResultResponse schema in response.

{
  "result": "success",
  "requestId": "c8bebb07b6fc0a3613ae",
  "list": [
    {
      "id": 2,
      "name": "jednoosobowa działalność gospodarcza"
    },
    {
      "id": 3,
      "name": "fundacja"
    }
  ]
}

Sale Categories List

You can expand the data scope during merchant registration by including the sales category, i.e., the merchant’s industry. To do this, display a selection list to the user or map your available data to the sales categories defined in the Tpay system.

To obtain the list, you can send a GET request to the following address:

https://api.tpay.com/accounts/category

Check details in API Reference documentation: GET /accounts/legalForm

After sending the request, you will receive the CategoryListResultResponse schema in response.

{
  "result": "success",
  "requestId": "c1e31156cf99ad6a4425",
  "list": [
    {
      "id": 60,
      "name": "Sklepy  usługi sportowe"
    },
    {
      "id": 61,
      "name": "Zdrowie i uroda"
    }
  ]
}

Downloading the Merchant Account Data

To retrieve a list of merchant accounts registered so far, send a GET request to the following endpoint:

https://api.tpay.com/accounts

Check details in API Reference documentation: GET /accounts

After sending the request, you will receive the AccountListResultResponse schema in response.

{
  "list": [
    {
      "result": "success",
      "requestId": "376f310aba18a2ed6389",
      "id": "01GM5QNY2SANHEXFK6FEV2DWYD",
      "offerCode": "PFA7M",
      "email": "[email protected]",
      "taxId": "7773061579",
      "regon": "",
      "krs": "",
      "legalForm": 20,
      "categoryId": 66,
      "verificationStatus": 0,
      "activationLink": "https://panel.tpay.com/Auth/Account/Activate/123xyz",
      "website": [
        {
          "posId": "01GM5QNY2N7Z4BKTAH8JJAXX25",
          "accountId": "01GM5QNY2SANHEXFK6FEV2DWYD",
          "name": "Przykladowe Zakupy Online",
          "friendlyName": "",
          "description": "Zakupy online - rtv i agd",
          "url": "https://przykladowezakupy.pl",
          "date": {
            "create": "2022-12-13 13:34:46",
            "modification": "2023-02-13 14:23:34"
          },
          "settings": {
            "confirmationCode": "txf&#YE37gxq8f5q+*gC7q>%hq*6o",
            "isTestMode": false
          },
          "verificationScope": 0,
          "verificationDate": "0000-00-00 00:00:00",
          "verificationStatus": 0
        }
      ],
      "person": [
        {
          "personId": "pr_X9x61ZG9KJrqPOAN",
          "name": "John",
          "surname": "Doe",
          "nationality": "",
          "sharesPct": 0,
          "pesel": "",
          "isBeneficiary": false,
          "isRepresentative": false,
          "isContactPerson": true,
          "isAuthorizedPerson": false,
          "pepStatement": 0,
          "dateOfBirth": null,
          "countryOfBirth": "",
          "typeOfDocument": 0,
          "serialNumber": "",
          "expiryDate": null,
          "issuingAuthority": "",
          "contact": [
            {
              "contact": "987654321",
              "type": 2
            },
            {
              "contact": "[email protected]",
              "type": 1
            }
          ]
        }
      ],
      "address": [
        {
          "addressId": "ar_e1Z3xlEEDBElXngY",
          "friendlyName": "Adres Korespondencyjny",
          "name": "Example Sp. z o.o.",
          "street": "Ul. Jelenia",
          "houseNumber": "123",
          "roomNumber": "",
          "postalCode": "54-134",
          "postOffice": "",
          "city": "Warszawa",
          "country": "PL",
          "phone": "",
          "isMain": true,
          "isCorrespondence": true,
          "isInvoice": true
        }
      ],
      "transactionApiCredentials": {
        "merchantId": 12345,
        "apiKey": "string"
      },
      "apiCredentials": []
    }
  ],
  "result": "success",
  "requestId": "376f310aba18a2ed6389",
  "page": 1,
  "limit": 35,
  "total": 1
}

If you have the merchant account ID returned during registration via the API or retrieved using the method described above, you can query the Tpay API for detailed information about that specific account.

To do this, you can send a GET request to the following address:

https://api.tpay.com/accounts/{accountId}

Check details in API Reference documentation: GET /accounts/{accountId}

After sending the request, you will receive the Account schema in response.

{
  "result": "success",
  "requestId": "376f310aba18a2ed6389",
  "id": "01GM5QNY2SANHEXFK6FEV2DWYD",
  "offerCode": "PFA7M",
  "email": "[email protected]",
  "taxId": "7773061579",
  "regon": "",
  "krs": "",
  "legalForm": 20,
  "categoryId": 66,
  "verificationStatus": 0,
  "activationLink": "https://panel.tpay.com/Auth/Account/Activate/123xyz",
  "website": [
    {
      "posId": "01GM5QNY2N7Z4BKTAH8JJAXX25",
      "accountId": "01GM5QNY2SANHEXFK6FEV2DWYD",
      "name": "Przykladowe Zakupy Online",
      "friendlyName": "",
      "description": "Zakupy online - rtv i agd",
      "url": "https://przykladowezakupy.pl",
      "date": {
        "create": "2022-12-13 13:34:46",
        "modification": "2023-02-13 14:23:34"
      },
      "settings": {
        "confirmationCode": "txf&#YE37gxq8f5q+*gC7q>%hq*6o",
        "isTestMode": false
      },
      "verificationScope": 0,
      "verificationDate": "0000-00-00 00:00:00",
      "verificationStatus": 0
    }
  ],
  "person": [
    {
      "personId": "pr_X9x61ZG9KJrqPOAN",
      "name": "Jan",
      "surname": "Kowalski",
      "nationality": "",
      "sharesPct": 0,
      "pesel": "",
      "isBeneficiary": false,
      "isRepresentative": false,
      "isContactPerson": true,
      "isAuthorizedPerson": false,
      "pepStatement": 0,
      "dateOfBirth": null,
      "countryOfBirth": "",
      "typeOfDocument": 0,
      "serialNumber": "",
      "expiryDate": null,
      "issuingAuthority": "",
      "contact": [
        {
          "contact": "987654321",
          "type": 2
        },
        {
          "contact": "[email protected]",
          "type": 1
        }
      ]
    }
  ],
  "address": [
    {
      "addressId": "ar_e1Z3xlEEDBElXngY",
      "friendlyName": "Adres Korespondencyjny",
      "name": "Example Sp. z o.o.",
      "street": "Ul. Jelenia",
      "houseNumber": "123",
      "roomNumber": "",
      "postalCode": "54-134",
      "postOffice": "",
      "city": "Warszawa",
      "country": "PL",
      "phone": "",
      "isMain": true,
      "isCorrespondence": true,
      "isInvoice": true
    }
  ],
  "transactionApiCredentials": {
    "merchantId": 12345,
    "apiKey": "string"
  },
  "apiCredentials": []
}