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

Konfigurasi	Deskripsi	Default
`DIGIFLAZZ_USERNAME`	Username akun DigiFlazz Anda	-
`DIGIFLAZZ_API_KEY`	API Key dari dashboard DigiFlazz	-
`DIGIFLAZZ_PRODUCTION`	Mode production (true) atau development (false)	false
`DIGIFLAZZ_WEBHOOK_SECRET`	Secret untuk verifikasi webhook	API Key
`DIGIFLAZZ_WEBHOOK_ENABLED`	Aktifkan webhook handler	true

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:

Parameter	Tipe	Wajib	Deskripsi
`buyer_sku_code`	string	Ya	Kode produk yang akan dibeli
`customer_number`	string	Ya	Nomor tujuan (nomor HP, ID pelanggan, dll)
`ref_id`	string	Tidak	ID referensi unik dari sistem Anda
`extra_data`	string	Tidak	Data tambahan (opsional)

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:

Parameter	Tipe	Wajib	Deskripsi
`start_date`	string	Tidak	Tanggal mulai (format: Y-m-d)
`end_date`	string	Tidak	Tanggal akhir (format: Y-m-d)
`status`	string	Tidak	Filter status (pending, success, failed)
`buyer_sku_code`	string	Tidak	Filter berdasarkan kode produk
`page`	int	Tidak	Halaman (default: 1)
`limit`	int	Tidak	Jumlah data per halaman (default: 20)

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

Login ke dashboard DigiFlazz
Masuk ke menu Callback/Webhook
Masukkan URL endpoint webhook Anda
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

Pastikan URL webhook dapat diakses dari internet (tidak localhost)
Periksa SSL certificate jika menggunakan HTTPS
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

Lisensi

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

ndradev / digiflazz-sdk-laravel

Maintainers

Package info

Statistics

Security