Overview

Welcome to the PPaaS developer platform. This section encompasses details on how to create a simple integration with PPaaS.

High-level view of the API integration solution

Banks and acquirers can leverage API to provision merchant, store, devices. They can also handle the subscription to their services and their configuration. Reporting is also a key functionality available via API. Those core functionalities of PPaaS are available in the core services section.

For service provider who wants to be part of the PPaaS ecosystem can implement the various SPI (Service Provider Interface) and the API. PPaaS manages several business services that can be found in the payment services and commerce services sections.

For development on devices, it can be done by leveraging directly API, or PPaaS SDK. For more information, contact sales.

PPaaS offers the capability for Point of Sales (POS), to connect and perform operations from POS to a terminal leveraging the Nexo Retailer protocol. This part is described in the endpoint section.

Step 1: Sign up for the PPaaS program

Get started with PPaaS by creating a free test account in our demo environment. Your test account gives you access to the test area, which allows you to generate credentials and interact with PPaaS.

Please fill out the sign up form. A member of the partner enablement team will assist you in the journey.

Step 2: Connect to the PPaaS portal

Once your onboarding has been validated by the partner enablement team, you will receive an e-mail from PPaaS noreply@ppaas.tech. The email will provide a link to create your password and set up your OTP (One Time Password). Take care to register, as the link expires within 24 hours.

You will be able to connect to a dedicated portal based on your persona:

Merchant Aggregator portal for an acquirer
Provider Portal for a service provider

In the demo environment, perform the following steps to login:

Set your user domain. The user domain will be communicated by your solution manager, this allows PPaaS to manage your tenant. Enter the e-mail in the format userName@userdomain.com
Enter your login and password (login can be either a username or e-mail address).
Enter your OTP.

The first user will have an Administrator role and will be able to invite colleagues, leveraging the user management section. Ensure that the users created have either the role Developer or Administrator, to be able to create applications and declare services.

Step 3: Register your application and get an application credential

Registering your application in PPaaS allows you to use PPaaS APIs. The application provides the necessary credentials to interact with PPaaS. You can register one or multiple applications.

To register your application, perform the following steps:

Access the Application Management section.
Click on +ADD APPLICATION.
Enter the application name, and description. The description may help other users of your organization to quickly identify the application.
Click on SAVE to validate the registration of your application.

PPaaS supports the below grant types (as defined in the OAuth 2.0 specification:

Authorization Code Grant: To get an access token in exchange for a temporary code, after a user authorizes an application. Use it for B2C scenarios, where your application requires end-user authentication, e.g. acquirer or merchant credentials.
Client Credentials Grant: To get access on behalf of an application, not a user. Use it for B2B scenarios or for all machine-to-machine communication in general.

Note that for B2C flows, you have to set the redirection URL and the web origin URL. For more information about the security mechanism, refer to the integration with OAuth2 section.

You can regenerate your Client Secret whenever it is required. To regenerate your Client Secret, perform the following steps:

Select your application and navigate to the ADVANCED tab.
Click on the RENEW button next to your Client Secret.
Copy the new key that is generated and paste it in your application.

Important: Renewing the Client Secret makes the old one obsolete. All access tokens already generated remain valid until their expiration date.

Step 4: Testing your application

For quick onboarding, generate an application that supports client credential workflows. Use the resource API that allows you to retrieve a list of basics, such as currencies.

Generate an access token

Here is the result:

- json

{
    "access_token":"Access_Token",
    "expires_in":18000,
    "refresh_expires_in":0,
    "token_type":"Bearer",
    "not-before-policy":1609968533,
    "scope":"email profile"
}

Use the token to call the resource endpoint

- text

curl --location 'curl --location 'https://api.int.ppaas.tech/resources/v1/countries'  \
--header 'Authorization: Bearer Access_Token
--header 'Content-Type: application/json' \

You should receive a HTTP response code 200.

Sample payload

- json

[
    {
        "code": "BG",
        "display": "Bulgaria"
    },
    {
        "code": "MM",
        "display": "Myanmar"
    },
    {
        "code": "BI",
        "display": "Burundi"
    },

]

Now you have completed your first API call on PPaaS.

Step 5: As a service provider, register your service

As a service provider, you need to declare your service so that, after implementation, it becomes part of the service catalog that the acquirer can propose to their merchant. In the demo environment, the service that you are building will be attached to a generic acquirer, a generic merchant and store, and device. This will allow you to test your implementation in a self-service model.

Step 6: Advanced testing leveraging webhook & asynchronous callback

In most service provider scenarios, an action on the terminal will trigger a webhook call to the service provider. The service provider must implement this webhook and even provide an asynchronous response.

Here is a typical example with these two concepts: Webhook and asynchronous reply.

Terminal triggers a call; for instance, generate a QR code payment.
PPaaS receives the call from the terminal, enriches the content by providing additional data such as merchant ID, acquirer, and then forwards it to the service provider.
The service provider sends a response to PPaaS with an image, for instance.
This image is displayed on the terminal so that the consumer can scan it and follow the payment journey on his smartphone directly with the service provider.
The service provider sends events to PPaaS to inform them about the payment process flow.
PPaaS acknowledges events.
PPaaS forwards the events to the terminal.

This is a typical complex action workflow. For more details, refer to the Alternative payment methods with QR code page.

Trigger a call as a terminal

One of the pain points is triggering the first set of transactions, i.e., trigger the action on the terminal. This process is not easy to perform as it requires a physical terminal and does not suit automation and development.

Terminal communication is highly secure it requires a special OAuth2 token and an mTLS connection.

To ease the integration, on the demonstration environment only PPaaS allows you to generate this custom token.

To regenerate the custom token, follow the steps:

Ask for a merchant token.
Enter the merchant credential (OTP is disabled for the generic account).
Given this merchant token, call the custom token endpoint within the specific terminal information.
Use this token and inject it into the call that requires it.

You can find the details in the respective topics: APM, gift card, and digital receipt.

This is presented to leverage the sandbox and demo account of a store. Once you have a setup available for your dedicated store, you can also leverage it.

Overall flow leveraging Postman

Request a token

tenant used: sandbox-ma

Callback URL: https://portal.demo.ppaas.tech

Auth URL: https://auth.demo.ppaas.tech/auth/realms/sandbox-ma/protocol/openid-connect/auth

Access Token: https://auth.demo.ppaas.tech/auth/realms/sandbox-ma/protocol/openid-connect/token

clientId: ppaas-portal

Using Postman

Enter merchant credential

Fill the form with the following credentials: username: merchant

password: @Welcome123

No OTP required.

Retrieve custom token POST https://auth.demo.ppaas.tech/auth/realms/sandbox-ma/custom-token you need to provide the url encoded.
Device model
deviceId

Curl command equivalent

- text

curl --location 'https://auth.demo.ppaas.tech/auth/realms/sandbox-ma/custom-token' \
--header 'Authorization: Bearer  TokenRetreivedFromPreviousCall' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'device_model=DX8000' \
--data-urlencode 'device_id=ingenico-DX8000-2097CD800007' \
--data-urlencode 'method=[api, device_flow]'

The results will look like this:

- text

{
    "access_token": "a JWT device token",
    "expires_in": 300,
    "refresh_expires_in": 900,
    "refresh_token": "a JWT to refresh the access token,
    "token_type": "Bearer",
    "id_token": "a JWT representing the Identity of the merchant",
    "not-before-policy": 1609968533,
    "session_state": "ff4fd585-1e54-4514-ba9a-b258edf2f384",
    "scope": "profile email"
}

Trigger a call as a terminal leveraging the custom token

- text

curl --location 'https://api.demo.ppaas.tech/qrcode-payment/v1/transactions' \
--header 'Authorization: Bearer JWTCustomTokenRetreivedFromPreviousCall' \
--header 'Content-Type: application/json' \
--data '{
    "paymentType": "KB",
    "paymentScenario": "consumerscan",
    "scannedPaymentId": "281666027690188713769014",
    "clientTransactionId": "9236613c-ef7e-4a98-bfb6-16048c0e4f9b",
    "paymentAmount": {
        "amount": 2000,
        "currency": "EUR"
    },
    "order": {

        "orderId": "628ac1ce-480a-40bd-8533-48a27371cac0",

        "orderDescription": "Venmo Test"
    }
}

The overall flow is synthesized in this Postman collection.

Environment and portal

Environment	Main API URL	Security	Client portal	Service provider portal
Demo (worldwide)	api.demo.ppaas.tech	auth.demo.ppaas.tech	client-portal.demo.ppaas.tech	spportal.demo.ppaas.tech
North America (UAT/Production)	api.nar.ppaas.com	auth.nar.ppaas.com	{client_name}.client-portal.nar.ppaas.nar	spportal.nar.ppaas.tech
India (UAT/production)	api.ind.ppaas.com	api.ind.ppaas.com	{client_name}.client-portal.ind.ppaas.nar	spportal.ind.ppaas.tech
Europe (UAT/ production)	api.eur.ppaas.com	api.eur.ppaas.com	{client_name}.client-portal.eur.ppaas.nar	spportal.eur.ppaas.tech

Notes:

In a production environment, the client portal URL contains the client's name.
In a demo environment, the client portal and the service provider portal require a two-step login: to determine the user domain and to set credentials.

Production environment and mTLS

Terminal must connect to PPaaS using an mTLS connection to precisely identify the terminal and avoid spoofing. The MTLS flows are essentially used for the devices connecting to the PPaaS API gateway directly on port 9021.

The device must submit a valid client certificate that is recognized by the PPaaS platform. All Ingenico devices contain such a certificate that can be leveraged using a dedicated SDK.

You can obtain the authentication token in one or two steps:

First method for machine-to-machine model
Second method involves end user identification

Machine-to-machine mode

This section provides the process to get a device token.

Do MTLS calls to identify the terminal

As the terminal certificate contains its serial number, PPaaS will be able to identify the store.

- text

curl --key conf/client.key --cert conf/client.pem --cacert conf/bundle.pem  -X GET \
--header 'Content-Type: application/json' \
  https://auth.demo.ppaas.tech/oauth2-mtls/v1/merchants-credentials?serial_number=220597303201181723869389

Notice that the serial number must be provided as a query parameter for the tetra device.

Retrieve clientId / secret

The result of the call provides you with a response, where you can retrieve the clientId and clientSecret.

- json

[
  {
  "merchantName": "firstname lastname",
  "userDomain": "ppaasfr",
  "clientId": "XXX",
  "clientSecret": "YYY"
  }
]

Apply client credential code flow call to get a device token

- text

curl --key conf/client.key --cert conf/client.pem --cacert conf/bundle.pem  -X POST \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode "client_id=${client_id}" \
--data-urlencode "client_secret=${client_secret}" \
--data-urlencode 'grant_type=client_credentials' \
  https://auth.device.demo.ppaas.tech:9021/oauth2-mtls/v1/token

Retrieve access token

Example

- json

{
    "access_token":"JWT access Token",
    "token_type":"Bearer",
    "expires_in":300,
    "refresh_expires_in":0,
    "id_token":"JWT ID token",
    "scope":"openid email profile"
}

Use it on all subsequent calls as a bearer token

End user identification

Connect to https://auth.device.demo.ppaas.tech:9021/oauth2-mtls/v1/token
Provide a username and password leveraging the password grant type
Use the application ppaas-powered-app

- text

curl  --key conf/client.key --cert conf/client.pem --cacert
conf/bundle.pem  --tlsv1.2 --tls-max 1.3 -X POST \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode "username=${username}" \
--data-urlencode "password=${password}" \
--data-urlencode 'grant_type=password' \
--data-urlencode 'client_id=ppaas-powered-app' \
--data-urlencode 'scope=openid profile email'

Retrieve the access token

The result of the call will look like this example.

- json

{
    "access_token": "a JWT device token",
    "expires_in": 300,
    "refresh_expires_in": 900,
    "refresh_token": "a JWT to refresh the access token",
    "token_type": "Bearer",
    "id_token": "a JWT representing the Identity of the the merchant",
    "not-before-policy": 1609968533,
    "session_state": "ff4fd585-1e54-4514-ba9a-b258edf2f384",
    "scope": "profile email"
}

Use the access token in subsequent calls as a bearer token

For more information about OAuth2, refer to the integration with OAuth2 section.