GuidesAPI ExplorerSupport

Provisioning

Check the Provisioning API reference:

Provisioning is about creating and managing your assets, i.e. your merchants, stores, physical and logical devices. The available asset operations are:

  • Creation

  • Update

  • Deletion

There is also the possibility of provisioning in bulk. To read more about it, see the Bulk Provisioning section.

The Provisioning APIs are available at https://{baseUrl}/provisioning/v2/.

Prerequisites

To successfully provision your assets:

  • Your organization must be created and successfully onboarded into the platform.

  • Regarding your application:

    • It must be created and configured in the client portal. Only Developer and Admin accounts are able to create an application, so your account needs to be assigned at least one of these roles.

    • It must have your preferred client credentials flow enabled.

    • It must be assigned the Onboarding role.

Provisioning an asset

You can do the following for any of your assets, i.e. your merchants, stores, logical and physical devices.

Create a new asset.

e.g. POST /v2/merchants, POST /v2/physical-devices

View an asset's details. The asset is specified by its unique identifier.

e.g. GET /v2/merchants/{id}, GET /v2/logical-devices/{id}

Update an asset's details. The asset is specified by its unique identifier.

e.g. PUT /v2/merchants/{id}, PUT /v2/logical-devices/{id}

Delete an asset. The asset is specified by its unique identifier.

e.g. DELETE /v2/merchants/{id}, DELETE /v2/logical-devices/{id}

Important

Deleting an entity is only allowed when it does not have any dependency. For example, you can only delete a merchant, if there is no store attached to it.

Link a logical and physical device

A logical device is an abstract form of a payment device without any hardware accompanying it. It belongs to a store of a merchant and can be mapped to a physical payment device of any type or model. A logical device can be mapped to none, one or two physical devices (e.g. while a device is being repaired and we swap it with another one).

To link a logical device to a physical one:

  • Both devices need to be already registered in the PPaaS portal.

  • You need the unique identifiers for both the logical and physical device to successfully link them together.

Bulk Provisioning

You can provision your assets in bulk in two ways:

  • Using the Bulk API family.

  • Through the portal.

Bulk Provisioning APIs

Use these APIs as described in the Provisioning APIs reference page.

Bulk Provisioning in the portal

  1. Go to the Bulk Imports section.

  2. Click Bulk Import Templates and select the one suitable for your use case.

  3. Fill in the template with your data and save it.

  4. Click Bulk Import.

  5. Select the template type you are using and place it in the designated box.

  6. You see a success message that the file has been uploaded.

  7. Next to "Process File", select Start.

  8. You should see a success message that the campaign has started successfully.

  9. The campaign is now in Processed status.

  10. Click the campaign to see important details such as its status, the total records that have been processed as well as how many of them were accepted or rejected.

  11. Click Download Report to see more details such as the exact error messages of your campaign.

Child organizations

A child organization is an entity in your PPaaS organizational structure that belongs to another entity, often called the parent organization. A child organization can have its own merchants which are in turn considered indirect merchants to the parent organization.

PPaaS Provisioning APIs allow you to create and manage your child organization(s) along with their merchants, stores, logical and physical devices.

Minimum Provisioning API

The Minimum Provisioning API family is designed to facilitate provisioning of organizations, merchants, stores and devices all at once. It can also be useful when the organization to be provisioned has only one store and one device for a given merchant.

Use the merchant-hierarchy API family to create the above assets for your organization in one go. If your logical and physical devices are already known and created in the portal, you can create their links with the same API. Otherwise, you can link your devices later using the attach-device API method.

What's new in Provisioning v2

Version 2.3.0

Added

Segments concept and API method.

A segment is a group of merchants that meet certain criteria set by the organization admin. Using segments, the MA admin can have filtered views of their merchants based on their predefined criteria, making it easier to categorize the data.

Changed

The physical-devices API method has organization as its parent type (instead of device-stock in v1).

Removed

Device-stocks API method.