API Reference
API Reference
Start typing to search…

Transactions

This API facilitates "transactions" to deliver value to beneficiaries, such as mobile airtime top-ups and data bundles. A transaction progresses through distinct status stages, as illustrated in the following diagram

Final Statuses for Transactions

A final status is a status after which there are no further statuses. Note that 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.


---
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

  • Two-Step Flow:CREATED 1 → CONFIRMED 2
    • This approach is used when the initiator needs a short delay (e.g., to collect payment) between creating the transaction and submitting it to DT One.
    • The maximum allowed time between the CREATED 1 and CONFIRMED 2 statuses is 60 minutes.
    • If the transaction is not confirmed within 60 minutes, it will be automatically canceled.
  • One-Step Flow: Create a Confirmed transaction
    • This approach is used by DT Shop and UI SDK, where transactions are created and confirmed in a single step.


Transaction Updates and Retrieval:

Real-time Notifications

When a callback URL is configured, the API sends real-time updates as the transaction status changes.

Transaction Status Queries

You can query the current transaction status using either the id returned by the API or your provided external_id.

External ID Usage

The external_id is essential for retrieving transaction details in exceptional scenarios, such as when an API response is not received.