Welcome to the Digital Value Services (DVS) API reference.

This API serves as the primary gateway to facilitate digital value transfers through Prism.

The Digital Value Services API is organized according to REST principles, using JSON as format for data interchange, and provides the following services:

• Discovery Services
• Transaction Services
• Account Services

Endpoints of the API are prefixed with a corresponding version number.

This is done to provide complete isolation between implementations and to ensure that subsequent major changes to the API will never affect existing integrations.

When a new version of the API is available and you are keen to upgrade, testing in the sandbox environment to ensure that everything works well with your implementation before switching to the production environment comes highly recommended.

The main purpose of this API is to deliver value (e.g. mobile airtime top-up, data bundles, etc.) to a beneficiary. This is what we call a "transaction".

During the course of a transfer, a transaction undergoes various status changes (or transitions) as illustrated below.

As changes in transaction status occur, updates are sent in real-time when a callback URL is provided. In conjunction, transaction status can be queried through one of two means: via the returned id or a provided external_id.

The latter serves as your unique reference and provides a utility to retrieve transaction details when exceptions occur, such as when the supposed API response was not received, as an example.

Transactions can be created through the platform as long as there is enough balance available in your account. A given balance is composed of the following:

As a given transaction goes through various changes in status as outlined here, corresponding balance movements will be made. The following table illustrates the relationship between transaction status and balance movements:

As soon as a transaction is confirmed, the transfer order will be sent to the operator for immediate processing. During this time, the transaction will remain in a CONFIRMED status until the final status is received from the operator.

As a transaction is being processed, changes in status will be notified in real-time if a callback URL was provided.

This callback endpoint must be implemented by the sending partner, which should expect an HTTP POST request containing a transaction object represented in JSON.

Upon successful receipt of data, the callback endpoint should respond with an HTTP 2XX status. In the event that the platform did not receive a successful status, callback notifications will be retried several times, beyond which, the transaction status will have to be queried through the API.

HTTP Status Codes

Standard HTTP response codes are used to indicate whether an API request was successful or not.

API Error Codes

Transaction Status

REJECTED and DECLINED status classes both denote unsuccessful transactions. The primary distinction between these two relates to the party that determined the failure:

• REJECTED are issued by the DVS platform based on various business rules (e.g. insufficient balance, limitations, etc)
• DECLINED are issued by the operators

Separately, it is recommended to define application logic based on classes, while additional distinction and/or insight are reflected on the actual status.

API resources supporting bulk fetches via "list" API methods will be returned in a paginated fashion.

Input Parameters

Output Headers

The Digital Value Services platform provides access to various products across several industries. Such industries are termed as "services" in the Digital Value Services platform.

Products are available across various geographical boundaries. These endpoints provide the means to enumerate available countries, which can then be used to filter against the list of available products in your account.

Products in the Digital Value Services Platform are associated to individual service providers, termed as "operators".

Products ultimately redeem into one or more underlying benefits. These endpoints provide the means to enumerate available benefits, which can then be used to filter against the list of available products in your account.

Receiving operators are running seasonal promotions on selected products, this endpoint will provide visiblity on these promotions: start date, end date, terms and conditions, eligible products, ...

Products form the actual digital values and/or products being transferred through the Digital Value Services platform.

Products are organized and subdivided into distinct types as each one has distinct characteristics and technical implications when transactions are performed. As such, each product type also carries a distinct schema.