usezeny / laravel
PHP and Laravel SDK for the Merchant API v1
Requires
- php: ^8.2
- guzzlehttp/guzzle: ^7.8
- illuminate/http: ^12.0|^13.0
- illuminate/support: ^12.0|^13.0
- psr/http-client: ^1.0
- psr/http-message: ^1.1|^2.0
Requires (Dev)
- laravel/pint: ^1.18
- orchestra/testbench: ^10.0|^11.0
- pestphp/pest: ^3.0
- pestphp/pest-plugin-arch: ^3.0
- phpstan/phpstan: ^2.0
- symfony/var-dumper: ^7.0|^8.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
usezeny/laravel
Take payments in your Laravel app in minutes.
Payment links, QRIS, virtual accounts and e-wallets, with one composer require.
Get started ยท See it work ยท Full guide ยท Changelog
Why you'll like it
| ๐ Payment links in one call | Create a hosted checkout page and send your customer there. No checkout UI to build. |
| ๐ฎ๐ฉ Every way Indonesia pays | QRIS, bank virtual accounts (BCA and more) and e-wallets such as GoPay, all from the same link. |
| ๐ก๏ธ Never charges twice | Network hiccups are retried for you, and every retry is the same request, so a customer is never charged twice. |
| ๐ Know the moment you're paid | Webhooks arrive signed and checked. One middleware, and your route gets a ready-to-use event. |
| ๐งช Sandbox first | A test key gives you a full playground with fake money. Switch to a live key when you're ready. Nothing else changes. |
| ๐ฏ Feels like Laravel | Auto-discovered service provider, a Zeny facade, .env config and a mockable interface for your tests. |
Get started in 3 steps
1. Install
composer require usezeny/laravel
2. Add your keys to .env
ZENY_SECRET_KEY=sk_test_... # from the dashboard, Developers page ZENY_WEBHOOK_SECRET=whsec_... # from your webhook endpoint
A sk_test_ key works in Sandbox, where no real money moves.
3. Create a payment link and send your customer to it
use App\Models\Order; use Illuminate\Http\RedirectResponse; use Illuminate\Support\Facades\Route; use Zeny\Domain\RequestOptions; use Zeny\Laravel\Facades\Zeny; Route::post('/orders/{order}/pay', function (Order $order): RedirectResponse { $link = Zeny::paymentLinks()->create([ 'name' => "Order #{$order->id}", 'amount' => ['value' => $order->total, 'currency' => 'IDR'], // a decimal string, never a float 'successRedirectUrl' => route('orders.thanks', $order), 'maxPayments' => 1, // one order, one payment: the link closes once paid 'requiredPayerFields' => ['email'], // the payer must give an email for the receipt ], new RequestOptions(idempotencyKey: "order-{$order->id}-link"))->toArray(); $order->update(['payment_link' => $link['id']]); // pl_..., matched on the payment.paid webhook return redirect()->away($link['url']); // the hosted checkout page });
That's it. Your customer pays on the hosted page and comes back to your thank-you page.
How a payment flows
sequenceDiagram
autonumber
actor Customer
participant App as Your Laravel app
participant Pay as Payment page
Customer->>App: Clicks "Pay"
App->>Pay: Zeny::paymentLinks()->create(...)
Pay-->>App: Link with a url
App-->>Customer: Redirect to the url
Customer->>Pay: Pays with QRIS, VA or e-wallet
Pay-->>App: payment.paid webhook
App->>App: Mark the order paid
Pay-->>Customer: Back to your thank-you page
Loading
๐ก Golden rule: mark an order paid only when the
payment.paidwebhook arrives, never just because the customer came back to your site.
Know when you're paid
Add the zeny.webhook middleware to a route. It checks every webhook's signature, and your code only sees real events:
use App\Models\Order; use Illuminate\Foundation\Http\Middleware\ValidateCsrfToken; use Illuminate\Http\Request; use Illuminate\Http\Response; use Illuminate\Support\Facades\DB; use Illuminate\Support\Facades\Route; use Zeny\Laravel\Middleware\VerifyZenyWebhook; Route::post('/webhooks/payments', function (Request $request): Response { $event = VerifyZenyWebhook::event($request); // checked by the zeny.webhook middleware DB::transaction(function () use ($event): void { // A unique key on id: a repeated event inserts nothing and changes nothing. $isNew = DB::table('webhook_events')->insertOrIgnore(['id' => $event['id'], 'type' => $event['type']]) === 1; if (! $isNew || $event['type'] !== 'payment.paid') { return; } $payment = $event['data']['object']; // A link payment carries its pl_ id; an API payment carries your reference. if ($payment['paymentLink'] !== '') { Order::markPaidByLink($payment['paymentLink']); } else { Order::markPaid($payment['reference']); } }); // 204 only after the commit. An exception answers 500, so the event comes again. return response()->noContent(); })->middleware('zeny.webhook')->withoutMiddleware(ValidateCsrfToken::class);
Webhooks can arrive twice, so the route saves each event once by its id and ignores repeats.
What you can do
| Payment links | Create, list, close, reopen and cancel hosted checkout links. Limit how many times a link can be paid, and ask for the payer's name, email or phone. |
| Payments | Build your own checkout: create a payment, then show the customer a QR code, a virtual account number or an e-wallet redirect. |
| Payouts | Send money out to a bank account, and cancel a payout before it goes out. |
| Disputes | See the disputes raised on your payments. |
| Sandbox test funds | Top up your Sandbox balance to try payouts. |
Every option and edge case is in the Guide:
- Payment links in detail
- Custom checkout
- Laravel setup and config
- Webhooks without Laravel
- Handling errors
- Safe retries
- Sandbox, Production and white-label hosts
Built to be safe
- Your secret key stays secret. It never shows up in error messages, logs or
dd()dumps. - Money is exact. Amounts are strings like
'150000', never floats that round wrong. - No double charges. Retries reuse the same idempotency key, so the payment happens once.
- Webhooks fail closed. A webhook with a bad or old signature is rejected before your code runs.
- Typed end to end. PHPStan knows every field of every response, and the types come straight from the API contract.
Requirements
| PHP | Laravel |
|---|---|
| 8.2+ | 12 |
| 8.3+ | 12 or 13 |
Outside Laravel, the client works in any PHP 8.2+ project. See the Guide.
Contributing
Issues and pull requests are welcome. AGENTS.md has the architecture, the commands and the rules every change follows, and RELEASING.md explains how a version ships.
License
MIT. See LICENSE.