README

Unified Laravel Payment Orchestrator for Indonesian Payment Gateways

PayID adalah package Laravel yang menyatukan berbagai payment gateway Indonesia dalam satu API yang konsisten dan extensible. Integrasikan sekali, gunakan provider mana saja melalui model driver.

Tujuan, Cakupan, dan Batasan

Tujuan

• Menyediakan API pembayaran yang konsisten lintas provider untuk use case umum aplikasi.
• Mengurangi vendor lock-in dengan pendekatan driver dan capability-based contracts.
• Menstandarkan lifecycle pembayaran (charge, status, webhook, dsb.) agar mudah diuji dan dipelihara.

Cakupan

• Orkestrasi pembayaran pada layer aplikasi Laravel melalui facade/manager PayID.
• Standardisasi DTO, enum status, dan webhook normalization lintas driver.
• Ekstensi provider-specific melalui package driver terpisah (mis. Midtrans, Xendit, iPaymu, Nicepay).
• Integrasi opsional dengan stack transaksi/ledger lewat package pendamping.

Batasan

• PayID bukan payment gateway; eksekusi transaksi tetap dilakukan oleh provider masing-masing.
• Fitur provider-specific yang sangat khusus tidak selalu tersedia di API generic manager, dan diakses via extension method pada driver.
• Compliance, legal, settlement, rekonsiliasi bank, dan dispute handling tetap menjadi tanggung jawab aplikasi/operasional bisnis.
• Konfigurasi kredensial, endpoint, serta kebijakan retry/queue production harus ditetapkan di aplikasi host sesuai kebutuhan domain.

Requirements

• PHP 8.2+
• Laravel 11.x, 12.x, atau 13.x

Instalasi

Install PayID core:

composer require aliziodev/payid

Install driver provider yang diinginkan:

composer require aliziodev/payid-midtrans
composer require aliziodev/payid-xendit

Publish konfigurasi:

php artisan vendor:publish --tag=payid-config

Opsional, gunakan installer interaktif:

php artisan payid:install

Installer akan memandu:

• pemilihan driver gateway
• pemilihan transaction stack: payid-transactions atau manual

Konfigurasi

Tambahkan ke .env:

PAYID_DEFAULT_DRIVER=midtrans

MIDTRANS_ENV=sandbox
MIDTRANS_SERVER_KEY=SB-Mid-server-xxxx
MIDTRANS_CLIENT_KEY=SB-Mid-client-xxxx

Penggunaan Dasar

Membuat Transaksi

use Aliziodev\PayId\DTO\ChargeRequest;
use Aliziodev\PayId\Enums\PaymentChannel;
use Illuminate\Support\Facades\PayId;

$response = PayId::charge(ChargeRequest::make([
    'merchant_order_id' => 'ORDER-001',
    'amount'            => 150000,
    'currency'          => 'IDR',
    'channel'           => PaymentChannel::Qris,
    'customer'          => [
        'name'  => 'Alizio',
        'email' => 'budi@example.com',
    ],
]));

return redirect($response->paymentUrl);

Cek Status Transaksi

$status = PayId::status('ORDER-001');

if ($status->status->isSuccessful()) {
    // Tandai order sebagai dibayar
}

Ganti Driver Saat Runtime

$response = PayId::driver('xendit')->charge($request);

Operasi Lain yang Tersedia

PayID manager/facade juga menyediakan:

• directCharge(ChargeRequest $request)
• refund(RefundRequest $request)
• cancel(string $merchantOrderId)
• expire(string $merchantOrderId)
• approve(string $merchantOrderId)
• deny(string $merchantOrderId)
• createSubscription(SubscriptionRequest $request)
• getSubscription(string $providerSubscriptionId)
• updateSubscription(UpdateSubscriptionRequest $request)
• pauseSubscription(string $providerSubscriptionId)
• resumeSubscription(string $providerSubscriptionId)
• cancelSubscription(string $providerSubscriptionId)
• supports(Capability $capability)

Menangani Webhook

Daftarkan URL webhook ke dashboard provider: https://yourdomain.com/payid/webhook/midtrans

Tangkap event di listener:

use Aliziodev\PayId\Events\WebhookReceived;
use Aliziodev\PayId\Enums\PaymentStatus;

Event::listen(WebhookReceived::class, function (WebhookReceived $event) {
    $webhook = $event->webhook;

    if ($webhook->status === PaymentStatus::Paid) {
        Order::markAsPaid($webhook->merchantOrderId);
    }
});

Testing

$fake = PayId::fake();

$fake->fakeCharge(ChargeResponse::make([
    'provider_name'           => 'midtrans',
    'provider_transaction_id' => 'TRX-001',
    'merchant_order_id'       => 'ORDER-001',
    'status'                  => PaymentStatus::Pending,
    'payment_url'             => 'https://example.com/pay',
    'raw_response'            => [],
]));

// Jalankan kode yang memanggil PayId::charge(...)

$fake->assertCharged();

Fake helper lain yang tersedia termasuk:

• fakeDirectCharge, fakeStatus, fakeRefund, fakeCancel, fakeExpire
• fakeApprove, fakeDeny, fakeSubscription
• assertion seperti assertDirectCharged, assertStatusChecked, assertRefunded, assertNothingRecorded

Driver yang Tersedia

Dokumentasi

• R&D Document
• Technical Architecture
• Package Blueprint
• Implementation Roadmap
• README and Docs Structure Draft
• Production Readiness Checklist
• Driver Authoring Guide
• Driver Acceptance Checklist
• Midtrans Complete Usage Guide
• Xendit Complete Usage Guide
• Driver Feature Matrix (Midtrans vs Xendit vs iPaymu vs Nicepay)
• Xendit Extension API Quick Reference
• Midtrans Extension API Quick Reference
• iPaymu Complete Usage Guide
• iPaymu Extension API Quick Reference
• Nicepay Complete Usage Guide
• Nicepay Extension API Quick Reference
• Diagram Index
• PayID Complete System Flow Diagram
• Checkout and Payment Lifecycle Flow
• Webhook Processing Flow
• Subscription Flow
• Driver Extension Flow
• ADR: Core and Driver Separation
• ADR: Capability-based Contracts
• ADR: Immutable DTO
• ADR: Webhook Pipeline

Status Kesiapan

• Test suite: passing
• Static analysis (PHPStan): passing
• Coverage report: butuh coverage driver (Xdebug/PCOV/phpdbg-compatible) di environment

Known Limitations

• Coverage report belum dapat dijalankan jika environment belum memuat driver coverage.
• Driver iPaymu sudah tersedia pada level beta dan dapat dipakai untuk flow charge/status/webhook.
• Driver Nicepay sudah final dan berstatus stable, mencakup fitur SNAP + V2 melalui extension method.
• Fitur queue processing webhook disiapkan pada konfigurasi, tetapi implementasi orchestration async tetap perlu ditangani di aplikasi host.

Kontribusi

Lihat CONTRIBUTING.md untuk panduan berkontribusi.

Security

Untuk pelaporan vulnerability, lihat SECURITY.md.

Upgrade

Panduan upgrade antar versi tersedia di UPGRADE.md.

Changelog

Riwayat perubahan tersedia di CHANGELOG.md.

Lisensi

MIT License.