README

SDK Laravel profesional untuk DigiFlazz API - Platform PPOB (Payment Point Online Bank) terkemuka di Indonesia untuk pembelian pulsa, paket data, token listrik, dan berbagai produk digital lainnya.

Daftar Isi

• Fitur
• Persyaratan
• Instalasi
• Konfigurasi
• Penggunaan
  • Menggunakan Facade
  • Menggunakan Dependency Injection
• Metode yang Tersedia
  • Produk & Harga
  • Transaksi
  • Saldo & Akun
  • Cek Tagihan
  • Webhook/Callback
• Models
• Penanganan Error
• Webhook Handler
• Testing
• Kontribusi
• Lisensi

Fitur

• Integrasi mudah dengan Laravel 10 dan 11
• Cakupan lengkap API DigiFlazz
• Autentikasi aman dengan SHA256
• Type-safe models dan DTOs
• Webhook handler untuk callback otomatis
• Event system untuk integrasi yang fleksibel
• Siap untuk production
• Dokumentasi lengkap dalam Bahasa Indonesia

Persyaratan

• PHP >= 8.1
• Laravel >= 10.0
• Guzzle HTTP Client >= 7.8
• Akun DigiFlazz aktif (daftar di https://digiflazz.com)

Instalasi

Instal package melalui Composer:

composer require ndradev/digiflazz-sdk-laravel

Laravel (Auto-discovery)

Untuk Laravel 5.5 ke atas, service provider dan facade akan otomatis terdaftar melalui package auto-discovery.

Laravel (Registrasi Manual)

Untuk versi Laravel yang lebih lama, tambahkan service provider dan facade ke config/app.php:

'providers' => [
    // ...
    NadrDev\Digiflazz\Providers\DigiflazzServiceProvider::class,
],

'aliases' => [
    // ...
    'Digiflazz' => NadrDev\Digiflazz\Facades\Digiflazz::class,
],

Konfigurasi

Publish file konfigurasi:

php artisan vendor:publish --provider="NadrDev\Digiflazz\Providers\DigiflazzServiceProvider" --tag="digiflazz-config"

Tambahkan kredensial DigiFlazz Anda ke file .env:

DIGIFLAZZ_USERNAME=username_anda
DIGIFLAZZ_API_KEY=api_key_anda
DIGIFLAZZ_PRODUCTION=false
DIGIFLAZZ_WEBHOOK_SECRET=api_key_anda
DIGIFLAZZ_WEBHOOK_ENABLED=true

Penjelasan Konfigurasi

Penggunaan

Menggunakan Facade

use NadrDev\Digiflazz\Facades\Digiflazz;

// Mendapatkan daftar harga
$priceList = Digiflazz::getPriceList();

// Mendapatkan saldo
$balance = Digiflazz::getBalance();

// Membuat transaksi
$transaction = Digiflazz::createTransaction([
    'buyer_sku_code' => 'TELKOMSEL10',
    'customer_number' => '081234567890',
    'ref_id' => 'ORDER-' . time(),
]);

Menggunakan Dependency Injection

use NadrDev\Digiflazz\Http\DigiFlazzClient;

class PaymentController extends Controller
{
    private DigiFlazzClient $digiFlazz;

    public function __construct(DigiFlazzClient $digiFlazz)
    {
        $this->digiFlazz = $digiFlazz;
    }

    public function purchase()
    {
        $balance = $this->digiFlazz->getBalance();
        // ...
    }
}

Metode yang Tersedia

Produk & Harga

Mendapatkan Daftar Harga

// Semua produk
$priceList = Digiflazz::getPriceList();

// Berdasarkan kategori (pulsa, data, pln, dll)
$priceList = Digiflazz::getPriceList('pulsa');
$priceList = Digiflazz::getPriceList('data');
$priceList = Digiflazz::getPriceList('pln');

Mendapatkan Produk Berdasarkan SKU

$product = Digiflazz::getProductBySku('TELKOMSEL10');

Transaksi

Membuat Transaksi Baru

use NadrDev\Digiflazz\Models\TransactionRequest;

// Menggunakan array
$response = Digiflazz::createTransaction([
    'buyer_sku_code' => 'TELKOMSEL10',
    'customer_number' => '081234567890',
    'ref_id' => 'ORDER-' . time(),
    'extra_data' => 'data_opsional',
]);

// Menggunakan TransactionRequest DTO
$request = TransactionRequest::create('TELKOMSEL10', '081234567890')
    ->setRefId('ORDER-' . time());

$response = Digiflazz::createTransaction($request->toArray());

Parameter:

Cek Status Transaksi

$status = Digiflazz::getTransactionStatus('ORDER-123');

Riwayat Transaksi

// Semua transaksi
$history = Digiflazz::getTransactionHistory();

// Dengan filter
$history = Digiflazz::getTransactionHistory(
    startDate: '2024-01-01',
    endDate: '2024-01-31',
    status: 'success',
    buyerSkuCode: 'TELKOMSEL10',
    page: 1,
    limit: 20
);

Parameter:

Saldo & Akun

Cek Saldo

use NadrDev\Digiflazz\Models\Balance;

$response = Digiflazz::getBalance();
$balance = Balance::fromArray($response);

echo $balance->getBalanceInRupiah(); // Rp 1.000.000
echo $balance->getBalanceFormatted(); // 1.000.000

Cek Tagihan

Cek PLN Prabayar (Token)

$info = Digiflazz::checkPlnPrepayment('123456789012');

// Response berisi:
// - meter_number: Nomor meter
// - customer_name: Nama pelanggan
// - segment_power: Daya listrik
// - status: Status ketersediaan

Cek PLN Pascabayar

$info = Digiflazz::checkPlnPostpayment('123456789012');

Cek PDAM

$info = Digiflazz::checkPdam(
    customerNumber: '123456789012',
    companyCode: 'PDAM_JKT'
);

Cek BPJS

$info = Digiflazz::checkBpjs('123456789012');

Cek Kartu Kredit

$info = Digiflazz::checkCreditCard(
    cardNumber: '1234567890123456',
    bankCode: 'BCA'
);

Webhook/Callback

Setup Webhook di Dashboard DigiFlazz

1. Login ke dashboard DigiFlazz
2. Masuk ke menu Callback/Webhook
3. Masukkan URL endpoint webhook Anda
4. Simpan konfigurasi

URL webhook harus dapat diakses dari internet.

Testing Webhook

// Test callback URL
Digiflazz::testCallback('https://your-domain.com/api/digiflazz/webhook');

Models

SDK ini menyediakan beberapa model untuk memudahkan pengolahan data:

Product Model

use NadrDev\Digiflazz\Models\Product;

$product = Product::fromArray($responseData);

echo $product->name;
echo $product->price;
echo $product->isAvailable() ? 'Tersedia' : 'Habis';

Transaction Model

use NadrDev\Digiflazz\Models\Transaction;

$transaction = Transaction::fromArray($responseData);

if ($transaction->isSuccess()) {
    // Transaksi berhasil
    echo $transaction->serialNumber;
} elseif ($transaction->isFailed()) {
    // Transaksi gagal
    echo $transaction->message;
} elseif ($transaction->isPending()) {
    // Transaksi masih diproses
}

Balance Model

use NadrDev\Digiflazz\Models\Balance;

$balance = Balance::fromArray($responseData);

echo $balance->getBalanceInRupiah(); // Rp 1.000.000
echo $balance->balance; // 1000000
echo $balance->point; // 0

TransactionRequest Model

use NadrDev\Digiflazz\Models\TransactionRequest;

$request = TransactionRequest::create('TELKOMSEL10', '081234567890')
    ->setRefId('ORDER-' . time())
    ->setExtraData('catatan');

$data = $request->toArray();

Penanganan Error

SDK ini menyediakan beberapa exception class untuk penanganan error yang lebih baik:

use NadrDev\Digiflazz\Exceptions\ApiException;
use NadrDev\Digiflazz\Exceptions\ConnectionException;
use NadrDev\Digiflazz\Exceptions\ValidationException;

try {
    $result = Digiflazz::createTransaction([
        'buyer_sku_code' => 'TELKOMSEL10',
        'customer_number' => '081234567890',
    ]);
} catch (ValidationException $e) {
    // Error validasi data
    $errors = $e->getErrors();
    foreach ($errors as $field => $message) {
        logger()->error("Validasi {$field}: {$message}");
    }
} catch (ConnectionException $e) {
    // Error koneksi ke API
    logger()->error('Koneksi ke DigiFlazz gagal: ' . $e->getMessage());
} catch (ApiException $e) {
    // Error dari API DigiFlazz
    logger()->error('Error dari DigiFlazz: ' . $e->getMessage());
    logger()->error('Context: ' . json_encode($e->getContext()));
}

Webhook Handler

Setup Route Webhook

Tambahkan route untuk webhook di routes/api.php:

use Illuminate\Support\Facades\Route;
use NadrDev\Digiflazz\Http\Controllers\WebhookController;
use NadrDev\Digiflazz\Http\WebhookHandler;

Route::post('/digiflazz/webhook', function (
    Illuminate\Http\Request $request,
    WebhookHandler $webhookHandler
) {
    $controller = new WebhookController();
    return $controller->handle($request, $webhookHandler);
})->name('digiflazz.webhook');

Event Listener

SDK ini memancarkan event TransactionStatusChanged ketika webhook diterima. Anda bisa membuat listener:

// app/Providers/EventServiceProvider.php
protected $listen = [
    \NadrDev\Digiflazz\Events\TransactionStatusChanged::class => [
        \App\Listeners\DigiFlazzWebhookListener::class,
    ],
];

// app/Listeners/DigiFlazzWebhookListener.php
namespace App\Listeners;

use NadrDev\Digiflazz\Events\TransactionStatusChanged;

class DigiFlazzWebhookListener
{
    public function handle(TransactionStatusChanged $event): void
    {
        $transaction = $event->transaction;

        // Update status transaksi di database Anda
        // Kirim notifikasi ke customer
        // dll
    }
}

Contoh Lengkap Webhook Handler

// routes/api.php
Route::post('/digiflazz/webhook', function (Illuminate\Http\Request $request) {
    $signature = $request->header('X-Digiflazz-Signature') 
        ?? $request->header('X-Signature')
        ?? $request->input('signature');

    if (!$signature) {
        return response()->json(['success' => false, 'message' => 'Missing signature'], 400);
    }

    $webhookHandler = new \NadrDev\Digiflazz\Http\WebhookHandler(
        config('digiflazz.webhook.secret')
    );

    try {
        $data = $webhookHandler->handleFromRequest($request->getContent(), $signature);

        // Proses transaksi berdasarkan data webhook
        \Log::info('Webhook DigiFlazz diterima', $data);

        // Update database Anda
        // Order::where('ref_id', $data['ref_id'])->update([
        //     'status' => $data['status'],
        //     'serial_number' => $data['serial_number'],
        //     'message' => $data['message'],
        // ]);

        // Kirim notifikasi
        // if ($data['status'] === 'success') {
        //     // Kirim SMS/Email ke customer
        // }

        return response()->json(['success' => true]);
    } catch (\Exception $e) {
        \Log::error('Error webhook DigiFlazz: ' . $e->getMessage());
        return response()->json(['success' => false], 500);
    }
});

Testing

Jalankan test suite:

composer test

Contoh Penggunaan Lengkap

Controller untuk Pembelian Pulsa

namespace App\Http\Controllers;

use App\Models\Order;
use Illuminate\Http\Request;
use NadrDev\Digiflazz\Facades\Digiflazz;
use NadrDev\Digiflazz\Exceptions\ApiException;
use NadrDev\Digiflazz\Exceptions\ConnectionException;
use NadrDev\Digiflazz\Exceptions\ValidationException;

class PulsaController extends Controller
{
    public function purchase(Request $request)
    {
        $validated = $request->validate([
            'phone_number' => 'required|numeric',
            'product_sku' => 'required|string',
        ]);

        $refId = 'ORDER-' . uniqid();

        try {
            $response = Digiflazz::createTransaction([
                'buyer_sku_code' => $validated['product_sku'],
                'customer_number' => $validated['phone_number'],
                'ref_id' => $refId,
            ]);

            // Simpan ke database
            Order::create([
                'ref_id' => $refId,
                'buyer_sku_code' => $validated['product_sku'],
                'customer_number' => $validated['phone_number'],
                'status' => $response['status'] ?? 'pending',
                'price' => $response['price'] ?? 0,
            ]);

            return response()->json([
                'success' => true,
                'data' => $response,
            ]);
        } catch (ValidationException $e) {
            return response()->json([
                'success' => false,
                'message' => 'Data tidak valid',
                'errors' => $e->getErrors(),
            ], 422);
        } catch (ConnectionException $e) {
            return response()->json([
                'success' => false,
                'message' => 'Gagal terhubung ke DigiFlazz',
            ], 503);
        } catch (ApiException $e) {
            return response()->json([
                'success' => false,
                'message' => $e->getMessage(),
            ], 400);
        }
    }

    public function status(string $refId)
    {
        try {
            $status = Digiflazz::getTransactionStatus($refId);

            return response()->json([
                'success' => true,
                'data' => $status,
            ]);
        } catch (\Exception $e) {
            return response()->json([
                'success' => false,
                'message' => $e->getMessage(),
            ], 500);
        }
    }
}

Troubleshooting

Error: Invalid Signature

Pastikan API Key yang digunakan benar dan sesuai dengan yang ada di dashboard DigiFlazz.

Error: Connection Timeout

Periksa koneksi server Anda ke internet dan pastikan firewall tidak memblokir koneksi ke api.digiflazz.com.

Webhook Tidak Diterima

1. Pastikan URL webhook dapat diakses dari internet (tidak localhost)
2. Periksa SSL certificate jika menggunakan HTTPS
3. Pastikan endpoint webhook mengembalikan response JSON dengan status 200

Saldo Tidak Cukup

Pastikan saldo DigiFlazz Anda mencukupi sebelum melakukan transaksi. Gunakan Digiflazz::getBalance() untuk cek saldo.

Kontribusi

Kami sangat menghargai kontribusi dari komunitas. Silakan buat Pull Request untuk fitur atau perbaikan bug.

Changelog

Lihat CHANGELOG untuk informasi lebih lanjut.

Keamanan

Jika Anda menemukan masalah keamanan, silakan kirim email ke nadradev@example.com.

Kredit

• NadrDev
• DigiFlazz
• Semua Kontributor

Lisensi

MIT License (MIT). Lihat LICENSE untuk informasi lebih lanjut.