Download the PHP package ghanem/dtone without Composer

Laravel Dtone

A package that provides an interface between Laravel and DT One DVS API.

Requirements

• PHP ^7.2.5 | ^8.0
• Laravel ^7.0 | ^8.0 | ^9.0 | ^10.0 | ^11.0 | ^12.0

Installation

• Dtone on Packagist
• Dtone on GitHub

You can install the package via composer:

Publish the config file:

Configuration

Add the following to your .env file:

Set DTONE_IS_PRODUCTION=true when you are ready to use the production API.

Retry Configuration

You can enable automatic retries for failed requests:

This will retry failed requests up to 3 times with a 100ms delay between attempts.

Usage

You can use the Dtone facade or resolve it from the container.

Services

Countries

Operators

Products

Campaigns

Promotions

Benefit Types

Balances

Transactions

Lookups

Response DTOs

All API responses are returned as typed DTO objects. Every DTO has a toArray() method for backward compatibility:

Available DTOs: Service, Country, Operator, Product, Balance, Transaction, Campaign, Promotion, BenefitType, PaginatedResponse, Meta.

Paginated Responses

List endpoints return a PaginatedResponse DTO:

Webhooks

The package automatically registers a webhook endpoint to receive DT One transaction callbacks.

Configuration

You can also configure middleware in config/dtone.php:

Set webhook_path to null to disable the webhook route.

Events

The webhook controller dispatches the following events:

Listen to events in your EventServiceProvider:

Each event has $payload, $status, and $transactionId properties:

Signature Verification

If DTONE_WEBHOOK_SECRET is set, the VerifyWebhookSignature middleware is available:

This verifies the X-Dtone-Signature header using HMAC-SHA256.

Laravel Notifications Channel

Send top-ups as Laravel notifications using the DtoneChannel:

DtoneMessage API

On-Demand Notifications

Caching

Discovery endpoints (services, countries, operators, products, campaigns, promotions, benefit-types) can be cached to reduce API calls:

Override TTL per endpoint:

Set DTONE_CACHE_TTL=0 (default) to disable caching. Transactions, balances, and lookups are never cached.

Clear cache programmatically:

Artisan Commands

Examples:

Done

• [x] Services (list, get by ID)
• [x] Countries (list, get by ISO code)
• [x] Operators (list, get by ID)
• [x] Products (list with filters, get by ID)
• [x] Campaigns (list, get by ID)
• [x] Promotions (list, get by ID)
• [x] Benefit types (list)
• [x] Balances
• [x] Transactions (list, get by ID, create async/sync, confirm async/sync, cancel)
• [x] Lookup operators by mobile number
• [x] Statement inquiry lookup
• [x] Credit party lookup (remaining benefits, status)
• [x] Pagination support with meta data
• [x] Production / Sandbox environment switching
• [x] Retry mechanism for failed requests
• [x] Response DTOs (typed objects with toArray() compatibility)
• [x] Webhook / Callback support with event dispatching
• [x] Signature verification middleware
• [x] Laravel notifications channel integration
• [x] Caching layer for discovery endpoints
• [x] Configurable cache TTL per endpoint
• [x] Rate limiting awareness (respects X-RateLimit headers)
• [x] Artisan commands (dtone:balance, dtone:products, dtone:transaction, dtone:cache-clear, dtone:health)
• [x] Health check command
• [x] Test suite (110 tests, 248 assertions)
• [x] Support for Laravel 7 - 12

Roadmap

• [ ] Batch transactions support
• [ ] Auto-paginate helper (fetch all pages automatically)
• [ ] Webhook queue integration (dispatch events to queue)

Testing

License

The MIT License (MIT). Please see License File for more information.