Technical documentation
Overview
This chapter provides the instruction of the integration with the solution and with it's methods. Prior to using this solution the Customer have to proceed onboarding process. To create account please contact with support.
Integration
This section describes how to integrate the solution using the SDK provided by Verestro. The merchant-paytool.js is a JavaScript-based client-side SDK. The SDK adds MerchantPayTool class to the global JavaScript scope which can be further instantiated to start Donate Widget’s payment process. Alternatively, it also defines a custom element called merchant-paytool for a more straightforward, plug-and-play solution.
An optional step is to send a transaction status notification to the Merchant Server. Details of the notification are described in the postback section.
Additionally, the PayTool SDK provides a method that allows you to " get transaction details " using " transactionId" parameter.
API Reference
Initialization Add the following script to your website:
Test environment:
Production environment:
The type="module" attribute is currently required, because the SDK utilizes modern JavaScript code splitting syntax.
SDK Methods
init
(class approach only) Starts PayTool's payment process using the provided data.
After successful initialization, resolves a promise and redirects to PayTool's website.
Rejects a promise if any error occurs.
Parameters
data
initData
Returns
Promise
Interfaces
Data object passed to PayTool's backend API.
initData
Name
Type
Description
apiKey
string
Merchant identifier, given during onboarding.
amount
number
Transaction amount in the lowest unit of money, fe. cents for USD.
currency
string
Transaction currency code.
description
string
Short description of transaction.
redirectUrls
object
Optional return url object. If not provided, urls from merchant’s config will be used instead.PayTool might append additional query parameters to the urls, fe. a transaction identifier.
redirectUrls.successUrl
string
The url where users will be redirected after a successful payment.
redirectUrls.failureUrl
string
The url where users will be redirected after a failed payment.
Examples
The SDK offers different ways to initialize a payment. It can do most of the heavy lifting by itself, including UI, but it also exposes a lower-end API to let you customize your UX.
Class approach
Angular
{
import { Component } from '@angular/core';
@Component({
selector: 'app-root',
template: '',
})
export class AppComponent {
payTool = new MerchantPayTool();
onClick() {
this.payTool
.init({
apiKey: 'YOUR_API_KEY',
amount: 9999,
currency: 'CURRENCY_CODE',
description: 'TRANSACTION_DESCRIPTION',
redirectUrls: {
successUrl: 'YOUR_SUCCESS_URL',
failureUrl: 'YOUR_FAILURE_URL'
}
})
.catch(console.log);
}
}
}
React
export const App = () => {
const payTool = new MerchantPayTool();
return (
);
};
Plain JavaScript
Web component approach
This approach focuses on modern solutions to help your integrate with PayTool as fast as possible and keep your code clean, providing a pre-built "Click to Pay" button. The component accepts data as Init Data, similarly to the init method.
Angular
import { Component } from '@angular/core';
@Component({
selector: 'app-root',
template: '',
})
export class AppComponent {
data = {
apiKey: 'YOUR_API_KEY',
amount: 9999,
currency: 'CURRENCY_CODE',
description: 'TRANSACTION_DESCRIPTION',
redirectUrls: {
successUrl: 'YOUR_SUCCESS_URL',
failureUrl: 'YOUR_FAILURE_URL',
},
};
}
React@^18
export const App = () => {
return (
{
if (el) {
el.data = {
apiKey: 'YOUR_API_KEY',
amount: 9999,
currency: 'CURRENCY_CODE',
description: 'TRANSACTION_DESCRIPTION',
redirectUrls: {
successUrl: 'YOUR_SUCCESS_URL',
failureUrl: 'YOUR_FAILURE_URL'
}
};
}
}}
/>
);
};
React@experimental
export const App = () => {
return (
);
};
Plain JavaScript
export const App = () => {
return (
);
};
In case of questions regarding the integration, Verestro actively supports Customer in the implementation.
Postbacks
This section describes the method that allows Customer to receive notifications after every donation made. If Customer wants to handle notifications after transactions Customer must create HTTP POST endpoint which will accept requests in format JSON. If this option is enabled, the Donate Widget API will send information about the donation made to the endpoint provided by the Customer.
This feature is optional but we strongly recommend using it. Without this method, the Customer will not receive any information whether the donation was successful or not.
POST site.customer.com/notifications
Request body:
POST site.customer.com/notifications HTTP/1.1
Content-Type: application/json
Content-Length: 265
{
"transactionId": "3a1e9961-75bc-4279-8791-033c180fa239",
"status": "DEPOSITED",
"amount": 100,
"currency": "USD",
"description": "description"
}
Request headers:
Type
Value
Constraints
Description
Content-Type
application/json
Required
Content type of the request.
Request fields:
Type
Value
Constraints
Description
transactionId
String
Required
Unique Id of transaction.
status
String
Required
Transaction status. AUTHORIZED , DEPOSITED , FAILED , UNKNOWN ,
REFUNDED , REVERSED.
amount
Number
Required
Amount for transaction (minor units of currency).
currency
String
Required
Currency of given amount.
description
String
Required
Simple description of transaction.
Response status: HTTP/1.1 200 OK
Example cURL:
$ curl 'https://site.customer.com/notifications' -i -u 'login:password' -X POST -H 'Content-Type: application/json' -d '{
"transactionId": "387cd038-fa39-40e1-a6ac-0d610b594787",
"status": "DEPOSITED",
"amount": 100,
"currency": "USD",
"description": "description",
}'
Get transaction details
GET [base-url]/transactions/{{transactionId}}
Method allows getting transaction details using " transactionId" . Method is protected by BasicAuth of the Customer.
Request:
GET /champion/transactions/cd670818-dfbe-44fc-8948-8fbf8992d8d3 HTTP/1.1
Authorization: Basic bG9naW46cGFzc3dvcmQ=
Content-Type: application/json
Host: merchant.upaid.pl
Request headers:
Type
Value
Constraints
Description
Content-Type
application/json
Required
Content type of the request.
Authorization
Basic bG9naW46cGFzc3dvcmQ=
Required
Basic Authorization token.
Response body:
HTTP Response - SUCCESS:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 211
{
"transactionId" : "cd670818-dfbe-44fc-8948-8fbf8992d8d3",
"amount" : 100,
"currency" : "PLN",
"description" : "description",
"bin" : "4442211",
"lastFourDigits" : "1234",
"status" : "DEPOSITED"
}
Response fields:
Type
Value
Description
transactionId
String
Unique Id of transaction.
amount
Number
Transaction amount in pennies.
currency
String
Transaction currency.
description
String
Transaction description.
bin
String
Card bin.
lastFourDigits
String
Card last four digits.
status
String
Transaction Status. Possible values: DEPOSITED - transaction finished with success INITIALIZED_3DS - transaction during processing FAILED - transaction failed.
Example cURL:
$ curl 'https://merchant.upaid.pl/champion/transactions/cd670818-dfbe-44fc-8948-8fbf8992d8d3' -i -u 'login:password' -X GET \
-H 'Content-Type: application/json'