Marketplace

The Partner Program is a collaboration model with companies that offer a diverse range of services including implementing e-commerce solutions for their clients and creating their own marketplaces. Within this program, the Partner recommends Tpay services and earns a specified percentage from each invoice for the client they referred.

To use the Tpay Marketplace, you must be part of the Tpay Partner Program. If you are not yet a partner - learn how to join the Program.

Instructions for setting up and managing Tpay marketplace payments in the Partner Panel can be found here.

Available payment methods

The following payment methods are available within the Tpay marketplace:

• BLIK.
• Online transfer (PayByLink).
• Installment payments.
• Buy now, pay later payments.

Authorization

As a Partner, from your Panelu Partnera in the API > Partner API tab, you can generate credentials for registering merchants via API.

This tab allows you to generate credentials for communication via API, which allow you to access the accunts and marketplace methods.

To generate API access keys, click the Add new key button, which will generate:

• Client ID.
• Secret.

For API authorization, check the instructions First Steps -> Authorization

Transaction

After enabling the marketplace functionality for your account, prepare the data to create a transaction:

• Seller ID identifiers.
• The previously added POS ID.

You can obtain seller data identifiers using the method that lists the seller accounts assigned to your marketplace GET /accounts. You can find the POS ID where you want to create the transaction using the GET /accounts/pos, method, which lists the POSes of your marketplace.

With the necessary identifiers, you can send a request using the POST method to:

https://api.tpay.com/marketplace/v1/transaction.

Specify the following parameters in the request:

The basic request body should look like this:

{
  "currency": "PLN",
  "description": "Example description",
  "hiddenDescription": "Example hidden description",
  "languageCode": "PL",
  "pos": {
    "id": "01G6WAS5MNGQ2X728AW53D8JPR"
  },
  "billingAddress": {
    "email": "[email protected]",
    "name": "Name"
  },
  "childTransactions": [
    {
      "amount": 1500,
      "description": "Item no1",
      "merchant": {
        "id": "01G6WAPZFNNX4CXBPKQH5MYD4R"
      }
    },
    {
      "amount": 4000,
      "description": "Item no2",
      "merchant": {
        "id": "01GGA49YQ9NGN0YQV0HW1VHDV3"
      }
    }
  ]
}

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

The key response parameters:

After successfully processing the request, the system will email the payer notifying them of the new transaction.

Redirect the payer to the transaction panel

Redirect the payer to the URL provided in the response under paymentUrl.

The payer will then choose their preferred payment method on the transaction panel and complete the payment.

Payment authorization

Some payment methods require additional authorizations that the payer must confirm or complete, such as:

• BLIK Code Authorization
• 3D Secure Authorization
• Visa Mobile Authorization

For more details, refer to the documentation of individual payment methods.

The Payer will be redirected to a success or error page

Once the payment is completed, the payer will be redirected to a success page or an error page, depending on the outcome of the transaction.

Await notification of a successful transaction

The payment process in our system is fully asynchronous.

Asynchronous means that the payment process is not performed immediately or within a time period specified upfront. Therefore, while most payment methods will notify us within minutes, the transaction status can change at any time after the transaction creation up to a month from transaction creation.

When the transaction status changes to paid, we will notify your system of the successful payment via a notification. More information on marketplace transaction webhooks can be found here.

On-Site transaction

For some payment methods, on-site integration is possible on-site. To complete an on-site transaction, use the transaction creation endpoint, then, instead of redirecting the user to the paymentUrl, use the transactionId parameter to send a POST request to the following URL:

https://api.tpay.com/marketplace/v1/transaction/{transactionId}/pay

Place {transactionId} in the URL, for example:

https://api.tpay.com/marketplace/v1/transaction/01GENKAM5WKYYDJQ929P7T1MXN/pay

In the request, you can specify the following parameters:

Transaction containing products' description

You can optionally pass a short list of details about the customer's cart to help your implementation differentiate any possible refunds later.

The list of products should be associated with merchants' supplying them and provided in the products key of a child transaction.

The basic request body containing products description should look like this:

{
  "currency": "PLN",
  "description": "Example transaction with products",
  "hiddenDescription": "example_hidden_description",
  "languageCode": "PL",
  "pos": {
    "id": "01G6WAS5MNGQ2X728AW53D8JPR"
  },
  "billingAddress": {
    "email": "[email protected]",
    "name": "Name"
  },
  "childTransactions": [
    {
      "amount": 1500,
      "description": "Item no1",
      "merchant": {
        "id": "01G6WAPZFNNX4CXBPKQH5MYD4R"
      },
      "products": [
        {
          "name": "Cherries (lb)",
          "externalId": "111.222.33.44",
          "quantity": 1.2,
          "unitPrice": 1250
        }
      ]
    },
    {
      "amount": 4000,
      "description": "Item no2",
      "merchant": {
        "id": "01GGA49YQ9NGN0YQV0HW1VHDV3"
      },
      "products": [
        {
          "name": "Sink",
          "externalId": "Your.identifier.s1Nk",
          "quantity": 1,
          "unitPrice": 4000
        }
      ]
    }
  ]
}

Notifications

When creating a transaction, you can pass various notification types in the transactionCallbacks parameter:

Refunds

You can request a refund by specifying the amount refunded per merchant account, the products refunded per merchant account (both similar to the data used when creating the transaction), specifying either amount or products per child transaction using child transaction identifiers, or without any data – in which case, you will refund the entire transaction.

During the transaction, we perform appropriate validations, such as whether the maximum refund amount, which is 100% of the paid amount, has not been exceeded, whether in full or appropriately divided into per-merchant amount.

The balances of the merchants for whom the refund is requested are debited the same way as in individual transactions.

The amount needed for the refund and the fee for the operation are deducted from the merchant's balance. If the merchant does not have sufficient funds in the balance, the refund request will be rejected.

Full refund

To issue a full refund, send a POST request to the endpoint:

https://api.tpay.com/marketplace/v1/transaction/{transactionId}/refund

Replace {transactionId} with the ID of the transaction you want to refund.

Check the details in the API Reference documentation: POST /marketplace/v1/transaction/{transactionId}/refund

Example URL: https://api.tpay.com/marketplace/v1/transaction/01GENKAM5WKYYDJQ929P7T1MXN/refund

The request body should be an empty JSON object:

{}

Partial refund by amount

To issue a partial refund, send a POST request to the endpoint:

https://api.tpay.com/marketplace/v1/transaction/{transactionId}/refund

Replace {transactionId} with the ID of the transaction you want to refund.

https://api.tpay.com/marketplace/v1/transaction/01GENKAM5WKYYDJQ929P7T1MXN/refund

In the request, specify the following parameters:

The basic request body should look like either of the payloads below:

{
  "childTransactions": [
    {
      "merchantId": "01G6QRHEBPFAECEWRWVEEPM9WY",
      "amount": 2000
    },
    {
      "merchantId": "01G6WAPZFNNX4CXBPKQH5MYD4R",
      "amount": 1000
    }
  ]
}

{
  "childTransactions": [
    {
      "id": "01JENG92HA094GVX7QT60EP0K9",
      "amount": 2000
    },
    {
      "id": "01JENG98VYHM1YF0SBDCM66AH9",
      "amount": 1000
    }
  ]
}

Partial refund by products

To issue a partial refund, send a POST request to the endpoint:

https://api.tpay.com/marketplace/v1/transaction/{transactionId}/refund

Replace {transactionId} with the ID of the transaction you want to refund:

https://api.tpay.com/marketplace/v1/transaction/01GENKAM5WKYYDJQ929P7T1MXN/refund

In the request, specify the following parameters:

The basic request body should look like either of the payloads below:

{
  "childTransactions": [
    {
      "merchantId": "01G6QRHEBPFAECEWRWVEEPM9WY",
      "products": [
        {
          "externalId": "111.222.33.44",
          "quantity": 1.0,
          "unitPrice": 1250
        },
        {
          "externalId": "111.222.33.44",
          "quantity": 0.2,
          "unitPrice": 500
        }
      ]
    },
    {
      "merchantId": "01G6WAPZFNNX4CXBPKQH5MYD4R",
      "products": [
        {
          "externalId": "Your.identifier.s1Nk",
          "quantity": 1,
          "unitPrice": 4000
        }
      ]
    }
  ]
}

{
  "childTransactions": [
    {
      "id": "01JENG92HA094GVX7QT60EP0K9",
      "products": [
        {
          "externalId": "111.222.33.44",
          "quantity": 1.0,
          "unitPrice": 1250
        },
        {
          "externalId": "111.222.33.44",
          "quantity": 0.2,
          "unitPrice": 500
        }
      ]
    },
    {
      "id": "01JENG98VYHM1YF0SBDCM66AH9",
      "products": [
        {
          "externalId": "Your.identifier.s1Nk",
          "quantity": 1,
          "unitPrice": 4000
        }
      ]
    }
  ]
}

List of available payment methods

The available payment methods depend on the settings of the merchants assigned to your marketplace. The list of methods available for the whole transaction is an intersection of payment methods available for all the merchants whose products are a part of the transaction – that is, you can only use methods that are enabled for all the merchants taking part. You can retrieve the list of channels that are enabled on the merchants' accounts for display in the checkout.

To retrieve the list of payment methods for the marketplace, send a GET request to the endpoint:

https://api.tpay.com/marketplace/v1/bank-groups

In the request, specify the following parameters:

Example:

https://api.tpay.com/marketplace/v1/bank-groups?merchantId[]=01G6WAPZFNNX4CXBPKQH5MYD4R&merchantId[]=01G6QRHEBPFAECEWRWVEEPM9WY

This method requires providing the IDs of all merchants involved in the transaction in one call, as it limits the set of returned methods to their intersection. For example, if Merchant 1 does not have installment payments enabled, you cannot choose this method even if other merchants have it enabled.

Transaction cancellation

You can cancel a marketplace transaction provided that the payer has not yet completed the payment.

To cancel a marketplace transaction, send a POST request to the endpoint:

https://api.tpay.com/marketplace/v1/transaction/{transactionId}/cancel

Replace {transactionId} with the ID of the transaction you wish to cancel:

https://api.tpay.com/marketplace/v1/transaction/01GENKAM5WKYYDJQ929P7T1MXN/cancel

A successful response to the cancellation request ensures that the payment cannot be completed.