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

As the main gateway, this API plays a crucial role in faciliating a broad spectrum of digital value transactions across the extensive DT One network. Beyond its remarkable global reach, which includes over 160 countries and partnerships with more than 875 mobile operators and billers, the network also encompasses a diverse array of services. These include eSIM options, utility and bill payment services, a multitude of gift card products, gaming PINs, and much more. This diversity in offering ensures that the API can cater to a wide range of digital transaction needs, making it a versatile tool for users worldwide.

Structured in the robust foundations of REST principles, the DVS API uses JSON for its data interchange format. It encompasses a variety of services, including:

• Discovery Services - Explore and identify a wide range of available products and services.
• Transaction Services - Manage and execute various transaction types efficiently.
• Account Services - Account related operations.
• Look-Up Services - Utilize search functionalities for specific needs.

To access the API, you will need a valid pair of keys as detailed in the Authentication section. This requires you to first register for a DT Shop account. Once registered, you can generate keys for both production and pre-production environments in the Developer Section of your DT Shop account.

Your queries and feedback are invaluable to us. Should you have any questions or suggestions about our API, we warmly encourage you to reach out to us by sending an email to the DVS API support team. Your inputs help us continually improve and tailor our services to better meet your needs.

Officially supported SDKs are available for the following languages:

• Java
• Node.js

These SDKs offer an accelerated path to developing your applications as an alternative to accessing the REST API directly.

Separately, we would love to hear from you! If you have any questions and/or suggestions related to our SDKs, please do not hesitate to create corresponding GitHub issues or send an email to the DVS Open Source team.

A sandbox environment is available for testing integrations with the DVS API. It is available at https://preprod-dvs-api.dtone.com/v1/.

You can generate sandbox API keys from your DT Shop account, under the Pre-Production API Keys section.

All transactions on the sandbox environment are simulated: no real transaction goes through. To simulate different responses, the last three digits of the credit_party_identifier (i.e. mobile_number or account_number, depending on the required_credit_party_identifier_fields of a given Product) will have to be replaced with one of the following suffixes:

The different suffixes for a given transaction status can be used to simulate delays, as follows:

• 10X suffix will take at least 3 seconds to finish
• 20X suffix will take at least 20 seconds to finish
• 30X suffix will take at least 5 minutes to finish

Please note that there are products that do not require any credit party identifier such as Gift Cards. For these products, the simulated transaction will always be in COMPLETED status.

Endpoints of the API are prefixed with a corresponding version number. This method provides complete isolation between implementations and guarantees subsequent major changes to the API will never affect existing integrations. No breaking changes will be introduced within a major version. This distinction is further expounded in the subsection that follows.

Non-Breaking Changes

Also known as backward-compatible changes, such changes allow for your integration to continue without requiring additional changes on your side. Such changes also do not warrant a new version number and will be released without prior communication.

Changes in this category are mainly "additive" in nature, with the following examples:

• Adding new API endpoints
• Adding optional fields to a request body and/or header
• Adding fields to a response body and/or header
• Data changes:
  • Adding new Countries / Operators / Products / Services
  • Modification of text and/or numeric field values, such as:
    • Country / Operator / Product / Service Names
    • Wholesale / Retail Prices and/or Rates
    • Status and Error Descriptions
• Adding fields to a callback request body

💡 Before going live, it is very important to validate that your integration is capable of handling non-breaking API changes to mitigate avoidable disruptions to your service.

Breaking Changes

Breaking changes, on the other hand, require additional changes to your integration. Such changes correspond to major updates in the API and are mainly reserved for changes that brings about a substantial feature and/or improvement to the platform. When such changes occur, as endpoints of the API are prefixed with a corresponding version number, your existing integration won't be at risk of breaking as complete isolation of differences in implementation between versions are provided.

Examples of changes in this category are as follows:

• Removing and/or renaming API endpoints
• Adding required fields to a request body and/or header
• Removing and/or renaming fields from a request body and/or header
• Removing and/or renaming fields from a response body and/or header
• Removing and/or renaming fields from a callback request body

💡 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:

Once a product has been selected through one of the discovery methods provided by the API, the actual transfer (i.e. transaction) can be performed in either one of the following modes:

• Asynchronous (recommended)
• Synchronous

Each mode is accessible via a specific endpoint.

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.

Asynchronous Mode

When a transaction is created and confirmed in an asynchronous fashion, the HTTP connection won't have to be kept open. This preserves system resources on your applications. As such, performing transactions asynchronously is recommended.

Synchronous Mode

When a transaction is created and confirmed in a synchronous fashion, the HTTP connection will be kept open in an attempt to capture the final status from the receiving operator so it can be returned in the API response. The processing time usually takes just a few seconds. However, with some receiving operators, it may take longer.

Our system will keep the HTTP connection open for up to 180 seconds and will return a status before closing this connection. This status can be in one of the final status (e.g. COMPLETED, DECLINED) or not (e.g. SUBMITTED). In the latter case, this denotes the transaction is still being processed by the receiving operator.

Note: your application does not have to wait for the connection to close, it can listen for a shorter period of time and query the final status later on (refer to the "Final Status" section below for more details).

Final Status

Regardless of the processing mode, the application should be designed to capture the final status of a transaction. This can be done through one of the following means:

• Checking the status of a specific transaction via the corresponding API method ("pull" mechanism)
• Configuring a callback URL passed in the request when creating a transaction ("push" mechanism)

As a transaction is being processed, changes in status will be notified in real-time if a callback URL was provided. Even though one callback per transaction is expected (i.e. change to either COMPLETED or DECLINED), a manual reversal from the DT One team, which may happen in very rare occasions, will also trigger a callback to inform your application of a change in transaction status to REVERSED.

This callback endpoint must be implemented by the sending partner, which should expect an HTTP POST request containing a transaction object represented in JSON. As callbacks will be sent from the DT One servers, these endpoints will have to be publicly-accessible in most cases. During development, a service such as ngrok can be used to expose local servers to the internet.

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

DT One uses standard HTTP response codes 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

Support for internationalization (i18n) is implemented via standard HTTP content negotiation. API resources offering i18n will have the following request and response headers:

Input Headers

Output Headers

The API endpoints have rate limiting in place to protect our service from excessive number of requests. Rate limiting is enforced for every pair of API key and secret and the number of remaining API requests over a period of time (i.e. expressed in seconds) is conveyed through corresponding HTTP headers:

Response Headers

If the limit is reached, an HTTP error 429 will be returned by the server.

The Digital Value Services platform offers a wide array of products spread across diverse industries, categorized as "services." Each service encompasses specific examples, providing a broad spectrum of options to cater to different needs.

Digital products on our platform are designed for different areas: some are for use in just one country, while others can be used across multiple countries or even globally. One of the key features of the API is its ability to return "coverage" - a list of countries where a particular product is supported. This feature is currently in beta-testing mode. To start utilizing it, it's important to ensure that your account is opted-in for beta features. You can activate this by sending a detailed request to our Customer Care team, expressing your interest in accessing this feature. This will enable you to fully leverage the global capabilities of the API.

Additionally, some services are further subdivided into subservices:

💡 Access to services and subservices on the DVS platform will depend on whether these services are included in your pricelist. If you notice a service that you need is not available, it may be because products under this specific service has not yet been added to your pricelist. To address this, you can reach out directly to your Account Manager, who can assist in customizing your pricelist to include the needed services. Alternatively, you can send an email to our Customer Care team with a detailed request of adding a specific service type. This process ensures that your pricelist is tailored to meet your unique business requirements and preferences, allowing you to fully utilize the range of services offered by the platform.

Products available in the platform cover various geographical areas. 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. Countries are displayed in the official names along with their standard ISO 3166 codes. For countries that have multi-country coverage, these are indicated by especially-designated 3-digit codes that conforms with the same pattern as with the standard ISO codes:

Please note that these countries are in addition to the official list of ISO 3166 codes, and are introduced to cater to specific needs to denote regional coverage. This flexibility allows for more comprehensive product discovery and tailored services, especially in contexts like eSIM and multi-country products, where geographical specificity is important.

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

Some examples of operators include:

• Mobile Network Operators
• Utility Prepayment Meter Operators
• VoIP Providers
• etc.

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, ...

Custom marketing campaigns, this endpoint will provide visiblity on these campaigns.

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.

The regions field indicates product coverage on a given country across its constituents where applicable. Examples of the discovery flow for such products are as follows:

1. Retrieve all Global products:

   • Endpoint: GET /v1/products?country_iso_code=GXX
   • Returns: Global products

2. Retrieve Regional products:

   • Endpoint: GET /v1/products?country_iso_code=EXX
   • Returns: Products in the Europe region.

3. Retrieve Country-Specific products:

   • Endpoint: GET /v1/products?country_iso_code=MXN
   • Returns: Products specifically for Mexico.

4. Retrieve all products available for a given country, including Global and Regional products:

   • Endpoint: GET /v1/products?region={country_iso_code}
   • Returns: Products covering a specific country, including Global, Regional, and Country-Specific products.