BLIK transaction
Process BLIK payments using the transaction creation endpoint by providing groupId: 150.
Send a request to create a BLIK transaction
To create a BLIK transaction, send a POST request to the endpoint:
https://api.tpay.com/transactions
Check the details in the API Reference documentation: POST /transactions
Specify the following parameters in the request:
amount | The transaction amount (in PLN). |
description | The transaction description visible to the payer. |
payer.email | The payer's email address. |
payer.name | The payer's name. |
groupId | The payment group ID for BLIK: 150. |
Parametr taxId
In B2B transactions, it is crucial to identify contractors using the Tax Identification Number. Providing this parameter may be required for some accounting operations. Therefore, we recommend providing the taxId parameter (the payer's Tax Identification Number) in the request body.
- When to use it? Add this parameter, if you perform B2B transactions and already ask for the payer's NIP.
- Is the parameter required? No, the
taxIdfield is optional. If you don't specify a value here, the transaction will still be processed without being considered as a B2B one.
The basic request body should look like this:
{ "amount": 0.1, "description": "test transaction via BLIK", "payer": { "email": "[email protected]", "name": "Jan Nowak" }, "pay": { "groupId": 150 } }
Example:
curl --location 'https://api.tpay.com/transactions' \ --header 'Content-Type: application/json' \ --header 'Authorization: Basic MTExMS0wNjE2Yjc4NmVhZDM1MmE4OmUwMDdiMDA1MzNkY2JlOTFlYWI2ZTI0YzdlMGZiOTVlYzU3NGI4ZGM3YTIyMjdjZjBiYmNjOTFlNWIxMzVmN2M=' \ --data-raw '{ "amount": 0.1, "description": "test transaction via BLIK", "payer": { "email": "[email protected]", "name": "Jan Nowak" }, "pay": { "groupId": 150 } }'
After sending the request, you will receive a TransactionCreated schema in response.
Key response parameters:
result | success - The transaction was created successfully. |
payments.status | pending - The transaction is awaiting payment. |
transactionPaymentUrl | The URL to which the payer should be redirected. |
Example response:
{ "result": "success", "requestId": "b6325d51e8c4b9130476", "transactionId": "ta_jrkNGj5L29pnlbqw", "title": "TR-BRA-CCP1S9X", "posId": "ps_NyRBLzV5kelrpjaM", "status": "pending", "date": { "creation": "2024-05-08 21:01:15", "realization": null }, "amount": 0.1, "currency": "PLN", "description": "test transaction via BLIK", "hiddenDescription": "", "payer": { "payerId": "py_a9rjlZ3qyPPG1bqY", "email": "[email protected]", "name": "Jan Nowak", "phone": "", "address": "", "city": "", "country": "PL", "postalCode": "" }, "payments": { "status": "pending", "method": "pay_by_link", "amountPaid": 0, "date": { "realization": null } }, "transactionPaymentUrl": "https://secure.tpay.com/?title=TR-BRA-CCP1S9X&uid=01HXCS9KVQBDZDDWDHP1TZKJ1K" }
Redirect the payer to the Transaction Panel
Redirect the payer to the URL provided in the response in the transactionPaymentUrl field.
Next, the payer generates a 6-digit code in their bank application, enters it on the eBLIK payment form, and confirms the form.
The bank sends a push notification to the payer's banking app to confirm the payment.
The payer will be redirected to a success or error page
When the card payment is completed, the payer will be redirected to a success page or error page depending on whether the transaction was successful.
Handle the notification
We will notify you of the transaction status via transaction posting notifications.
BLIK Level 0
BLIK Level 0, also known as BLIK on-site, involves providing a field in the store to enter the six-digit BLIK code. The payer enters the generated BLIK code in your system. Then, when creating the transaction, you pass this code in the *blikTokenId*. The payment is made without redirecting to the eBLIK form.
Build a BLIK payment form
To process a BLIK Level 0 payment, display the payment form in your system.
- Display BLIK as an available payment method.
- Include a field for the payer to enter the 6-digit BLIK code.
- Include the Tpay terms and conditions - link and information clause - link here.
Send a request to create a BLIK level 0 transaction
To create a BLIK Level 0 transaction, send a POST request to the endpoint:
https://api.tpay.com/transactions
Specify the following parameters in the request:
amount | The transaction amount (in PLN). |
description | The transaction description visible to the payer. |
payer.email | The payer's email address. |
payer.name | The payer's name. |
payer.ip | The payer's IP address (Accepted types are IP V4 and V6). |
payer.userAgent | The payer's browser user agent. |
groupId | The payment group ID for BLIK: 150 |
blikPaymentData.blikToken | 6-digit BLIK code entered by the payer on the form. |
The basic request body should look like this:
{ "amount": 0.1, "description": "test transaction via BLIK", "payer": { "email": "<[email protected]>", "name": "Jan Nowak", "ip": "127.0.0.1", "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36" }, "pay": { "groupId": 150, "blikPaymentData": { "blikToken": "908118" } } }
After sending the request, you will receive a TransactionCreated schema in response.
Key response parameters:
result | success - The transaction was created successfully. |
payments.status | pending - The transaction is awaiting payment. |
Example response:
{ "result": "success", "requestId": "b6325d51e8c4b9130476", "transactionId": "ta_jrkNGj5L29pnlbqw", "title": "TR-BRA-CCP1S9X", "posId": "ps_NyRBLzV5kelrpjaM", "status": "pending", "date": { "creation": "2024-05-08 21:01:15", "realization": null }, "amount": 0.1, "currency": "PLN", "description": "test transaction via BLIK", "hiddenDescription": "", "payer": { "payerId": "py_a9rjlZ3qyPPG1bqY", "email": "<[email protected]>", "name": "Jan Nowak", "phone": "", "address": "", "city": "", "country": "PL", "postalCode": "", "ip": "127.0.0.1", "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36" }, "payments": { "status": "pending", "method": "pay_by_link", "amountPaid": 0, "date": { "realization": null } }, "transactionPaymentUrl": "<https://secure.tpay.com/?title=TR-BRA-CCP1S9X&uid=01HXCS9KVQBDZDDWDHP1TZKJ1K>" }
Display a waiting screen
Display a waiting screen to the payer. Include information that you are waiting for the payment confirmation.
The bank sends a push notification to the payer's banking app to confirm the payment.
Handle the notification
We will notify you of the transaction status via transaction posting notifications.
Display the transaction result
After receiving the notification about the transaction status, use the tr_status field.
BLIK One Click
BLIK One Click is an extension of the Level 0 payment method that allows the system from which the payment is made to be remembered. When the payer memorizes the system during a transaction, subsequent transactions will not require entering the 6-digit BLIK code, only confirming the transaction in the banking app.
To register a payer in BLIK One Click, a 6-digit BLIK code along with a user alias must be provided. For subsequent payments, only the alias provided during the first payment is needed.
Before you start
Ensure that:
-️ You have completed a BLIK Level 0 payment.
Send a request to create a BLIK Level 0 transaction with BLIK one click authorization
To invite the payer to initiate recurring payments, complete a BLIK Level 0 payment by adding appropriate recurring payment fields.
Send a POST request to the endpoint:
https://api.tpay.com/transactions
Specify the following parameters in the request:
amount | Transaction amount (in PLN). |
description | Description of the transaction visible to the payer. |
payer.email | The payer's email address. |
payer.name | The payer's name. |
payer.ip | The payer's IP address (Accepted types are IP V4 and V6). |
payer.userAgent | The payer's browser user agent. |
groupId | Payment group identifier for BLIK: 150. |
blikPaymentData.blikToken | 6-digit BLIK code entered by the payer in the form. |
blikPaymentData.aliases.value | Unique alias per user, defined by the merchant's system. |
blikPaymentData.aliases.label | Store name or, optionally, a payer-defined name. |
blikPaymentData.aliases.type | UID. |
The basic request body should look as follows:
{ "amount": 0.1, "description": "test transaction via BLIK", "payer": { "email": "<[email protected]>", "name": "Jan Nowak", "ip": "127.0.0.1", "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36" }, "pay": { "groupId": 150, "blikPaymentData": { "blikToken": "908118", "aliases": { "value": "user_unique_alias_123", "type": "UID", "label": "Shop label" } } } }
After sending the request, we will return a TransactionCreated schema.
The most important response parameters:
result | success - The transaction was created successfully. |
payments.status | pending - The transaction is awaiting payment. |
Example response:
{ "result": "success", "requestId": "b6325d51e8c4b9130476", "transactionId": "ta_jrkNGj5L29pnlbqw", "title": "TR-BRA-CCP1S9X", "posId": "ps_NyRBLzV5kelrpjaM", "status": "pending", "date": { "creation": "2024-05-08 21:01:15", "realization": null }, "amount": 0.1, "currency": "PLN", "description": "test transaction via BLIK", "hiddenDescription": "", "payer": { "payerId": "py_a9rjlZ3qyPPG1bqY", "email": "<[email protected]>", "name": "Jan Nowak", "phone": "", "address": "", "city": "", "country": "PL", "postalCode": "", "ip": "127.0.0.1", "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36" }, "payments": { "status": "pending", "method": "pay_by_link", "amountPaid": 0, "date": { "realization": null } }, "transactionPaymentUrl": "<https://secure.tpay.com/?title=TR-BRA-CCP1S9X&uid=01HXCS9KVQBDZDDWDHP1TZKJ1K>" }
Display the waiting screen
Display a waiting screen to the payer, informing them that the payment is pending approval.
The bank sends a push notification to the payer's banking app to approve the payment.
Handle notifications
We will notify you of the transaction status via transaction posting notifications.
Alias authorization
After successful payment authorization, the payer will receive a push notification in their banking app to approve the sent alias.
Handle alias creation status notifications
Wait for a webhook notification about the alias status. The address we will send a webhook to must be static and set in merchant account settings in Merchant Panel in the Settings - notifications tab.
When the alias is accepted, we will send you its data to confirm alias creation.
Notification parameters:
id | Merchant identifier. |
event | ALIAS_REGISTER. |
msg_value.value | Unique alias identifier provided during the transaction. |
msg_value.type | UID. |
msg_value.expirationDate | Alias expiration date. If this parameter is missing in the notification, it means the alias does not expire. |
md5sum | Unique md5 value (deprecated). |
Example:
Respond to our notification with HTTP 200 status and body:
The notification content is signed with JSON Web Signature.
Make sure the notification is from Tpay.
Save the msg_value.value parameter for future transactions, correlate this value with the payer/user of your system for subsequent payment handling.
Display the transaction result
Upon receiving the transaction status notification, use the tr_status field.
Send a request to create a transaction using a registered alias
When the payer makes another payment, you don't need to display a form for entering the BLIK code. The saved alias is sufficient.
Send a POST request to the endpoint
https://api.tpay.com/transactions
Specify the following parameters in the request:
amount | Transaction amount (in PLN). |
description | Description of the transaction visible to the payer. |
payer.email | The payer's email address. |
payer.name | The payer's name. |
payer.ip | The payer's IP address (Accepted types are IP V4 and V6). |
payer.userAgent | The payer's browser user agent. |
groupId | Payment group identifier for BLIK: 150. |
blikPaymentData.aliases.value | Unique alias per user, set by the merchant's system and saved during payer authorization in BLIK One Click. |
blikPaymentData.aliases.type | UID. |
The basic request body should look as follows:
{ "amount": 0.1, "description": "test transaction via BLIK", "payer": { "email": "<[email protected]>", "name": "Jan Nowak", "ip": "127.0.0.1", "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36" }, "pay": { "groupId": 150, "blikPaymentData": { "aliases": { "value": "user_unique_alias_123", "type": "UID" } } } }
After sending the request, we will return a TransactionCreated schema.
The most important response parameters:
result | success - The transaction was created successfully. |
payments.status | pending - The transaction is awaiting payment. |
Example response:
{ "result": "success", "requestId": "b6325d51e8c4b9130476", "transactionId": "ta_jrkNGj5L29pnlbqw", "title": "TR-BRA-CCP1S9X", "posId": "ps_NyRBLzV5kelrpjaM", "status": "pending", "date": { "creation": "2024-05-08 21:01:15", "realization": null }, "amount": 0.1, "currency": "PLN", "description": "test transaction via BLIK", "hiddenDescription": "", "payer": { "payerId": "py_a9rjlZ3qyPPG1bqY", "email": "<[email protected]>", "name": "Jan Nowak", "phone": "", "address": "", "city": "", "country": "PL", "postalCode": "", "ip": "127.0.0.1", "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36" }, "payments": { "status": "pending", "method": "pay_by_link", "amountPaid": 0, "date": { "realization": null } }, "transactionPaymentUrl": "<https://secure.tpay.com/?title=TR-BRA-CCP1S9X&uid=01HXCS9KVQBDZDDWDHP1TZKJ1K>" }
Display the waiting screen
Display a waiting screen to the payer, informing them that the payment is pending approval.
The bank sends a push notification to the payer's banking app to approve the payment.
Handle notifications
We will notify you of the transaction status via transaction posting notifications.
Delete an alias
Implement the option to delete a BLIK alias in your system by the payer.
Send a DELETE request to the endpoint:
https://api.tpay.com/blik/alias/{aliasValue}
Request parameters:
aliasValue | The value of the alias to delete. |
aliasType | UID. |
Example request body:
Handle alias expiration or deletion notification
An alias may be deleted or its validity period may expire.
Prepare an endpoint to receive BLIK alias notifications for a message about the expiration or deletion of a saved alias.
Notification parameters for alias deletion:
id | Merchant identifier. |
event | ALIAS_UNREGISTER. |
msg_value.value | The unique alias identifier provided during the transaction. |
msg_value.type | UID. |
md5sum | Unique MD5 value (deprecated). |
Example:
Handle the deletion of the alias upon receiving the notification.
Notification parameters for alias expiration:
id | Merchant identifier. |
event | ALIAS_EXPIRED. |
msg_value.value | The unique alias identifier provided during the transaction. |
msg_value.type | UID. |
md5sum | Unique MD5 value (deprecated). |
Example:
Handle the deletion of the alias upon receiving the notification.
Handle non-unique aliases
If multiple aliases are active (the user registered the alias multiple times in different banking apps), the payment attempt will fail, and the response will contain a list of available banking app aliases.
Example response:
{ "payments": { "status": "pending", "method": "pay_by_link", "amountPaid": 0, "date": { "realization": null }, "errors": [ { "errorCode": "payment_failed", "errorMessage": "aliases: Too many aliases found for aliasValue: user_unique_alias_123" } ], "alternatives": [ { "applicationName": "My qwerty bank", "applicationCode": "1ec8f352-463c-6334-be44-9fede70e64b8" }, { "applicationName": "My azerty bank", "applicationCode": "1ec8fe63-ea6e-6b48-ac6f-f7f170888d37" } ] } }
Handle displaying the list of alternative aliases to the payer to allow them to choose the desired alias. Then, provide the applicationCode in the key field when reprocessing the transaction.
Example:
BLIK Recurring Payments
Recurring BLIK Payments are an extension of Level 0 payments. Recurring BLIK Payments allow merchants to initiate and collect payments from payers who have given their consent.
In the process of Recurring BLIK Payments, two key events occur:
- Activation of Recurring Payment, which is the user's consent for the merchant to initiate recurring transactions. This consent is initiated by the user on the merchant's website/application and confirmed in the user's banking app. The user can also view and cancel all Recurring Payments in their banking app.
- Recurring Transaction, which is a single transaction initiated by the merchant based on the Recurring Payment activated by the user.
When the user agrees to activate Recurring BLIK Payments during the first transaction, next transactions will no longer require entering the 6-digit BLIK code. From the user's perspective, the transactions will be processed automatically or after approval in the banking app, depending on the chosen model. Subsequent account charges are initiated by the merchant's system, requiring a separate transaction each time. Three models of Recurring Payments are available: A, M, and O.
Model A - Fixed Amount Recurring BLIK Payments
This model is used for settling a fixed amount at a regular frequency, e.g., repayment of a product in equal installments over a specified period or a recurring fee for a streaming service. In this model, the payment is deducted without requiring confirmation in the banking app.
Model M - Variable Amount Recurring BLIK Payments
This model is used for settling variable amounts with a declared or variable frequency. The validity of the Recurring Payment can be specified by a set date or marked as indefinite/until canceled. In this model, the banking app displays a request for the user to approve each payment. Users have 72 hours to approve the payment.
Model O - BLIK Recurring Payments with a varying amount, without confirmation
This model is also used for settling variable amounts with a declared or variable frequency. The validity of the Recurring Payment can be specified by a set date or marked as indefinite/until canceled. In this model, the payment is deducted without requiring confirmation in the banking app.
For more information about the models and their applications, visit: BLIK Guidelines.
The use of the Model O is restricted and requires additional approval from Tpay. Contact your Tpay account manager or the Customer Service Office for details.
Recurring Payments do not need to be activated during the first payment. This method of registration is described in the section: Invite the payer to initiate BLIK Recurring Payments without debiting, using appropriate recurring payment fields
To initiate a Recurring BLIK Payment, you must provide the 6-digit BLIK code along with the Recurring Payment alias. Subsequent payments will only require the alias set during the first payment.
The parameters sent during the invitation will be presented to the user in their banking app, depending on the chosen model:
Model A 
Model M 
Model O 
The implementation of BLIK Recurring Payments must comply with the BLIK guidelines
Before you start
Ensure that:
- You have completed a BLIK Level 0 payment
Send a request to create a BLIK Level 0 transaction with authorization for BLIK Recurring Payments
To authorize the user for BLIK Recurring Payments, complete a BLIK Level 0 payment by adding an alias.
Send a POST request to the endpoint:
https://api.tpay.com/transactions
In the request, specify the following parameters:
amount | The transaction amount (in PLN). |
description | A description of the transaction visible to the payer. |
payer.email | The payer's email address. |
payer.name | The payer's name. |
payer.ip | The payer's IP address (Accepted types are IP V4 and V6). |
payer.userAgent | The payer's browser user agent. |
groupId | The payment group identifier for BLIK: 150. |
blikPaymentData.blikToken | The 6-digit BLIK code entered by the payer in the form. |
blikPaymentData.refuseNoPayId | true/false - the payment will be automatically rejected if the provided BLIK code was generated in a banking app that does not currently support BLIK Recurring Payments. |
blikPaymentData.aliases.value | A unique identifier for the Recurring Payment. |
blikPaymentData.aliases.label | A unique name for the Recurring Payment, composed of elements like the payer's email or username and the plan name (e.g. "[email protected] Gold+"), enabling unambiguous identification of the payment on the payment list in the banking app. The following considerations must be taken into account
|
blikPaymentData.aliases.type | PAYID. |
blikPaymentData.aliases.autopayment.model | The model in which the alias is registered (A, M or O). |
blikPaymentData.aliases.autopayment.frequency | The frequency of the recurring payment, e.g. 1M - once per month. The values should consist of a number of one to three digits, leading zeros omitted, and a one-character period identifier: D, W, M or Y. Required for Model A, optional for Model M, not included for Model O. |
blikPaymentData.aliases.autopayment.singleLimitAmount | The maximum amount for a single payment (in PLN, applicable to Model A). |
blikPaymentData.aliases.autopayment.totalLimitAmount | The total payment amount (in PLN, applicable to Model A). |
blikPaymentData.aliases.autopayment.currency | The currency for Recurring Payments – currently limited to PLN. |
blikPaymentData.aliases.autopayment.initDate | The date of the first Recurring Transaction (required for Model A, optional for Model O, not included for Model M). |
blikPaymentData.aliases.autopayment.expirationDate | The expiration date of the Recurring Payment (required for Model A). If this parameter is not provided for models M or O, the Recurring Payment will be generated without a defined expiration date. |
The basic request body for Model A should look as follows:
{ "amount": 20.08, "description": "Recurring Payment initiation", "hiddenDescription": "MyShop:user:172838953:2024-06", "payer": { "email": "[email protected]", "ip": "127.0.0.1", "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36" }, "pay": { "groupId": 150, "blikPaymentData": { "blikToken": "777777", "aliases": { "value": "172838953_he7vqanrfazzaeyb3q", "label": "MyShop, your shop", "type": "PAYID", "autopayment": { "model": "A", "frequency": "1M", "singleLimitAmount": 10.0, "totalLimitAmount": 100.0, "currency": "PLN", "initDate": "2024-10-30 00:00:00", "expirationDate": "2025-01-01 00:00:00" } } } } }
The basic request body for Model M should look as follows:
{ "amount": 21.08, "description": "Recurring Payment initiation", "hiddenDescription": "MyShop:user:172838953:2024-06", "payer": { "email": "[email protected]", "ip": "127.0.0.1", "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36" }, "pay": { "groupId": 150, "blikPaymentData": { "blikToken": "777777", "aliases": { "value": "172838953_he7vqanrfazzaeyb3q", "label": "MyShop, your shop", "type": "PAYID", "autopayment": { "model": "M" } } } } }
The basic request body for Model O should look as follows:
{ "amount": 21.08, "description": "Recurring Payment initiation", "hiddenDescription": "MyShop:user:172838953:2024-06", "payer": { "email": "[email protected]", "ip": "127.0.0.1", "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36" }, "pay": { "groupId": 150, "blikPaymentData": { "blikToken": "777777", "aliases": { "value": "172838953_he7vqanrfazzaeyb3q", "label": "MyShop, your shop", "type": "PAYID", "autopayment": { "model": "O" } } } } }
After sending the request, we will return a TransactionCreated schema.
Key response parameters:
result | success - The transaction has been successfully created. |
payments.status | pending - The transaction is awaiting payment. |
Example response:
{ "result": "success", "requestId": "b6325d51e8c4b9130476", "transactionId": "ta_jrkNGj5L29pnlbqw", "title": "TR-BRA-CCP1S9X", "posId": "ps_NyRBLzV5kelrpjaM", "status": "pending", "date": { "creation": "2024-05-08 21:01:15", "realization": null }, "amount": 21.08, "currency": "PLN", "description": "Recurring Payment initiation", "hiddenDescription": "", "payer": { "payerId": "py_a9rjlZ3qyPPG1bqY", "email": "<[email protected]>", "name": "Jan Nowak", "phone": "", "address": "", "city": "", "country": "PL", "postalCode": "", "ip": "127.0.0.1", "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36" }, "payments": { "status": "pending", "method": "pay_by_link", "amountPaid": 0, "date": { "realization": null } }, "transactionPaymentUrl": "https://secure.tpay.com/?title=TR-BRA-CCP1S9X&uid=01HXCS9KVQBDZDDWDHP1TZKJ1K" }
Display a waiting screen
Show the user a waiting screen. Include information indicating that we are awaiting payment approval.
The bank will send a push notification to the user’s banking application for payment authorization.
Handle notifications
We will inform you about the transaction status via a notification once the transaction is processed.
Recurring Payment Authorization
After successful payment authorization, the user will receive a push notification in their banking app to approve the submitted Recurring Payment.
Handle Notifications for the Status of Recurring Payment Creation
Wait for the webhook notification regarding the status of the Recurring Payment. The webhook URL must be static and configured in the merchant account settings under the Settings -> Notifications section in the Merchant Panel.
Once the alias is accepted, we will send its details to confirm the creation of the Recurring Payment.
Notification Parameters:
id | Merchant identifier. |
event | ALIAS_REGISTER. |
msg_value.value | Unique identifier of the Recurring Payment provided during the transaction. |
msg_value.type | PAYID. |
msg_value.expirationDate | Expiration date of the Recurring Payment. If this parameter is missing in the notification, it means the alias does not expire. |
md5sum | Unique md5 value (deprecated). |
Example:
Respond to our notification with an HTTP 200 status and body:
The content of the notification is signed using JSON Web Signature.
Check if the notification comes from Tpay.
Save the msg_value.value parameter for future transactions and correlate this value with the user in your system for later payment processing.
Display transaction result
After receiving the notification about the transaction status, use the tr_status field.
Send a request to create a transaction using the registered alias
To retrieve the next payment resulting from the Recurring Payment, create a transaction by providing the previously saved user alias.
Send a POST request to the endpoint:
https://api.tpay.com/transactions
In the request, specify the following parameters:
amount | Transaction amount (in PLN). |
description | Transaction description visible to the payer. |
email | Payer's email address. |
name | Payer's full name. |
groupId | Payment group identifier for BLIK: 150. |
blikPaymentData.type | For recurring payments, type: 2. |
blikPaymentData.aliases.value | Unique alias per payer. Saved during user authorization in BLIK Recurring Payments. |
blikPaymentData.aliases.type | PAYID. |
blikPaymentData.aliases.noDelay | true/false – Parameter available for models A and O, triggers an immediate attempt to collect funds. In model A, without this parameter, the payer has 72 hours to approve the payment. |
blikPaymentData.aliases.recommendedAuthLevel | Request to perform a charge without payer confirmation. Parameter available and required only in model O. Value NOCONFREQ will cause the authorization screen to be omitted from the flow. |
The basic request body for models A and M should look as follows:
{ "amount": 27.08, "description": "Płatność za 07/2024", "hiddenDescription": "MyShop:user:172838953:2024-07", "payer": { "email": "[email protected]" }, "pay": { "groupId": 150, "blikPaymentData": { "type": 2, "aliases": { "value": "172838953_he7vqanrfazzaeyb3q", "type": "PAYID" } } } }
The basic request body for model O should look as follows:
{ "amount": 27.08, "description": "Płatność za 07/2024", "hiddenDescription": "MyShop:user:172838953:2024-07", "payer": { "email": "[email protected]" }, "pay": { "groupId": 150, "blikPaymentData": { "type": 2, "aliases": { "value": "172838953_he7vqanrfazzaeyb3q", "type": "PAYID", "recommendedAuthLevel": "NOCONFREQ" } } } }
After sending the request, we will return a TransactionCreated schema.
The most important response parameters:
result | success - The transaction was successfully created. |
payments.status | pending - The transaction is awaiting payment. |
Handle the notification
We will inform you about the transaction status through a notification after the transaction is posted.
Remove Recurring Payment
Implement the option for the user to remove a BLIK Recurring Payment in your system.
Send a POST request to the endpoint:
https://api.tpay.com/blik/alias/{aliasValue}
Request parameters:
aliasValue | The value of the Recurring Payment to be removed. |
aliasType | PAYID. |
Example request body:
Handle the expiration or removal notification of a Recurring Payment
A Recurring Payment can either be removed or its expiration date can pass.
Prepare an endpoint to receive notifications about BLIK aliases regarding the expiration or removal of a saved Recurring Payment.
Parameters for the Recurring Payment removal notification:
id | Merchant identifier. |
event | ALIAS_UNREGISTER. |
msg_value.value | Unique alias per user. Saved during user authorization in BLIK Recurring Payments. |
msg_value.type | PAYID. |
md5sum | Unique MD5 value (deprecated). |
Example:
Handle the removal of the Recurring Payment upon receiving the notification.
Parameters of the Recurring Payment expiration notification:
id | Merchant identifier. |
event | ALIAS_EXPIRED. |
msg_value.value | Unique alias per user. Saved during the payer's authorization in BLIK Recurring Payments. |
msg_value.type | PAYID. |
md5sum | Unique MD5 value (deprecated). |
Example:
Handle the removal of the Recurring Payment upon receiving the notification.
Handle non-unique aliases
If multiple recurring payments are active for the same alias, an attempt to collect funds will fail, and the response will include a list of the recurring payments with their names (blikPaymentData.aliases.label parameter). If you do not want this situation to occur, you can generate a unique alias for each recurring payment for the user.
Example response:
{ "payments": { "status": "pending", "method": "pay_by_link", "amountPaid": 0, "date": { "realization": null }, "errors": [ { "errorCode": "payment_failed", "errorMessage": "aliases: Too many aliases found for aliasValue: user_unique_alias_123" } ], "alternatives": [ { "applicationName": "Subscription 1", "applicationCode": "1ec8f352-463c-6334-be44-9fede70e64b8" }, { "applicationName": "Subscription 2", "applicationCode": "1ec8fe63-ea6e-6b48-ac6f-f7f170888d37" } ] } }
Handle displaying a list of alternative aliases to the user to allow them to select the desired alias. Then, provide the applicationCode in the key field when re-processing the transaction.
Example:
Send an invitation to enable BLIK Recurring Payments without charging a fee by adding the appropriate fields related to Recurring Payment
Send a POST request to the endpoint:
https://api.tpay.com/blik/alias
In the request, specify the following parameters:
description | Description of the transaction visible to the payer. |
lang | The language in which the communication with the payer will be conducted (pl or en). |
blikPaymentData.blikToken | 6-digit BLIK code entered by the payer in the form. |
blikPaymentData.refuseNoPayId | true/false – The payment will be automatically rejected if the provided BLIK code was generated in the bank's application, which currently does not support BLIK Recurring Payments. |
blikPaymentData.aliases.value | Unique identifier for the Recurring Payment. |
blikPaymentData.aliases.label | Unique name for the Recurring Payment, which could include an email or username and the plan name (e.g. "[email protected] Gold+"), allowing for easy identification of the payment on the bank's payment list. It should account for
|
blikPaymentData.aliases.type | PAYID. |
blikPaymentData.aliases.autopayment.model | The model in which the alias is registered (A, M, or O). |
blikPaymentData.aliases.autopayment.frequency | Frequency of the collected payment, e.g., 1M - once per month. The values should consist of a number containing 1 to 3 digits, leading zeros omitted, followed by a single letter to denote the period: D, W, M, or Y. Required for Model A, Optional for Model M, not sent for Model O. |
blikPaymentData.aliases.autopayment.singleLimitAmount | Maximum amount for a one-time payment (in PLN, applied in model A). |
blikPaymentData.aliases.autopayment.totalLimitAmount | Total amount due (in PLN, applied in model A). |
blikPaymentData.aliases.autopayment.currency | Currency for the Recurring Payment – currently only PLN. |
blikPaymentData.aliases.autopayment.initDate | Date of the first Recurring Transaction (required in Model A, optional for Model O, not sent for Model M). |
blikPaymentData.aliases.autopayment.expirationDate | Expiration date for the Recurring Payment (required in Model A). If the parameter is not sent in models M or O, a non-expiring Recurring Payment will be generated. |
The basic request body for model A should look like the following:
The basic request body for model M should look like the following:
The basic request body for model O should look like the following:
After sending the request, we will return a TransactionCreated schema.
Key response parameters:
result | success - The request was successfully processed. |
payments.status | correct - The Recurring Payment was successfully initiated. |
Example response:
Display a waiting screen
Display a waiting screen to the user. Include information that we are waiting for the approval of the Recurring Payment.
Authorization of the Recurring Payment
The bank sends a push notification to the user's banking app to approve the Recurring Payment.
Handle notifications about the creation status of the Recurring Payment
Wait for a webhook notification about the status of the Recurring Payment. The webhook URL must be static and entered in the merchant account settings in the Merchant Panel under Settings > Notifications.
Once the alias is approved, we will send its data to you to confirm the creation of the Recurring Payment.
Notification parameters:
id | Merchant identifier. |
event | ALIAS_REGISTER. |
msg_value.value | Unique identifier of the Recurring Payment provided during the transaction. |
msg_value.type | PAYID. |
msg_value.expirationDate | Expiry date of the Recurring Payment. If this parameter is missing in the notification, it means that the alias does not expire. |
md5sum | Unique md5 value. |
Example:
Respond to our notification with an HTTP 200 status and body:
The content of the notification is signed using JSON Web Signature.
Make sure to verify that the notification is from Tpay.
Save the msg_value.value parameter for future transactions, and correlate this value with the user in your system for later payment processing.
Display the result of the Recurring Payments creation
After receiving the notification of the Recurring Payment registration, display a success screen to the user.