--- updatedAt: 2026-08-28T06:14:47.000Z agentTools: projectIndex: https://developers.dtone.com/llms.txt --- # Retrieve promotion by ID # OpenAPI definition ```json { "openapi": "3.0.2", "info": { "title": "Digital Value Services API", "version": "1.23.2", "x-logo": { "url": "https://dvs-api-doc.dtone.com/images/dtone.png" }, "description": "Starting out on your integration journey? Access our [quick start guide](https://developers.dtone.com/get-started.html).\n\n# Overview\n\nWelcome to the comprehensive reference and guide to the Digital Value Services (DVS) API.\n\nAs the main gateway, this API plays a crucial role in faciliating a broad spectrum of digital value transactions across the extensive [DT One](https://www.dtone.com) 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.\n\nStructured in the robust foundations of [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) principles, the DVS API uses [JSON](https://en.wikipedia.org/wiki/JSON) for its data interchange format. It encompasses a variety of services, including:\n - [Discovery Services](#tag/Services) - Explore and identify a wide range of available products and services.\n - [Transaction Services](#tag/Transactions) - Manage and execute various transaction types efficiently.\n - [Account Services](#tag/Balances) - Account related operations.\n - [Look-Up Services](#tag/Mobile-Number) - Utilize search functionalities for specific needs.\n\nTo access the API, you will need a valid pair of keys as detailed in the [Authentication](#section/Authentication) section. This requires you to first register for a [DT Shop](https://dtshop.dtone.com/account?tab=developer) account. Once registered, you can generate keys for both production and pre-production environments in the Developer Section of your DT Shop account.\n\nYour 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](mailto:dvs-api-support@dtone.com). Your inputs help us continually improve and tailor our services to better meet your needs.\n\n## Integration Libraries\n\nOfficially supported [SDK](https://en.wikipedia.org/wiki/Software_development_kit)s are available for the following languages:\n\n* [Java](https://github.com/dtone/dtone-dvs-api-java-client)\n* [Node.js](https://www.npmjs.com/package/@dtone/dvs)\n\nThese SDKs offer an accelerated path to developing your applications as an alternative to accessing the REST API directly.\n\nSeparately, 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](https://guides.github.com/features/issues/) or send an email to the [DVS Open Source team](mailto:opensource@dtone.com).\n\n## Sandbox\n\nA sandbox environment is available for testing integrations with the DVS API. It is available at [https://preprod-dvs-api.dtone.com/v1/](https://preprod-dvs-api.dtone.com/v1/).\n\nYou can generate sandbox API keys from your [DT Shop](https://dtshop.dtone.com/account?tab=developer) account, under the **Pre-Production API Keys** section.\n\nAll 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](/#tag/Products)) will have to be replaced with one of the following suffixes:\n\n| Suffix | Transaction Status | Example |\n| --- | --- | --- |\n| `100`, `200`, `300` | `COMPLETED` (PIN-less) | `+6595123100` |\n| `101`, `201`, `301` | `COMPLETED` (PIN-based) | `+6595123201` |\n| `102`, `202`, `302` | `DECLINED-INVALID-CREDIT-PARTY` | `+6595123102` |\n| `103`, `203`, `303` | `DECLINED-BARRED-CREDIT-PARTY` | `+6595123103` |\n| `104`, `204`, `304` | `DECLINED-OPERATOR-CURRENTLY-UNAVAILABLE` | `+6595123204` |\n| `105`, `205`, `305` | `DECLINED-DUPLICATED-TRANSACTION` | `+6595123105` |\n| `106`, `206`, `306` | `DECLINED` | `+6595123206` |\n| `107`, `207`, `307` | `DECLINED-EXCEPTION` | `+6595123107` |\n\nThe different suffixes for a given transaction status can be used to simulate delays, as follows:\n * `10X` suffix will take at least 3 seconds to finish\n * `20X` suffix will take at least 20 seconds to finish\n * `30X` suffix will take at least 5 minutes to finish\n\nPlease 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.\n\n## Versioning\n\nEndpoints 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.\n\n### Non-Breaking Changes\n\nAlso 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.\n\nChanges in this category are mainly \"additive\" in nature, with the following examples:\n * Adding new API endpoints\n * Adding optional fields to a request body and/or header\n * Adding fields to a response body and/or header\n * Data changes:\n - Adding new Countries / Operators / Products / Services\n - Modification of text and/or numeric field values, such as:\n - Country / Operator / Product / Service Names\n - Wholesale / Retail Prices and/or Rates\n - Status and Error Descriptions\n * Adding fields to a callback request body\n\n💡 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.\n\n### Breaking Changes\n\nBreaking 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.\n\nExamples of changes in this category are as follows:\n * Removing and/or renaming API endpoints\n * Adding required fields to a request body and/or header\n * Removing and/or renaming fields from a request body and/or header\n * Removing and/or renaming fields from a response body and/or header\n * Removing and/or renaming fields from a callback request body\n\n💡 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.\n\n## Transactions\n\nThe 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\".\n\nDuring the course of a transfer, a transaction undergoes various status changes (or transitions) as illustrated below.\n\n![transaction states](/images/transaction_states.png)\n\nAs 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`.\n\nThe 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.\n\n## Balances\n\nTransactions 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:\n\n| Balance | Description |\n| --- | --- |\n| Available | Balance amount available for use |\n| Holding | Amount being held while transactions are being processed |\n\nAs a given transaction goes through various changes in status as outlined [here](#section/Overview/Transactions), corresponding balance movements will be made. The following table illustrates the relationship between transaction status and balance movements:\n\n| Transaction Status | Balance Movement | Description |\n| --- | --- | --- |\n| `CREATED` | Authorize | Transfer wholesale price and fee from available to holding |\n| `CANCELLED`, `REJECTED`, `DECLINED` | Void | Amount authorized in holding moves back to available |\n| `COMPLETED` | Capture | Amount authorized in holding is captured, i.e. debited |\n| `REVERSED` | Reverse | Debited amount is reversed back into available |\n\n## Flow\n\nOnce a product has been selected through one of the [discovery methods](/#tag/Services) provided by the API, the actual transfer (i.e. transaction) can be performed in either one of the following modes:\n - Asynchronous (recommended)\n - Synchronous\n\nEach mode is accessible via a specific endpoint.\n\nAs 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.\n\n### Asynchronous Mode\n\nWhen 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**.\n\n### Synchronous Mode\n\nWhen 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.\n\nOur 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.\n\n**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).\n\n### Final Status\n\nRegardless 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:\n - Checking the status of a specific transaction via the corresponding API method (\"pull\" mechanism)\n - Configuring a callback URL passed in the request when creating a transaction (\"push\" mechanism)\n\n## Callbacks\n\nAs 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](https://dtone.com/) 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`.\n\nThis callback endpoint must be implemented by the sending partner, which should expect an HTTP `POST` request containing a transaction object represented in [JSON](https://en.wikipedia.org/wiki/JSON). As callbacks will be sent from the [DT One](https://dtone.com/) servers, these endpoints will have to be publicly-accessible in most cases. During development, a service such as [ngrok](https://ngrok.com/) can be used to expose local servers to the internet.\n\nUpon 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.\n\n## Status and Errors\n\n### HTTP Status Codes\n\n[DT One](https://dtone.com/) uses standard HTTP response codes to indicate whether an API request was successful or not.\n\n| Status | Description |\n| --- | --- |\n| `200` | OK |\n| `201` | Created: Resource created |\n| `202` | Accepted: Request has been accepted for processing |\n| `400` | Bad Request: Request was malformed |\n| `401` | Unauthorized: Credentials missing or invalid |\n| `404` | Not Found: Resource doesn't exist |\n| `429` | Too Many Requests |\n| `500` | Server Error: Error occurred on DT One |\n| `503` | Service Unavailable |\n\n### API Error Codes\n\n| Code | Description | HTTP Status |\n| --- | --- | --- |\n| `1000400` | Bad Request | `400` |\n| `1000401` | Unauthorized | `401` |\n| `1000404` | Resource not found | `404` |\n| `1000429` | Too many requests | `429` |\n| `1003001` | Product is not available in your account | `404` |\n| `1003002` | Requested product amount is out of range | `400` |\n| `1003003` | Requested product unit is invalid | `400` |\n| `1003101` | Benefits not defined for available products | `404` |\n| `1003201` | Promotion not found | `404` |\n| `1003301` | Campaign not found | `404` |\n| `1005003` | Credit party mobile number is invalid | `400` |\n| `1005004` | Service not found | `404` |\n| `1005005` | Country not found | `404` |\n| `1005006` | Operator not found | `404` |\n| `1005503` | Sender mobile number is invalid | `400` |\n| `1006001` | Insufficient balance | `400` |\n| `1006003` | Debit party mobile number is invalid | `400` |\n| `1006009` | Account balance not found | `404` |\n| `1006503` | Beneficiary mobile number is invalid | `400` |\n| `1007001` | Transaction external ID has already been used | `400` |\n| `1007002` | Transaction has already been confirmed | `400` |\n| `1007004` | Transaction can no longer be confirmed | `400` |\n| `1007005` | Transaction has already been cancelled | `400` |\n| `1007007` | Transaction can no longer be cancelled | `400` |\n| `1007500` | Method not supported by operator | `400` |\n| `1008004` | Transaction not found | `404` |\n| `1009001` | Unexpected error, please contact our support team | `500` |\n| `1009503` | Service unavailable, please retry later | `503` |\n\n### Transaction Status\n\n| Class | Status | Description |\n| --- | --- | --- |\n| `CREATED` | `CREATED` | Created |\n| `CONFIRMED` | `CONFIRMED` | Confirmed |\n| `REJECTED` | `REJECTED` | Rejected |\n| `REJECTED` | `REJECTED-INVALID-CREDIT-PARTY` | Rejected - Credit party is invalid |\n| `REJECTED` | `REJECTED-BARRED-CREDIT-PARTY` | Rejected - Credit party is barred |\n| `REJECTED` | `REJECTED-INELIGIBLE-CREDIT-PARTY` | Rejected - Credit party is ineligible for chosen product |\n| `REJECTED` | `REJECTED-INVALID-DEBIT-PARTY` | Rejected - Debit party is invalid |\n| `REJECTED` | `REJECTED-BARRED-DEBIT-PARTY` | Rejected - Debit party is barred |\n| `REJECTED` | `REJECTED-LIMITATIONS-ON-CREDIT-PARTY-AMOUNT` | Rejected - Limitations on credit party cumulative transaction amount |\n| `REJECTED` | `REJECTED-LIMITATIONS-ON-CREDIT-PARTY-QUANTITY` | Rejected - Limitations on credit party cumulative transaction quantity |\n| `REJECTED` | `REJECTED-OPERATOR-CURRENTLY-UNAVAILABLE` | Rejected - Operator currently unavailable |\n| `REJECTED` | `REJECTED-INSUFFICIENT-BALANCE` | Rejected - Insufficient balance |\n| `CANCELLED` | `CANCELLED` | Cancelled |\n| `SUBMITTED` | `SUBMITTED` | Submitted |\n| `COMPLETED` | `COMPLETED` | Completed |\n| `REVERSED` | `REVERSED` | Reversed |\n| `DECLINED` | `DECLINED` | Declined (no additional information available) |\n| `DECLINED` | `DECLINED-INVALID-CREDIT-PARTY` | Declined - Credit party is invalid |\n| `DECLINED` | `DECLINED-BARRED-CREDIT-PARTY` | Declined - Credit party is barred |\n| `DECLINED` | `DECLINED-INELIGIBLE-CREDIT-PARTY` | Declined - Credit party is ineligible for chosen product |\n| `DECLINED` | `DECLINED-INVALID-DEBIT-PARTY` | Declined - Debit party is invalid |\n| `DECLINED` | `DECLINED-BARRED-DEBIT-PARTY` | Declined - Debit party is barred |\n| `DECLINED` | `DECLINED-LIMITATIONS-ON-OPERATOR-AMOUNT` | Declined - Limitations on operator cumulative transaction amount |\n| `DECLINED` | `DECLINED-LIMITATIONS-ON-CREDIT-PARTY-AMOUNT` | Declined - Limitations on credit party cumulative transaction amount |\n| `DECLINED` | `DECLINED-LIMITATIONS-ON-CUSTOMER-AMOUNT` | Declined - Limitations on customer cumulative transaction amount |\n| `DECLINED` | `DECLINED-LIMITATIONS-ON-OPERATOR-QUANTITY` | Declined - Limitations on operator cumulative transaction quantity |\n| `DECLINED` | `DECLINED-LIMITATIONS-ON-CREDIT-PARTY-QUANTITY` | Declined - Limitations on credit party cumulative transaction quantity |\n| `DECLINED` | `DECLINED-LIMITATIONS-ON-CUSTOMER-QUANTITY` | Declined - Limitations on customer cumulative transaction quantity |\n| `DECLINED` | `DECLINED-DUPLICATED-TRANSACTION` | Declined - Duplicated transaction |\n| `DECLINED` | `DECLINED-OPERATOR-CURRENTLY-UNAVAILABLE` | Declined - Operator currently unavailable |\n\n`REJECTED` and `DECLINED` status classes both denote unsuccessful transactions. The primary distinction between these two relates to the party that determined the failure:\n * `REJECTED` are issued by the DVS platform based on various business rules (e.g. insufficient balance, limitations, etc)\n * `DECLINED` are issued by the operators\n\nSeparately, it is recommended to define application logic based on **classes**, while additional distinction and/or insight are reflected on the actual **status**.\n\n## Pagination\n\nAPI resources supporting bulk fetches via \"list\" API methods will be returned in a paginated fashion.\n\n### Input Parameters\n\n| Field | Required | Type | Description |\n| --- | --- | --- | --- |\n| `page` | No | Integer | Page number |\n| `per_page` | No | Integer | Number of results per page (default 50, max 100) |\n\n### Output Headers\n\n| Field | Description |\n| --- | --- |\n| `X-Total` | Total number of records |\n| `X-Total-Pages` | Total number of pages |\n| `X-Per-Page` | Number of records per page |\n| `X-Page` | Current page number |\n| `X-Next-Page` | Next page number (if any) |\n| `X-Prev-Page` | Previous page number (if any) |\n\n## Internationalization\n\nSupport for internationalization (i18n) is implemented via [standard HTTP content negotiation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation). API resources offering i18n will have the following request and response headers:\n\n### Input Headers\n\n| Field | Required | Type | Description |\n| --- | --- | --- | --- |\n| `Accept-Language` | No | String | List of preferred languages for the content |\n\n### Output Headers\n\n| Field | Description |\n| --- | --- |\n| `Content-Language` | List of languages in the returned content |\n\n## Rate Limiting\n\nThe 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:\n\n### Response Headers\n\n| Field | Description |\n| --- | --- |\n| `X-Ratelimit-Limit` | Number of allowed API calls over period of time |\n| `X-Ratelimit-Remaining` | Remaining number of allowed API calls |\n\nIf the limit is reached, an [HTTP error 429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) will be returned by the server.\n" }, "servers": [ { "url": "https://preprod-dvs-api.dtone.com/v1", "description": "Pre-Production" }, { "url": "https://dvs-api.dtone.com/v1", "description": "Production" } ], "security": [ { "BasicAuth": [] } ], "tags": [ { "name": "Promotions", "description": "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, ...\n" } ], "paths": { "/promotions/{promotion_id}": { "get": { "tags": [ "Promotions" ], "summary": "Retrieve promotion by ID", "operationId": "getPromotionById", "x-mojo-to": "v1#get_promotion_by_id", "parameters": [ { "$ref": "#/components/parameters/Accept-Language" }, { "name": "promotion_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/promotion_id" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/promotion" } } }, "headers": { "Content-Language": { "$ref": "#/components/headers/Content-Language" }, "Vary": { "$ref": "#/components/headers/Vary" } } }, "404": { "description": "Promotion not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "default": { "description": "default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } } } } }, "components": { "securitySchemes": { "BasicAuth": { "type": "http", "scheme": "basic", "description": "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](https://dtshop.dtone.com/).\n\nYour API keys carry many privileges, so please keep them secure! Do not share your secret API keys in publicly-accessible areas such as [GitHub](https://github.com/), client-side code, and so forth.\n\nAuthentication to the API is performed via [HTTP Basic Auth](https://tools.ietf.org/html/rfc7235). Provide your API key as the basic auth username value and your API secret as your password.\n\nExcept when site-to-site VPN is set up, all API requests must be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure) with TLS 1.2.\n\nOn a side note, we strongly recommend securing your applications against common security flaws by employing best practices such as the [OWASP Top 10](https://www.owasp.org/index.php/Category:OWASP_Top_Ten_Project).\n" } }, "schemas": { "x-iso-3166-1_alpha-3": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Country code in [ISO 3166](https://www.iso.org/iso-3166-country-codes.html) format. Note that the official list can be extended with additional country codes." }, "error": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } } }, "required": [ "errors" ] }, "operator_id": { "type": "integer", "format": "int32", "minimum": 1, "description": "Operator identifier." }, "product_types": { "type": "string", "enum": [ "FIXED_VALUE_RECHARGE", "RANGED_VALUE_RECHARGE", "FIXED_VALUE_PIN_PURCHASE", "RANGED_VALUE_PIN_PURCHASE", "RANGED_VALUE_PAYMENT" ] }, "promotion": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "terms": { "type": "string", "nullable": true }, "start_date": { "type": "string", "format": "date-time" }, "end_date": { "type": "string", "format": "date-time" }, "operator": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/operator_id" }, "name": { "type": "string" }, "country": { "type": "object", "properties": { "name": { "type": "string" }, "iso_code": { "$ref": "#/components/schemas/x-iso-3166-1_alpha-3" } }, "required": [ "name", "iso_code" ] } }, "required": [ "id", "name", "country" ] }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "type": { "$ref": "#/components/schemas/product_types" } }, "required": [ "id", "name", "description", "type" ] } } }, "required": [ "id", "title", "description", "terms", "start_date", "end_date", "operator", "products" ], "additionalProperties": false }, "promotion_id": { "type": "integer", "format": "int32", "minimum": 1, "description": "Promotion identifier." } }, "parameters": { "Accept-Language": { "name": "Accept-Language", "description": "Preferred language for the content", "in": "header", "schema": { "type": "string", "example": "es" } } }, "headers": { "Content-Language": { "description": "Language of the returned content", "schema": { "type": "string", "example": "es" } }, "Vary": { "description": "List of request header fields influencing response content", "schema": { "type": "string", "example": "Accept-Language" } } } }, "x-tagGroups": [ { "name": "Discovery", "tags": [ "Services", "Countries", "Operators", "Benefits", "Promotions", "Campaigns", "Products" ] }, { "name": "Transaction", "tags": [ "Transactions" ] }, { "name": "Account", "tags": [ "Balances" ] }, { "name": "Look-Up", "tags": [ "Mobile-Number", "Statement-Inquiry", "Credit-Party" ] } ] } ```