VIPASO PSP Integration Template

The VIPASO payment system is an end-to-end payment solution that facilitates payments
from consumers to merchants on the point of sale using a PoS app for the merchant and a Pay app for the consumer
or through the respective mobile SDKs.

This document describes the core concepts as well as a template API for payment service providers that want to
provide an integration API for the VIPASO solution. Once a PSP provides an integration API like the template
described here, VIPASO can integrate the PSP and use it to facilitate payments.

Further details on the VIPASO solution itself can be found in our online solution documentation
starting at the following page: Getting Started with VIPASO

Concepts

The core concepts and entities of the integration API for PSPs are divided into two groups.

The reference data is mostly static data that can be provided to the VIPASO system for automatically importing
consumers, merchants and payment instruments.

The payment API group contains the concepts and actions to facilitate dynamic workflows of the API like
the actual payment itself as well as pre-authorizing amounts for offline usage.

Reference data

The VIPASO payment system facilitates payments from consumers to merchants. More specifically from a payment
instrument of a consumer (like a bank account, a mobile number account or a credit card) to a merchants account.
This account of the merchant is pre-configured during onboarding of a merchant and always used for receiving payments.
Payment instruments for consumers can be added and each consumer can have multiple instruments of different types.

Merchants

Merchants are the receiving end of a payment transaction and usually have an account configured at the PSPs system
to be able to receive payments.

The VIPASO system needs at least the following properties:

Name
Legal name
Supported currencies

Other examples of properties are:

Legal address
Geolocation of the shop
Email contact
Phone contact
Website

Consumers

Consumers are the ones paying for goods or services of a merchant. They want to transfer money to the merchant
in a payment transaction. In order to do so they have one or multiple payment instruments from which money can be
transferred over the PSP.
It is important to notice, that the VIPASO system doesn't necessarily need any consumer data from the PSPs system.
If no consumers should be imported, the VIPASO system can be configured that consumers can register themselves but then
need to add a payment instrument to the system themselves as well.

Optional examples of properties are:

First and last name
Phone number
Email address

Payment instruments

Payment instruments are the source of the money for a payment and are owned by a consumer. Payment instruments
can either be bank accounts, mobile money accounts or credit/debit cards. These can either be imported from the
PSP system while importing the consumer data or be added to the system over the PSP by the consumers using the
VIPASO apps.

The VIPASO system needs at least the following properties:

Owner name
Type (card, bank, mobile money)
Last 4 digits of account number (PAN, IBAN, phone number)

Payment

Actions with payments are the core use cases of the VIPASO payment system. Initializing and executing payments
is the most generic concept but for offline usage VIPASO also uses the concept of pre-authorizations which
reserves some amount of a consumers payment instrument.

Payments

Payments are transferring money from a consumer to a merchant using one of the consumers payment instruments.

Properties of a payment include:

Consumer reference
Consumers payment instrument reference
Merchant reference
Amount value
Currency
Status of transaction

Pre-authorizations

Pre-authorizations are means to reserve some amount of money on a payment instrument of a consumer so the consumer
can not spend that amount for the time the pre-authorization is active. It is used by the VIPASO system to ensure
funding of a payment instrument while consumers use the VIPASO apps offline. The concept is based on credit card
pre-authorizations like car rental companies or hotels use for deposits.

A pre-authorization can be referenced in a payment which will deduct the amount of the payment from it. That means
the amount of the reserved money is reduced by the actual payment done, the rest of the pre-authorization amount
is still reserved.

Pre-authorizations can also be deleted in which case the reserved amount should be free to be spent
by the consumer with the payment instrument again.

Properties of a pre-authorization include:

Consumer reference
Consumers payment instrument reference
Amount value
Currency

Workflows

Gather reference data

If possible and provided by the PSP, the VIPASO system imports merchant and consumer reference data on system
initialization and can update it periodically if needed. This is simply done by getting lists of all merchants,
consumers and their payment instruments and storing it in the system for future payments.

Add new payment instrument

If consumers and their payment instruments are not imported during optional gathering of reference data,
consumers can onboard their payment instruments through our VIPASO Pay app and SDK.

Execute payment

The following diagram shows the usual flow of executing a payment from a consumer to a merchant with the VIPASO
system through the PSP integration.

Offline payment

In case either the merchant and/or the consumer mobile devices are offline, the VIPASO system supports to reserve
some amount of money on a consumers payment instrument to settle the actual payments later when one or both
are back online.

API template specification

In order for a PSP to provide the concepts and workflows described above, it needs to provide a REST API to the
VIPASO system. A template of how such an API could look like is provided here in
OpenAPI specification format.

VIPASO PSP integration API template