nujek-indonesia / payment

v0.2.1 2026-10-13 04:11 UTC

Requires

• php: ^8.1
• guzzlehttp/guzzle: ^7.8

Requires (Dev)

• phpunit/phpunit: ^10.5

MIT

Published on Packagist.org on 2026-10-13 04:25 UTC

README

Client Composer untuk Merchant API Nujek. Membuat signature request, memverifikasi webhook, dan menyediakan method untuk bill, onboarding, wallet, payout, saldo, serta QRIS static.

Memerlukan PHP 8.1 atau lebih baru.

Instalasi

composer require nujek-indonesia/payment

Mulai cepat

Simpan API key dan secret di environment variable, bukan di source code.

use Nujek\Payment\Client;

$payment = new Client(
    baseUrl: $_ENV['PAYMENT_BASE_URL'],
    apiKey: $_ENV['PAYMENT_API_KEY'],
    apiSecret: $_ENV['PAYMENT_API_SECRET'],
);

$bill = $payment->createBill([
    'external_id' => 'order-123',
    'channel_id' => 'NOBU_QRIS',
    'total' => '150000.00', // kirim nominal sebagai string
    'currency' => 'IDR',
    'expired_at' => '2026-10-13T10:15:00Z', // RFC3339, harus di masa depan
]);

echo $bill['data']['uuid'];

Contoh siap jalan ada di examples/create_bill.php:

PAYMENT_BASE_URL=https://payment.example.com \
PAYMENT_API_KEY=... PAYMENT_API_SECRET=... PAYMENT_CHANNEL_ID=NOBU_QRIS \
php examples/create_bill.php

Operasi utama

Area	Method
Bill	createBill, getBill, getBillByExternalId, listBills, listBillsForUser, getBillForUser, listUserBills, getUserBill
Onboarding	createOnboardingSession, getOnboardingSession, listOnboardingSessionBills, revokeOnboardingSession
User/wallet	listUsers, getUser, getUserWallet, topupUserWallet, debitUserWallet, userHistory, userWalletTransactions, lookupWalletTransaction
Merchant	createPayout, listPayouts, getPayout, balance, listQrisStatic, getQrisStatic

Seluruh respons API didekode menjadi array asosiatif PHP. List memakai ['data' => [...], 'meta' => [...]]; resource tunggal biasanya memakai ['data' => [...]].

Wallet yang aman untuk retry

reference_id adalah kunci idempotensi scoped ke merchant dan user. Pakai ID yang sama bila request harus dicoba ulang. Jangan membuat ID baru saat timeout.

$payment->topupUserWallet('USER-001', [
    'amount' => '150000.00',
    'reference_id' => 'TOPUP-USER-001-001',
]);

// Cari hasil bila outcome request sebelumnya tidak pasti.
$transaction = $payment->lookupWalletTransaction('USER-001', 'TOPUP-USER-001-001');

Error dan retry

Respons HTTP non-2xx melempar Nujek\Payment\ApiError. Error memiliki status, errorCode, requestId, retryAfter, dan helper retry.

use Nujek\Payment\ApiError;

try {
    $payment->createPayout($request);
} catch (ApiError $error) {
    if ($error->isRetryable()) {
        // Hormati $error->retryAfter bila tersedia.
    } elseif ($error->isConflict()) {
        // Contoh: reference_id dipakai kembali dengan data berbeda.
    }
    throw $error;
}

Verifikasi webhook

Gunakan raw body sebelum json_decode. X-Webhook-Timestamp harus dipakai apa adanya dan body tidak boleh diubah sebelum validasi.

use Nujek\Payment\Webhook;

$rawBody = file_get_contents('php://input');
$valid = Webhook::verify(
    $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '',
    $rawBody,
    $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '',
    $_ENV['NUJEK_WEBHOOK_SECRET'],
);

if (!$valid) { http_response_code(401); exit; }
$event = json_decode($rawBody, true, 512, JSON_THROW_ON_ERROR);

Simpan X-Nujek-Webhook-Id secara atomik sebelum memproses event supaya delivery retry tidak diproses dua kali. Event umum termasuk bill.paid, user.onboarding.completed, dan webhook.test.