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. |
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. |
* Fields required.
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. |
* Fields that always appear in the response body.
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/" }
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.
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.
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.
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:
Upon sending the request, you will receive a GetTransaction schema in the response.
The primary payment identifier is the transactionId parameter.
Guidelines for storing transactionId:
transactionId parameter in your system.transactionId long-term to analyze issues, handle reports, and conduct investigations in case of problems.Ensuring that transactionId is stored and accessible in your system is crucial for effective payment processing and technical support.