Paytool

A solution based on the Web Checkout product but extended by various payment methods such as Google Pay™, Apple Pay or Blik. The whole solution is based on the two integration models: payment using the Paytool frontend application or via a direct server to server connection. Our solution frees you from the need to integrate with acquiring institutions and banks. The payment process and threeDs authentication are performed on the Verestro side.

• Introduction
• Overview
• Use cases
• Onboarding
• How to integrate
• Test Guide

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.

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.

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

Terminology

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

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 and Payment process via API 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 and 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.

{
  "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"
}

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 integration model because it is much simpler and faster to implement. Additionally, in the  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.

{
  "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"
}

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:

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:

Allowed card networks

Listed below are the types of cards supported in transactions using Paytool application:

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.

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 and Payment process via API 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-AuthorizationBasic-Authorization data will be issued to you after completing the onboarding process.

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.

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 integration path:

Tip: We are fully responsible for the execution of the transaction and threeDs authentication process. You only initialize transaction by redirecting the end user to the Paytool payment form and providing basic transaction metadata via the your backend.

Server to server

An alternative path to carry out a transaction is a Payment process via API 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.

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

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:

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 process may be required. The payment process using plain card details from the end user's perpective has been shown below:

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:

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

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™ 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 methods provided by Paytool API.

Important: If you use Paytool with Payment process via API 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 route.

Note: Google Pay™ provides a  Google Pay Web 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 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:

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 process may be required. The payment process using Apple Pay™ card payment token from the end user's perpective has been shown below:

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:

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:

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  or CHALLENGE. The meaning of each status is described in the section 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  or CHALLENGE.

ThreeDs modes

FRICTIONLESS

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

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.

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:

Notification after transaction

As mentioned in the Transaction result 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 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, 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 process, the you can provide a valid and accessible URL address that will serve as the endpoint for the post-transaction notifications. 

{
  "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 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 process and always can be edited.

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

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.

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:

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:

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 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 or contact Google Pay™ support. After completing registration as a merchant, the Customer will receive an access to Google Pay™ documentation enabling technical integration.

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

https://paytool-api.verestro.dev

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.

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 in SwaggerUI format.

Methods in API

Our solution provides API method allowing you to order and process transaction by creating payment session 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.

{
  "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
}

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

{
  "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"
}

{
  "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"
}

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

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 chapter. Does not apply to Customers redirecting the payer to the Paytool frontend app.

{
  "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"
  }
}

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

{
  "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"
}

{
  "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"
}

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 transactionPostbackmethod described below.

{
  "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"
}

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

{
  "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"
}

{
  "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"
}

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 transactionPostbackmethod will inform you about the current transaction status.

Note: You should provide postback endpoint during the onboarding process.

{
  "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"
  }
}

Tip: Integration with the transactionPostbackmethod 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 for THREE_DS_MODE=THREE_DS_METHOD or finalize3ds 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.

{
  "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
  }
}

{
    "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"
    }
}

{
    "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\"}"
    }
}

  "browserData": {
    "javaEnabledVal": "ENABLED",
    "javaScriptEnabled": true,
    "windowSize": "S_250X400",
    "language": "PL",
    "screenHeight": 200,
    "screenWidth": 200,
    "timeZone": "60",
    "screenColorDepth": 24
  }

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

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

{
  "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"
}

{
  "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"
}

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

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.

{
  "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"
}

{
    "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"
    }
}

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

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

{
  "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"
}

{
  "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"
}

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

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.

{
  "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"
}

{
    "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"
    }
}

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

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

{
  "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"
}

{
  "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"
}

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

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.

{
  "amount": 100
}

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

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

{
  "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"
}

{
  "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"
}

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

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

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

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

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

{
  "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"
}

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

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.

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

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

{
  "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"
}

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

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:

<script src="https://paytool.verestro.com/v1/paytool.js"></script>

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

static redirect(transactionId: string): void

<button id="pay-btn">Pay</button>
<script>
  var transactionId = '1234-1234-1234-1234'; // <- Fetched from server
  var btn = document.getElementById('pay-btn');
  btn.addEventListener('click', function () {
    Paytool.redirect(transactionId);
  });
</script>

export function App() {
  const transactionId = '1234-1234-1234-1234'; // <- Fetched from server
  return <button onClick={() => Paytool.redirect(transactionId)}>Pay</button>;
}

embed

Type signature

static async embed(transactionId: string, opts?: Partial<EmbedOptions>): Promise<EmbedResponse>

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.

<button id="pay-btn">Pay</button>
<script>
  var transactionId = '1234-1234-1234-1234'; // <- Fetched from server
  var btn = document.getElementById('pay-btn');
  btn.addEventListener('click', function () {
    Paytool.embed(transactionId)
      .then(function (result) {
        // Handle success here
      })
      .catch(function (err) {
        // Handle error here
      });
  });
</script>

<button id="pay-btn">Pay</button>
<div id="paytool-container"></div>
<script>
  var transactionId = '1234-1234-1234-1234'; // <- Fetched from server
  var btn = document.getElementById('pay-btn');
  btn.addEventListener('click', function () {
    Paytool.embed(transactionId, {
      size: 'compact',
      target: document.getElementById('paytool-container')
    })
      .then(function (result) {
        // Handle success here
      })
      .catch(function (err) {
        // Handle error here
      });
  });
</script>

export function App() {
  const transactionId = '1234-1234-1234-1234'; // <- Fetched from server
 
  const handleClick = async () => {
    try {
      const result = await Paytool.embed(transactionId);
      // Handle success here
    } catch (err) {
      // Handle error here
    }
  };
 
  return <button onClick={handleClick}>Pay</button>;
}

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 (
    <>
      <button onClick={handleClick}>Pay</button>
      <div ref={containerRef}></div>
    </>
  );
}

isEmbedError

Type signature

static async embed(transactionId: string, opts?: Partial<EmbedOptions>): Promise<EmbedResponse>

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.

<button id="pay-btn">Pay</button>
<script>
  var transactionId = '1234-1234-1234-1234'; // <- Fetched from server
  var payButton = document.getElementById('pay-btn');
  payButton.addEventListener('click', function () {
    Paytool.embed(transactionId).catch(function (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);
    });
  });
</script>

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 <button onClick={handleClick}>Pay</button>;
}

Interfaces

EmbedOptions

interface EmbedOptions {
  target: HTMLElement;
  size: 'full' | 'compact';
  allowCancel: boolean;
}

Defaults

{
  target: document.body,
  size: 'full',
  allowCancel: true
}

EmbedResponse

interface EmbedResponse {
  transactionId: string;
  status: string;
  final: true;
  success: boolean;
}

EmbedError

interface EmbedError {
  transactionId: string;
  status?: string;
  reason: string;
  final: boolean;
  success: false;
}

Test Guide

Tip: Check it now. Verestro Paytool demo application is available here.

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.

Test cards

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

Testing various transaction paths

Note: Amount is a value determining amount of cash transferred in one hundredth of the currency [1,00 USD = 100].

Tip: Select an amount between 3001-8000 to test failed transaction.

Google Pay

Note: To be able to test all flows of ThreeDs in Google Pay follow the description about testing various transaction paths

Apple Pay

This method involves processing payments using tokenized credit or debit cards. You need to create Apple sandbox tester account. Follow apple documentation 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. Payment with Apple Pay use case is described here.

Blik

Important! Implemenation is work in progress...