Gift Card: FIXED_VALUE_RECHARGE
Top up a receiver's account with a fixed value.
| 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.
Example Product Retrieval
For full endpoint descriptions, see:
GET /v1/products/59587GET /v1/products?service_id=4&subservice_id=41{
"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"
}
}Required Fields - Pay Close Attention
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.
WarningThe 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 isnull, 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!
{
"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
}{
// ... other necessary fields from the minimum payload ...
"credit_party_identifier": {
"mobile_number": "+639173143100"
},
// ... other fields ...
}Example Benefits: Credits
For products requiring a mobile_number, the PIN code will be delivered via SMS to that number.
"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 endpoint.
Implementation Techniques
Technique 1: One-Step Transaction
Create and confirm the transaction 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):
{
"external_id": "TEST-000006",
"product_id": 59587,
"credit_party_identifier": {
"mobile_number": "+639173143100"
},
"auto_confirm": false,
"callback_url": "[https://testcallbackurl.com/](https://testcallbackurl.com/)"
}Statuses for Transactions
For even more detailed information, see Handling Transactions.
---
config:
theme: neutral
fontSize: 16
look: neo
layout: fixed
---
flowchart LR
B@{ label: "<b>CREATED</b><br><span style=\"font-size: 2em;\">1</span>" } -- "<span style=color:>POST<br>/transactions<br>/[id]<br>/confirm</span>" --> C@{ label: "<b>CONFIRMED</b><br><span style=\"font-size: 2em;\">2</span>" }
C -- "<span style=color:>Sent to<br>receiving<br>partner</span>" --> D@{ label: "<b>SUBMITTED</b><br><span style=\"font-size: 2em;\">5</span>" }
D --> E@{ label: "<b>COMPLETED</b><br><span style=\"font-size: 2em;\">7</span>" }
E -- "<span style=color:>Callback</span>" --> F@{ label: "<b>REVERSED</b><br><span style=\"font-size: 2em;\">8</span>" }
B -- "<span style=color:>Callback</span>" --> G@{ label: "<b>REJECTED</b><br><span style=\"font-size: 2em;\">3</span>" }
B -- "<span style=color:>Callback<br>POST<br>/transactions<br>/[id]<br>/cancel</span>" --> H@{ label: "<b>CANCELLED</b><br><span style=\"font-size: 2em;\">4</span>" }
D -- "<span style=color:>Callback</span>" --> I@{ label: "<b>DECLINED</b><br><span style=\"font-size: 2em;\">9</span>" }
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.
- 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.
Minimum Payload Request for POST: Create a transaction asynchronously
{
"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
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
Look up the transaction using the Transaction ID that DT One 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.
GET /transactions?external_id=TEST-00001GET /transactions/2239238836{
"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"
}
}Updated 26 days ago