sunrice / commerce-xendit
Xendit payments for Sunrice Commerce: virtual accounts, e-wallets, QRIS, cards and retail outlets on a Xendit invoice.
Package info
github.com/Digital-Citra-Kreatif/sunrice-commerce-xendit
pkg:composer/sunrice/commerce-xendit
Requires
- php: ^8.4
- illuminate/contracts: ^13.0
- illuminate/http: ^13.0
- illuminate/support: ^13.0
- spatie/laravel-package-tools: ^1.93
- sunrice/commerce: ^0.1 || ^0.2 || ^0.3 || ^0.4
- xendit/xendit-php: ^7.0
Requires (Dev)
- larastan/larastan: ^3.0
- laravel/pint: ^1.0
- orchestra/testbench: ^11.0
- pestphp/pest: ^4.0
- pestphp/pest-plugin-laravel: ^4.1
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-21 14:50:57 UTC
README
Xendit invoices for Sunrice Commerce: the customer pays on Xendit's invoice page by virtual account, e-wallet, QRIS, card or retail outlet, and comes back to the order. Currencies: IDR, PHP, THB, VND and MYR.
Sunrice\CommerceXendit\Xendit, key xendit, module xendit (Payments; needs payments, off by default).
Contents
- Install
- Keys
- Webhook
- Switching it on
- Sandbox (test mode)
- How it works
- Statuses
- The scheduler
- Deposits
- Refunds
- Troubleshooting
- Testing your own code
Install
composer require sunrice/commerce-xendit
Requirements: PHP 8.4+, Laravel 13, Sunrice Commerce 0.1, 0.2, 0.3 or 0.4 (sunrice/commerce, which Composer
installs with it). The provider is discovered automatically.
The package uses Xendit's SDK, xendit/xendit-php 7.x, which needs Guzzle 7
(guzzlehttp/guzzle ^7.3). Laravel 13 takes Guzzle 7 or 8, so Composer installs Guzzle 7; an
application that requires Guzzle 8 itself can't install this package until the SDK allows it.
To change the config file, config/commerce-xendit.php (key commerce-xendit; it only reads
.env):
php artisan vendor:publish --tag=commerce-xendit-config
Keys
Xendit has a test mode and a live mode, each with its own keys. In the Xendit dashboard, in test mode and again in live mode:
- Settings → Developers → API Keys: create a secret key with write access to Money-in (invoices);
- Settings → Developers → Webhooks: copy the Webhook verification token (the callback token).
Put them in .env:
XENDIT_SANDBOX_SECRET_KEY=xnd_development_… XENDIT_SANDBOX_CALLBACK_TOKEN=… XENDIT_SECRET_KEY=xnd_production_… XENDIT_CALLBACK_TOKEN=…
| Key | Default | |
|---|---|---|
commerce-xendit.secret_key |
env('XENDIT_SECRET_KEY') |
Live secret key |
commerce-xendit.callback_token |
env('XENDIT_CALLBACK_TOKEN') |
Live webhook verification token |
commerce-xendit.sandbox_secret_key |
env('XENDIT_SANDBOX_SECRET_KEY') |
Test secret key |
commerce-xendit.sandbox_callback_token |
env('XENDIT_SANDBOX_CALLBACK_TOKEN') |
Test webhook verification token |
Keys stay in .env, never in the store settings: the settings form says which are set, never
their values.
The dashboard menu paths above were written from Xendit's documentation at the time and have not been checked against the live dashboard; Xendit renames menus from time to time. If a path doesn't match, look for "API Keys" and "Webhooks" under the dashboard's developer settings.
Webhook
In the same Webhooks page, in test mode and again in live mode, set the Invoices webhook URL (invoice paid) to:
https://<your-store>/commerce/webhooks/xendit
This is commerce's own webhook route for the method key xendit; the method's settings show the
exact URL. The return URL needs no setting: each invoice sends the customer back to
/order/{key}/payment/return.
Switching it on
- Switch on Xendit in Settings → Store → Features (it needs Payment methods).
- Switch on the method in Settings → Store → Payments.
The method is offered only when both keys of the current mode are set and the store currency is
one Xendit takes. Switching the module off hides the method and its webhook answers 404; orders
already paid this way keep their payments.
Sandbox (test mode)
Settings: Sandbox (test mode) (sandbox, on by default: uses the XENDIT_SANDBOX_ keys; off:
the live ones) and Instructions per language, shown on the order page and in the email, plus
commerce's shared method fields (title, fee, deadline…).
Switch Sandbox off once the live keys and the live webhook are set.
How it works
start()creates the invoice once per payment:external_id{number}-{payment id}-{random}, the amount and currency, the customer's email, aninvoice_durationup to the payment deadline, and the return URL for success and failure. Its URL and id are stored on the payment; paying again reuses them, and the order page and the "order received" email link to it while the payment is pending.- Webhooks must carry the verification token in
x-callback-token. A wrong or missing token, or a paid amount that isn't the payment's, answers400(loggedfailed). - The event id is the invoice id with the status, so a repeated callback is a duplicate.
- On the customer's return, and once before the deadline, the method reads the invoice
(
getInvoiceById) rather than trusting the query string.
Statuses
Xendit status |
Result |
|---|---|
PAID, SETTLED |
paid (the second changes nothing) |
PENDING |
pending |
EXPIRED |
expired (the order is cancelled) |
The scheduler
Run Laravel's scheduler, which runs commerce's commerce:tick every minute:
* * * * * cd /path/to/site && php artisan schedule:run >> /dev/null 2>&1
It is the safety net for webhooks. When an unpaid payment's deadline passes, commerce:tick first
asks Xendit for its status, so a payment whose notification was lost is still recorded as paid. Only
a payment that is still unpaid then expires, which cancels the order. Without the scheduler, a lost
notification leaves the order unpaid and unpaid orders never expire.
Deposits
When an extension asks for a deposit (commerce's Deposits, Sunrice Commerce 0.3), the deposit and the balance are two separate payments, each with its own Xendit invoice for its own amount. The deposit is charged at checkout, the balance when the customer pays it from the order page. A notification for the balance with the deposit's amount, or the reverse, is refused like any other wrong amount. An expired balance leaves the order open and Partially paid.
Refunds
Xendit doesn't report invoice refunds to the store, so a refund made in the Xendit dashboard doesn't reach the order. Record it yourself: Refund on the order page, with the amount (and the items to restock). The method doesn't send refunds to Xendit.
Troubleshooting
Commerce stores every call to /commerce/webhooks/xendit in the commerce_webhook_calls table
(kept 30 days, commerce.webhooks.keep_days). The admin has no page for it, so query it:
SELECT received_at, status, error, event_id, payment_id FROM commerce_webhook_calls WHERE method = 'xendit' ORDER BY id DESC LIMIT 20;
status |
Meaning |
|---|---|
processed |
Verified and recorded: the payment (and order) changed. |
ignored |
Verified, but nothing to change: a duplicate, a status the payment already has, or an unknown reference (error says which). |
failed |
Refused with 400 (error says why), or failed while recording with 500 (Xendit retries). |
If a payment doesn't update:
- No rows at all: Xendit isn't calling the store. Check that the webhook URL is set in the
dashboard for the mode you're paying in (test and live are separate), that it is reachable from
the internet, and that the Payments and Xendit modules are on (a module that's off answers
404). failed, token: the callback token (XENDIT_SANDBOX_CALLBACK_TOKENorXENDIT_CALLBACK_TOKEN) in.envbelongs to the other mode, or the method's Sandbox switch doesn't match the dashboard you're paying in. After editing.env, clear the config cache (php artisan config:clear).failed, amount: Xendit reported a different amount from the payment's, and the payment stays unpaid. Check the transaction in the dashboard, then mark the order paid by hand if the money arrived.ignored, unknown reference: the notification is for a transaction this store didn't create (another site on the same Xendit account, or a dashboard test).- No change after the customer paid: wait for the notification or the scheduler's check (see The scheduler).
Testing your own code
The SDK calls go through Sunrice\CommerceXendit\Gateways\XenditClient (bound to XenditSdkClient with
bindIf). Bind your own to test without the network:
app()->instance(XenditClient::class, new FakeXenditClient);
This package's tests (tests/Feature/XenditTest.php) do exactly that.
Development
composer test # Pest composer lint # Pint (test mode) composer analyse # Larastan
License
MIT.