First transaction

Below is an overview of the basic process for creating and processing a transaction in our system.

Create a transaction

To create a transaction, send a POST request to the endpoint:

https://api.tpay.com/transactions

Check the details in the API Reference documentation: POST /transactions

In the request, specify the following parameters:

amount	Transaction amount (in PLN).
description	Description of the transaction visible to the payer.
payer.email	Payer's email address.
payer.name	Payer's name.
callbacks.notification.url	URL for payment notification handling.
callbacks.payerUrls.success	Success page URL.
callbacks.payerUrls.error	Error page URL.

The basic request body should look like this:

{
  "amount": 0.1,
  "description": "Test transaction",
  "payer": {
    "email": "[email protected]",
    "name": "Jan Nowak"
  },
  "callbacks": {
    "notification": {
      "url": "https://example.shop/payment_notification"
    },
    "payerUrls": {
      "success": "https://example.shop/success",
      "error": "https://example.shop/error"
    }
  }
}

Example:

curl --location 'https://api.tpay.com/transactions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token> '\
--data-raw '{
   "amount": 0.1,
   "description": "Test transaction",
   "payer": {
      "email": "[email protected]",
      "name": "Jan Nowak"
   },
   "callbacks": {
      "notification": {
         "url": "https://example.shop/payment_notification"
      },
      "payerUrls": {
         "success": "https://example.shop/success",
         "error": "https://example.shop/error"
      }
   }
}'

Key response parameters:

result	success - The transaction was created successfully.
status	pending - The transaction is awaiting payment.
transactionId	Unique identifier of the transaction.
transactionPaymentUrl	The URL to which the payer should be redirected.

Example response:

{
  "result": "success",
  "requestId": "d3a9826d92c48cb8c185",
  "transactionId": "01K5BK4HEPB0WBCGT51FMTYSYJ",
  "title": "TR-CWM-CS7LW1X",
  "posId": "ps_e4dkPVDEm4Jg726q",
  "status": "pending",
  "date": {
    "creation": "2024-06-12 21:29:35",
    "realization": null
  },
  "amount": 0.1,
  "currency": "PLN",
  "description": "Test transaction",
  "hiddenDescription": "",
  "payer": {
    "payerId": "py_a9rjlZWxRLdG1bqY",
    "email": "[email protected]",
    "name": "Jan Nowak",
    "phone": "",
    "address": "",
    "city": "",
    "country": "PL",
    "postalCode": ""
  },
  "payments": {
    "status": "pending",
    "method": null,
    "amountPaid": 0,
    "date": {
      "realization": null
    }
  },
  "transactionPaymentUrl": "https://secure.tpay.com/"
}

Redirect the payer to the Transaction Panel

Redirect the payer to the URL contained in the response field transactionPaymentUrl.

Then, on the Transaction Panel, the payer selects the payment method and completes the transaction.

Payment authorization

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

BLIK code authorization
3D Secure authorization
Visa Mobile authorization

For more information, refer to the documentation for each payment method.

Payer will be redirected to success or error page

Once the payment is completed, the payer will be redirected to, stated during payment initiation, success page callbacks.payerUrls.success or error page callbacks.payerUrls.error, depending on whether the transaction was successful.

Note

Customer navigating to success page does not state payment was processed. At this time we only accepted payment request. Once payment is fully processes notification will be sent to your system.

Expect a notification of successful transaction

Payments in our system are processed asynchronously.

Asynchronicity means that the payment process does not occur immediately or on a single timeline but operates independently. Therefore, the transaction status may change at any time.

When the transaction status changes to paid, we will notify your system of the successful payment via a notification. Upon receiving the notification, handle it appropriately in your system, such as updating the order status, sending a confirmation to the customer, or fulfilling the service. For more information on transaction webhooks, see here.

Retrieve transaction status

Note

Do not use this endpoint to check the status of every transaction. Instead, implement receiving notifications of successful transactions. We recommend using this as a fallback solution only.

To check the current status of a transaction, send a GET request to the endpoint.

https://api.tpay.com/transactions/{transactionId}

Replace {transactionId} with the transaction identifier for which you want to retrieve the status.

https://api.tpay.com/transactions/01K5BK4HEPB0WBCGT51FMTYSYJ

Check the details in the API Reference documentation: GET /transactions/{transactionId}

Example:

curl --location 'https://api.tpay.com/transactions/01K5BK4HEPB0WBCGT51FMTYSYJ' \
--header 'Authorization: Bearer <access_token>

Upon sending the request, you will receive a GetTransaction schema in the response.

Payment Identifier

The primary payment identifier is the transactionId parameter.

Guidelines for storing transactionId:

When creating a transaction: Ensure you save the transactionId parameter in your system.
Long-term storage: Store the transactionId long-term to analyze issues, handle reports, and conduct investigations in case of problems.
Customer Support: This parameter allows our Customer Support Team to assist you with any issues.

Ensuring that transactionId is stored and accessible in your system is crucial for effective payment processing and technical support.