# Paytool # Introduction Verestro Paytool is a solution that provides a payment gateway functionalities that supports various methods of payments. By using our solution your users can easily pay for their purchases selecting the Verestro Paytool as the payment option. This technology is delivered in the form of payment widget or API method which is opening payment session in Verestro server. After opening a payment session, the transaction can be carried out in two ways - either via widget or via API.
**Tip:** Check it now. Verestro Paytool demo application is available [here.](https://paytool.verestro.dev/demo/)
#### How to connect with us? The Paytool solution provides two independent integration paths. ##### Web integration The first way is that after opening a payment session, your browser should redirect the payer to the Paytool application or open it in iframe. Verestro will be fully responsible for the execution of transactions and handling 3D Secure authentication. In the application the payer can see the transaction metadata and chooses payment method he wish to pay. All required payment data is transferred to the Verestro Paytool backend over the Verestro internal network. ##### API integration The second way is that after opening a payment session, you can carry out the payment process using the API methods provided by us. Your server should then integrate with our API, which allows you to make payments and carry out the 3D Secure process. Verestro does not provide any frontend application in this way of integration.**Tip:** More information about Paytool API can be found in [API integration guide](https://developer.verestro.com/books/paytool/page/how-to-integrate#bkmrk-api).
**Note:** It is required that you have an account in Acquirer's system which will settle your transactions. For more informations please contact our Sale Department. We are suggesting to use [Fenige](https://www.fenige.com/) as this is our partner acquiring institution and we are fully integrated with this Acquirer
# Overview This document provides a description of functionalities offered by Verestro Paytool. Our solution supports various payment methods such as Google Pay™, Apple Pay, Blik and many others in the form of the payment gateway . In addition, you can decide which payment methods should be enabled. Simply put, you may decide that, for example, you want Verestro Paytool to provide payment via Google Pay but payment via Apple Pay should be disabled. In such a situation, the end user will see the Google Pay as the availabe payment method in the Verestro Paytool payment form, but the Apple Pay payment method will not appear at all. Transaction process mainly takes place on Verestro's side. This means that you are completely relieved of responsibility for processing the transaction and/or performing 3D Secure authentication. The only action that the you must do is to provide metadata of the transaction, which includes order number, description, amount, currency and some optional parameters.**Important!** Note that if you require the settlement of the transaction by an Acquirer to which Verestro is not integrated there will be required new integration between Verestro and the new Acquirer. You should provide the specification of the new Acquirer which will allow us to perform integration.
## Abbreviations In this chapter there are abbreviations and acronyms used in the document listed in below table.**Abbreviation** | **Description** |
ACQ | Acquiring Institution / Acquirer |
ACS | Access Control Server |
SDK | Software Development Kit |
PSP | Payment Service Provider |
OS | Operative System |
Mid | Merchant Identifier |
PCI DSS | Payment Card Industry Data Security Standard |
PAN | Permanent Account Number |
CVC | Card Verification Code |
3DS | 3-D Secure |
**Name** | **Description** |
Customer/Merchant | Institution which uses Verestro products. This institution decides which payment method should be available in the solution and how transaction should be processed. |
End user/payer | The entity which uses Paytool solution to pay for ordered good from Customer. It is root of entity tree. End user is an owner of the wallet/card and he decides to pay for the purchase using Paytool solution, selecting it from the list of payment methods available in the Customer application. |
Payment service provider | The entity which provides a payment services for external Customers who do not have direct integration with acquirers or are not PSI DSS compilent. From the perspective of he Paytool application, Verestro is the PSP. |
Card | Card belongs to the user. If user intends to pay with the Paytool solution using plain card payment method, then has to insert required card's data to the appropriate fields shared by the Paytool solution payment form. Card data will not be stored in the Verestro system. They will be provided to Acquirer. |
Card payment token | It is a numerical value in the form of a PAN number. It shows a given card from Google Pay or Apple Pay wallet. The card payment token replaces the card number and is delivered by Google Pay/Apple Pay to Verestro if the end user selects one of the two above mentioned payment options. Verestro passes this value to Acquirer for the payment to be made. |
Authorization Method | The way of the authentication of the Google Pay™ card transaction. Verestro supports followed authorization methods: `PAN_ONLY` and `CRYPTOGRAM_3DS` if Customer's country belongs to the European Union. Authorization method is always provided in the Google Pay™ encrypted payload as `authMethod` parameter. |
Gateway Id | Phrase/value that identifies a given Payment Service Provider in the Google Pay™ system. The Merchant provides gateway Id to Google Pay™ to obtain a card payment token. By provided gateway Id, Google Pay™ encrypts the card payment token with the appropriate public key. Verestro is defined by a gateway Id with the value `verestro` in Google Pay™ server. |
Gateway Merchant Id | Unique Customer identifier assigned by Verestro during the onboarding process. This identifier is in the form of a `UUID`. Verestro understands and uses this to verify that the message was for the Customer that made the request. Customer passes it to Google Pay™. More information about the Gateway Merchant Id can be found in [Google Pay™ documentation.](https://developers.google.com/pay/api/processors/guides/implementation/understand-our-payload) |
MID | Merchant identifier. This entity is represending Customer in the Acquirer's system. Customer has to provide the mid information to enable mid configuration in the Verestro system. Required to process transactions and 3DS process via Verestro system. |
Bank/Issuer | Card issuing institution. In the case of an e-commerce transaction, this entity is responsible for checking whether the cardholder's balance has the appropriate amount of funds to perform a given transaction, determining whether 3D secure authentication is necessary or simply checking whether the card is active. |
Cardholder | This is the end user who pays for his purchases using one of the available payment options in Verestro Paytool. |
PAN | It is 7-16 digits of the credit/debit card number. These digits contain the Permanent Account Number assigned by the bank to uniquely identify the account holder. It is necessary to provide it when end user wants to pay with a card for purchases via Verestro Paytool solution. |
CVC | Card Verification Code. It is a type of security code protecting against fraud in remote payments. CVC is necessary to provide it when end user wants to pay with a card for purchases via Paytool solution. |
Expiration date | It is a date of the card validity ending and contains two values – month/year - for example 01/28. Card will be valid to the last day of the month of the year showed on it. It is necessary to provide it when end user wants to pay with a card for purchases via Verestro Paytool solution. |
3DS | 3-D Secure is a method of authorization of transaction made without the physical use of a card, used by payment organization. The 3DS process in the Verestro Paytool solution is performed internally in the Verestro system which means the Customer is not responsible for end user authentication. |
PCI DSS | It is a security standard used in environments where the data of payment cardholders is processed. The standard covers meticulous data processing control and protection of users against violations. |
**Tip: **It is also important to mention that you should create a server method which we will be used to send you `postback after transaction`. This step is not required but we highly recommend it as this is the way we will inform you about transaction status. We can also send e-mail post-transaction notification to your payer. More information about transaction postbacks are described in the [Use cases](https://developer.verestro.com/books/paytool/page/use-cases) and [How to integrate](https://developer.verestro.com/books/paytool/page/how-to-integrate) chapters.
### Redirect your payer The first way is to redirect your payer to the payment webview or open this webview in iframe. This implementation model is more comprehensive because when redirecting the payer, you only need to provide us with transaction metadata and the payment session identifier. We are responsible for the rest of the payment process. You need to authenticate your merchant account providing `Basic-Authorization` data in the `transaction initialization` method header.**Tip:** We highly recommend using this integration model because it is much simpler and faster to implement. Additionally, most of the responsibility for the process is on our side.
**Note:** The `Basic-Authorization` data will be issued to you after completing the [onboarding process](https://developer.verestro.com/books/merchant-paytool/page/onboarding).
**Tip:** We highly recommend using [Redirect your payer](https://developer.verestro.com/books/paytool/page/overview#bkmrk-redirect-your-payer) integration model because it is much simpler and faster to implement. Additionally, in the [Redirect your payer](https://developer.verestro.com/books/paytool/page/overview#bkmrk-redirect-your-payer) integration model most of the responsibility for the process is on our side.
**Important:** In this integration model we do not provide any frontend view.
**Note:** The `Basic-Authorization` data will be issued to you after completing the [onboarding process](https://developer.verestro.com/books/merchant-paytool/page/onboarding).
Services that are the part of the Verestro Paytool Solution. |
Services supporting the functionalities offered by Verestro Paytool Solution. |
**Services that are the part of the Verestro Paytool Solution** | |
**Component** | **Description** |
Paytool API | A service with all methods required to complete the entire transaction process. The methods are called by Paytool Frontend App or by your API in the right order to make the entire payment and 3D Secure process. This service also communicates with the Verestro Acquirer Connector, which orders the execution of the transaction. The last and probably the most important element for which the Paytool API is responsible is opening a payment session and saving the transaction entities in the Verestro system. |
**Services supporting the functionalities offered by the Verestro Paytool Solution** | |
**Component** | **Description** |
Midas API | A connector between the Verestro system and the Acquirer's system. This service transfers transaction requests to the Acquirers and also informs if the 3D Secure authentication process is required. |
Notification Service API | A service responsible for sending notifications to end users and Customers. Notifications to end user can be sent via e-mail. The Customer can receive [transaction postback](https://developer.verestro.com/books/paytool/page/how-to-integrate#bkmrk-transaction-postback) via a specific URL he provided. |
Admin Panel API | A service which is communicating with Paytool API along with other listed services supporting Verestro Paytool solution. Admin Panel API provide all obtained data to the Admin Panel Frontend allowing the Customer to perform many actions such as displaying transaction history, downloading transaction reports or ordering refunds.
**Warning: **Implementation is work in progress... |
**Component** | **Description** |
Paytool Frontend App | This is a frontend application hosted by Verestro. This is where you redirect the user when you are using the [Redirect your payer](https://developer.verestro.com/books/paytool/page/overview#bkmrk-redirect-your-payer) integration path. This service is intended to display transaction data to the end user, enable him to select a payment method and confirm payment. To perform the above actions, the Paytool Frontend App communicates directly with the Paytool API. This service does not participate in the payment process at all if you use the [Payment process via API](https://developer.verestro.com/books/paytool/page/overview#bkmrk-payment-process-via-) integration path. Alternatively you can open Paytool in iframe. |
Admin Panel Frontend | Independent frontend application hosted on the Verestro side. This website allows you to manage your account in the Verestro system. From the Admin Panel Frontend, you are able to:
- view transaction history
- generate transaction reports
- configure mid/terminals
- perform refunds
- manage the Paytool frontend form appearance
**Warning:** Implementation is work in progress... **Info: **This service is not obligatory. It is intended for Customers who want to have more control over their account in the Verestro system and want to be able to order a reversal manually. |
**Card type** |
`MASTERCARD` |
`VISA` |
`MAESTRO` |
**Note:** We does not store any sensitive data such as PAN or CVC in our system. The obtained data are only required to be transferred to the Acquirer to perform transaction.
### Authorization Authorization in the Paytool application is intended to check whether the entity trying to execute the request is authorized to do so. If you have a merchant account in the Paytool system, each of your requests should be signed with the `Basic-Authorization` data for both [Redirect your payer](https://developer.verestro.com/books/paytool/page/overview#bkmrk-redirect-your-payer) and [Payment process via API](https://developer.verestro.com/books/paytool/page/overview#bkmrk-payment-process-via-) integration paths. Using one of these data, we will check whether the action you have taken can be implemented. We will also check whether your merchant account is associated with a given transaction, and therefore whether it can perform any actions in the context of this transaction, and whether such a merchant account even exists in our system.**Note:** The `Basic-Authorization`Basic-Authorization data will be issued to you after completing the [onboarding process](https://developer.verestro.com/books/merchant-paytool/page/onboarding).
# Use cases This chapter is mainly dedicated to the appearance of the application and a description of the individual paths that the end user will follow depending on the payment method he choosed. Each of the payment method available in Paytool application is described in a separate section. Additionally, every chapter contains diagrams depicting the entire transaction process per payment method.**Tip:** Check it now. Verestro Paytool demo application is available [here.](https://paytool.verestro.dev/demo/)
## Transaction initialization The first step of the each transaction always takes place in your application. Your application integrated with the Verestro Paytool solution should have exposed option allowing to pay using Paytool available in your application. Your backend should deliver the initial transaction data to the Paytool API to open new transaction session when your payer selects the Paytool as payment option. Our API will return you the transaction identifier and the payer's redirection address. The view of transaction initiatialization from the end user's perspective has been shown below. This view refers to the [Redirect your payer](https://developer.verestro.com/books/paytool/page/overview#bkmrk-redirect-your-payer) integration path:[](https://developer.verestro.com/uploads/images/gallery/2023-06/image-1687851731553.png) | [](https://developer.verestro.com/uploads/images/gallery/2024-04/image-1713956541731.png) |
**Tip:** We are fully responsible for the execution of the transaction and [threeDs authentication](https://developer.verestro.com/books/paytool/page/use-cases#bkmrk-threeds) process. You only initialize transaction by redirecting the end user to the Paytool payment form and providing basic transaction metadata via the your backend.
**Payment methods in Paytool** |
Google Pay™ |
Apple Pay |
Blik |
Plain card number |
**Note:** Each of the payment methods available from the Paytool frontend is also available with an API to API connection.
**Note:** It is required that you have created account in the Acquirer's system which will settle your transactions. Verestro Paytool solution has been implemented so that it is possible to process transactions with the participation of various Acquirers. If you require the settlement of the transaction by a new Acquirer – to which we are not yet integrated – there will be required new integration between Verestro and the new Acquirer. You should provide a specification of the Acquirer API.
### Plain card number The most common payment method available in our application is payment using plain card details. This payment method consists in providing a payment form in which the end user can enter his payment card details. The option to pay with plain card details is available at the button shown below: [](https://developer.verestro.com/uploads/images/gallery/2023-05/image-1685428055821.png) After clicking on the payment option using plain card details, the end user is redirected to the specially prepared payment form. Now he is able to provide the appropriate card details and clicks the **Pay** button at the bottom of the screen. At this point, the card details are encrypted and sent to the Paytool backend which requests Acquirer to process transaction. At this moment [threeDs authentication](https://developer.verestro.com/books/paytool/page/use-cases#bkmrk-threeds) process may be required. The payment process using plain card details from the end user's perpective has been shown below: [](https://developer.verestro.com/uploads/images/gallery/2024-04/image-1713956617464.png)**Important:** If you use Paytool with [Payment process via API](https://developer.verestro.com/books/paytool/page/overview#bkmrk-payment-process-via-) integration path, make sure you are a registered merchant in the Google Pay™ system. This does not apply to Customers using the [Redirect your payer](https://developer.verestro.com/books/paytool/page/overview#bkmrk-redirect-your-payer) route.
**Note:** Google Pay™ provides a [Google Pay Web integration checklist](https://developers.google.com/pay/api/web/guides/test-and-deploy/integration-checklist) that will help you with the integration step by step. The documentation is available after whitelisting in Google Pay™ system. The whitelisting process is performed by Google Pay™ during the Customer's merchant account registration process.
**Note:** Google Pay™ provides [Google Pay Web Brand Guidelines](https://developers.google.com/pay/api/web/guides/brand-guidelines) that presents branding requirements for web merchants registered in Google Pay™. You must meet these requirements so that you can allow his payers to pay via the Google Pay™ solution.
### Apple Pay Verestro as a PSP registered in the Apple Pay™ allows to perform a payment with card token generated by Apple. Using our application your payer can choose the Apple Pay™ as the payment method from the Paytool payment methods list. The option to pay with Apple Pay™ card token is available at the button shown below: [](https://developer.verestro.com/uploads/images/gallery/2023-11/image-1699524383207.png)**Warning!** Apple Pay payment method is available in Safari web browser only.
After clicking on the Apple Pay™ payment option, the Apple Pay™ Wallet popup is displayed. End user should select the appropriate card from the Apple Pay™ Wallet popup which is then encrypted on the Apple Pay™ side and transferred to our application. We decrypt obtained data and transfer them to the Acquirer in the transaction request. At this moment [threeDs authentication](https://developer.verestro.com/books/paytool/page/use-cases#bkmrk-threeds) process may be required. The payment process using Apple Pay™ card payment token from the end user's perpective has been shown below: [](https://developer.verestro.com/uploads/images/gallery/2023-11/image-1699526152020-18-03.png)**Note:** At this moment Apple Pay biometric authorization may be required.
**Note:** Payment using the Apple Pay Wallet is only possible if the payer uses MacOS.
### Blik**Warning!** Implemenation is work in progress...
Paytool supports cardless payments using the Blik code. The end user can choose the Blik as the payment method from the Verestro Paytool payment methods list. The option to pay with Blik code is available at the button shown below: [](https://developer.verestro.com/uploads/images/gallery/2023-05/image-1685523665104.png)After selecting this payment method, the end user must provide his e-mail address in the proper field in displayed popup and then confirm the willingness to make the transaction. Blik as an external service, in response opens a view that allows end user to enter the 6 digits code. This step of the process takes place outside the Verestro. The 6 digits Blik code is generated in the end user's bank application. The payment process using Blik code from the end user's perpective has been shown below:[](https://developer.verestro.com/uploads/images/gallery/2023-06/image-1687851945379.png) | [](https://developer.verestro.com/uploads/images/gallery/2023-06/image-1687852047098.png) |
ThreeDs mode | Description |
`FRICTIONLESS` | The response containing the `FRICTIONLESS` mode denotes that payment is successfully finnished. Additional 3DS authentication is not required. |
`CHALLENGE` | The response containing this mode denotes that the card holder must be additionally authenticated. Along with the `CHALLENGE` mode, the Bank also returns an encoded HTML template, which is displayed to the end user in the Verestro Paytool Frontend, thus allowing the end user to perform 3DS authentication. |
[](https://developer.verestro.com/uploads/images/gallery/2023-05/image-1684330553924.png) | [](https://developer.verestro.com/uploads/images/gallery/2023-05/image-1684330621724.png) |
**Important:** In order for you to receive [notification after transaction](https://developer.verestro.com/books/paytool/page/how-to-integrate#bkmrk-transaction-postback), you must define your own endpoint to which notification will be directed. This is necessary so that we know where to send an HTTP POST request with transaction details. During the [onboarding](https://developer.verestro.com/books/merchant-paytool/page/onboarding) process, the you can provide a valid and accessible URL address that will serve as the endpoint for the post-transaction notifications.
**Note:** The appearance of the e-mail notification is configurable.
Example e-mail notification after successful transaction | Example e-mail notification after failed transaction |
[](https://developer.verestro.com/uploads/images/gallery/2023-07/image-1689254790584.png) | [](https://developer.verestro.com/uploads/images/gallery/2023-07/image-1689254800782.png) |
**Tip:** Please remember to inform us on which environment you want us to configure an account for you. Verestro Paytool offers two environments: `TEST` and `PROD`. For more information about application environments please visit [How to integrate chapter](https://developer.verestro.com/books/paytool/page/how-to-integrate).
**To start using Paytool payment widget you need to go through a few on-boarding steps:** |
1\. Please contact our sales - *salesteam@verestro.com* |
2\. Please respond to some introduction question that will let us prepare proposal for you. |
3\. You will receive offer for eCommerce payments. |
4\. If you accept the offer you will be asked to provide some company documents required for the AML verification process. |
5\. After succesful AML process you will receive contract with our partnering acquiring institution. |
6\. You will be asked to provide account numbers for settlements and the data necessary to configure Paytool for you (see below) |
7\. And finally you will enable Paytool widget or API on your website or mobile app to enable payments. |
**Tip:** The onboarding process takes place mainly on Verestro side. However, in order for all possibilities offered by Verestro Paytool to be available, the you must provide some information needed to correctly configure your merchant account in our system. Configuration includes below presented information:
**Configuration parameter** | **Description** |
Customer name | Basically, it's the name of the your company. The following parameter will be displayed to the end user in Verestro Paytool form. |
Customer website URL | Basically, it's the website URL of the your online application. The following parameter will be displayed to the end user in Verestro Paytool form. Such addresses are required to be added to our whitelist. |
Transaction session life time | The time given in seconds after which the initialization of the transaction will expire and processing of the payment in its context will no more be possible. |
Redirect URL's | Those are the addresses to which end user will be redirected after a successful or unsuccessful transaction performed in Verestro Paytool. These parameters can be static (added to the your merchant account configuration) or sent in the order initiating the transaction. |
Postback URL | Using this address we will send you information about the transaction made by a given end user. This parameter is not required if you does not want to receive notifications regarding the transaction. |
Autodeposit property | This parameter controls whether a transactions made by merchant will be automatically deposited. This parameters can be static (added to the your merchant account configuration) or sent during the transaction initialization. |
Supported payment methods | You should determine which of available payment methods you want to enable in Verestro Paytool. Defaultly all payment methods are enabled. This parameter can be changed anytime. Available payment methods in Paytool: Google Pay, Apple Pay, Blik, plain card number. |
Acquirer's Merchant Id (MID) | It is an identifier of your account in the Acquirer system. This parameter is obligatory to perform transaction. If your company supports more then 1 MID, please let us know which one should be treat as default one.
**Note: **Default MID will be selected if you will not provide any of your MIDs in the transaction initialization request. **Tip: **We are suggesting to use [Fenige](https://www.fenige.com/) as this is our partner acquiring institution and we are fully integrated with this Acquirer |
Acquirer credentials | Login and password that should be used to authorize your payment in the system of a given Acquirer in the context of a given terminal. |
(Optional) Customer's employee e-mail address | This e-mail will be used as login to Admin Panel. |
(Optional) Customer's logo and/or picture | These are image that could be, for example, your company logo. They will be posted as requested in the Verestro Paytool webview. This point is optional. If you do not provide such pictures, the Verestro Paytool will be shown with it's default appearance. |
**Important!** If you require transactions to be processed with the participation of a Acquirer to which Verestro is not integrated, then there must be performed a new integration. You should provide the given Acquirer API documentation that Verestro will use during the integration.
#### Returned data After creating an account for the Customer, Verestro returns all necessary data which allow to use the solution. Such data includes:**Configuration parameter** | **Description** |
Basic Authorization | This is map of the key: login and value: password. Basic Authorization is required to use [API ](https://developer.verestro.com/books/verestro-paytool/page/how-to-integrate#bkmrk-api)methods in Verestro Paytool. Basic Authorization is issued to the Customer after onboarding process. |
Gateway Id | This is a constant and unique value that defines the PSP in the Google Pay™ system. When making a call to get a card token, the Customer transfers this value to Google Pay™ in the request. Verestro is defined by Gateway Id with `verestro` value.
**Note:** This only applies to Customers who make Google Pay payments by connecting directly to the Paytool API. Customers redirecting their payers to the Paytool frontend form should ignore this information. |
Gateway Merchant Id | This is a unique Customer identifier assigned by Verestro during the onboarding process. This identifier is in the form of a `UUID`. Verestro understands and uses this to verify that the message was for the Customer that made the request. Customer passes it to Google Pay™. More information about the Gateway Merchant Id can be found in [Google Pay™ documentation.](https://developers.google.com/pay/api/processors/guides/implementation/understand-our-payload)
**Note:** This only applies to Customers who make Google Pay payments by connecting directly to the Paytool API. Customers redirecting their payers to the Paytool frontend form should ignore this information. |
**Note:** This only applies to Customers who make Google Pay payments by connecting directly to the Paytool API. If you are using [Redirect your payer](https://developer.verestro.com/books/paytool/page/overview#bkmrk-redirect-your-payer) integration path you can ignore this section.
To use the Token Payment Service solution, it is necessary for the Customer to be registered as merchant in the Google Pay™ system. An unregistered Customer will not be able to get the card payment token from Google Pay. To register merchant account in Google Pay™ visit [Google Pay for Business quick start guide](https://support.google.com/pay/business/topic/7684388?hl=en&ref_topic=7513501) or contact Google Pay™ support. After completing registration as a merchant, the Customer will receive an access to Google Pay™ documentation enabling technical integration.[Google Pay Web integration checklist](https://developers.google.com/pay/api/web/guides/test-and-deploy/integration-checklist) | A checklist presenting the Google Pay integration requirements that must be met by the Customer integrating web application |
[Google Pay Web developer documentation](https://developers.google.com/pay/api/web) | Technical documentation describing web integration with the Google Pay solution |
[Google Pay Web Brand Guidelines](https://developers.google.com/pay/api/web/guides/brand-guidelines) | Branding requirements that must be met by the Customer's web application to be able to use the Google Pay solution |
**Note:** To create an account in the Verestro Paytool system please contact with support.
**Tip:** Below are presented sequence diagrams describing both ways of using the Paytool solution. In both cases depending on your Customer account configuration in Paytool, our backend will send e-mail notification to the payer.
**Note:** If you choose to redirect the payer to our Paytool web view, the following payment methods will be available. The payment methods available in the Paytool payment form are customizable according to your requirements.
## Methods in API Our solution provides API method allowing you to order and process transaction by [creating payment session](https://developer.verestro.com/books/paytool/page/how-to-integrate#bkmrk-get-transaction-deta) and send transaction metadata to our system. In order to opening new payment session you receive `transactionId` in response which is unique identifier of the created session. Every ordered transaction has his own payment session. Using `transactionId` you can whether redirect your payer to our Paytool web view or continue the transaction process using other API methods provided by our solution. This section describes all API methods in Paytool solution.**Tip:** There are description of every Paytool API method. To see example request bodies please visit complete API documentation is [available here](https://paytool-api.verestro.dev/swagger-ui/index.html#/) in SwaggerUI format. Please visit to see our methods.
**Tip:** Detailed information about what is included in the transaction metadata is shown in the `transactionInitialization` method.
### [Transaction initialization](https://paytool-api.verestro.dev/swagger-ui/index.html#/Create%20Transaction%20Pre%20Initialization/preinit) ``` POST /external-api/transactions ``` You need to call this API method to create new payment session in the Verestro Paytool system. You request this method with every new transaction order. After successful initialization, the generated `transactionId` in the form of UUID will be returned in the response. The `transactionId` parameter is required for the further parts of the payment process, regardless of whether you redirect your payer to our Verestro web view or you continue the process by requesting other of our API methods. This is important that you saves the `transactionId` parameter in cache for example - by this parameter, our system will map proper session with a given transaction.**Note:** You must use this method whenever you start the Paytool payment process, regardless of whether in the next step you redirect the payer to our Paytool frontend application or continue the process by connecting to other Paytool methods from your API.
### [Google Pay](https://paytool-api.verestro.dev/swagger-ui/index.html#/Google%20pay/GooglePay) ``` POST /external-api/transactions/google-pay ``` This method allows you to pay using the received card payment token from Google Pay. Please note that in the case of Google Pay payments using the API method, you must first obtain a Google payment token yourself. This method can only be executed after creating a payment session using `transactionInitialization` method.**Note:** Use this method only when you continue the payment process by communicating with Paytool via API requests.
**Important!** 3D Secure authentication may be required when requesting a server-to-server Google Pay transaction. To perform 3D Secure authentication, please refer to the methods in the [threeDs authentication](https://developer.verestro.com/books/paytool/page/use-cases#bkmrk-threeds) chapter. Does not apply to Customers redirecting the payer to the Paytool frontend app.
**Important!** You need to be registered merchant in Google Pay system if you want to use this method. You will find the detailed information about registration in Google Pay in the [Onboarding chapter](https://developer.verestro.com/books/paytool/page/onboarding#bkmrk-register-and-integra).
### Apple Pay**Important!** Apple Pay is available only in the Redirect your payer implementation model. Implementation of the server to server communication version of the method is work in progress...
**Warning!** Apple Pay payment method is available in Safari web browser only.
### [Get transaction details](https://paytool-api.verestro.dev/swagger-ui/index.html#/Get%20Transaction%20Details/GetTransactionDetails) ``` GET /external-api/transactions/{transactionId} ``` This method allows you to get the current status of the transaction. Using this you can obtain information whether a given transaction has already been made or has been rejected for some reason. Based on the response from this method, you are able to determine whether you can release the goods to your payer or not. Method is basing on the `transactionId` parameter which is provided in the `transactionInitialization` method response.**Tip:** You can call this method regardless of which integration way you perform (redirecting the payer to Paytool or continuing the payment process via server to server communication) as `getTransactionDetails` method will inform you about the current transaction status.
**Tip:** Integration with the `getTransactionDetails` method described is optional but we hardly recommend using this method as without it, you will not receive any information about the ordered transaction. You can also integrate [`transactionPostback`](https://developer.verestro.com/books/paytool/page/how-to-integrate#bkmrk-transaction-postback)method described below.
### [Transaction postback](https://paytool-api.verestro.dev/swagger-ui/index.html#/Postback/post_postback) ``` POST htttps://merchant-url-address.com/postback ``` This method allows our Paytool backend to send a webhook notification containing information about the transaction made by the end user. You must define his own endpoint to which postbacks will be directed by our server - this is necessary so that the Verestro system knows where to send an HTTP POST request with conversion data. The URL must be a valid and accessible endpoint that can receive HTTP requests. When the conversion event occurs, the server will send an HTTP POST request to the provided URL with the conversion data in the request body.**Note:** You should provide postback endpoint during the [onboarding](https://developer.verestro.com/books/verestro-paytool/page/onboarding) process.
**Tip:** You should implement this method regardless of which integration option you use (redirecting the payer to Paytool or continuing the payment process via server to server communication) as [`transactionPostback`](https://developer.verestro.com/books/paytool/page/how-to-integrate#bkmrk-transaction-postback)method will inform you about the current transaction status.
**Tip:** Integration with the [`transactionPostback`](https://developer.verestro.com/books/paytool/page/how-to-integrate#bkmrk-transaction-postback)method is optional but we hardly recommend using this method as without it, you will not receive any information about the ordered transaction. You can also integrate `getTransactionDetails` method described above.
### Payment with threeDs authentication This section describes how you should integrate with the threeDs authentication process provided by Verestro Paytool API. The threeDs authentication process consists of 3 methods that will need to be invoked or omitted depending on the status. More detailed information can be found in the description of each of the 3 methods that make up the entire threeDs authentication process. After successfully threeDs authentication process the payment is executed automatically.**Note:** Use below threeDs authentication methods only when you continue the payment process by communicating with Paytool via API requests.
#### [Initialize threeDs process](https://paytool-api.verestro.dev/swagger-ui/index.html#/3ds%20Initialize/Init3ds) ``` POST /external-api/transactions/3ds ``` This is the method you always call to start the threeDs authentication process. Depending on the returned `THREE_DS_MODE` parameter, you will need to call one of the other two methods - [`continue3ds`](https://developer.verestro.com/books/paytool/page/how-to-integrate#bkmrk-continue-threeds-pro) for `THREE_DS_MODE=THREE_DS_METHOD` or [`finalize3ds`](https://developer.verestro.com/books/paytool/page/how-to-integrate#bkmrk-finalize-threeds-pro) for `THREE_DS_MODE=CHALLENGE`. If you receive the `FRICTIONLESS` mode in the `THREE_DS_MODE` field, no further action is required. The cardholder's bank allowed the transaction to be performed without additional authentication. The payment has been completed successfully.**Note:** Use this method only when you continue the payment process by communicating with Paytool via API requests.
#### [Continue threeDs process](https://paytool-api.verestro.dev/swagger-ui/index.html#/3ds%20Continue/Continue3ds) ``` POST /external-api/transactions/3ds/continue ``` This is a method by which threeDs authentication process can be continued. This method should be executed after receiving `THREE_DS_MODE=THREE_DS_METHOD`.**Note:** Use this method only when you continue the payment process by communicating with Paytool via API requests.
#### [Finalize threeDs process](https://paytool-api.verestro.dev/swagger-ui/index.html#/3ds%20Finalize/Finalize%203ds) ``` POST /external-api/transactions/3ds/finalize ``` This is the method you must use if we want to end the transaction flow after the successful `CHALLENGE` process. This is the last step in the threeDs authentication process.**Note:** Use this method only when you continue the payment process by communicating with Paytool via API requests.
### [Deposit](https://paytool-api.verestro.dev/swagger-ui/index.html#/Deposit%20Transaction/post_external_api_transactions__transactionId__deposit) ``` POST /external-api/transactions/{transactionId}/deposit ``` This method allows you to deposit frozen funds from the payer's account and to collect the proper amount for the user purchase. It can only be used when the transaction status is `WAITING_FOR_DEPOSIT` and thus requires a deposit to complete the payment process. The deposit amount must be equal to or less than the amount declared in the `transactionInitialization` process.**Note:** If a transaction with the `WAITING_FOR_DEPOSIT` status will not be deposited with this method, the frozen funds will be returned to the payer's account.
**Note:** This method must be used regardless of whether the funds have been frozen via the redirect or API payment path.
### [Transaction refund](https://paytool-api.verestro.dev/swagger-ui/index.html#/Refund/Refund) ``` POST /external-api/transactions/refund ``` This method allows you to refund funds to the payer's account. After calling this method, the funds for the purchase will be refunded to the payer. The method can only be called if the transaction is cleared. This method is optional.**Tip:** You can call this method regardless of which integration option you use (redirecting the payer to Paytool or continuing the payment process via server to server communication) as [`transactionRefund`](https://developer.verestro.com/books/paytool/page/how-to-integrate#bkmrk-refund) is one of the two ways to return funds to the payer. The second way is to make a return from the Admin Panel. If you want to access the Admin Panel, please specify this during the [onboarding](https://developer.verestro.com/books/paytool/page/onboarding) process.
### [Get public key](https://paytool-api.verestro.dev/swagger-ui/index.html#/Get%20Public%20Key/get_external_api_public_key) ``` GET /external-api/public-key ``` This method returns Paytool public key which can be used to encrypt sensitive data which some of our other methods require, for example `initialize3ds.sendersEncryptedData`. ### [Get resources](https://paytool-api.verestro.dev/swagger-ui/index.html#/Get%20Resources/get_external_api_links) ``` GET /external-api/links ``` This method returns url address to the most actual terms of use and RODO info. Terms can be get in two languages depending on the Accept-Language header value: `pl,en-us;q=0.7`. If header value is `null`, the default resources language will be set to english. ### [Get card details](https://paytool-api.verestro.dev/swagger-ui/index.html#/Get%20Card%20Details/getCardDetails) ``` POST /external-api/card-details ``` This method returns detailed information about the card submitted in the request. The data returned includes the consumer type, funding type and its origin (country). We distinguish two consumer types: `CONSUMER` and `BUSSINESS`. We distinguish three funding types: `DEBIT`, `CREDIT` and `PREPAID`. If it is not possible to determine the consumer type, it is marked as `UNKNOWN`. ## [Opening Paytool in iframe](https://paytool.verestro.dev/v1/docs/modules.html) This section describes the steps you need to take if you want the Paytool form to be displayed as an iframe on your website instead of redirecting your payer to Verestro Paytool website.**Tip:** This section applies to customers who use the Redirect your payer implementation model. If you use a different integration model with Paytool, you can ignore this chapter.
### [Initialization](https://paytool.verestro.dev/v1/docs/modules.html) To start working with the SDK, add the following script to your website: ```HTML ``` The script creates a new property named **`Paytool`** in the **`window`** object, giving a global access to it's API.**Tip:** Complete Paytool Client SDK documentation is [available here](https://paytool.verestro.dev/v1/docs/modules.html). Please visit to see our methods.
**Note:** Cross-Origin Resource Sharing -> Your domain must be whitelisted for the script to load properly on your website. See the full integration guidelines for more.
**Testing:** You can also check your integration on a staging environment to avoid charging payments. To do this, simply replace the script's src with `https://paytool.verestro.dev/v1/paytool.js` .
**Note:** A separate enrollment is required, your production credentials won't work. The staging environment, even though meant to be stable, often changes and temporal issues might occur.
#### **``** # Test Guide**Tip:** Check it now. Verestro Paytool demo application is available [here.](https://paytool.verestro.dev/demo/)
## Plain card number This method involves processing payments using credit or debit cards. In order to test it you will need to generate test cards because of possibility of getting card blocked due to anti-fraud policies on the acquirer side. Payment with plain card number use case is described [here](https://developer.verestro.com/books/paytool/page/use-cases#bkmrk-plain-card-number). ### Test cardsCard type | Card BIN |
VISA | 511796XXXXXXXXXX |
Mastercard | 545313XXXXXXXXXX |
**Note:** CVV may be randomized, expiration date must not be expired.
### Testing various transaction pathsThreeDs mode | Amount |
[`FRICTIONLESS`](https://developer.verestro.com/books/paytool/page/use-cases#bkmrk-%40startumlskinparam-p-2) | 100 - 1000 |
[`CHALLENGE`](https://developer.verestro.com/books/paytool/page/use-cases#bkmrk-challenge) | 1001 - 3000 |
**Note:** Amount is a value determining amount of cash transferred in one hundredth of the currency \[1,00 USD = 100\].
**Tip:** Select an amount between 3001-8000 to test failed transaction.
## Google Pay**Note:** To be able to test all flows of ThreeDs in Google Pay follow the description about [testing various transaction paths](https://developer.verestro.com/books/paytool/page/test-guide#:~:text=an%20expired%20date.-,Testing%20various%20transaction%20paths,-As%20described%20in)
## Apple Pay This method involves processing payments using tokenized credit or debit cards. You need to create Apple sandbox tester account. Follow [apple documentation](https://developer.apple.com/apple-pay/sandbox-testing/#:~:text=supports%20TLS%C2%A01.2.-,Create%20a%20Sandbox%20Tester%20Account,-To%20create%20a) to do so. After registration and logging in into tester account you are ready to test Apple Pay token payment. There is a list of [apple-pay valid payment cards.](https://developer.apple.com/apple-pay/sandbox-testing/#:~:text=Test%20Cards%20for%20Apps%20and%20the%20Web) Payment with Apple Pay use case is described [here](https://developer.verestro.com/books/paytool/page/use-cases#bkmrk-apple-pay). ## Blik**Important!** Implemenation is work in progress...