README

A framework-agnostic PHP SDK for the Digiflazz API, built for the Gonon ecosystem.

Requirements

• PHP 8.2 or higher
• gonon/core package
• gonon/http-symfony (or any PSR-18 compliant HTTP client adapter supported by Gonon Core)

Installation

composer require gonon/digiflazz

Basic Configuration

To start using the SDK, you need to configure the DigiflazzClient. This SDK utilizes Gonon\Core\Http\Client for robust, abstracted HTTP communication.

use Gonon\Core\Configuration\Environment;
use Gonon\Core\Http\Client;
use Gonon\Digiflazz\Authentication\DigiflazzAuthenticator;
use Gonon\Digiflazz\Client\DigiflazzClient;
use Gonon\Digiflazz\Config\DigiflazzConfig;
use Gonon\Http\Symfony\SymfonyClientAdapter;

$config = new DigiflazzConfig(
    username: 'YOUR_USERNAME',
    apiKey: 'YOUR_API_KEY',
    webhookSecret: 'YOUR_WEBHOOK_SECRET', // Optional, needed for webhook validation
    environment: Environment::Production // or Environment::Sandbox
);

$client = new DigiflazzClient($config);

Usage

1. Balance & Deposit

You can check your Digiflazz account balance and request deposit instructions.

use Gonon\Digiflazz\DTO\Requests\DepositRequest;

// Check Balance
$balance = $client->balance()->check();
echo "Your balance is: " . $balance->deposit;

// Request a Deposit Ticket
$request = new DepositRequest(
    amount: 1000000, 
    bank: 'BCA', 
    ownerName: 'John Doe'
);
$deposit = $client->balance()->deposit($request);

echo "Transfer exactly {$deposit->amount} to {$deposit->bank} ({$deposit->accountNo})";

2. Products (Price List)

Fetch products, categories, or brands separately for Prepaid and Postpaid.

// Fetch all prepaid products
$prepaidProducts = $client->products()->getPrepaid();
foreach ($prepaidProducts as $product) {
    echo $product->productName . ' - Rp ' . $product->price . "\n";
}

// Fetch all postpaid products
$postpaidProducts = $client->products()->getPostpaid();
foreach ($postpaidProducts as $product) {
    echo $product->productName . ' - Admin: ' . $product->admin . "\n";
}

// Fetch available categories
$prepaidCategories = $client->products()->getPrepaidCategories();
$postpaidCategories = $client->products()->getPostpaidCategories();

// Fetch available brands under a specific category
$prepaidBrands = $client->products()->getPrepaidBrands(category: 'Pulsa');
$postpaidBrands = $client->products()->getPostpaidBrands(category: 'PLN');

3. Prepaid Transactions (Topup)

Topup prepaid products (e.g., Pulsa, Data, Token PLN).

use Gonon\Digiflazz\DTO\Requests\PrepaidTopupRequest;
use Gonon\Digiflazz\DTO\Requests\TransactionStatusRequest;

// Create Topup
$topupRequest = new PrepaidTopupRequest(
    buyerSkuCode: 'xld10', 
    customerNo: '087800001233', 
    refId: 'INV-12345'
);
$transaction = $client->prepaid()->topup($topupRequest);
echo $transaction->status; // 'Pending' or 'Sukses'

// Check Topup Status
$statusRequest = new TransactionStatusRequest(
    buyerSkuCode: 'xld10',
    customerNo: '087800001233',
    refId: 'INV-12345'
);
$status = $client->prepaid()->status($statusRequest);
echo $status->sn; // Serial Number

4. Postpaid Transactions (PPOB)

Postpaid transactions require two steps: Inquiry and Payment.

use Gonon\Digiflazz\DTO\Requests\PostpaidInquiryRequest;
use Gonon\Digiflazz\DTO\Requests\PostpaidPaymentRequest;
use Gonon\Digiflazz\DTO\Requests\TransactionStatusRequest;

// Step 1: Inquiry (Check the bill)
$inquiryRequest = new PostpaidInquiryRequest(
    buyerSkuCode: 'pln', 
    customerNo: '530000000003', 
    refId: 'INV-POST-123'
);
$inquiry = $client->postpaid()->inquiry($inquiryRequest);

echo "Your bill is: " . $inquiry->sellingPrice;

// Step 2: Pay (Using the tr_id from Inquiry)
$payRequest = new PostpaidPaymentRequest(
    trId: $inquiry->trId
);
$payment = $client->postpaid()->pay($payRequest);
echo $payment->status; // 'Sukses'

// Check Postpaid Status
$statusRequest = new TransactionStatusRequest(
    buyerSkuCode: 'pln',
    customerNo: '530000000003',
    refId: 'INV-POST-123'
);
$status = $client->postpaid()->status($statusRequest);

5. Webhooks

Digiflazz sends callbacks for transaction updates. The SDK securely parses and verifies the payload signature automatically using your webhookSecret.

use Gonon\Digiflazz\Exceptions\WebhookException;

$rawBody = file_get_contents('php://input'); // The raw JSON body
$signature = $_SERVER['HTTP_X_HUB_SIGNATURE'] ?? ''; // Digiflazz signature header

try {
    $webhookData = $client->webhook()->process($rawBody, $signature);
    
    echo "Update for Ref ID: " . $webhookData->refId;
    echo "New Status: " . $webhookData->status;
    echo "SN: " . $webhookData->sn;

} catch (WebhookException $e) {
    http_response_code(400);
    echo "Invalid Webhook: " . $e->getMessage();
}

Exceptions

The SDK throws strictly typed exceptions that extend Gonon\Core\Exceptions\GononException.

• Gonon\Digiflazz\Exceptions\DigiflazzException: Base exception.
• Gonon\Digiflazz\Exceptions\TransactionException: Thrown on invalid transaction responses.
• Gonon\Digiflazz\Exceptions\WebhookException: Thrown when a webhook signature is invalid or parsing fails.
• InvalidArgumentException: Thrown directly by Request DTO constructors when missing required parameters.

License

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