Digital Value Services API (1.2.0)

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.

Integration Libraries

Officially supported SDKs are available for the following languages:

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.

Sandbox

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 recipient mobile number (i.e. credit_party_identifier.mobile_number) will have to be replaced with one of the following suffixes:

Suffix Transaction Status Example
100, 200, 300 COMPLETED (PIN-less) +6595123100
101, 201, 301 COMPLETED (PIN-based) +6595123201
102, 202, 302 DECLINED-INVALID-CREDIT-PARTY +6595123102
103, 203, 303 DECLINED-BARRED-CREDIT-PARTY +6595123103
104, 204, 304 DECLINED-OPERATOR-CURRENTLY-UNAVAILABLE +6595123205
105, 205, 305 DECLINED-DUPLICATED-TRANSACTION +6595123105
106, 206, 306 DECLINED +6595123206
107, 207, 307 DECLINED-EXCEPTION +6595123107

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

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 the production environment 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 undergoes various status changes (or transitions) as illustrated below.

transaction states

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.

Balances

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:

Balance Description
Available Balance amount available for use
Holding Amount being held while transactions are being processed

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:

Transaction Status Balance Movement Description
CREATED Authorize Transfer wholesale price and fee from available to holding
CANCELLED, REJECTED, DECLINED Void Amount authorized in holding moves back to available
COMPLETED Capture Amount authorized in holding is captured, i.e. debited
REVERSED Reverse Debited amount is reversed back into available

Flow

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 (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. 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)

Callbacks

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.

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
1000429 Too many requests
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
1007500 Method not supported by operator
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-LIMITATIONS-ON-OPERATOR-AMOUNT Rejected - Limitations on operator cumulative transaction amount
REJECTED REJECTED-LIMITATIONS-ON-CREDIT-PARTY-AMOUNT Rejected - Limitations on credit party cumulative transaction amount
REJECTED REJECTED-LIMITATIONS-ON-CUSTOMER-AMOUNT Rejected - Limitations on customer cumulative transaction amount
REJECTED REJECTED-LIMITATIONS-ON-OPERATOR-QUANTITY Rejected - Limitations on operator cumulative transaction quantity
REJECTED REJECTED-LIMITATIONS-ON-CREDIT-PARTY-QUANTITY Rejected - Limitations on credit party cumulative transaction quantity
REJECTED REJECTED-LIMITATIONS-ON-CUSTOMER-QUANTITY Rejected - Limitations on customer cumulative transaction quantity
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-LIMITATIONS-ON-OPERATOR-AMOUNT Declined - Limitations on operator cumulative transaction amount
DECLINED DECLINED-LIMITATIONS-ON-CREDIT-PARTY-AMOUNT Declined - Limitations on credit party cumulative transaction amount
DECLINED DECLINED-LIMITATIONS-ON-CUSTOMER-AMOUNT Declined - Limitations on customer cumulative transaction amount
DECLINED DECLINED-LIMITATIONS-ON-OPERATOR-QUANTITY Declined - Limitations on operator cumulative transaction quantity
DECLINED DECLINED-LIMITATIONS-ON-CREDIT-PARTY-QUANTITY Declined - Limitations on credit party cumulative transaction quantity
DECLINED DECLINED-LIMITATIONS-ON-CUSTOMER-QUANTITY Declined - Limitations on customer cumulative transaction quantity
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
Finance Financial Services and Institutions
Government Government Agencies

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
[
  • {
    }
]