Mobile: FIXED_VALUE_PIN_PURCHASE
Send the user a PIN or voucher code for redemption at a later time.
| Product Type | Service (ID) | Subservice (ID) |
|---|---|---|
| FIXED_VALUE_PIN_PURCHASE | Mobile (1) | Airtime (11) or Bundle (12) or Data (13) |
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 /products/8975{
"availability_zones": [
"INTERNATIONAL"
],
"benefits": [
{
"additional_information": null,
"amount": {
"base": 5,
"promotion_bonus": 0,
"total_excluding_tax": 5,
"total_including_tax": 5
},
"type": "CREDITS",
"unit": "GBP",
"unit_type": "CURRENCY"
}
],
"description": "5 GBP PIN",
"destination": {
"amount": 5,
"unit": "GBP",
"unit_type": "CURRENCY"
},
"id": 8795,
"name": "5 GBP PIN",
"operator": {
"country": {
"iso_code": "GBR",
"name": "United Kingdom",
"regions": [
{
"code": "GBR",
"name": "United Kingdom"
}
]
},
"id": 1732,
"name": "Lebara PIN UK",
"regions": null
},
"pin": {
"terms": null,
"usage_info": [
"Activate this voucher viaMyLebara app or dial 5588.Get 5 off when you register& buy at lebara.co.uk. Usepromocode EPIN at checkout",
"To recharge your phone, please dial *#1345* followed by the pin number and the # key.",
"",
"IVR: 1345"
],
"validity": {
"quantity": 6,
"unit": "MONTH"
}
},
"prices": {
"retail": {
"amount": 7.4,
"fee": 0,
"unit": "USD",
"unit_type": "CURRENCY"
},
"wholesale": {
"amount": 6.51,
"fee": 0,
"unit": "USD",
"unit_type": "CURRENCY"
}
},
"promotions": null,
"rates": {
"base": 0.768049155145929,
"retail": 0.675675675675676,
"wholesale": 0.768049155145929
},
"regions": null,
"required_additional_identifier_fields": null,
"required_beneficiary_fields": null,
"required_credit_party_identifier_fields": null,
"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": 6.51,
"unit": "USD",
"unit_type": "CURRENCY"
},
"tags": [
"AIRTIME"
],
"type": "FIXED_VALUE_PIN_PURCHASE",
"validity": {
"quantity": -1,
"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 ...
}
Additonal Fields for PIN-based Products
Most PIN-based products do not require additional fields beyond the standard minimum payload, as a PIN code for redemption is provided. Therefore, fields such as credit_party_identifier.mobile_number are typically not mandatory.
However, if you include the credit_party_identifier.mobile_number in your request for a PIN-based product, the PIN code will also be delivered via SMS to the provided mobile number.
When purchasing a PIN product, the discovery process will include a new "pin" field. This field contains the following information:
"pin": {
"terms": "Determined terms and conditions on the operator's side, this information will be provided here",
"usage_info": [
"Activate this voucher via MyLebara app or dial 5588. Get 5 off when you register & buy at lebara.co.uk. Use promocode EPIN at checkout",
"To recharge your phone, please dial *#1345* followed by the pin number and the # key.",
"",
"IVR: 1345"
],
"validity": {
"quantity": 6,
"unit": "MONTH"
}
}
The "pin" field provides "usage_info" detailing how to redeem the delivered PIN code, as well as "validity" information and any applicable "terms" and conditions.
Example Benefits: Airtime, Data, and Bundles
The key functional differences between the transaction objects for Airtime, Data, and Bundle services are discernable when you discover the products and compare the benefits returned.
The discovery endpoints from which you can find the transactions showing the benefits are:
.
# Find credits as benefits for airtime top-ups.
# Find the Local Amount Received in the field "total_excluding_tax".
# Same as "Data Benefits" example except for "additional information", "type", "unit", and "unit_type".
"benefits": [
{
"additional_information": "",
"amount": {
"base": 8,
"promotion_bonus": 0,
"total_excluding_tax": 5,
"total_including_tax": 8
},
"type": "CREDITS",
"unit": "USD",
"unit_type": "CURRENCY"
}
]# Find credits as benefits for data top-ups
# Find the Local Amount Received in the field "total_excluding_tax"
# Same as "Airtime Benefits" example except for "additional information", "type", "unit", and "unit_type".
"benefits": [
{
"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": 5,
"total_including_tax": 8
},
"type": "DATA",
"unit": "GB",
"unit_type": "DATA"
}
]
# Find the benefit details for a package, like Talktime, SMS and Data.
# As the word "bundle" suggests, there is more than one "benefit" under "benefits".
"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"
}
]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-001",
"product_id": 8795,
"auto_confirm": true
}
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 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.
{
"external_id": "TEST-001",
"product_id": 8795,
"auto_confirm": false
}
Statuses for Transactions
A final status is a status after which there 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.
---
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
Final Status Descriptions
Minimum Payload Request for POST: Create a transaction asynchronously
{
"external_id": "TEST-001",
"product_id": 8795,
"auto_confirm": true,
"callback_url": "[https://testcallbackurl.com/](https://testcallbackurl.com/)"
}Field Descriptions:
| Field Path | Description | Example |
|---|---|---|
external_id | Unique ID per request generated from customer side. | "TEST-001" |
product_id | ID of the product to be purchased | 8795 |
auto_confirm | Specify if the transaction will be generated in one or two steps. | true |
callback_url | Callback URL or Webhook provided by the customer. DT One sends status updates to this url. | "https://testcallbackurl.com/" |
Response for POST: Create a transaction asynchronously
{
"benefits": [
{
"additional_information": null,
"amount": {
"base": 5,
"promotion_bonus": 0,
"total_excluding_tax": 5,
"total_including_tax": 5
},
"type": "CREDITS",
"unit": "GBP",
"unit_type": "CURRENCY"
}
],
"callback_url": "https://testcallbackurl.com/",
"confirmation_date": "2025-04-04T15:22:56.323095000Z",
"confirmation_expiration_date": "2025-04-04T16:22:56.029745000Z",
"creation_date": "2025-04-04T15:22:56.029745000Z",
"external_id": "TEST-000003",
"id": 2239243378,
"prices": {
"retail": {
"amount": 7.4,
"fee": 0,
"unit": "USD",
"unit_type": "CURRENCY"
},
"wholesale": {
"amount": 6.51,
"fee": 0,
"unit": "USD",
"unit_type": "CURRENCY"
}
},
"product": {
"description": "5 GBP PIN",
"id": 8795,
"name": "5 GBP PIN",
"operator": {
"country": {
"iso_code": "GBR",
"name": "United Kingdom",
"regions": [
{
"code": "GBR",
"name": "United Kingdom"
}
]
},
"id": 1732,
"name": "Lebara PIN UK",
"regions": null
},
"pin": {
"terms": null,
"usage_info": [
"Activate this voucher viaMyLebara app or dial 5588.Get 5 off when you register& buy at lebara.co.uk. Usepromocode EPIN at checkout",
"To recharge your phone, please dial *#1345* followed by the pin number and the # key.",
"",
"IVR: 1345"
],
"validity": {
"quantity": 6,
"unit": "MONTH"
}
},
"regions": null,
"service": {
"id": 1,
"name": "Mobile",
"subservice": {
"id": 11,
"name": "Airtime"
}
},
"tags": [
"AIRTIME"
],
"type": "FIXED_VALUE_PIN_PURCHASE"
},
"promotions": null,
"rates": {
"base": 0.768049155145929,
"retail": 0.675675675675676,
"wholesale": 0.768049155145929
},
"status": {
"class": {
"id": 2,
"message": "CONFIRMED"
},
"id": 20000,
"message": "CONFIRMED"
}
}Descriptions of Important Fields:
| Field Path | Description | Example |
|---|---|---|
callback_url | Callback URL for status updates. | "https://testcallbackurl.com/" |
confirmation_date | Date when the confirmation was sent. | "2025-04-04T15:22:56.323095000Z" |
confirmation_expiration_date | Date and time when the confirmation will expire. | "2025-04-04T16:22:56.029745000Z" |
creation_date | Date and time when the transaction was created. | "2025-04-04T15:22:56.029745000Z" |
external_id | Unique ID per request generated from customer side. | "TEST-000003" |
id | Unique ID for the transaction generated by the system. | 2239243378 |
status[].class[].id | Class ID for the current transaction status. | 2 |
status[].class[].message | Class description for the current transaction status. | "CONFIRMED" |
status[].id | Status ID for the current transaction. | 20000 |
status[].message | Description of the current transaction status. | "CONFIRMED" |
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.
Note Regarding Transaction Details in ResponseFor PIN-based products with a COMPLETED status, the response will specifically contain the
pinobject with thecodeandserial, as well as the redemption instructions located inproduct.pin.usage_info. This information must be delivered to the end user to enable PIN redemption."pin": { "code": "1616359901", "serial": "243474230" }
For Technique 2: Query the transaction using an ID, here are the relevant requests and responses.
GET /transactions/2239243378GET /transactions?external_id=TEST-00003{
"benefits": [
{
"additional_information": null,
"amount": {
"base": 5,
"promotion_bonus": 0,
"total_excluding_tax": 5,
"total_including_tax": 5
},
"type": "CREDITS",
"unit": "GBP",
"unit_type": "CURRENCY"
}
],
"callback_url": "https://testcallbackurl.com/",
"confirmation_date": "2025-04-04T15:22:56.323095000Z",
"confirmation_expiration_date": "2025-04-04T16:22:56.029745000Z",
"creation_date": "2025-04-04T15:22:56.029745000Z",
"external_id": "TEST-000003",
"id": 2239243378,
"operator_reference": "TX_2239243378",
"pin": {
"code": "1616359901",
"serial": "243474230"
},
"prices": {
"retail": {
"amount": 7.4,
"fee": 0,
"unit": "USD",
"unit_type": "CURRENCY"
},
"wholesale": {
"amount": 6.51,
"fee": 0,
"unit": "USD",
"unit_type": "CURRENCY"
}
},
"product": {
"description": "5 GBP PIN",
"id": 8795,
"name": "5 GBP PIN",
"operator": {
"country": {
"iso_code": "GBR",
"name": "United Kingdom",
"regions": [
{
"code": "GBR",
"name": "United Kingdom"
}
]
},
"id": 1732,
"name": "Lebara PIN UK",
"regions": null
},
"pin": {
"terms": null,
"usage_info": [
"Activate this voucher viaMyLebara app or dial 5588.Get 5 off when you register& buy at lebara.co.uk. Usepromocode EPIN at checkout",
"To recharge your phone, please dial *#1345* followed by the pin number and the # key.",
"",
"IVR: 1345"
],
"validity": {
"quantity": 6,
"unit": "MONTH"
}
},
"regions": null,
"service": {
"id": 1,
"name": "Mobile",
"subservice": {
"id": 11,
"name": "Airtime"
}
},
"tags": [
"AIRTIME"
],
"type": "FIXED_VALUE_PIN_PURCHASE"
},
"promotions": null,
"rates": {
"base": 0.768049155145929,
"retail": 0.675675675675676,
"wholesale": 0.768049155145929
},
"status": {
"class": {
"id": 7,
"message": "COMPLETED"
},
"id": 70000,
"message": "COMPLETED"
}
}Updated 26 days ago