# 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

## Terminology This section explains a meaning of key terms and concepts used in the document.

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.

## Implementation models Integration with Paytool should be performed by API call. To initiate a payment, you must request an `transaction initialization` method, which in response opens a payment session with a unique identifier. Once you have an active payment session and its identifier, you can choose one of two available payment processing methods described in [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-) chapters.

**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).

Example request body of the transaction metadata provided by Customer

```JSON { "transactionId": "42be3d06-4577-4a9f-b525-2cfaba244557", "currencyCode": "PLN", "amount": 100, "description": "Test transaction", "formLanguage": "en", "redirectUrl": { "successUrl": "https://paytool.verestro.com/demo/?success=1", "failureUrl": "https://paytool.verestro.com/demo/?success=0" }, "sender": { "firstName": "Yoshimoto", "lastName": "Imagawa", "address": { "countryCode": "PL", "city": "Kyoto", "postalCode": "12-345", "street": "Ichijo", "houseNumber": "1" } }, "merchantUrl": "https://paytool.verestro.com/demo/", "orderNumber": "1" } ```

Sequence diagram of the payer redirection process

### Payment process via API The second way to continue the payment process is to integrate your application along with payment session identifier with the rest of the API methods provided by our solution. By continuing the process along this path, you need to call the individual payment method you want to use and handle the threeDs authentication process if required. We are responsible for carrying out the above-mentioned processes, but you are the entity that must request individual methods responsible for every step of a given transaction. We are responsible for the rest of the payment process. In this case, you authenticate with the `Basic-Authorization` data passed in the header.

**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).

Example request body of the transaction metadata provided by Customer

Sequence diagram of the payment via API process

## Application components Application components are all Verestro's internal services which are taking part in the Paytool processes. This chapter describes every component of the Verestro Paytool solution along with it's responsibility. ### Verestro Paytool Server Verestro Paytool Server is the backend component which consists of few internal services responsible for managing cards, card payment tokens and user data, processing transactions and 3D Secure, send notification to the Customer and enduser and storing transaction history. This component is also responsible for connection with Acquirers. Services included in the Verestro Paytool backend can be divided into two groups:

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...

### Verestro Paytool Frontend Verestro Paytool Frontend is the frontend component consists of two internal services which are responsible for displaying all necessary data comming from Paytool API. Verestro Paytool Frontend can be divided into two services:

**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.

### Allowed card networks Listed below are the types of cards supported in transactions using Paytool application:

**Card type**

`MASTERCARD`

`VISA`

`MAESTRO`

## Security Due to the need to process card data and perform money operations, we had to create security measures that would not allow violations of the transaction process and prevent unauthorized entities from using the solution. In this chapter, we described the main security elements for customers and their transactions.

The sequence diagram below illustrates the application workflow

@startuml skinparam ParticipantPadding 30 skinparam BoxPadding 30 skinparam noteFontColor #FFFFFF skinparam noteBackgroundColor #1C1E3F skinparam noteBorderColor #1C1E3F skinparam noteBorderThickness 1 skinparam sequence { ArrowColor #1C1E3F ArrowFontColor #1C1E3F ActorBorderColor #1C1E3F ActorBackgroundColor #FFFFFF ActorFontStyle bold ParticipantBorderColor #1C1E3F ParticipantBackgroundColor #1C1E3F ParticipantFontColor #FFFFFF ParticipantFontStyle bold LifeLineBackgroundColor #1C1E3F LifeLineBorderColor #1C1E3F } participant "Customer Frontend" as browser participant "Customer Backend" as psdk participant "Paytool Frontend" as pfront participant "Paytool Backend" as pback participant "Acquirer" as acq note right of browser: User chooses "Pay with Verestro Paytool" browser->psdk: Transaction initialization + metadata psdk-->pback: Transaction initialization + metadata pback->pback: Validate transaction metadata pback->pback: Store transaction session data pback->psdk: OK + transactionId psdk->pfront: Redirect end user to Paytool Frontend + transactionId pfront-->pback: Get transaction metadata + list of the supported payment options pback-->pfront: Return transaction metadata + list of the supported payment options pfront->pfront: Display transaction metadata + list of the supported payment options pfront->pback: Process transaction by chosen payment option pback->pback: Consisteny validation between current transaction data and provided when opening the session pback->acq: Order transaction @enduml

### Payment session In order to start a payment in Paytool, a payment session must first be opened. Opening a payment session involves authorizing your merchant account and sending transaction metadata to Paytool API. Transaction metadata should be encrypted using JWE encryption standard. Based on the obtained transaction data, validation of each data is performed and then a transaction object is created and saved in the internal Verestro database. Thanks to authorization, the context of your merchant account is assigned to the created transaction. Once you have created a payment session, you will receive an identifier for this transaction. Using this identifier you will be able to continue the payment process and we will be able to check whether there has been any interference in the transaction data you provided and interrupt the process if necessary.

**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:

[![image-1687851731553.png](https://developer.verestro.com/uploads/images/gallery/2023-06/scaled-1680-/image-1687851731553.png)](https://developer.verestro.com/uploads/images/gallery/2023-06/image-1687851731553.png)

[![image-1713956541731.png](https://developer.verestro.com/uploads/images/gallery/2024-04/scaled-1680-/image-1713956541731.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.

The sequence diagram below illustrates the transaction initialization process step by step

### Server to server An alternative path to carry out a transaction is a [Payment process via API](https://developer.verestro.com/books/paytool/page/overview#bkmrk-payment-process-via-) integration path. Paytool Frontend does not appear in this path. You make all requests directly from your server to the Paytool API methods we described in [technical integration guide](https://developer.verestro.com/books/paytool/page/how-to-integrate).

The sequence diagram below illustrates the transaction initialization process step by step

## Payment methods Verestro as a PSP provides several different payment methods in Paytool solution. You decide which payment method should be available in Paytool payment form. You decide this during the [onboarding](https://developer.verestro.com/books/merchant-paytool/page/onboarding) process but it is editable whenever necessary. The end user, seeing the available payment methods, can choose the option that is most convenient for him. This chapter describes all payment methods supported by our application.

**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: [![image-1685428055821.png](https://developer.verestro.com/uploads/images/gallery/2023-05/scaled-1680-/image-1685428055821.png)](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: [![image-1713956617464.png](https://developer.verestro.com/uploads/images/gallery/2024-04/scaled-1680-/image-1713956617464.png)](https://developer.verestro.com/uploads/images/gallery/2024-04/image-1713956617464.png)

The sequence diagram below illustrates the transaction with plain card details process step by step

@startuml skinparam ParticipantPadding 30 skinparam BoxPadding 30 skinparam noteFontColor #FFFFFF skinparam noteBackgroundColor #1C1E3F skinparam noteBorderColor #1C1E3F skinparam noteBorderThickness 1 skinparam sequence { ArrowColor #1C1E3F ArrowFontColor #1C1E3F ActorBorderColor #1C1E3F ActorBackgroundColor #FFFFFF ActorFontStyle bold ParticipantBorderColor #1C1E3F ParticipantBackgroundColor #1C1E3F ParticipantFontColor #FFFFFF ParticipantFontStyle bold LifeLineBackgroundColor #1C1E3F LifeLineBorderColor #1C1E3F } actor "End User" as user participant "Paytool Frontend" as pfront participant "Paytool Backend" as pback participant "Customer Server" as custback participant "Acquirer" as acq user->pfront: User chooses payment by plain card details user<-pfront: Redirect end user to the payment form user->pfront: User filling data (CN, CVC, EXP) pfront->pfront: Encrypt data pfront->pback: Perform transaction providing encrypted payment request body pback->pback: Decrypt encrypted payment request body pback->acq: Order transaction note left of acq: At this point 3D Secure process may occur acq->pback: Response pback->pfront: Transaction Result pback-->pback: Store transaction result pfront->pfront: Redirect end user (success/failure) pback->custback: Send transaction postback to provided URL (optional - configurable) note right of pback: Verestro can also send the notification after transaction to the end user(optional) custback->pback: Get transaction status (optional) pback->custback: Return transaction status @enduml

### Google Pay Paytool as a registered hosted checkout in the Google Pay™ allows to perform a payment with the card from the Google Pay™ Wallet. Using our application your payer can choose the Google Pay™ as the payment method from the Verestro Paytool payment methods list. The option to pay with Google Pay™ card token is available at the button shown below: [![image-1685428002241.png](https://developer.verestro.com/uploads/images/gallery/2023-05/scaled-1680-/image-1685428002241.png)](https://developer.verestro.com/uploads/images/gallery/2023-05/image-1685428002241.png) After clicking on the Google Pay™ payment option, the Google Pay™ Wallet popup is displayed. The payer should select the appropriate card from the Google Pay™ Wallet which is then encrypted on the Google Pay™ side and transferred to our application. We will 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 but it will be handled on our side. The payment process using Google Pay™ card payment token from the end user's perpective has been shown below: [![image-1689246683126.png](https://developer.verestro.com/uploads/images/gallery/2023-07/scaled-1680-/image-1689246683126.png)](https://developer.verestro.com/uploads/images/gallery/2023-07/image-1689246683126.png)

The sequence diagram below illustrates the payment process using Google Pay™ card payment token step by step

@startuml skinparam ParticipantPadding 30 skinparam BoxPadding 30 skinparam noteFontColor #FFFFFF skinparam noteBackgroundColor #1C1E3F skinparam noteBorderColor #1C1E3F skinparam noteBorderThickness 1 skinparam sequence { ArrowColor #1C1E3F ArrowFontColor #1C1E3F ActorBorderColor #1C1E3F ActorBackgroundColor #FFFFFF ActorFontStyle bold ParticipantBorderColor #1C1E3F ParticipantBackgroundColor #1C1E3F ParticipantFontColor #FFFFFF ParticipantFontStyle bold LifeLineBackgroundColor #1C1E3F LifeLineBorderColor #1C1E3F } actor "End User" as user participant "Paytool Frontend" as pfront participant "Paytool Backend" as pback participant "Google Pay" as gpay participant "Customer Server" as custback participant "Acquirer" as acq user->pfront: End user chooses payment by Google Pay pfront->gpay: Open end user Google Wallet user<--gpay: Opens end user's Google Wallet user-->gpay: Choose card from Google Wallet gpay->gpay: Encrypt chosen card token data pfront<-gpay: Provide encrypted card token data pfront->pback: Order transaction pfront-->pback: Provide encrypted card token data pback->pback: Decrypt encrypted card token data pback->acq: Order transaction note left of acq: At this point 3D Secure process may occur acq->pback: Response pback->pfront: Transaction Result pback-->pback: Store transaction result pfront->pfront: Redirect end user (success/failure) pback->custback: Send transaction postback to provided URL (optional - configurable) note right of pback: Verestro can also send the notification after transaction to the end user (optional) custback->pback: Get transaction status (optional) pback->custback: Return transaction status @enduml

#### Google Pay payment via API Alternatively Verestro as a registered PSP in the Google Pay™ allows to perform a payment with card token generated by Google. This payment option provides a backend to backend oriented solution. In this payment model you must be [registered merchant in Google Pay™](https://developer.verestro.com/books/paytool/page/onboarding#bkmrk-register-and-integra) to be able to get a card payment token from Google Pay™. To use this option your API should be integrated with the `googlePayTransaction` method provided by Paytool API. By using this solution you need to display Google Pay™ Wallet in your application by your own. After selecting the Google Pay™ as the payment option a payer chooses proper card from Google Pay™ Wallet. After that action you get encrypted card payment token from Google Pay™. Card payment token is encrypted on the Google Pay™ side with Verestro's public key. You have to provide this encrypted token to Paytool API by using `googlePayTransaction` method. If you do this, we will handle transaction process on our side. At this moment 3D Secure process may be required and you need to handle it on your side using [threeDs authentication](https://developer.verestro.com/books/paytool/page/use-cases#bkmrk-threeds) methods provided by Paytool API.

The sequence diagram below illustrates the payment process using Google Pay™ card payment token API to API step by step

**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: [![image-1699524383207.png](https://developer.verestro.com/uploads/images/gallery/2023-11/scaled-1680-/image-1699524383207.png)](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: [![image-1699526152020.18.03.png](https://developer.verestro.com/uploads/images/gallery/2023-11/scaled-1680-/image-1699526152020-18-03.png)](https://developer.verestro.com/uploads/images/gallery/2023-11/image-1699526152020-18-03.png)

The sequence diagram below illustrates the payment process using Apple Pay™ card payment token step by step

@startuml skinparam ParticipantPadding 30 skinparam BoxPadding 30 skinparam noteFontColor #FFFFFF skinparam noteBackgroundColor #1C1E3F skinparam noteBorderColor #1C1E3F skinparam noteBorderThickness 1 skinparam sequence { ArrowColor #1C1E3F ArrowFontColor #1C1E3F ActorBorderColor #1C1E3F ActorBackgroundColor #FFFFFF ActorFontStyle bold ParticipantBorderColor #1C1E3F ParticipantBackgroundColor #1C1E3F ParticipantFontColor #FFFFFF ParticipantFontStyle bold LifeLineBackgroundColor #1C1E3F LifeLineBorderColor #1C1E3F } actor "End User" as user participant "Paytool Frontend" as pfront participant "Paytool Backend" as pback participant "Apple Pay" as gpay participant "Customer Server" as custback participant "Acquirer" as acq user->pfront: End user chooses payment by Apple Pay pfront->gpay: Open end user's Apple Pay Wallet user<--gpay: Opens end user's Apple Pay Wallet user-->gpay: Choose card from Apple Pay Wallet note left of user: At this point Apple Pay may require user authorization gpay->gpay: Encrypt chosen card token data pfront<-gpay: Provide encrypted card token data pfront->pback: Order transaction pfront-->pback: Provide encrypted card token data pback->pback: Decrypt encrypted card token data pback->acq: Order transaction note left of acq: At this point 3D Secure process may occur acq->pback: Response pback->pfront: Transaction Result pback-->pback: Store transaction result pfront->pfront: Redirect end user (success/failure) pback->custback: Send transaction postback to provided URL (optional - configurable) note right of pback: Verestro can also send the notification after transaction to the end user (optional) custback->pback: Get transaction status (optional) pback->custback: Return transaction status @enduml

**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: [![image-1685523665104.png](https://developer.verestro.com/uploads/images/gallery/2023-05/scaled-1680-/image-1685523665104.png)](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:

[![image-1687851945379.png](https://developer.verestro.com/uploads/images/gallery/2023-06/scaled-1680-/image-1687851945379.png)](https://developer.verestro.com/uploads/images/gallery/2023-06/image-1687851945379.png)

[![image-1687852047098.png](https://developer.verestro.com/uploads/images/gallery/2023-06/scaled-1680-/image-1687852047098.png)](https://developer.verestro.com/uploads/images/gallery/2023-06/image-1687852047098.png)

The sequence diagram below illustrates the payment process using Blik step by step

@startuml skinparam ParticipantPadding 30 skinparam BoxPadding 30 skinparam noteFontColor #FFFFFF skinparam noteBackgroundColor #1C1E3F skinparam noteBorderColor #1C1E3F skinparam noteBorderThickness 1 skinparam sequence { ArrowColor #1C1E3F ArrowFontColor #1C1E3F ActorBorderColor #1C1E3F ActorBackgroundColor #FFFFFF ActorFontStyle bold ParticipantBorderColor #1C1E3F ParticipantBackgroundColor #1C1E3F ParticipantFontColor #FFFFFF ParticipantFontStyle bold LifeLineBackgroundColor #1C1E3F LifeLineBorderColor #1C1E3F } actor "End User" as user participant "Paytool Frontend" as pfront participant "Paytool Backend" as pback participant "Acquirer" as acq participant "Blik" as blik participant "Customer Server" as custback user->pfront: End user chooses payment by Blik (1) pfront->pback: Requests for payment by Blik (2) pback->acq: Orders Blik transaction (3) acq->blik: Internal request to Blik system (4) acq<-blik: Response from Blik system with HTML payment Base64 encoded form (5) pback<-acq: Provides Blik's response (5.1) pfront<-pback: Provides Blik's response (5.2) pfront->pfront: Decode Blik HTML form (6) user<-pfront: Displays Blik HTML form (7) user->user: Enters Blik's 6 digits code (8) user-->blik: After form submitting request to Blik system is triggered (9) pfront<--blik: Redirects to Paytool Frontend (10) user<--pfront: Shows progress bar because the user has to wait for transaction status (11) acq<--blik: Webhook with information about Blik's transaction status (12) pback<--acq: Webhook with information about Blik's transaction status (12.1) pfront->pback: Get status of the Blik transaction (13) pfront<-pback: Provides Blik transaction status (14) user<-pfront: Displays transaction status (15) custback<--pback: Send transaction postback to provided URL (16) (optional - configurable) @enduml

## ThreeDs authentication Transactions using payment cards usually require additional authentication of the end user (card holder). In accordance with the Europenian Union directive PSD2, the Paytool solution uses the threeDs protocol version 2.0 for the authentication process. The threeDs process consists in asking the card issuer whether additional authentication of the card holder is necessary or not. It depends on the bank's response whether the threeDs process will be necessary to perform. This is determined by one of two statuses that the bank returns during the transaction process: [`FRICTIONLESS`](https://developer.verestro.com/books/paytool/page/use-cases#bkmrk-%40startumlskinparam-p-2) or [`CHALLENGE`](https://developer.verestro.com/books/paytool/page/use-cases#bkmrk-challenge). The meaning of each status is described in the section [ThreeDs modes](https://developer.verestro.com/books/paytool/page/use-cases#bkmrk-threeds-modes). We take responsibility for performing the threeDs authentication process. The sequence diagrams below illustrates the threeDs authentication process step by step separatly for both cases: [`FRICTIONLESS`](https://developer.verestro.com/books/paytool/page/use-cases#bkmrk-%40startumlskinparam-p-2) or [`CHALLENGE`](https://developer.verestro.com/books/paytool/page/use-cases#bkmrk-challenge). ### ThreeDs modes

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.

#### `FRICTIONLESS` In this threeDs mode there is not any additional action from the end user side required.

The sequence diagram below illustrates the threeDs process for frictionless mode step by step

#### `CHALLENGE` In this threeDs mode the end user authentication is required. Authentication takes place on the threeDs bank template displayed by the Verestro Paytool application to the end user during the transaction process.

The sequence diagram below illustrates the threeDs process for challenge mode step by step

@startuml skinparam ParticipantPadding 30 skinparam BoxPadding 30 skinparam noteFontColor #FFFFFF skinparam noteBackgroundColor #1C1E3F skinparam noteBorderColor #1C1E3F skinparam noteBorderThickness 1 skinparam sequence { ArrowColor #1C1E3F ArrowFontColor #1C1E3F ActorBorderColor #1C1E3F ActorBackgroundColor #FFFFFF ActorFontStyle bold ParticipantBorderColor #1C1E3F ParticipantBackgroundColor #1C1E3F ParticipantFontColor #FFFFFF ParticipantFontStyle bold LifeLineBackgroundColor #1C1E3F LifeLineBorderColor #1C1E3F } actor "End User" as user participant "Paytool Frontend" as pfront participant "Paytool Backend" as pback participant "Acquirer" as acq participant "Bank" as bank user->pfront: End user confirmed transaction (1) note right of user: For example the end user choosed payment with plain card number (1.1) pfront->pback: Provide transaction request to perform (2) pback->acq: Provide transaction request to perform (3) acq->bank: contact with end user's bank (4) bank->acq: Return CHALLENGE status along with bank HTML template (5) acq->pback: Provide bank's response (6) pback->pfront: Provide bank's response (6.1) pfront->pfront: Decode bank HTML template (7) pfront->user: Display bank content to the end user (8) user-->bank: Perform 3DS authentication (9) user<--bank: Authentication succeed (10) acq<-bank: Provide success status and authentication ID (11) pback<-acq: Provide success status and authentication ID (11.1) pfront<-pback: Provide success status and authentication ID (11.2) pfront->pback: Finalize transaction and provide authentication ID (12) pback->acq: Finalize transaction and provide authentication ID (12.1) acq->bank: Finalize transaction (12.2) bank->acq: Transaction succeed (13) acq->pback: Provide transaction status (14) pback->pfront: Provide transaction status (15) pfront->user: Display transaction status (16) @enduml

## Transaction result Depending on whether the transaction was successful or not, the end user will see the appropriate status on the screen. From the status screen, he is able to return to the store's website manually - by clicking the **Return to the shop** button or wait for an automatic redirection. At the same time, we will send you post-transaction notification containing the status and details of the transaction. Depending on the configuration of your merchant account, an e-mail notification may be sent to the end user. Transaction status views from the end user's perspective are presented below:

[![image-1684330553924.png](https://developer.verestro.com/uploads/images/gallery/2023-05/scaled-1680-/image-1684330553924.png)](https://developer.verestro.com/uploads/images/gallery/2023-05/image-1684330553924.png)

[![image-1684330621724.png](https://developer.verestro.com/uploads/images/gallery/2023-05/scaled-1680-/image-1684330621724.png)](https://developer.verestro.com/uploads/images/gallery/2023-05/image-1684330621724.png)

### Notification after transaction As mentioned in the [Transaction result](https://developer.verestro.com/books/paytool/page/use-cases#bkmrk-notifications) chapter, Paytool solution supports the sending of post-transaction notifications informing you about the status of a given transaction made in your context. This functionality is optional and it is up to you to decide whether you want to receive post-transaction notifications. This decision is made during the [onboarding](https://developer.verestro.com/books/merchant-paytool/page/onboarding) process and always can be edited. We recommend using this functionality, as this allow you to receive information on each of the transactions made using Verestro Paytool.

**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.

Post-transaction notification example sent by Verestro Paytool to the Customer

```json { "transactionId": "string", "orderNumber": "9afds032dad", "transactionState": "FAILED", "amount": 0, "message": "string", "currency": "string", "externalTransactionId": "string", "transactionType": "ONE_TIME_PAYMENT", "cardDetails": { "cardProvider": "MASTERCARD", "cardNumber": "512485******4875" }, "failedDetails": { "code": "SYSTEM_ERROR", "message": "E0200: Transaction rejected, card is blocked" } } ```

### End user notifications As mentioned in the [Transaction result](https://developer.verestro.com/books/paytool/page/use-cases#bkmrk-notifications) chapter, Paytool solution supports an e-mail notification sending. Such notification contains the status and details of the transaction. This message is purely informative so that the payer knows that a transaction has been made in the context of his chosen payment instrument. This functionality is optional and it is up to you to decide whether you us to send end users notifications after the transaction. This decision is made during the [onboarding](https://developer.verestro.com/books/merchant-paytool/page/onboarding) process and always can be edited.

**Note:** The appearance of the e-mail notification is configurable.

Example e-mail notification after successful transaction

Example e-mail notification after failed transaction

[![image-1689254790584.png](https://developer.verestro.com/uploads/images/gallery/2023-07/scaled-1680-/image-1689254790584.png)](https://developer.verestro.com/uploads/images/gallery/2023-07/image-1689254790584.png)

[![image-1689254800782.png](https://developer.verestro.com/uploads/images/gallery/2023-07/scaled-1680-/image-1689254800782.png)](https://developer.verestro.com/uploads/images/gallery/2023-07/image-1689254800782.png)

# Onboarding This chapter is intended to present you the requirements that will allow you to use the Paytool solution in your application. We have presented here what information is necessary to provide so that you can join the Paytool program and so that we can properly create the required merchant account for you in our system. ### Business onboarding

**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.

### Technical onboarding

**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.

### Register in Google Pay™

**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

# How to integrate This chapter provides the instruction of the integration with the solution and with it's methods. Prior to using this solution is you have to proceed [onboarding](https://developer.verestro.com/books/paytool/page/onboarding) process and you require created account in the Verestro Paytool system.

**Note:** To create an account in the Verestro Paytool system please contact with support.

Environment Test API base URL

``` https://paytool-api.verestro.dev ```

Environment Production API base URL

``` https://paytool-api.verestro.com ```

**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.

Integration method consisting in redirecting the payer to Paytool web view

Integration method consisting in continuing process via API calls

**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.

**Tip:** API to API integration path documentation is also [available here](https://paytool-api.verestro.dev/swagger-ui/index.html#/) in SwaggerUI format.

## 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:** Detailed information about what is included in the transaction metadata is shown in the `transactionInitialization` method.

### Transaction initialization 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.

POST /external-api/transactions

Headers
Key	Value
`Content-Type`	`application/json`
`Basic-Authorization`	`Basic dXNlcm5hbWU6cGFzc3dvcmQ=`

Example request body in JSON format

```json { "currencyCode": "PLN", "amount": 1000, "receiverAmount": 1000, "description": "Preinit for trx", "merchantUrl": "https://merchanturl.verestro.com", "notificationUrl": "https://custom-merchant-notificationurl.com", "orderNumber": "fgugbb4gd665564", "formLanguage": "pl", "redirectUrl": { "successUrl": "https://successurl.verestro.com/paytool/redirection/success", "failureUrl": "https://failureurl.verestro.com/paytool/redirection/success" }, "sender": { "firstName": "John", "lastName": "Doe", "address": { "countryCode": "PL", "city": "Warszawa", "postalCode": "03-672", "street": "Promienna", "houseNumber": "10" } }, "transactionConfigurationId": "dc387e4e-885e-455f-9dd9-c7cad002b476", "autoDeposit": true, "validityTime": 2 } ```

Parameter	Type	Description
`currencyCode`	string required	Currency for transaction (in accordance with 3-digit ISO-4217), example: USD
`amount`	number required	Field determining amount of cash transferred in one hundredth of the currency. \[1,00 USD = 100\]
`orderNumber`	string required	Declarative number of order that is just purchased by cardholder, set by merchant, should be unique.
`receiverAmount`	number	Information field only. Field determine receiving amount of cash transferred in one hundredth of the currency. \[1 USD = 100\]
`description`	string	Description of the transaction.
`formLanguage`	string	Language of transaction process in web browser, use only lowercase.
`notificationUrl`	string	URL address of merchant web system to which the notification will be sent after the transaction is completed. When notificationUrl is null, the value from the merchant configuration will be used.
`redirectUrl`	object	Object containing URL addresses where payer should be redirected after transaction finalization depending on transaction status. Adress may be the same in both fields: `successUrl` and `failureUrl`
`successUrl`	string	URL of merchant web service to forward after successful transaction flow.
`failureUrl`	string	URL of merchant web service to forward after failed transaction flow
`sender`	object	Object containing datailed payer's data.
`sender.firstName`	string	Payers's first name.
`sender.lastName`	string	Payers's last name.
`sender.address`	object	Payer's address.
`sender.address.countryCode`	string	Two character ISO 3166-1 alpha-2 code of country. For example: PL
`sender.address.city`	string	Payer's city.
`sender.address.postalCode`	string	Payer's postal code.
`sender.address.street`	string	Payer's street.
`sender.address.houseNumber`	string	Payer's house number.
`transactionConfigurationId`	string	A parameter pointing to a given terminal in the merchant's configuration. If it is not passed, the transaction will be executed in the context of the default merchant terminal.
`autoDeposit`	boolean	Flag specifying whether the funds will be immediately withdrawn from the payer's account after the transaction. If the value is `false`, the funds will be frozen on the payer's account and will wait for the [`deposit`](https://developer.verestro.com/books/paytool/page/how-to-integrate#bkmrk-refund) to be made. If the [`deposit`](https://developer.verestro.com/books/paytool/page/how-to-integrate#bkmrk-refund) is not made, the funds will be returned to the payer.
`validityTime`	number	Through this field, we can specify expiration time for transaction in minutes. If this parameter has not been provided, it will be taken from Merchant configuration.

Example response body in JSON format - 200 - OK

```json { "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ```

Parameter	Type	Description
`transactionId`	string($uuid)	The identifier of transaction assigned by Paytool system after transaction preinitialization occurrence.

Possible errors

Errors that may occur when attempting to initialize transaction:

404 - Not found

```json { "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "traceId": "8fc17b6c-6995-4d33-a4f5-93e99b8af2b2", "errorType": "MERCHANT_NOT_EXISTS", "merchantStatus": "Merchant entity with typed UUID: 3fa85f64-5717-4562-b3fc-2c963f66afa6 not exists in database" } ```

Parameter	Type	Description
`uuid`	string	The identifier of transaction assigned by Paytool system after transaction preinitialization occurrence.
`traceId`	string	Identifier of the occured error.
`errorType`	string	Type of the occured error: - MERCHANT\_NOT\_EXISTS
`message`	string	Description of the occured error.

409 - Conflict

```json { "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "traceId": "8fc17b6c-6995-4d33-a4f5-93e99b8af2b2", "errorType": "ENTITY_EXISTS", "merchantStatus": "Pre initialization with typed UUID: 3fa85f64-5717-4562-b3fc-2c963f66afa6 exists in database" } ```

Parameter	Type	Description
`uuid`	string	The identifier of transaction assigned by Paytool system after transaction preinitialization occurrence.
`traceId`	string	Identifier of the occured error.
`errorType`	string	Type of the occured error: - ENTITY\_EXISTS
`message`	string	Description of the occured error.

500 - Internal server error

```JSON { "date": "2023-09-26 13:51:40.869246", "traceId": "8fc17b6c-6995-4d33-a4f5-93e99b8af2b2", "errorType": "INTERNAL_SERVER_ERROR", "message": "Internal server error occured." } ```

Parameter	Type	Description
`date`	string($date-time)	Timestamp of the occured error.
`traceId`	string	Identifier of the occured error.
`errorType`	string	Type of the occured error: - INTERNAL\_SERVER\_ERROR
`message`	string	Description of the occured error.

### 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.

POST /external-api/transactions/google-pay

Headers
Key	Value
`Content-Type`	`application/json`
`Basic-Authorization`	`Basic dXNlcm5hbWU6cGFzc3dvcmQ=`

Example request body in JSON format

```json { "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "token": { "signature": "MEYCIQDypF11YBH1coN5ZUadvPzkqvlJzV2TgtCZZcK9jpY14QIhAKnNp4iPAfUNMgMyew/RCjIpFhph7He8kwgilSmQ+iCL", "intermediateSigningKey": { "signedKey": "{\"keyValue\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEFTC7wcoKdNZaC8nMT+okwTe3X+0BdS2PHQg8wMBj+hFyXCZZ03D6Q0WC6Hj2Opc77pZidc1dLQpb4CyvYiB7rQ\\u003d\\u003d\",\"keyExpiration\":\"1692395417939\"}", "signatures": [ "MEUCIElbkp4lt6lQ6JFT9aZygQX9K2nYb4pEdqQtPjFTde5MAiEAqcQ0OQZ+8xNYY2AWXz+RgycyAtAr3ZiRkmE3NYCRGJ4=" ] }, "protocolVersion": "ECv2", "signedMessage": "{\"encryptedMessage\":\"Kbe6TjKavqbk9lsjaJB20hufV+l6Vpm3j+8djXUO9gNalFHUDFF3CS/f1KvzPVirRHZGFft+XlzrlabKhtbvfKuN9Hotp5h5csPngGUMabYAx+m5MU8X+Y98v7kueozLVuxMjPmUonWGmQxO0l7pqdVfOJPO2GckAyxRd9EBHoaC2CJjo1IAJzFdjuEdjMS4GoHU15n8iM8fJVrmeagmaZ4H8zcdo9WnuQbQ00HIHnczdyGTLeglTq8dY3lSE+WjrirqvwRfXbRSsfXmp+QQtvLAR9ZW6ula2xwp5Nz14atYGKJFk9OOcF+cdoGrzlyU0ruWEVhUeBEJzRiiSdL2xk9SK3hL+itpmxEFKL27Cibo2VHmo8MpgTxgftGTDwCnENgq6ZRf6deazHe8I/Un8QTBKO5JxLyvvUKVLWqaz1nqaCfDcRK4SM3yRejgOaJPV/vy/joygyHS+UNjw71dy9/UcdVxJ8oQlG/34NUl9tCMYn5N9aSd8qPJcnf5PzJQpgUXZwoGgBT5Wi7zdSrTF4RH6wMODH5IjLkSbD86s6RtjP2z+WZb9n2YwTdtlojgyD/BNBv3GA\\u003d\\u003d\",\"ephemeralPublicKey\":\"BLX9MA6SWxduIZyxoNHVaj0L0H4WtJfX10MTQe3bii/vAIjrB3Kfa6OiWw+BX+QwFRyfwEENJjOiN0EDqIxLQk8\\u003d\",\"tag\":\"Jxdb9OuKwqn6baKiAnpJpB+FumFXHbHho3xnacK5o6A\\u003d\"}" }, "sender": { "firstName" : "John", "lastName" : "Doe", "email" : "test@verestro.com" "language":{ "language" : "PL" }, "threeDsData": { "cavv": "sdf", "eci": "01", "authenticationStatus": "Y", "transactionXId": "9734301f-4025-4e91-81b2-f74e64f40037" } } ```

Parameter	Type	Description
`transactionId`	string($uuid) required	The identifier of transaction assigned by Paytool system after transaction preinitialization occurrence.
`token`	object required	Object containing all data of the encrypted card payment token obtained by Customer from Google Pay.
`token.signature`	string	Google Pay token signature.
`token.protocolVersion`	string	Version of the protocol.
`token.signedMessage`	string	Message encrypted by Verestro public key.
`token.intermediateSigningKey`	object	Object containing key and signature.
`token.intermediateSigningKey.signedKey`	string	Key used to verification of the signature.
`token.intermediateSigningKey.signatures`	list<string>	Verification signature.
`sender`	object required	Object containing payer's data.
`sender.firstName`	string	Payer's first name.
`sender.lastName`	string	Payer's last name.
`sender.email`	string	Email address of the payer.
`threeDsData`	object	Outside 3ds data authorization that have been send to our API.
`threeDsData.cavv`	string	This property is determined by the Access Control Server. This property will be valid if the TransactionStatus is "Y" or "A". The value may be used to provide proof of authentication.
`threeDsData.eci`	string	This property is determined by the Access Control Server. This property contains the two digit Electronic Commerce Indicator (ECI) value, which is to be submitted in a credit card authorization message. This value indicates to the processor that the customer data in the authorization message has been authenticated. The data contained within this property is only valid if the TransactionStatus is "Y" or "A".
`threeDsData.authenticationStatus`	string	Status of the 3D Secure authentication.
`threeDsData.transactionXId`	string	External transaction Id assigned by the Acquirer.

Example response body in JSON format - 200 - OK

```json { "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "transactionState": "COMPLETED" } ```

Parameter	Type	Description
`transactionId`	string($uuid)	The identifier of transaction assigned by Paytool system after transaction preinitialization occurrence.
`transactionState`	string	TransactionState is a main parameter that indicates state of transaction: - 'COMPLETED' - we are sure that transaction passed correctly. - 'FAILURE' - transaction surely not passed with paytool internal error or with processing error from acquirer. - 'IN\_PROGRESS' - when transaction is in this state we are need to continue process - wait for challenge etc.

Possible errors

Errors that may occur when attempting to order Google Pay transaction:

404 - Not found

Parameter	Type	Description
`uuid`	string	The identifier of transaction assigned by Paytool system after transaction preinitialization occurrence.
`traceId`	string	Identifier of the occured error.
`errorType`	string	Type of the occured error: - MERCHANT\_NOT\_EXISTS
`message`	string	Description of the occured error.

500 - Internal server error

```JSON { "date": "2023-09-26 13:51:40.869246", "traceId": "8fc17b6c-6995-4d33-a4f5-93e99b8af2b2", "errorType": "THREE_DS_REQUIRED", "message": "Google Pay token payment with PAN_ONLY authMethod parameter - 3DS is required" } ```

Parameter	Type	Description
`date`	string($date-time)	Timestamp of the occured error.
`traceId`	string	Identifier of the occured error.
`errorType`	string	Type of the occured error: - INTERNAL\_SERVER\_ERROR - THREE\_DS\_REQUIRED - EXTERNAL\_PAYMENT\_SERVICE\_ERROR
`message`	string	Description of the occured error.

### 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 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.

GET /transactions/details/{transactionId}

Headers
Key	Value
`Content-Type`	`application/json`
`Basic-Authorization`	`Basic dXNlcm5hbWU6cGFzc3dvcmQ=`

Query parameter	Value
`transactionId`	``

Example response body in JSON format - 200 - OK

```json { "transactionId": "5755a7a4-490f-4a83-ad25-535fbe9d7443", "orderNumber": "fgugbb4gd665564", "transactionState": "SUCCESS", "externalId": "5755a7a4-490f-4a83-ad25-535fbe9d7443", "merchantName": "Merchant", "amount": 2599, "currencyCode": "PLN", "description": "Transaction description", "transactionType": "ONE_TIME_PAYMENT", "cardDetails": { "cardProvider": "MASTERCARD", "cardNumber": "512485******4875" }, "failedDetails": { "code": "SYSTEM_ERROR", "message": "E0200: Transaction rejected, card is blocked" }, "merchantUuid": "1361d514-943b-11ee-b9d1-0242ac120002" } ```

Parameter	Type	Description
`transactionId`	string($uuid)	The identifier of transaction assigned by Paytool system after transaction initialization occurrence.
`orderNumber`	string	The identifier of transaction assigned by Customer. Should be unique.
`transactionState`	string	Transaction result. There are three statuses: - COMPLETED - transaction finished with success - FAILED - transaction finished with failure - IN\_PROGRESS - transaction not yet finished
`externalId`	string	The identifier of the transaction processed by Acquirer.
`merchantName`	string	The name of the Customer's merchant account in Paytool system.
`amount`	number	The amount of transaction in pennies, for instance: 1000 = 10.00$
`currencyCode`	string	ISO 4217 Alpha-2 currency code for example: PLN, EUR, USD
`description`	string	The description of the transaction provided by Customer.
`transactionType`	string	The type of method used for make transaction. Possible transaction types: - ONE\_TIME\_PAYMENT - payment with bare card number - GOOGLE\_PAY - payment using Google Pay Wallet - APPLE\_PAY - payment using Apple Pay Wallet - BLIK - payment using Blik code
`cardDetails`	object	The object containing card data.
`cardDetails.cardProvider`	string	The type of the card used to transaction. Possible card providers: - MASTERCARD - VISA - MAESTRO
`cardDetails.cardNumber`	string	Masked card number. BIN and last four digits of the card number has been shown.
`failedDetails`	object	Object containing more detailed information about transaction's fail reason. This object remains empty if transaction was successfully completed.
`failedDetails.code`	string	Transaction's fail code/status.
`failedDetails.message`	string	Transaction's fail message.
`merchantUuid`	string($uuid)	UUID of the Customer's merchant account in Paytool system. Required for passing in next request.

Possible errors

Errors that may occur when attempting to retrieve transaction details:

The below table defines the status codes that this method may return

[![image-1702896831130.png](https://developer.verestro.com/uploads/images/gallery/2023-12/scaled-1680-/image-1702896831130.png)](https://developer.verestro.com/uploads/images/gallery/2023-12/image-1702896831130.png)

401 - Unauthorized

```JSON { "timestamp": "2023-03-29T19:16:01.288+00:00", "status": 401, "error": "Unauthorized", "path": "/api/v1/transactions/9609a08e-cd80-4e6e-8664-f1e6b2f2dc50" } ```

Parameter	Type	Description
`timestamp`	string($date-time)	Timestamp of the occured error.
`status`	numeric	Numeric HTTP code of the occured error.
`error`	string	Description of HTTP status of the occured error.
`path`	string	Requested endpoint's path

**Warning:** The structure of this error is different from other errors

404 - Not found

```JSON { "date": "2023-09-26 13:51:40.869246", "traceId": "9f4c5101-6d78-4c80-9e79-3b2060c227ad", "errorType": "TRANSACTION_NOT_EXISTS", "message": "Transaction with transactionId: a39cc08a-5458-4b05-868d-3c484c9f601e not exists" } ```

Parameter	Type	Description
`date`	string($date-time)	Timestamp of the occured error.
`traceId`	string	Identifier of the occured error.
`errorType`	string	Enum type of the occured error.
`message`	string	Description of the occured error.

500 - Internal server error

```JSON { "date": "2023-09-26 13:51:40.869246", "traceId": "8fc17b6c-6995-4d33-a4f5-93e99b8af2b2", "errorType": "EXTERNAL_PAYMENT_SERVICE_ERROR", "message": "Initialize transaction process ends with some critical failure caused by error in request to external service" } ```

Parameter	Type	Description
`date`	string($date-time)	Timestamp of the occured error.
`traceId`	string	Identifier of the occured error.
`errorType`	string	Enum type of the occured error.
`message`	string	Description of the occured error.

### Transaction 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.

**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.

**Note:** You should provide postback endpoint during the [onboarding](https://developer.verestro.com/books/verestro-paytool/page/onboarding) process.

POST https://customer-notification-endpoint.com/postback

Headers
Key	Value
`Content-Type`	`application/json`

Example request body in JSON format

```JSON { "transactionId": "string", "orderNumber": "9afds032dad", "transactionState": "FAILED", "amount": 0, "message": "string", "currency": "string", "externalTransactionId": "string", "transactionType": "ONE_TIME_PAYMENT", "cardDetails": { "cardProvider": "MASTERCARD", "cardNumber": "512485******4875" }, "failedDetails": { "code": "SYSTEM_ERROR", "message": "E0200: Transaction rejected, card is blocked" } } ```

Parameter	Type	Description
`transactionId`	string	Customer's external, custom transaction identifier. We are recommending to use random UUID.
`orderNumber`	string	The identifier of transaction assigned by Customer. Should be unique.
`transactionState`	string	Transaction result. There are three statuses: - COMPLETED - transaction finished with success - FAILED - transaction finished with failure - IN\_PROGRESS - transaction not yet finished
`amount`	number	The amount of transaction in pennies, for instance: 1000 = 10.00$
`message`	string	The message about the transaction.
`currency`	string	ISO 4217 Alpha-2 currency code for example: PLN, EUR, USD
`externalTransactionId`	string	ID of the transaction received and forwarded from Acquirer. It is optional parameter.
`transactionType`	string	Payment option chosen by the end user. There are four types of the transaction: - ONE\_TIME\_PAYMENT - GOOGLE\_PAY - APPLE\_PAY - BLIK
`cardDetails`	object	Object containing card data
`cardDetails.cardProvider`	string	Type of the card. There are two types of the card: MASTERCARD or VISA.
`cardDetails.cardNumber`	string	Masked card number with visible BIN and last four digits.
`failedDetails`	object	Object containing more detailed information about transaction's fail reason. This object remains empty if transaction was successfully completed.
`failedDetails.code`	string	Transaction's fail code/status.
`failedDetails.message`	string	Transaction's fail message.

**Tip:** You need to response with the status `HTTP 200 - OK` after the positively received postback request. Otherwise Paytool API will retry postback sending.

**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 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.

POST /external-api/transactions/3ds

Headers
Key	Value
`Content-Type`	`application/json`
`Basic-Authorization`	`Basic dXNlcm5hbWU6cGFzc3dvcmQ=`

Example request body in JSON format

```json { "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "senderDataEncrypted": "eyJ0eXAiOiJKT1NFIiwiZW5jIjoiQTI1NkdDTSIsImlhdCI6MiwiYWxnIjoiUlNBLU9BRVAtMjU2Iiwia2lkIjoiNjdlNTVlM2QyZDc1YTNiNzg2NzI1NjkxOTBiZTdlMWY5Njc0ZDZlMiJ9.TkwHHD8w7rm8c7A5i2D1lUfl65LHESBmEJldZ93u5UwWPLankMTGcEiMEeoOFK4hCpFy83HwZy4SyeY4hcyBXNtHq0NCslv9rwToIty0FubriBE1MBy5Ed1j2NUyrnTFyrX9s0qhZVRc_COs8CGVvArLM7_WDBRAqvN8Td7xxsG6Ms3vEzesDRDBm85kzOTvJW6UzRLCTw6CAY9UT83DlWTWbpLXet17BPRvOtUtXgfhbWh5FbZHxet00BVGGLTVTdRYV2-_WQvzsQa-eIqaNO_agjGqOnpZ_SpP6TRbY1rd9GFraSjd4uKt4C3LZdhkUOkI_fJMwJgbFfzEgziPYg.khjzevA2hqjQ1OYh.iZT6PgvHiwxzFAw-OwIUyBIuoKz_Dhf88ZEBT5c1bAYEFenpXB1Z_aaKez7Z3C-X_yPfYTCGFhFN9ImtH8TX-3qbMQ7C1CEbZIJoV_PyJ6b7LEw0CFo7P9guQ5tv3foUJI6Sz1rYC-48GJGYybs0DyiD5FrEifF79cfXC8yzbf-O6MFt-5ppSSXcl5jsjX4Rk996nkBT4YO2hTR80LY5NoK6_akvgqJqgO1TXqfOv6D1qJkmxYaWiLmIQlJtSXmQtbEgVkIRg3hvpVFAY0EOl_uevRZSIBPNxjXP4GjjfE5yunSReOvdBMMktgifxoLYfKYu8cxXpoGzcHTTiMkLjYArEM2CAGQRA_ftf2CQ5jhCcs6Z-jhW.CEMzAbRS1FC8bhQxlPPOBg", "typeOfTransaction": "ONE_TIME_PAYMENT", "challengeNotificationUrl": "https://challengeNotificationUrl.com/198271c2", "browserData": { "javaEnabledVal": "ENABLED", "javaScriptEnabled": true, "windowSize": "S_250X400", "language": "PL", "screenHeight": 200, "screenWidth": 200, "timeZone": "60", "screenColorDepth": 24 } } ```

Parameter	Type	Description
`transactionId`	string($uuid) required	The identifier of transaction assigned by Paytool system after transaction preinitialization occurrence.
`senderDataEncrypted`	string required	Sender's encrypted data. Use `getPublicKey` method to obtain Paytool public key Example ONE\_TIME\_PAYMENT decrypted sender's data in JSON format ```json { "email": "okonomiyaki@verestro.com", "homePhone": "1-1234567899", "mobilePhone": "1-1234567899", "workPhone": "48-1234567899", "firstName": "Madara", "lastName": "Uchicha", "card": { "cardNumber" : "5453131785534417", "cardExpirationDate" : "12/24", "cvc2": "123" } } ``` Example GOOGLE\_PAY decrypted sender's data in JSON format ```json { "email" : "testmail@verestro.com", "homePhone" : "123456789", "mobilePhone" : "123456789", "workPhone" : "123456789", "firstName": "firstName", "lastName": "lastName", "token": { "signature": "MEUCIQCi0ZKCaLyQ7g2rImycYDHdYGSHla5fRIB0FZAHP5yhgQIgEj/pqXaa/CRmNqgYi4lvIbG0vAD57mGl4VTtRR63Jvc=", "intermediateSigningKey": { "signedKey": "{\"keyValue\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEQ/S16zMkhdvy/MmAzsR5HF1u1OalFL8B/jHnNy+Q3W4ugKxd84bHuJ+aYXlAWuS4HJ6A7DCSdIr96jcV+cWxJw\\u003d\\u003d\",\"keyExpiration\":\"1692662007861\"}", "signatures": [ "MEQCIG1NpruK5bKwWxK4u22myiXDRHngHPmC4695dfjlfS1oAiA4E49lAAqZ1HvRHGg38sSUg+KNORmUlVX1x3Smbk3ZoQ==" ] }, "protocolVersion": "ECv2", "signedMessage": "{\"encryptedMessage\":\"uWxxzuN6+0SA35t0au5tHONLUPOm4pZFTpQP1eH/X2M+6Mm2uAM93cS4vMX/uFRost1tf+Cl21Xq44dJ/HpBr+OZti8tbcG6dUIUteQKrU/INVnaNHIQXUUHLZ+POv9JWo58S2owrDXQNHRAUnz1IM848W4MPCXrpG0rFyJn1V3446yEppm+c/q9fCjr8ixiBNcqKZggxaYlb/9op/ZI5Hl5pG8wjczdqQAf1eB8WbQNzx5UGQpp90cb8AGWDvAasqIGiGEWi8b42GZ5pVN7J2am+GDIrWzMx9rRdNiSliYrKn32xIgyQNsk+CZPJk8BnXg08vo42YU14js3PyZlLe2ehne4HpXUbukF74uEwiQLGnLYn6BViKQ/JjYBAKiEH4G3re4QVlfwks1K8yk1ziU9q158rnTkxWcpzUGDDM3vRFu3i3qjbrYwWjVozh8HVTC9c97b2B/SNz1Jbp7qhr2VfeXCGHaDvVokokSLdrbmnQ6wnYokft75V1ebsrfGUeX2Ai99e2mVzqfBTSqIB0f5m0nMzHTgKTMgnDMZZ4/pXTfK6YsyGe0uckp5JeNIZYsJGn1BDA\\u003d\\u003d\",\"ephemeralPublicKey\":\"BJp0GNibdevp/Wtk70hhbAB+ycAh6YWHoAyrPi5Sl3zH3itmDxpbWogeKiFNuKNqDz1zJfGRdpz0amXRRY7LGEA\\u003d\",\"tag\":\"AUpekmBGgyXD7n7A8Vjt1u7525RmKVxykeNd0g/tE04\\u003d\"}" } } ```
`transactionType`	string required	Type of the transaction. This field defines which payment method was chosen by sender to pay for his goods. Examples: - ONE\_TIME\_PAYMENT - payment using plain card data - GOOGLE\_PAY - payment using card payment token obtained from Google Pay - APPLE\_PAY - payment using card payment token obtained from Apple Pay - BLIK - payment using 6 digits Blik code
`challengeNotificationUrl`	string required	This property specifies the URL to which the final challenge response will be send.
`browserData`	object required	Sender's browser details. Example browser details in JSON format ```json "browserData": { "javaEnabledVal": "ENABLED", "javaScriptEnabled": true, "windowSize": "S_250X400", "language": "PL", "screenHeight": 200, "screenWidth": 200, "timeZone": "60", "screenColorDepth": 24 } ```
`browserData.challengeWindowSize`	string	This field indicates the dimensions of the challenge window that has been displayed to the cardholder. The ACS shall reply with content that is formatted to appropriately render in this window to provide the best possible user experience. Preconfigured sizes are width x height in pixels of the window displayed in the cardholder browser. Possible values are: S\_250X400 S\_390X400 S\_500X600 S\_600X400 FULL\_SCREEN. This value is included in the Challenge Request Message (CReq).
`browserData.language`	string	This field contains the cardholder’s browser language alphanumeric with accordance to ISO 3166-1 alpha-2. For example polish language will be presented as "PL".
`browserData.screenHeight`	number	This field contains the total height of the cardholder’s screen in pixels.
`browserData.screenWidth`	number	This field contains the total width of the cardholder’s screen in pixels.
`browserData.screenColorDepth`	number	This field contains a value representing the bit depth of the color palette, in bits per pixel, for displaying images. Obtained from Cardholder browser using the screen.colorDepth property. Values accepted: 1 = 1 bit, 4 = 4 bits, 8 = 8 bits, 15 = 15 bits, 16 = 16 bits, 24 = 24 bits, 32 = 32 bits, 48 = 48 bits.
`browserData.timeZone`	string	This field contains the difference between UTC time and the cardholder’s browser local time in minutes.
`browserData.javaScriptEnabled`	boolean	This field contains a value representing the ability of the cardholder’s browser to execute JavaScript. Enumerated values: ENABLED, DISABLED.
`browserData.javaEnabledVal`	string	This field contains a value representing the ability of the cardholder’s browser to execute Java. Enumerated values: NOT\_PRESENT, ENABLED, DISABLED. Required if `browserData.javaScriptEnabled` is set to `ENABLED`.

Example response body in JSON format - 200 - OK

```json { "threeDsFlow": "THREE_DS_METHOD", "threeDsMethodData": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9wYXl0b29sLnBsL2FwaS92MS8zZHMvbm90aWZpY2F0aW9uLzAyYzcyNWYzLTM4NWUtNGM2OC1iY2NiLTczM2I1NGYxODliNCIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiY2U4OGQ3MTEtNWQ3MS00Yzk3LWIyYzgtMmIyOWE3OWFjNjU2In0", "threeDsMethodUrl": "https://mpi-staging.verestro.pl/v2/authentication/notification/acs-mock" } ```

Parameter	Type	Description
`threeDsFlow`	string	Indicates whether a transaction qualifies as an authenticated transaction or account verification. Possible values are: - THREE\_DS\_METHOD - Possible additional request to ACS, in which we should include the threeDsMethodData field - FRICTIONLESS - The transaction was released for processing without 3ds challenge because the issuer allowed it. Payment process is finnished - CHALLENGE - Challenge required - login to the bank on the user's side for authentication
`threeDsMethodData`	string	Encoded data used for request to ACS.
`threeDsMethodUrl`	string	ACS endpoint for hidden request. If endpoint is not present then request is not required.

Possible errors

Errors that may occur when attempting to initialize transaction:

401 - Unauthorized

```JSON { "timestamp": "2023-03-29T19:16:01.288+00:00", "status": 401, "error": "Unauthorized", "path": "/api/v1/transactions/9609a08e-cd80-4e6e-8664-f1e6b2f2dc50" } ```

Parameter	Type	Description
`timestamp`	string($date-time)	Timestamp of the occured error.
`status`	numeric	Numeric HTTP code of the occured error.
`error`	string	Description of HTTP status of the occured error.
`path`	string	Requested endpoint's path

**Warning:** The structure of this error is different from other errors

404 - Not found

Parameter	Type	Description
`uuid`	string	The identifier of transaction assigned by Paytool system after transaction preinitialization occurrence.
`traceId`	string	Identifier of the occured error.
`errorType`	string	Type of the occured error: - MERCHANT\_NOT\_EXISTS
`message`	string	Description of the occured error.

422 - Unprocessable Entity

```json { "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "traceId": "8fc17b6c-6995-4d33-a4f5-93e99b8af2b2", "errorType": "TRANSACTION_PROCESSED", "merchantStatus": "Transaction with transactionId: q732ecw1-dcg2-4614-94e6-b931gb46r772 just exists" } ```

Parameter	Type	Description
`date`	string	The identifier of transaction assigned by Paytool system after transaction preinitialization occurrence.
`traceId`	string	Identifier of the occured error.
`errorType`	string	Type of the occured error: - UNPROCESSABLE\_ENTITY
`message`	string	Description of the occured error.

500 - Internal server error

```JSON { "date": "2023-09-26 13:51:40.869246", "traceId": "8fc17b6c-6995-4d33-a4f5-93e99b8af2b2", "errorType": "INTERNAL_SERVER_ERROR", "message": "Internal server error occured." } ```

Parameter	Type	Description
`date`	string($date-time)	Timestamp of the occured error.
`traceId`	string	Identifier of the occured error.
`errorType`	string	Type of the occured error: - INTERNAL\_SERVER\_ERROR
`message`	string	Description of the occured error.

#### Continue threeDs process 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.

POST /external-api/transactions/3ds/continue

Headers
Key	Value
`Content-Type`	`application/json`
`Basic-Authorization`	`Basic dXNlcm5hbWU6cGFzc3dvcmQ=`

Example request body in JSON format

Parameter	Type	Description
`transactionId`	string($uuid) required	The identifier of transaction assigned by Paytool system after transaction preinitialization occurrence.
`senderDataEncrypted`	string required	Sender's encrypted data. Example decrypted sender's data in JSON format ```json { "email": "okonomiyaki@verestro.com", "homePhone": "1-1234567899", "mobilePhone": "1-1234567899", "workPhone": "48-1234567899", "firstName": "Madara", "lastName": "Uchicha", "card": { "cardNumber" : "5453131785534417", "cardExpirationDate" : "12/24", "cvc2": "123" } } ```
`transactionType`	string required	Type of the transaction. This field defines which payment method was chosen by sender to pay for his goods. Examples: - ONE\_TIME\_PAYMENT - payment using plain card data - GOOGLE\_PAY - payment using card payment token obtained from Google Pay - APPLE\_PAY - payment using card payment token obtained from Apple Pay

Example response body in JSON format - 200 - OK

```json { "threeDsFlow": "CHALLENGE", "acsUrl": "acsurl.com", "cReq": "c29tZSBjcmVx", "challengeHtmlFormBase64": "PGh0bWw+PFNDUklQVCBMQU5HVUFHRT0iSmF2YXNjcmlwdCI+ZnVuY3Rpb24gT25Mb2FkRXZlbnQoKXsgZG9jdW1lbnQuZG93bmxvYWRGb3JtLnN1Ym1pdCgpOyB9PC9TQ1JJUFQ+PGJvZHkgT25Mb2FkPSJPbkxvYWRFdmVudCgpOyI+PGZvcm0gbmFtZT0iZG93bmxvYWRGb3JtIiBhY3Rpb249Imh0dHBzOi8vamF2YS1kZXZlbC5mZW5pZ2UucGw6ODE4MS9mZW5pZ2UtbXBpIiBtZXRob2Q9IlBPU1QiPjxJTlBVVCB0eXBlPSJoaWRkZW4iIG5hbWU9IlBhUmVxIiB2YWx1ZT0iZUp4bGtsdHZ3akFNaGY4SzRwM20wcVJVbFluRTRHSFZ4TVF1VDN1TFdndUsybERTRnNHL244TmxiRnFrU0Q2T2UrcDhEbnh1UGVMeUE0dkJvNEVWZHAzZDRLZ3FaMk01bFdwc1lEMS94NE9CSS9xdTJqc2pJaDVKWUhkSlgvaGlhMTF2d0JhSHAvelZhQ1ZFb29EZEpEVG84NlhodENhMEJiQnJBcHh0MEhUb1N0VWdzSXVDWWorNDNwOU5JaEpnZHdHRHI4MjI3OXN1WTJ4bmozWlM0aEZyRVEydHJjcW9yYk5VcVpnVmRZV3VCeGFxZ1QzYVdnOGg2c2o5VkpVbVg4dzMvL1l5ajFlN3R4bXdVQUdsN2RGSUxsSWVTejRTT2xNNjB5bXdTeDVzRTlveWk2K1hVYXg1eERuZDlKcUNOdnhwZmhWMEZvNStwNEFRZTNURm1jeGp1dDVkQVo3YXZhUGVEWEg5aVlFOUdsODhCN3BGVDlqaUFESXNSU3hwUUtsS3ROUnFtc2lVa04yS2dtTkY1Q1RuK21JWkJMQmd3MjdqSkVDWFNWUDA1d1Y4QTEvYXFXUT0iPjxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9IlRlcm1VcmwiIHZhbHVlPSJodHRwczovL3VybCI+PGlucHV0IHR5cGU9ImhpZGRlbiIgbmFtZT0iTUQiIHZhbHVlPSJiV1E9Ij42Zvcm0+PC9ib2R5PjwvaHRtbD4=", "threeDsSessionData": "ZGY0NDJhODQtOGJkZS00MmQ3LWExMTUtMzUyNjNlZGY1MGFk" } ```

Parameter	Type	Description
`threeDsFlow`	string	Indicates whether a transaction qualifies as an authenticated transaction or account verification. Possible values are: - FRICTIONLESS - The transaction was released for processing without 3ds challenge because the issuer allowed it. Payment process is finnished - CHALLENGE - Challenge required - login to the bank on the user's side for authentication
`threeDsSessionData`	string	Encoded data used for request to ACS.
`transactionStatus3ds`	string	ACS endpoint for hidden request. If endpoint is not present then request is not required.
`acsUrl`	string	The url to which the 3DS parameters will be sent.
`cReq`	string	Challenge Request Message - additional information to support the 3DS authentication process and to carry the authentication data from the Cardholder.
`challengeHtmlFormBase64`	string	Base64 encoded data contains HTML form to display for user in order to login bank account.

Possible errors

Errors that may occur when attempting to initialize transaction:

401 - Unauthorized

```JSON { "timestamp": "2023-03-29T19:16:01.288+00:00", "status": 401, "error": "Unauthorized", "path": "/api/v1/transactions/9609a08e-cd80-4e6e-8664-f1e6b2f2dc50" } ```

Parameter	Type	Description
`timestamp`	string($date-time)	Timestamp of the occured error.
`status`	numeric	Numeric HTTP code of the occured error.
`error`	string	Description of HTTP status of the occured error.
`path`	string	Requested endpoint's path

**Warning:** The structure of this error is different from other errors

404 - Not found

Parameter	Type	Description
`uuid`	string	The identifier of transaction assigned by Paytool system after transaction preinitialization occurrence.
`traceId`	string	Identifier of the occured error.
`errorType`	string	Type of the occured error: - MERCHANT\_NOT\_EXISTS
`message`	string	Description of the occured error.

422 - Unprocessable Entity

Parameter	Type	Description
`date`	string	The identifier of transaction assigned by Paytool system after transaction preinitialization occurrence.
`traceId`	string	Identifier of the occured error.
`errorType`	string	Type of the occured error: - UNPROCESSABLE\_ENTITY
`message`	string	Description of the occured error.

500 - Internal server error

```JSON { "date": "2023-09-26 13:51:40.869246", "traceId": "8fc17b6c-6995-4d33-a4f5-93e99b8af2b2", "errorType": "INTERNAL_SERVER_ERROR", "message": "Internal server error occured." } ```

Parameter	Type	Description
`date`	string($date-time)	Timestamp of the occured error.
`traceId`	string	Identifier of the occured error.
`errorType`	string	Type of the occured error: - INTERNAL\_SERVER\_ERROR
`message`	string	Description of the occured error.

#### Finalize threeDs process 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.

POST /external-api/transactions/3ds/finalize

Headers
Key	Value
`Content-Type`	`application/json`
`Basic-Authorization`	`Basic dXNlcm5hbWU6cGFzc3dvcmQ=`

Example request body in JSON format

```json { "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "senderDataEncrypted": "eyJ0eXAiOiJKT1NFIiwiZW5jIjoiQTI1NkdDTSIsImlhdCI6MiwiYWxnIjoiUlNBLU9BRVAtMjU2Iiwia2lkIjoiNjdlNTVlM2QyZDc1YTNiNzg2NzI1NjkxOTBiZTdlMWY5Njc0ZDZlMiJ9.TkwHHD8w7rm8c7A5i2D1lUfl65LHESBmEJldZ93u5UwWPLankMTGcEiMEeoOFK4hCpFy83HwZy4SyeY4hcyBXNtHq0NCslv9rwToIty0FubriBE1MBy5Ed1j2NUyrnTFyrX9s0qhZVRc_COs8CGVvArLM7_WDBRAqvN8Td7xxsG6Ms3vEzesDRDBm85kzOTvJW6UzRLCTw6CAY9UT83DlWTWbpLXet17BPRvOtUtXgfhbWh5FbZHxet00BVGGLTVTdRYV2-_WQvzsQa-eIqaNO_agjGqOnpZ_SpP6TRbY1rd9GFraSjd4uKt4C3LZdhkUOkI_fJMwJgbFfzEgziPYg.khjzevA2hqjQ1OYh.iZT6PgvHiwxzFAw-OwIUyBIuoKz_Dhf88ZEBT5c1bAYEFenpXB1Z_aaKez7Z3C-X_yPfYTCGFhFN9ImtH8TX-3qbMQ7C1CEbZIJoV_PyJ6b7LEw0CFo7P9guQ5tv3foUJI6Sz1rYC-48GJGYybs0DyiD5FrEifF79cfXC8yzbf-O6MFt-5ppSSXcl5jsjX4Rk996nkBT4YO2hTR80LY5NoK6_akvgqJqgO1TXqfOv6D1qJkmxYaWiLmIQlJtSXmQtbEgVkIRg3hvpVFAY0EOl_uevRZSIBPNxjXP4GjjfE5yunSReOvdBMMktgifxoLYfKYu8cxXpoGzcHTTiMkLjYArEM2CAGQRA_ftf2CQ5jhCcs6Z-jhW.CEMzAbRS1FC8bhQxlPPOBg", "typeOfTransaction": "ONE_TIME_PAYMENT", "cRes": "eJxlkltvwjAMhf8K4p3m0qRUlYnE4GHVxMQuT3uLWguK2lDSFsG/n8NlbFqk" } ```

Parameter	Type	Description
`transactionId`	string($uuid) required	The identifier of transaction assigned by Paytool system after transaction preinitialization occurrence.
`senderDataEncrypted`	string required	Sender's encrypted data. Example decrypted sender's data in JSON format ```json { "email": "okonomiyaki@verestro.com", "homePhone": "1-1234567899", "mobilePhone": "1-1234567899", "workPhone": "48-1234567899", "firstName": "Madara", "lastName": "Uchicha", "card": { "cardNumber" : "5453131785534417", "cardExpirationDate" : "12/24", "cvc2": "123" } } ```
`transactionType`	string required	Type of the transaction. This field defines which payment method was chosen by sender to pay for his goods. Examples: - ONE\_TIME\_PAYMENT - payment using plain card data - GOOGLE\_PAY - payment using card payment token obtained from Google Pay - APPLE\_PAY - payment using card payment token obtained from Apple Pay
`cRes`	string	Payer's authentication response.

Example response body in JSON format - 200 - OK

```json { "transactionId": "6f4c5101-6d78-4c80-9e79-3b2060c221ad", "approvalCode": "CODE_00", "externalId": "9f4c5101-6d78-4c80-9e79-3b2060c227ad", "transactionStatus": "APPROVED", "transactionStatus3ds": "Y" } ```

Parameter	Type	Description
`transactionId`	string
`approvalCode`	string
`externalId`	string
`transactionStatus`	string
`transactionStatus3ds`	string

Possible errors

Errors that may occur when attempting to initialize transaction:

401 - Unauthorized

```JSON { "timestamp": "2023-03-29T19:16:01.288+00:00", "status": 401, "error": "Unauthorized", "path": "/api/v1/transactions/9609a08e-cd80-4e6e-8664-f1e6b2f2dc50" } ```

Parameter	Type	Description
`timestamp`	string($date-time)	Timestamp of the occured error.
`status`	numeric	Numeric HTTP code of the occured error.
`error`	string	Description of HTTP status of the occured error.
`path`	string	Requested endpoint's path

**Warning:** The structure of this error is different from other errors

404 - Not found

Parameter	Type	Description
`uuid`	string	The identifier of transaction assigned by Paytool system after transaction preinitialization occurrence.
`traceId`	string	Identifier of the occured error.
`errorType`	string	Type of the occured error: - MERCHANT\_NOT\_EXISTS
`message`	string	Description of the occured error.

422 - Unprocessable Entity

Parameter	Type	Description
`date`	string	The identifier of transaction assigned by Paytool system after transaction preinitialization occurrence.
`traceId`	string	Identifier of the occured error.
`errorType`	string	Type of the occured error: - UNPROCESSABLE\_ENTITY
`message`	string	Description of the occured error.

500 - Internal server error

```JSON { "date": "2023-09-26 13:51:40.869246", "traceId": "8fc17b6c-6995-4d33-a4f5-93e99b8af2b2", "errorType": "INTERNAL_SERVER_ERROR", "message": "Internal server error occured." } ```

Parameter	Type	Description
`date`	string($date-time)	Timestamp of the occured error.
`traceId`	string	Identifier of the occured error.
`errorType`	string	Type of the occured error: - INTERNAL\_SERVER\_ERROR
`message`	string	Description of the occured error.

### 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.

POST /external-api/transactions/{transactionId}/deposit

Headers
Key	Value
`Content-Type`	`application/json`
`Basic-Authorization`	`Basic dXNlcm5hbWU6cGFzc3dvcmQ=`

Query parameter	Value
`transactionId`	``

Example request body in JSON format

```json { "amount": 100 } ```

Parameter	Type	Description
`amount`	number required	The amount of the transaction to be deducted from the payer's account. It cannot be higher than the amount declared when initiating the transaction.

Example response body in JSON format - 200 - OK

```json { "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ```

Parameter	Type	Description
`transactionId`	string	Identifier of the transaction assigned during the `transactionInitialization` process.

Possible errors

Errors that may occur when attempting to initialize transaction:

401 - Unauthorized

```JSON { "timestamp": "2023-03-29T19:16:01.288+00:00", "status": 401, "error": "Unauthorized", "path": "/api/v1/transactions/9609a08e-cd80-4e6e-8664-f1e6b2f2dc50" } ```

Parameter	Type	Description
`timestamp`	string($date-time)	Timestamp of the occured error.
`status`	numeric	Numeric HTTP code of the occured error.
`error`	string	Description of HTTP status of the occured error.
`path`	string	Requested endpoint's path

**Warning:** The structure of this error is different from other errors

404 - Not found

Parameter	Type	Description
`uuid`	string	The identifier of transaction assigned by Paytool system after transaction preinitialization occurrence.
`traceId`	string	Identifier of the occured error.
`errorType`	string	Type of the occured error: - MERCHANT\_NOT\_EXISTS
`message`	string	Description of the occured error.

422 - Unprocessable Entity

Parameter	Type	Description
`date`	string	The identifier of transaction assigned by Paytool system after transaction preinitialization occurrence.
`traceId`	string	Identifier of the occured error.
`errorType`	string	Type of the occured error: - UNPROCESSABLE\_ENTITY
`message`	string	Description of the occured error.

500 - Internal server error

```JSON { "date": "2023-09-26 13:51:40.869246", "traceId": "8fc17b6c-6995-4d33-a4f5-93e99b8af2b2", "errorType": "INTERNAL_SERVER_ERROR", "message": "Internal server error occured." } ```

Parameter	Type	Description
`date`	string($date-time)	Timestamp of the occured error.
`traceId`	string	Identifier of the occured error.
`errorType`	string	Type of the occured error: - INTERNAL\_SERVER\_ERROR
`message`	string	Description of the occured error.

### Transaction 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.

POST /external-api/transactions/refund

Headers
Key	Value
`Content-Type`	`application/json`
`Basic-Authorization`	`Basic dXNlcm5hbWU6cGFzc3dvcmQ=`

Example request body in JSON format

```json { "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "amountToRefund": 150 } ```

Parameter	Type	Description
`transactionId`	string($uuid) required	The identifier of transaction assigned by Paytool system after transaction preinitialization occurrence.
`amountToRefund`	number	Field determining amount to refund of cash transferred in one hundredth of the currency. Amount must be equal to the amount declared in the PreInitialization step. \[1 USD = 100\]

Example response body in JSON format - 200 - OK

```json { "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "transactionState": "COMPLETED" } ```

Parameter	Type	Description
`transactionId`	string($uuid)	The identifier of transaction assigned by Paytool system after transaction preinitialization occurrence.

Possible errors

Errors that may occur when attempting to initialize transaction:

401 - Unauthorized

```JSON { "timestamp": "2023-03-29T19:16:01.288+00:00", "status": 401, "error": "Unauthorized", "path": "/api/v1/transactions/9609a08e-cd80-4e6e-8664-f1e6b2f2dc50" } ```

Parameter	Type	Description
`timestamp`	string($date-time)	Timestamp of the occured error.
`status`	numeric	Numeric HTTP code of the occured error.
`error`	string	Description of HTTP status of the occured error.
`path`	string	Requested endpoint's path

**Warning:** The structure of this error is different from other errors

404 - Not found

Parameter	Type	Description
`uuid`	string	The identifier of transaction assigned by Paytool system after transaction preinitialization occurrence.
`traceId`	string	Identifier of the occured error.
`errorType`	string	Type of the occured error: - MERCHANT\_NOT\_EXISTS
`message`	string	Description of the occured error.

500 - Internal server error

```JSON { "date": "2023-09-26 13:51:40.869246", "traceId": "8fc17b6c-6995-4d33-a4f5-93e99b8af2b2", "errorType": "INTERNAL_SERVER_ERROR", "message": "Internal server error occured." } ```

Parameter	Type	Description
`date`	string($date-time)	Timestamp of the occured error.
`traceId`	string	Identifier of the occured error.
`errorType`	string	Type of the occured error: - INTERNAL\_SERVER\_ERROR
`message`	string	Description of the occured error.

### Get public key This method returns Patool public key which can be used to encrypt sensitive data which some of our other methods require, for example `initialize3ds.sendersEncryptedData`.

GET /external-api/public-key

Headers
Key	Value
`Content-Type`	`application/json`
`Basic-Authorization`	`Basic dXNlcm5hbWU6cGFzc3dvcmQ=`

Example response body in JSON format - 200 - OK

```json { "value": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEApFt6jz/LP7ZBbfuj6v1yRl/oKz2sbmkLnzP3mXb2eDWTKL/SyOxcCjwOxnlxNR5Q9BaHMbyFCBaCtAeOmT3mIgB+IoeH00bkibko1NdLi8q//kj/YLYO6x1qzHeSDE4vXWig/zE00k3ptU3qznLm1JqfFs7IRinVVqczO+p6NP/XaF5rs46mreqIOsvMzoX4wuIFeG2X+zwIws+YOyLUgJoOfpJT26FnJIDOPw1uYQMzrG+QY9akZoy0UbDCnezxH7eb8rxSxftUt0LUUKqjssETMU+pTcDVQ6cmeCkwPlnzbge4hozR04Q5J+y/m/JMzqDBAJ3jB16+XPjaWVleMQIDAQAB" } ```

Parameter	Type	Description
`value`	string	Paytool public key.

Possible errors

Errors that may occur when attempting to initialize transaction:

401 - Unauthorized

```JSON { "timestamp": "2023-03-29T19:16:01.288+00:00", "status": 401, "error": "Unauthorized", "path": "/api/v1/transactions/9609a08e-cd80-4e6e-8664-f1e6b2f2dc50" } ```

Parameter	Type	Description
`timestamp`	string($date-time)	Timestamp of the occured error.
`status`	numeric	Numeric HTTP code of the occured error.
`error`	string	Description of HTTP status of the occured error.
`path`	string	Requested endpoint's path

**Warning:** The structure of this error is different from other errors

Parameter	Type	Description
`uuid`	string	The identifier of transaction assigned by Paytool system after transaction preinitialization occurrence.
`traceId`	string	Identifier of the occured error.
`errorType`	string	Type of the occured error: - MERCHANT\_NOT\_EXISTS
`message`	string	Description of the occured error.

500 - Internal server error

```JSON { "date": "2023-09-26 13:51:40.869246", "traceId": "8fc17b6c-6995-4d33-a4f5-93e99b8af2b2", "errorType": "INTERNAL_SERVER_ERROR", "message": "Internal server error occured." } ```

Parameter	Type	Description
`date`	string($date-time)	Timestamp of the occured error.
`traceId`	string	Identifier of the occured error.
`errorType`	string	Type of the occured error: - INTERNAL\_SERVER\_ERROR
`message`	string	Description of the occured error.

## Opening Paytool in iframe This section describes the steps you need to take if you want the Paytool form to be displayed as an iframe on your 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 it.

### Initialization 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.

**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` . **Tip:** 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.

### API #### **`redirect`** **Type signature** ```Java static redirect(transactionId: string): void ```

Example usage

HTML & JavaScript

**`index.html`** ```HTML ```

React

**`App.jsx`** ```JavaScript export function App() { const transactionId = '1234-1234-1234-1234'; // <- Fetched from server return ; } ```

#### **`embed`** **Type signature** ```Java static async embed(transactionId: string, opts?: Partial): Promise ``` Attaches a custom dialog component to your app's body and opens Paytool Web App in an iframe. If the payment process ends successfully, resolves the promise with `EmbedResponse`. Otherwise, if the process fails or the user closes the dialog, the promise is rejected with `EmbedError`, that's why it is essential to catch any possible errors and act accordingly.

Example usage

HTML & JavaScript

**``**

Basic

**`index.html`** ```HTML ```

With options

**`index.html`** ```HTML

```

React

Basic

With options

**`App.jsx`** ```JavaScript export function App() { const transactionId = '1234-1234-1234-1234'; // <- Fetched from server const containerRef = useRef(); const handleClick = async () => { try { const result = await Paytool.embed(transactionId, { size: 'compact', target: containerRef.current }); // Handle success here } catch (err) { // Handle error here } }; return ( <>

); } ```

#### **`isEmbedError`** **Type signature** ```Java static async embed(transactionId: string, opts?: Partial): Promise ``` Accepts an unknown `err` and returns `true` if the `err` is an instance of `EmbedError`. Useful to determine whether the `err` is a message from the SDK or a different JavaScript error.

Example usage

HTML & JavaScript

**`index.html`** ```HTML ```

React

**`App.jsx`** ```JavaScript export function App() { const transactionId = '1234-1234-1234-1234'; // <- Fetched from server const handleClick = async () => { try { const result = await Paytool.embed(transactionId); } catch (err) { if (!Paytool.isEmbedError(err)) return; // Ignore (not recommended) or catch it using your monitoring tool (recommended) // Handle the err accordingly, for example: if (!err.final) return console.log('Transaction aborted.'); console.log('Transaction failed with status:' + err.status); } }; return ; } ```

### Interfaces #### **`EmbedOptions`** ```Java interface EmbedOptions { target: HTMLElement; size: 'full' | 'compact'; allowCancel: boolean; } ``` ##### Defaults ```Java { target: document.body, size: 'full', allowCancel: true } ``` #### **`EmbedResponse`** ```Java interface EmbedResponse { transactionId: string; status: string; final: true; success: boolean; } ``` #### **`EmbedError`** ```Java interface EmbedError { transactionId: string; status?: string; reason: string; final: boolean; success: false; } ``` # Test Guide

This section provides guidelines for testing various payment methods supported in Paytool solution, including plain card number, google pay, apple pay, and BLIK on environment `TEST`.

**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 cards

Card type

Card BIN

VISA

511796XXXXXXXXXX

Mastercard

545313XXXXXXXXXX

There's need of generation PAN numbers from these BIN's, in order to do such so you can use [Credit Card Generator](https://www.businer.com/discard_credit_card_generator.php).

**Note:** CVV may be randomized, expiration date must not be expired.

### Testing various transaction paths

As described in the chapter on [3DS authentication](https://developer.verestro.com/books/paytool/page/use-cases#bkmrk-blik:~:text=step%20by%20step-,ThreeDs%20authentication,-Transactions%20using%20payment), there are various ThreeDs paths, In order to be able to test different flows, you need to manipulate the transaction amount to get into the selected transaction path:

ThreeDs 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

In order to be able to test google-pay, you need to add a tokenized card to your google account. You need to register with the [google test card suite group](https://developers.google.com/pay/api/web/guides/resources/test-card-suite?hl=en) to do so. Follow these instructions from google's documentation. After registration in [google test card suite group](https://developers.google.com/pay/api/web/guides/resources/test-card-suite?hl=en) you are ready to test Google Pay token payment. After logging into your test account and selecting Google Pay, you should have a choice of several test cards added to your account which you can use to make a payment in Paytool `TEST` environment. Google Pay payment use case is described [here](https://developer.verestro.com/books/paytool/page/use-cases#bkmrk-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...

Headers
Key	Value
`Content-Type`	`application/json`