Digital Value Services API (1.0.1)

Download OpenAPI specification:Download

Overview

Welcome to the Digital Value Services API reference.

This API serves as the primary gateway to facilitate digital value transfers through DT One, a leading global network covering more than 160 countries and 550 mobile operators.

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

If you have any questions and/or suggestions related to our API, please do not hesitate to send an email to the DVS API support team.

Environments

To facilitate integration to the API and for testing, two distinct environments are provided:

Pre-production (or sandbox) can be used to access all the API methods and perform transactions to test operators and simulate different scenarios (e.g. response time, status, etc.). Success and failure responses are simulated depending on the suffix of the credit party mobile number as outlined in this link.

On the production environment, actual transactions will be performed to operators available in the product list. As such, real values will be delivered to beneficiaries and your account will be debited accordingly.

Note: We strongly recommend using the sandbox environment to test your implementation and to liaise with the DT One team before switching to production.

Versioning

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 production comes highly recommended.

Feel free to contact us should you have any questions and/or are in need of assistance during your tests.

Transactions

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 will undergo various status changes (or transitions) as illustrated below.

As changes in transaction status occur, updates will be 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 a unique reference in the perspective of the customer and serves as a utility to retrieve transaction details when exceptions occur, such as when the supposed response was not received, as an example.

transaction states

Flow

Once a product has been selected via 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 by 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 resources on the application side. 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 and return it in the HTTP 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 (this value can be configured upon request) 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. CONFIRMED). In the latter case, this means that the transaction is still under processing by the receiving operator.

Note: the 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)

Callbacks

While the 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 DT One team which may happen in very rare occasions will also trigger a callback to inform the customer 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.

Status and Errors

HTTP Status Codes

DT One uses standard HTTP response codes to indicate whether an API request was successful or not.

Status Description
200 OK
201 Created: Resource created
202 Accepted: Request has been accepted for processing
400 Bad Request: Request was malformed
401 Unauthorized: Credentials missing or invalid
404 Not Found: Resource doesn't exist
429 Too Many Requests
500 Server Error: Error occurred on DT One

API Error Codes

Code Description
1000400 Bad Request
1000401 Unauthorized
1000404 Resource not found
1003001 Product is not available in your account
1003002 Requested product amount is out of range
1003003 Requested product unit is invalid
1003101 Benefits not defined for available products
1003201 Promotion not found
1005003 Credit party mobile number is invalid
1005004 Service not found
1005005 Country not found
1005006 Operator not found
1005503 Sender mobile number is invalid
1006001 Insufficient balance
1006003 Debit party mobile number is invalid
1006009 Account balance not found
1006503 Beneficiary mobile number is invalid
1007001 Transaction external ID has already been used
1007002 Transaction has already been confirmed
1007004 Transaction can no longer be confirmed
1007005 Transaction has already been cancelled
1007007 Transaction can no longer be cancelled
1008004 Transaction not found
1009001 Unexpected error, please contact our support team

Transaction Status

Class Status Description
CREATED CREATED Created
CONFIRMED CONFIRMED Confirmed
REJECTED REJECTED Rejected
REJECTED REJECTED-INVALID-CREDIT-PARTY Rejected - Credit party is invalid
REJECTED REJECTED-BARRED-CREDIT-PARTY Rejected - Credit party is barred
REJECTED REJECTED-INVALID-DEBIT-PARTY Rejected - Debit party is invalid
REJECTED REJECTED-BARRED-DEBIT-PARTY Rejected - Debit party is barred
REJECTED REJECTED-OPERATOR-CURRENTLY-UNAVAILABLE Rejected - Operator currently unavailable
REJECTED REJECTED-INSUFFICIENT-BALANCE Rejected - Insufficient balance
CANCELLED CANCELLED Cancelled
SUBMITTED SUBMITTED Submitted
COMPLETED COMPLETED Completed
REVERSED REVERSED Reversed
DECLINED DECLINED Declined (no additional information available)
DECLINED DECLINED-INVALID-CREDIT-PARTY Declined - Credit party is invalid
DECLINED DECLINED-BARRED-CREDIT-PARTY Declined - Credit party is barred
DECLINED DECLINED-INVALID-DEBIT-PARTY Declined - Debit party is invalid
DECLINED DECLINED-BARRED-DEBIT-PARTY Declined - Debit party is barred
DECLINED DECLINED-DUPLICATED-TRANSACTION Declined - Duplicated transaction
DECLINED DECLINED-OPERATOR-CURRENTLY-UNAVAILABLE Declined - Operator currently unavailable

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

Pagination

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

Input Parameters

Field Required Type Description
page No Integer Page number
per_page No Integer Number of results per page (default 50, max 100)

Output Headers

Field Description
X-Total Total number of records
X-Total-Pages Total number of pages
X-Per-Page Number of records per page
X-Page Current page number
X-Next-Page Next page number (if any)
X-Prev-Page Previous page number (if any)

Rate Limiting

The API endpoints have rate limiting in place to protect our service from excessive number of requests.

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

Authentication

BasicAuth

The Digital Value Services API requires requests to be authenticated through individualized API keys. You can view and manage your API keys in DT Shop.

Your API keys carry many privileges, so please keep them secure! Do not share your secret API keys in publicly-accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value and your API secret as your password.

Except when site-to-site VPN is set up, all API requests must be made over HTTPS with TLS 1.2.

On a side note, we strongly recommend securing your applications against common security flaws by employing best practices such as the OWASP Top 10.

Security Scheme Type HTTP
HTTP Authorization Scheme basic

Services

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.

Service Examples
Mobile Airtime Top Ups, Mobile Data Bundles, SMS
Internet Broadband, Wi-Fi Recharge
Utilities Electricity, Water, Utilities
Gift Cards Vouchers, Groceries, Gift Cards
Landline Landline
Television Television
Insurance Insurance
Transportation Transportation
VoIP VoIP Credits

Retrieve list of services

Retrieve list of services

Authorizations:
query Parameters
page
integer <int32> >= 1
Default: 1

Page number

per_page
integer <int32> [ 1 .. 100 ]
Default: 50

Number of records per page

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve service by ID

Retrieve service by ID

Authorizations:
path Parameters
service_id
required
integer <int32> (ServiceID) >= 1

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "string"
}

Countries

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.

Retrieve list of countries

Retrieve list of countries

Authorizations:
query Parameters
page
integer <int32> >= 1
Default: 1

Page number

per_page
integer <int32> [ 1 .. 100 ]
Default: 50

Number of records per page

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve country by ISO code

Retrieve country by ISO code

Authorizations:
path Parameters
country_iso_code
required
string (ISO-3166-1_Alpha-3) ^[A-Z]{3}$

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "iso_code": "string",
  • "regions":
    [
    ]
}

Operators

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

Some examples of operators include:

Retrieve list of operators

Retrieve list of operators

Authorizations:
query Parameters
page
integer <int32> >= 1
Default: 1

Page number

per_page
integer <int32> [ 1 .. 100 ]
Default: 50

Number of records per page

country_iso_code
string (ISO-3166-1_Alpha-3) ^[A-Z]{3}$

Responses

Response samples

Content type
application/json
[
  • {
    }
]