Product Type	Service (ID)	Subservice (ID)
FIXED_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 /v1/products/59587 ``` ```json Retrieve list of products GET /v1/products?service_id=4&subservice_id=41 ``` ```json Response to Retrieve product by ID { "availability_zones": ["INTERNATIONAL"], "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" } ], "description": "Quickmart Giftcard 10000 KES 12 Months", "destination": { "amount": 10000, "unit": "KES", "unit_type": "CURRENCY" }, "id": 59587, "name": "Quickmart Giftcard 10000 KES 12 Months", "operator": { "country": { "iso_code": "KEN", "name": "Kenya", "regions": [ { "code": "KEN", "name": "Kenya" } ] }, "id": 5597, "name": "Quickmart Giftcard Kenya", "regions": null }, "prices": { "retail": null, "wholesale": { "amount": 78.16, "fee": 0, "unit": "USD", "unit_type": "CURRENCY" }, "type": "FIXED_VALUE_RECHARGE", "validity": { "quantity": 12, "unit": "MONTH" } } } ``` 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 ... } ``` For products requiring a `mobile_number`, the PIN code will be delivered via SMS to that number. ```json Example Benefits: Credits "benefits": [ { "additional_information": "HOW TO REDEEM:\n1. Customer enters the store and selects desired items.\n2. Customer requests to pay with an eVoucher.\n3. Customer dials *483*18# from the phone that received the voucher and selects the redeem option.\n4. Customer enters the outlet Till Number and the amount.\n5. Both the attendant and customer receive a confirmation message for the redemption.\n6. The customer pays any remaining balance if the redeemed amount is less than the total purchase value.", "amount": { "base": 10000, "promotion_bonus": 0, "total_excluding_tax": 10000, "total_including_tax": 10000 }, "type": "CREDITS", "unit": "KES", "unit_type": "CURRENCY" } ] ``` Redemption instructions for `Fixed_Value_Recharge` Gift Cards are in the `benefits.additional_information`. Note that some products (requiring an `account_number`) will directly recharge the account instead of sending a PIN. > **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, "credit_party_identifier": { "mobile_number": "+639173143100" }, "auto_confirm": true, "callback_url": "[https://testcallbackurl.com/](https://testcallbackurl.com/)" } ``` #### Technique 2: Two-Step Transaction Create the transaction, then confirm it separately. When `auto_confirm` is set to `false` (or not specified): ```json auto_confirm set to false { "external_id": "TEST-000006", "product_id": 59587, "credit_party_identifier": { "mobile_number": "+639173143100" }, "auto_confirm": false, "callback_url": "[https://testcallbackurl.com/](https://testcallbackurl.com/)" } ``` For even more detailed information, see [Handling Transactions](/docs/handling-transactions-r-for-review-copy#/). ```mermaid --- config: theme: neutral fontSize: 16 look: neo layout: fixed --- flowchart LR B@{ label: "CREATED
1" } -- "POST
/transactions
/[id]
/confirm" --> C@{ label: "CONFIRMED
2" } C -- "Sent to
receiving
partner" --> D@{ label: "SUBMITTED
5" } D --> E@{ label: "COMPLETED
7" } E -- "Callback" --> F@{ label: "REVERSED
8" } B -- "Callback" --> G@{ label: "REJECTED
3" } B -- "Callback
POST
/transactions
/[id]
/cancel" --> H@{ label: "CANCELLED
4" } D -- "Callback" --> I@{ label: "DECLINED
9" } B@{ shape: rounded} C@{ shape: rounded} D@{ shape: rounded} E@{ shape: rounded} F@{ shape: rounded} G@{ shape: rounded} H@{ shape: rounded} I@{ shape: rounded} style B fill:#FFFFFF,stroke:#1D8DF0,stroke-width:3px style C fill:#FFFFFF,stroke:#1D8DF0,stroke-width:3px style D fill:#FFFFFF,stroke:#1D8DF0,stroke-width:3px style E fill:#FFFFFF,color:#000,stroke:#90ee90,stroke-width:3px style F fill:#FFFFFF,stroke:black,stroke-width:3px style G fill:#FFFFFF,stroke:#f08080,stroke-width:3px style H fill:#FFFFFF,stroke:#f08080,stroke-width:3px style I fill:#FFFFFF,stroke:#f08080,stroke-width:3px ``` A final status is a status after which there are no further statuses. Only **COMPLETED 7**, **REJECTED 3**, **CANCELLED 4**, and **DECLINED 9** are final statuses. **SUBMITTED 5** and **CONFIRMED 2** are **NOT** final statuses.

###### **COMPLETED 7** The digital value service has been delivered. In rare cases, a successfully completed transaction can be reversed and assigned a **REVERSED 8** status (so the definition for "Final Status" is applicable almost always.).

###### **REJECTED 3** The transaction was unsuccessful on DT One’s side.

###### **CANCELLED 4** The transaction was canceled by the initiator before confirmation.

###### **DECLINED 9** The transaction was unsuccessful on the provider’s side.

* **Transaction reachesSUBMITTED 5 status.** * An immediate hold is placed on the initiator’s wallet for the wholesale price of the product. * **If Status changes toCOMPLETED 7** * The wholesale price is deducted from the wallet. * **If Status remainsSUBMITTED 5** * The balance remains on hold. * **If Status changes toREVERSED 8, REJECTED 3, or DECLINED 9** * The hold is released, and the wallet balance is adjusted accordingly. ```json Minimum Payload Request { "external_id": "TEST-000006", "product_id": 59587, "credit_party_identifier": { "mobile_number": "+639173143100" }, "callback_url": "[https://testcallbackurl.com/](https://testcallbackurl.com/)" } ``` > **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. We recommend using **Technique 1: Callback** and - in parallel - using **Technique 2: Query the transaction using an ID** as a backup plan. If you cannot use **Technique 1: Callback**, you must use **Technique 2: Query the transaction using an ID**. For **Technique 2: Query the transaction using an ID**, here are the relevant requests and responses. ```json Query using External ID (endpoint: GET: Query a list of transactions) GET /transactions?external_id=TEST-00001 ``` ```json Query by Transaction by ID GET /transactions/2239238836 ``` ```json Response (for either query) { "benefits": [ { "additional_information": "unlimited DITO-to-DITO voice calls, 300 mins of calls to other mobile networks!", "amount": { "base": -1, "promotion_bonus": 0, "total_excluding_tax": -1, "total_including_tax": -1 }, "type": "TALKTIME", "unit": "MINUTES", "unit_type": "TIME" }, { "additional_information": "Available for DITO Prepaid only. 8GB all-access data + unlimited all net SMS + unlimited DITO-to-DITO voice calls + 300 mins of calls to other mobile networks! + Optimax. Valid for 30 days.", "amount": { "base": 8, "promotion_bonus": 0, "total_excluding_tax": 8, "total_including_tax": 8 }, "type": "DATA", "unit": "GB", "unit_type": "DATA" }, { "additional_information": null, "amount": { "base": -1, "promotion_bonus": 0, "total_excluding_tax": -1, "total_including_tax": -1 }, "type": "SMS", "unit": "UNITS", "unit_type": "QUANTITY" } ], "callback_url": "[https://testcallbackurl.com/](https://testcallbackurl.com/)", "confirmation_date": "2025-03-31T17:34:01.570116000Z", "confirmation_expiration_date": "2025-03-31T18:34:01.511496000Z", "creation_date": "2025-03-31T17:34:01.511496000Z", "credit_party_identifier": { "mobile_number": "+639173143100" }, "external_id": "TEST-00001", "id": 2239238836, "operator_reference": "TX_2239238836", "prices": { "retail": null, "wholesale": { "amount": 1.92, "fee": 0, "unit": "USD", "unit_type": "CURRENCY" } }, "product": { "description": "Available for DITO Prepaid only. 8GB all-access data + unlimited all net SMS + unlimited DITO-to-DITO voice calls + 300 mins of calls to other mobile networks! + Optimax. Valid for 30 days.", "id": 56876, "name": "DITO Level-Up 109", "operator": { "country": { "iso_code": "PHL", "name": "Philippines", "regions": [ { "code": "PHL", "name": "Philippines" } ] }, "id": 3684, "name": "DITO Telecommunity Philippines", "regions": null }, "regions": null, "service": { "id": 1, "name": "Mobile", "subservice": { "id": 12, "name": "Bundle" }, "tags": [ "BUNDLE" ], "type": "FIXED_VALUE_RECHARGE" }, "promotions": null, "rates": { "base": 56.7708333333333, "retail": null, "wholesale": 56.7708333333333 } }, "status": { "class": { "id": 7, "message": "COMPLETED" }, "id": 70000, "message": "COMPLETED" } } ```