# Donate Widget # Introduction Donate Widget is a solution that allows you to make a donation using the Verestro payment gateway that supports e-commerce payments. Solution can be integrated with Merchants, on their online store to provide a simple and easy way for its consumers to perform a donation to a charity of Merchant choice by simply adding them to the cart. Donate Widget designed by Verestro supports all key web-browsers (see further in the document) and has mobile responsive design. Also, it can be customized and localized per specific Customer or Country. The trial version available for interaction from end user point of view is available [here](https://rpm-front.upaidtest.pl/donate-ukraine)[.](https://rpm-front.upaidtest.pl/donate-ukraine) ## How to connect with us? Verestro provides access to the solution via Web SDK. The Customer plugs in the JavaScript library received from Verestro, which allows the Customer's users to make donations. The plugged in SDK communicates with the Verestro backend which then communicates with the Acquirer. This is required that Customer has an account in Acquirer's system which settle his transactions. ### Web SDK Verestro provides Software Development Kit (SDK) which will be used to process donation. This is JavaScript library which should be plugged in Customer application. Verestro team actively supports Customer with integration. More information about Web SDK can be found [here](https://bookstack.verestro.dev/books/donate-widget/page/technical-documentation). Verestro team actively supports Customer with integration. Depending on the requirements as to the appearance of the payment form, the Customer must provide appropriate graphics (such as Customer's Company logo) to be uploaded to the payment form by Verestro. ### Widget screenshot examples An example of the donation form is presented below. All views included in the Donate Widget Solution are presented [here](https://bookstack.verestro.dev/books/donate-widget/page/use-cases#bkmrk-user-flow).[![image-1656856851386.00.00.png](https://bookstack.verestro.dev/uploads/images/gallery/2022-07/scaled-1680-/image-1656856851386-00-00.png)](https://bookstack.verestro.dev/uploads/images/gallery/2022-07/image-1656856851386-00-00.png) # Overview This document provides high level description of functionalities offered by Donate Widget. Donate Widget supports e-commerce transactions, thus releasing Customer from the need to handle the transaction process on his side – the entire transaction process will be handled by Verestro. The tool is very easy to integrate because it requires to plug one library. The solution can be supported by various Acquirers. Note that if the Customer requires the settlement of the transaction by a new Acquirer – to which Verestro is not integrated – there will be required new integration between Verestro and the new Acquirer. The specification of the new Acquirer should be provided by the Customer. ## Abbreviations Abbreviations and Acronyms used in the document:
**Abbreviation** **Description**
ACQ Acquiring Institution / Acquirer
ACS Access Control Server
SDK Software Development Kit
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 this document:
**Abberations** **Description**
Customer/Merchant Institution which uses Verestro products. This institution decides which solution should be used depending on the business requirements and how transaction should be processed.
User End-User which uses Donate Widget Solution. It is root of entity tree. User is an owner of the card and is an entity that decides to pay for the purchase with the Donate Widget Solution, selecting it from the list of payment methods available on the Merchant (Customer) website.
Card Card belongs to the user. If user intends to pay with the Donate Widget Solution, then has to insert required card's data to the appropriate fields shared by the Merchant Paytool solution. Card data will not be stored in the Verestro system. They will be provided to Acquirer.
Acquirer External Institution resposible for processing transaction and 3ds requests ordered by the Donate Widget Solution. Acquirer connects with banks / card issuers and returns an information whether the ordered action on a given card is possible.
MID Merchant identifier. This entity is represending Merchant in Acquirer's system. Customer has to provide the mid information to enable mid configuration in the Verestro system. Required to process transactions and 3DS via Verestro system.
API Key Unique UUID value assigned to the Customer account in Donate Widget Backend. Using this value, the Donate Widget SDK is able to get all configuration data required to perform transaction process via Donate Widget Solution.
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 User wants to pay with a card for purchases on the internet.
CVC It is a type of security code protecting against fraud in remote payments. Card Verification Code is necessary to provide it when User wants to pay with a card for purchases on the internet.
Expiration Date It is a date of the card validity ending and contains two values – month/year. Card will be valid to the last day of the month of the year showed on it. It is necessary to provide it when User wants to pay with a card for purchases on the internet.
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 Donate Widget Solution is performed internally in the Verestro system.
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.
## Donate Widget Key Components This section provides introduction to technologies which are supported by Donate Widget Solution.
**Component** **Description**
Donate Widget Frontend Component containing the part of the solution which is displayed to the User. Basic information about the transaction shown such as the name of the Merchant (Customer), amount and currency, as well as inputs for card data.
Donate Widget SDK Component containing all necessary scripts whether to perform communication between Donate Widget Frontend and Backend and the data exchanging between these two components. Donate Widget SDK should be included on the Customer website.
Donate Widget Backend Component stores the configuration data of a given Customer such Merchant Name or Merchant Id and it is responsible for providing all necessary configurations to the Frontend. It also communicating with various Acquirers and triggers notifications to the Customer and the User (depending on the Customer requirements) about successful or unsuccessful transaction.
Notification Service Component responsible for sending information to the Customer about the status of the transaction status. It is also responsible for sending email to the User about the transaction. Notification Service is triggered by Donate Widget Backend.
## Application Demo The trial version available for viewing and interaction is available [here](https://rpm-front.upaidtest.pl/donate-ukraine). # Onboarding The onboarding process takes place mainly on Verestro side. In order to perform onboarding, the Customer has to provide some information needed to correctly configure him an account in Donate Widget Server. Configuration includes following information: - Customer name – Basically, it's the name of the Customer's company. The following parameter will be displayed to the user in pay donation form – example appearance can be found [here](https://bookstack.verestro.dev/books/donate-widget/page/use-cases#bkmrk-user-flow). - Description – Information about the purpose of the donation. The following parameter will be displayed to the user in pay donation form – example appearance can be found [here](https://bookstack.verestro.dev/books/donate-widget/page/use-cases#bkmrk-user-flow). - Redirect URL’s - Those are the addresses to which user will be redirected after a successful or unsuccessful transaction. These parameters will be added to the Customers's account configuration. - Postback URL - This is the address to which information about the donation will be send to the Customer. This parameter is not required if the Customer does not want to receive notifications regarding the donation - more detailed information about the postbacks can be found [here](https://bookstack.verestro.dev/books/donate-widget/page/technical-documentation#bkmrk-doda%C4%86-opis-metody-po). - Notification to the User - It is a flag that defines whether e-mail notifications will be sent to the User. Such e-mail contains the donation status, donation identifier, date and amount. - Term of use and privacy notes URL – addresses where the Customer stores above-mentioned documents. - Customer's pictures – These are images that could be, for example, the Customer's logo. They will be posted as requested by Customer in the pay donation form and in the e-mail notification. This point is optional. If the Customer does not provide such pictures, the pay donation form will be shown with it's default appearance – example appearance can be found [here](https://bookstack.verestro.dev/books/donate-widget/page/use-cases#bkmrk-user-flow). After creating an account for the Customer, Verestro provides all necessary data for Customer which allow to use the solution. After Customer onboarding is done by Verestro partner can start integration with Donate Widget. Such data includes: - api key – value that defines a Customer in the context of donation process offered by Verestro. The value api-key should be send by the Customer in every request - Verestro system maps the request with the proper Customer's account. Technical information about the api-key can be found [here](https://merchant-beta.upaidtest.pl/champion/docs/paytool.html#_sdk_methods). - basic authorization - it is the login and password of the Customer account in the Verestro system. Basic authorization is needed if the Customer wants to download transaction data via the "[get transaction details](https://bookstack.verestro.dev/books/donate-widget/page/technical-documentation#bkmrk-get-transaction-deta)" method. The Customer must also have to create an account in the Acquirer's system which settles transactions. Such an account is defined by the MID parameter (to find out what MID is, see the "[Terminology](https://bookstack.verestro.dev/books/donate-widget/page/overview#bkmrk-terminology)" chapter). This is a very important parameter as it is required for payment processing. This parameter, together with it's authorization data, can be provided to Verestro by the Customer. Verestro offers support in creating such an account if it has integration with a given Acquirer. If the client requires transactions to be processed with the participation of a new Acquirer, then Verestro must perform a new integration. The client is then responsible for providing the documentation that Verestro will use during the integration. # Use cases Donate Widget is a solution for making cash donations. This functionality does not require any type of session or user account in the Verestro System. Donation is in fact one-time payment e-commerce transaction, therefore it is based on a form in which the user simply enters his card details. This chapter describes the business process from the user's point of view, extended by technical elements. ## Donation process The donation process in the Verestro system begins when user decides to make a donation while still on the Customer website. At this point, the transaction pre-initialization process takes place. 3D Secure process takes place fully on the Verestro side. The sequence diagram below shows the entire transaction process step by step. The diagram below shows a successful transaction process: @startuml skinparam ParticipantPadding 30 skinparam BoxPadding 30 skinparam noteFontColor #FFFFFF skinparam noteBackgroundColor #002060 skinparam noteBorderColor #002060 skinparam noteBorderThickness 1 skinparam sequence { ArrowColor #002060 ArrowFontColor #002060 ActorBorderColor #002060 ActorBackgroundColor #FFFFFF ActorFontStyle bold ParticipantBorderColor #002060 ParticipantBackgroundColor #002060 ParticipantFontColor #FFFFFF ParticipantFontStyle bold LifeLineBackgroundColor #002060 LifeLineBorderColor #002060 } participant "Customer App (Browser)" as browser participant "Donate Widget Front" as pfront participant "Donate Widget SDK" as psdk participant "Donate Widget Backend" as pback participant "Customer Server" as custback participant "Acquirer" as acq note right of browser: 1. User makes decisions about making a donation browser->psdk: 2. Begin transaction psdk->pback: 3. Transaction preinitialize /preinit pback->pback: 4. Store transaction session data pback->psdk: 5. OK - returns transactionId psdk->pfront: 6, Redirect with transactionId pfront->pback: 7. Get transaction (from point 3) pback->pfront: 8. Returns transaction details pfront->pfront: 9. User filling data (CN, CVC, EXP) pfront->pfront: 10. Encrypt data (from point 9) pfront->pback: 11. Perform transaction /transaction/TRX\_ID + enc body pback->acq: 12. Transaction with 3DS note left of acq: At this point 3D Secure process takes place acq->pback: 13. Response pback->pfront: 14. Transaction Result pback->custback: 15. Send postback to provided URL (Optional - configurable) pfront->browser: 16. redirect User (success/failure) note right of browser: Steps 17 & 18 require integration to one REST API POST method provided by Verestro custback->pback: 17. Get transaction status (Optional - configurable) pback->custback: 18. Return transaction status @enduml For easier understanding of the process, each of the steps listed in the diagram are described below: 1. The user which is using the Customer's application, selects the option of making the donation, providing amount and accepts terms of use. 2. The Customer application starts the transaction process by communicating with Donate Widget SDK. 3. Donate Widget SDK performs the transaction pre-initialization by making a request to Donate Widget Backend. 4. Donate Widget Backend creates an entry in the system about initiating the transaction and returns the unique id (in the form of UUID) of the transaction. 5. Donate Widget Backend returns transaction id to the Donate Widget SDK. 6. Donate Widget SDK redirects the user to a form in Donate Widget Frontend. 7. Donate Widget Frontend retrieves from the backend information about the created transaction (in point 4) using the previously obtained transaction id. 8. Donate Widget Backend returns transaction details to the Donate Widget Frontend. 9. The user fills in the form with card data and personal data and clicks “Confirm and Pay” button. 10. Donate Widget Frontend encrypts data with JWE standard. 11. Donate Widget Frontend makes a payment request (based on the previously received transaction id) to the Donate Widget Backend providing encrypted data collected from the user. 12. Donate Widget Backend makes transaction with 3D Secure request to the Acquirer. 13. Acquirer returns transaction with 3D Secure status. 14. Donate Widget Backend provide transaction status to Donate Widget Frontend. 15. Donate Widget Backend sends a postback about the completed transaction along with transaction status and a unique transaction id to the Customer Server (this step takes place if the Customer wants to use this option). 16. Donate Widget Frontend displays transaction status to the user and redirects him to the approciate site (redirect URL provided by the Customer). 17. Customer Server gets transaction details from Donate Widget Backend using transaction id (this step takes place if Customer wants to use this option). 18. Donate Widget Backend returns transaction details to the Customer Server.

**After the user completes the transaction, it is highly recommended that the Customer** **gets** **the transaction** **details from Donate Widget Backend** **(as shown in point 17 & 18 of the diagram above) or listen for postbacks (as shown in point 15 of the diagram above).**

## User flow This section describes each of the steps from end user point of view. Each of the steps is reflected in the pictures which are showing default application design. After the user selects the “make a donation” option, the redirection to a separate web page happens – hosted by Verestro – where the view for selecting the donation amount and accepting the terms of use appears:

The appearance of the donation form can be adapted to the expectations of the Customer, e.g. by adding his company's logo to the form.

[![image-1656932708108.png](https://bookstack.verestro.dev/uploads/images/gallery/2022-07/scaled-1680-/image-1656932708108.png)](https://bookstack.verestro.dev/uploads/images/gallery/2022-07/image-1656932708108.png) [![image-1656932679700.png](https://bookstack.verestro.dev/uploads/images/gallery/2022-07/scaled-1680-/image-1656932679700.png)](https://bookstack.verestro.dev/uploads/images/gallery/2022-07/image-1656932679700.png)
The default grant amounts and the minimum grant amount are configurable. The "Donate" button remains inactive until the user selects the amount of the donation and accepts the terms of use (this button is responsible for ordering the donation). After filling in all the required fields with the data, the "Donate" button is unlocked.
After clicking the "Donate" button, user will be redirected to the payment form - hosted by Verestro. Pictures and descriptions presented in the form example below are configurable depending on the needs of Customer a form for card data and personal data is displayed to the user. The picture below shows this form:

The appearance of the payment form can be adapted to the expectations of the Customer, e.g. by adding his company's logo to the form.

[![image-1651754546896.png](https://bookstack.verestro.dev/uploads/images/gallery/2022-05/scaled-1680-/image-1651754546896.png)](https://bookstack.verestro.dev/uploads/images/gallery/2022-05/image-1651754546896.png)
The user must fill in each of the fields with the appropiate data. Each parameter must meet the validation requirements, e.g. The card number must comply with the Luhn algorithm. The user must also confirm the acceptance of the terms of use. If the field's validation requirement is not met, the field is highlighted in red and the „Confirm and Pay” button remains inactive. The picture below shows a form with correctly filled data:
[![image-1651755384592.png](https://bookstack.verestro.dev/uploads/images/gallery/2022-05/scaled-1680-/image-1651755384592.png)](https://bookstack.verestro.dev/uploads/images/gallery/2022-05/image-1651755384592.png)
After pressing the "Confirm & Pay" button, the process of communication with the bank takes place. Upon its completion, the status of the transaction will be shown to the user. The pictures below show "success" and "fail" status view:
[![image-1651755895396.png](https://bookstack.verestro.dev/uploads/images/gallery/2022-05/scaled-1680-/image-1651755895396.png)](https://bookstack.verestro.dev/uploads/images/gallery/2022-05/image-1651755895396.png) [![image-1651755898629.png](https://bookstack.verestro.dev/uploads/images/gallery/2022-05/scaled-1680-/image-1651755898629.png)](https://bookstack.verestro.dev/uploads/images/gallery/2022-05/image-1651755898629.png)
Regardless of the transaction status, the user is redirected to the address provided by the Customer. The user can go to this address by clicking „Return to the shop” button or simply wait for an automatic redirection.
At the each stage, the user can view the “Term of use”, “Privacy notice”, “FAQ” by clicking approciate option as shown on the screen below: [![image-1651755975614.png](https://bookstack.verestro.dev/uploads/images/gallery/2022-05/scaled-1680-/image-1651755975614.png)](https://bookstack.verestro.dev/uploads/images/gallery/2022-05/image-1651755975614.png)