Product Type	Service (ID)	Subservice (ID)
RANGED_VALUE_RECHARGE	`GiftCard (4)`	`Retail Vouchers (41) or Gaming Vouchers (42) or Cash Cards Vouchers (43) or Food Vouchers (44) or Entertainment Vouchers (45) or Travel and Transport Vouchers (46)`

> **Disclaimer** > > Example field values in response JSON files are significant for format and type only. Do not interpret them as actual data; prices, for example, are invented and non-binding. For full endpoint descriptions, see: * **GET**: [Retrieve product by ID](/reference/getproductbyid) * **GET**: [Retrieve list of products](/reference/getproducts) ```json Retrieve product by ID GET /products/11874 ``` ```json Response to Retrieve product by ID { "accepted_calculation_modes": [ "SOURCE_AMOUNT", "DESTINATION_AMOUNT" ], "availability_zones": [ "INTERNATIONAL" ], "benefits": [ { "additional_information": null, "amount": { "base": { "max": 1000, "min": 0.5 }, "promotion_bonus": { "max": 0, "min": 0 }, "total_excluding_tax": { "max": 1000, "min": 0.5 }, "total_including_tax": { "max": 1000, "min": 0.5 } }, "type": "CREDITS", "unit": "GHS", "unit_type": "CURRENCY" } ], "description": "", "destination": { "amount": { "increment": 0.01, "max": 1000, "min": 0.5 }, "unit": "GHS", "unit_type": "CURRENCY" }, "id": 11874, "name": "Open_Range", "operator": { "country": { "iso_code": "GHA", "name": "Ghana", "regions": null }, "id": 1613, "name": "Vodafone Ghana", "regions": null }, "prices": { "retail": null, "wholesale": { "amount": { "max": 65.1759317171309, "min": 0.0325879658585655 }, "fee": 0, "unit": "USD", "unit_type": "CURRENCY" } }, "promotions": null, "rates": { "base": 15.036225400709, "retail": null, "wholesale": 15.3430871435806 }, "regions": null, "required_additional_identifier_fields": null, "required_beneficiary_fields": null, "required_credit_party_identifier_fields": [ [ "mobile_number" ] ], "required_debit_party_identifier_fields": null, "required_sender_fields": null, "required_statement_identifier_fields": null, "service": { "id": 1, "name": "Mobile", "subservice": { "id": 11, "name": "Airtime" } }, "source": { "amount": { "max": 66.5060527725826, "min": 0.0332530263862913 }, "unit": "USD", "unit_type": "CURRENCY" }, "tags": [ "AIRTIME" ], "type": "RANGED_VALUE_RECHARGE", "validity": null } ``` For Ranged Value products, here's what you need to know about the amounts: * **Source Amount** (`source.amount`): The amount in the customer's wallet currency (face value). * **Destination Amount** (`destination.amount`): The amount in the recipient's currency (face value). * **Retail Price** (`prices.retail`): The suggested selling price. Customers can choose to charge this or something else. * **Wholesale Price** (`prices.wholesale.amount`): The amount deducted from the customer's wallet when buying this product. Customers must use the **Wholesale Price** (`prices.wholesale.amount`) for ranged products and can add a margin. If they don't want to calculate this, they can set a **Retail Price** (`prices.retail`) in the DT Shop Portal and use that price from the API response. So, regardless of the **Source Amount** (`source.amount`) or **Destination Amount** (`destination.amount`), we recommend using the **Retail Price** (`prices.retail`) or the **Wholesale Price** (`prices.wholesale.amount`) plus a margin. For Ranged products, we recommend setting `auto_confirm` to `false`. This way, customers can see the **Retail Price** (`prices.retail`) before confirming the transaction. The `"required_*"` fields indicate the **additional** data elements beyond the standard minimum payload that you must include in `POST` transaction requests for each corresponding party or identifier. These fields specify the necessary information for a particular product. If a field is listed as required, your transaction request will likely be unsuccessful if it is not included. > ❗️ Warning > > The example shown is for a particular product type delivered by a specific operator. Always, always check the `"required_*"` configuration for the *exact product and operator* you are integrating with. When the value of a `"required_*"` field is `null`, it means that no additional fields are necessary for that specific section beyond the base requirements for this product. Don't assume based on this one provided example that the field or fields listed are the only possibilities! ```json Example Configuration for a Particular Product and Operator { "required_additional_identifier_fields": null, "required_beneficiary_fields": null, "required_credit_party_identifier_fields": [ [ "mobile_number" ] ], "required_debit_party_identifier_fields": null, "required_sender_fields": null, "required_statement_identifier_fields": null } ``` ```json Request Payload for this specific example { // ... other necessary fields from the minimum payload ... "credit_party_identifier": { "mobile_number": "+639173143100" }, // ... other fields ... } ``` You can find credits as benefits for airtime topups, you can also find the Local Amount Received in the field `total_excluding_tax`. ```json Example Benefits: Credits "benefits": [ { "additional_information": null, "amount": { "base": { "max": 150, "min": 10 }, "promotion_bonus": { "max": 0, "min": 0 }, "total_excluding_tax": { "max": 150, "min": 10 }, "total_including_tax": { "max": 150, "min": 10 } }, "type": "CREDITS", "unit": "EUR", "unit_type": "CURRENCY" } ] ``` > **Disclaimer** > > Example field values in response JSON files are significant for format and type only. Do not interpret them as actual data; prices, for example, are invented and non-binding. To post a transaction, you use the **POST**: [Create a transaction asynchronously](/reference/posttransactionasync#/) endpoint. #### Technique 1: One-Step Transaction Create and confirm the transaction in one step. ```json Create and confirm in one step { "external_id": "TEST-000006", "product_id": 59587, "auto_confirm": true, "credit_party_identifier": { "mobile_number": "+639173143100" }, "callback_url": "https://testcallbackurl.com/" } ``` **Explanation:** By setting `auto_confirm` to `true`, the transaction is created and confirmed immediately. #### Technique 2: Two-Step Transaction Create the transaction, then confirm it separately. When `auto_confirm` is set to `false` (or not specified): * A separate **POST** request to [Confirm a transaction asynchronously](/reference/posttransactionconfirmasync#/) is required. * This allows for a delay between transaction creation and submission to DT One, useful for: * Collecting payment. * Verifying RANGED product type prices. **Important:** * The maximum time allowed between the CREATED (1) and CONFIRMED (2) statuses is 60 minutes. * Transactions not confirmed within 60 minutes will be automatically canceled. ```json auto_confirm set to false { "external_id": "TEST-000006", "product_id": 59587, "auto_confirm": false, "credit_party_identifier": { "mobile_number": "+639173143100" }, "callback_url": "https://testcallbackurl.com/" } ``` ```json Minimum Payload { "external_id": "TEST-000006", "product_id": 59587, "credit_party_identifier": { "mobile_number": "+639173143100" }, "auto_confirm": true, "callback_url": "https://testcallbackurl.com/" } ``` **Field Descriptions:** | Field Path | Description | Example | | --------------------------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------- | | `external_id` | Unique ID per request generated from customer side. | `"TEST-000006"` | | `product_id` | ID of the product to be purchased. | `59587` | | `credit_party_identifier.mobile_number` | Mobile number to be recharged. | `"+639173143100"` | | `auto_confirm` | Specify if the transaction will be generated in one or two steps using the confirmation check. | `true` | | `callback_url` | Callback URL or Webhook provided by the customer, we will send status updates to this URL. | `"https://testcallbackurl.com/"` | ```json Response { "id": 2239243424, "external_id": "TEST-000006", "status": { "id": 2, "message": "CONFIRMED", "class": { "id": 2, "message": "CONFIRMED" } }, "creation_date": "2025-04-04T16:35:00.331224000Z", "confirmation_date": "2025-04-04T16:35:00.423077000Z", "callback_url": "https://testcallbackurl.com/", "product": { "id": 59587, "name": "Quickmart Giftcard 10000 KES 12 Months", "type": "RANGED_VALUE_RECHARGE", "description": "Quickmart Giftcard 10000 KES 12 Months" }, "benefits": [ { "additional_information": "HOW TO REDEEM:\n1. Customer walks into the store and picks up items of interest\n2. Customer requests to pay using eVoucher\n3. Customer dials *483*18#, from the phone that received the voucher and selects redeem\n4. Customer enters outlet Till Number and the amount\n5. Both attendant and customer will receive a message confirming redemption\n6. The customer pays for the difference, in cases where the amount redeemed is less than the total value of the goods purchased", "amount": { "base": 10000, "promotion_bonus": 0, "total_excluding_tax": 10000, "total_including_tax": 10000 }, "type": "CREDITS", "unit": "KES", "unit_type": "CURRENCY" } ], "prices": { "retail": null, "wholesale": { "amount": 78.16, "fee": 0, "unit": "USD", "unit_type": "CURRENCY" } } } ``` **Descriptions of Important Fields:** | Field Path | Description | Example | | ------------------------- | -------------------------------------------------------- | ------------------------------------------ | | `id` | Unique ID for the transaction generated by DTOne. | `2239243424` | | `external_id` | Unique ID for the transaction generated by the customer. | `"TEST-000006"` | | `status.id` | Status ID for the transaction. | `2` | | `status.message` | Status message for the transaction. | `"CONFIRMED"` | | `creation_date` | Date and time when the transaction was created. | `"2025-04-04T16:35:00.331224000Z"` | | `confirmation_date` | Date and time when the transaction was confirmed. | `"2025-04-04T16:35:00.423077000Z"` | | `callback_url` | URL provided by the customer to receive status updates. | `"https://testcallbackurl.com/"` | | `product.id` | ID of the product associated with the transaction. | `59587` | | `product.name` | Name of the product associated with the transaction. | `"Quickmart Giftcard 10000 KES 12 Months"` | | `benefits[].type` | Type of benefit provided by the transaction. | `"CREDITS"` | | `benefits[].amount.base` | Base amount of the benefit. | `10000` | | `prices.wholesale.amount` | Wholesale price of the product. | `78.16` | > **Disclaimer** > > Example field values in response JSON files are significant for format and type only. Do not interpret them as actual data; prices, for example, are invented and non-binding. ### Example Status Retrieval #### Technique 1: Callback Provide the `callback_url` (described in Step **2. Post Transactions**) in the transaction request to receive asynchronous status updates. #### Technique 2: Query the transaction using an ID Use one of the following endpoints: * **GET**: [Query a list of transactions](/reference/gettransactions#/) Can be used to look up the transaction using the **External ID** generated by the customer side (as well as to query a list). * **GET**: [Query a transaction by ID](/reference/gettransactionbyid#/) Look up the transaction using the **Transaction ID** that DTOne generated. ### Requests and Responses for "Get Final Status" #### Query Using External ID ```json GET /v1/transactions?external_id=TEST-000006 ``` #### Query Using Transaction ID ```json GET /v1/transactions/2239243424 ``` #### Response for "Get Final Status" ```json { "id": 2239243424, "external_id": "TEST-000006", "status": { "id": 7, "message": "COMPLETED", "class": { "id": 7, "message": "COMPLETED" } }, "creation_date": "2025-04-04T16:35:00.331224000Z", "confirmation_date": "2025-04-04T16:35:00.423077000Z", "callback_url": "https://testcallbackurl.com/", "product": { "id": 59587, "name": "Quickmart Giftcard 10000 KES 12 Months", "type": "RANGED_VALUE_RECHARGE", "description": "Quickmart Giftcard 10000 KES 12 Months" }, "benefits": [ { "additional_information": "HOW TO REDEEM:\n1. Customer walks into the store and picks up items of interest\n2. Customer requests to pay using eVoucher\n3. Customer dials *483*18#, from the phone that received the voucher and selects redeem\n4. Customer enters outlet Till Number and the amount\n5. Both attendant and customer will receive a message confirming redemption\n6. The customer pays for the difference, in cases where the amount redeemed is less than the total value of the goods purchased", "amount": { "base": 10000, "promotion_bonus": 0, "total_excluding_tax": 10000, "total_including_tax": 10000 }, "type": "CREDITS", "unit": "KES", "unit_type": "CURRENCY" } ], "prices": { "retail": null, "wholesale": { "amount": 78.16, "fee": 0, "unit": "USD", "unit_type": "CURRENCY" } } } ``` **Field Descriptions:** | Field Path | Description | Example | | ------------------------- | -------------------------------------------------------- | ------------------------------------------ | | `id` | Unique ID for the transaction generated by DTOne. | `2239243424` | | `external_id` | Unique ID for the transaction generated by the customer. | `"TEST-000006"` | | `status.id` | Status ID for the transaction. | `7` | | `status.message` | Status message for the transaction. | `"COMPLETED"` | | `creation_date` | Date and time when the transaction was created. | `"2025-04-04T16:35:00.331224000Z"` | | `confirmation_date` | Date and time when the transaction was confirmed. | `"2025-04-04T16:35:00.423077000Z"` | | `callback_url` | URL provided by the customer to receive status updates. | `"https://testcallbackurl.com/"` | | `product.id` | ID of the product associated with the transaction. | `59587` | | `product.name` | Name of the product associated with the transaction. | `"Quickmart Giftcard 10000 KES 12 Months"` | | `benefits[].type` | Type of benefit provided by the transaction. | `"CREDITS"` | | `benefits[].amount.base` | Base amount of the benefit. | `10000` | | `prices.wholesale.amount` | Wholesale price of the product. | `78.16` |