KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #developer-tools #ai-agent #claude-code #codex #typescript #ai-agents #deepseek-harness #mcp #cli #rust

xendivel

★ 44 Open GitHub ↗

A Laravel package for Xendit payment gateway. It currently supports credit cards, debit cards, QR code, and e-wallet payments. Future support for subscriptions, etc.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

![Project Logo](https://raw.githubusercontent.com/glennraya/xendivel/main/artwork/xendivel.jpg)

# Xendivel — A Laravel package for Xendit payment gateway

A Laravel package designed for the seamless integration of the [Xendit](https://xendit.co/) payment gateway into your Laravel-powered applications or websites. It facilitates payments through credit cards, debit cards, QR code, and eWallets. Additionally, the package provides support for custom invoicing, queued invoice or refund email notifications, webhook event listeners and verification.

## Video Demo

I've created a short video demo to showcase the package's features. You can find it [here](https://youtu.be/oxdE3Y6viAE).

## Roadmap

The following features, while not currently supported by the Xendivel, are planned for inclusion in upcoming updates.

- Direct Bank Debit
- Promotions (coupon/discount codes)
- Subscription services
- Real-time push notifications for payment status (Laravel Reverb)
- Disbursement APIs (for mass payment processing like employee payroll)
- PayLater

## Table of Contents

1. [Features](#features)
2. [Pre-requisites](#pre-requisites)
3. [Installation](#installation)
    - [PDF Runtime Requirements](#pdf-runtime-requirements)
    - [Install Xendivel](#install-xendivel)
4. [Initial Setup](#initial-setup)
    - [Xendit API keys](#xendit-api-keys)
    - [Configure Mail (Optional)](#configure-mail-optional)
    - [Queues (Optional)](#queues-optional)
    - [Publish Config and Assets](#publish-config-and-assets)
	    - [Publish Individual Assets](#publish-individual-assets)
    - [Browsershot Runtime Options](#browsershot-runtime-options)
    - [Laravel Herd and Valet Node Paths](#laravel-herd-and-valet-node-paths)
5. [Checkout Templates](#checkout-templates)
6. [Usage](#usage)
    - [Card Payments](#card-payments)
        - [Card Details Tokenization](#card-details-tokenization)
        - [Charge Credit Or Debit Cards](#charge-credit-or-debit-cards)
	        - [External ID](#external-id)
        - [Get Card Charge Transaction](#get-card-charge-transaction)
        - [Authorize Card / Hold Funds](#authorize-card--hold-funds)
        - [Capture Authorized Card Charge](#capture-authorized-card-charge)
        - [Void Card Authorization](#void-card-authorization)
        - [Test The Full Hold Flow In The Checkout Demo](#test-the-full-hold-flow-in-the-checkout-demo)
        - [Multi-Use Card Token](#multi-use-card-token)
    - [eWallet Payments](#ewallet-payments)
        - [Charge eWallet](#charge-ewallet)
        - [Get eWallet Charge](#get-ewallet-charge)
        - [Void eWallet Charge](#void-ewallet-charge)
    - [QR Code Payments](#qr-code-payments)
        - [Generate QR Code](#generate-qr-code)
        - [Get QR Code Status](#get-qr-code-status)
        - [Simulate QR Payment](#simulate-qr-payment)
        - [Responding to QR Payment Webhook Event](#responding-to-qr-payment-webhook-event)
    - [PDF Invoicing](#pdf-invoicing)
        - [Generate PDF Invoice](#generate-pdf-invoice)
        - [Download PDF Invoice](#download-pdf-invoice)
        - [Paper Size](#invoice-paper-size)
        - [Change Invoice Paper Size](#change-invoice-paper-size)
        - [Change Invoice Orientation](#change-invoice-orientation)
        - [Invoice Filenaming](#invoice-filename)
        - [Customizing PDF Invoice](#customizing-pdf-invoice-template)
        - [Sending PDF Invoice As Email Attachment](#sending-pdf-invoice-as-email-attachment)
	        - [Sending PDF Invoice for Card Payments](#sending-pdf-invoice-for-card-payments)
	        - [Sending PDF Invoice for eWallet Payments](#sending-pdf-invoice-for-ewallet-payments)
        - [Queue Invoice Email](#queue-invoice-email)
    - [Refunds](#refunds)
        - [Refund for Card Payments](#refund-for-card-payments)
        - [Refund for ewallet Payments](#refund-for-ewallet-payments)
        - [Get Refund Details](#get-refund-details)
        - [List All eWallet Refunds](#list-all-ewallet-refunds)
        - [Email Refund Confirmation](#email-refund-confirmation)
    - [Webhook](#webhook)
        - [Listen to Webhook Event](#listen-to-webhook-event)
        - [Webhook Verification](#webhook-verification)
7. [Deploying to Production](#deploying-to-production)
8. [Tests](#tests)

## Features

- **Credit/Debit Cards** - Easily process payments through major credit or debit cards.
- **eWallet Payments** - Accepts a diverse range of eWallet payments based on your region (GCash, ShopeePay, PayMaya, GrabPay, etc.).
- **QR Code Payments** - Generate dynamic or static QR codes customers can scan to pay, with asynchronous payment confirmation via webhook.
- **Custom Invoicing** - Provides built-in, highly customizable, and professional-looking invoice templates.
- **Queued Email Notifications** - Enables the use of markdown email templates and the option to schedule email notifications for background processing.
- **Webhooks** - Comes with built-in webhook event listeners from Xendit and ensures secure webhook verification.

### Pre-requisites

- PHP 8.2 or higher
- Laravel 10 or higher
- Node 22.0 LTS or higher
- npm and Puppeteer 23.0 or higher
- Chrome or Chromium for Browsershot PDF generation

### Supported Versions

| Target | Supported versions |
| --- | --- |
| PHP runtime | 8.2, 8.3, 8.4, 8.5 |
| Laravel runtime | 10, 11, 12, 13 |
| Default contributor test stack | PHP 8.3+, Laravel 12, Pest 4, Orchestra Testbench 10 |

Laravel 13 is officially supported and requires PHP 8.3+. Laravel 10 through 12 remain installable on PHP 8.2+.

## Installation

### PDF Runtime Requirements

Xendivel uses [Spatie Browsershot](https://spatie.be/docs/browsershot) for generating PDF invoices from HTML or Blade templates. Browsershot runs Puppeteer behind the scenes, so the Laravel application needs Node, npm, Puppeteer, and Chrome or Chromium available on the server that generates invoices.

> [!IMPORTANT]
> Browsershot does not require a paid Typeset.sh subscription or a private Composer repository. It does require a working browser runtime.

Install Puppeteer in the Laravel application:

```bash
npm install puppeteer
```

Install Chrome for Puppeteer when your deployment image does not already include it:

```bash
npx puppeteer browsers install chrome
```

Xendivel requires the Node and npm binary paths in the Laravel application's `.env` file. Browsershot is executed by PHP, queue workers, and web server processes that may not use the same shell `PATH` as your terminal, so set these values after installing Puppeteer:

```dotenv
XENDIVEL_BROWSERSHOT_NODE_BINARY="/absolute/path/to/node"
XENDIVEL_BROWSERSHOT_NPM_BINARY="/absolute/path/to/npm"
```

You can find the paths from the application terminal:

```bash
command -v node
command -v npm
```

On Linux servers, install the system libraries Chrome needs. The exact package names vary by distribution; Spatie's Browsershot requirements page includes examples for current Ubuntu and Laravel Forge servers.

### Install Xendivel

Xendivel utilizes Composer's package auto-discovery. Install Xendivel via Composer and it will automatically register itself.

```bash
composer require glennraya/xendivel
```

## Initial Setup

### Xendit API Keys

Prior to using Xendivel, it's essential to have a Xendit account with properly configured API keys. Activation of your Xendit account for production is not necessary to test Xendivel's features. Test mode will be automatically enabled upon signing up for a Xendit account. Obtain your API keys from the following URLs:

- Secret Key/Public Key: https://dashboard.xendit.co/settings/developers#api-keys
- Webhook Verification Token: https://dashboard.xendit.co/settings/developers#webhooks

Generate `Money-In` `secret key` with `read` and `write` permissions from your dashboard API keys section.

After you acquired all these keys, please make sure you include them to your Laravel's `.env` file:

```ini
XENDIT_SECRET_KEY=your-secret-key
XENDIT_PUBLIC_KEY=your-public-key
XENDIT_WEBHOOK_VERIFICATION_TOKEN=your-webhook-verification-token
```

### Configure Mail (Optional)

Xendivel can send invoices to your customers as email attachments. To utilize this feature, ensure your [Laravel Mail](https://laravel.com/docs/13.x/mail#main-content) is correctly set up. Before Xendivel dispatches invoice or refund email notifications, ensure your mail credentials are filled in your `.env` file.

```ini
MAIL_MAILER=smtp
MAIL_HOST=your-mailer-host
MAIL_PORT=your-mailer-port
MAIL_USERNAME=your-mailer-username
MAIL_PASSWORD=your-mailer-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS="fromaddress@example.com"
MAIL_FROM_NAME="${APP_NAME}"
```

### Queues (Optional)

Xendivel facilitates the queueing of email processes for background execution. If you intend to employ queued emails for tasks such as invoicing or refund notifications, ensure that you have properly configured [Laravel Queues](https://laravel.com/docs/13.x/queues#main-content).

Then, make sure you have a queue worker running:

```bash
php artisan queue:work
```

Finally, please ensure that `queue_email` is set to `true` from your `.env` file:

```php
'queue_email' => true,
```

Once you have successfully configured Laravel's queues and enabled `queue_email` to `true`, Xendivel is now capable of dispatching invoice or refund emails to the queue for background execution, enabling your app to respond to other requests or do other tasks without waiting for the jobs to finish. **This will improve overall user experience!**

### Publish Config and Assets

All assets and configuration file must be published to its proper directory for Xendivel to function properly:

```bash
php artisan vendor:publish --tag=xendivel
```

Executing this command will publish Xendivel's assets to the following directories:

- Config file - `config` directory.
- Invoice template - `resources/views/vendor/xendivel` directory.
- Email templates - `resources/views/vendor/xendivel/emails` directory.
- Blade checkout template - `resources/views/vendor/xendivel` directory.
- Webhook Event and Listener - `app/Events` and `app/Listeners` directory respectively.

#### Publish Individual Assets

##### Configuration File
```bash
php artisan vendor:publish --tag=xendivel-config
```

##### Invoice Template
```bash
php artisan vendor:publish --tag=xendivel-invoice
```

##### Checkout (Blade)
```bash
php artisan vendor:publish --tag=xendivel-checkout-blade
```

##### Checkout (ReactJS)
```bash
php artisan vendor:publish --tag=xendivel-checkout-react
```

##### Checkout (ReactJS + TypeScript)
```bash
php artisan vendor:publish --tag=xendivel-checkout-react-typescript
```

##### Webhook Event Listener
```bash
php artisan vendor:publish --tag=xendivel-webhook-listener
```

### Browsershot Runtime Options

Xendivel exposes Browsershot runtime options through `config/xendivel.php`. The Node and npm binary paths are required in `.env`; the remaining values are optional environment-specific overrides:

```php
'browsershot' => [
    'timeout' => 60,
    'node_binary' => env('XENDIVEL_BROWSERSHOT_NODE_BINARY'),
    'npm_binary' => env('XENDIVEL_BROWSERSHOT_NPM_BINARY'),
    'chrome_path' => env('XENDIVEL_BROWSERSHOT_CHROME_PATH'),
    'node_module_path' => env('XENDIVEL_BROWSERSHOT_NODE_MODULE_PATH'),
    'include_path' => env('XENDIVEL_BROWSERSHOT_INCLUDE_PATH'),
    'content_url' => env('XENDIVEL_BROWSERSHOT_CONTENT_URL', env('APP_URL')),
    'no_sandbox' => env('XENDIVEL_BROWSERSHOT_NO_SANDBOX', false),
],
```

- `timeout`: max Browsershot runtime in seconds.
- `node_binary` / `npm_binary`: required Node and npm executable paths.
- `chrome_path`: custom Chrome or Chromium executable path.
- `node_module_path`: custom `node_modules` path when Puppeteer is installed outside the app root.
- `include_path`: custom shell include path for resolving Node/npm.
- `content_url`: base URL used when invoice HTML contains relative asset paths.
- `no_sandbox`: enables Browsershot's `noSandbox()` option for Linux environments that require it.

Set at least these values in the Laravel application's `.env` file:

```dotenv
XENDIVEL_BROWSERSHOT_NODE_BINARY="/absolute/path/to/node"
XENDIVEL_BROWSERSHOT_NPM_BINARY="/absolute/path/to/npm"
```

Only non-empty optional path values are applied to Browsershot.

#### Laravel Herd and Valet Node Paths

When running a Laravel app through Herd or Valet on macOS, the PHP process may not inherit the same shell `PATH` as your terminal. Point Xendivel to the exact Node and npm binaries in the application's `.env` file so Browsershot can run reliably.

For Laravel Herd, the paths usually live under `~/Library/Application Support/Herd/config/nvm/versions/node/{version}/bin`. Use `command -v node` and `command -v npm` from the same terminal profile you use for the project, then add those paths to `.env`:

```dotenv
APP_URL=http://your-app.test

XENDIVEL_BROWSERSHOT_NODE_BINARY="/Users/your-user/Library/Application Support/Herd/config/nvm/versions/node/v24.14.1/bin/node"
XENDIVEL_BROWSERSHOT_NPM_BINARY="/Users/your-user/Library/Application Support/Herd/config/nvm/versions/node/v24.14.1/bin/npm"
```

After changing these values, clear Laravel's cached config:

```bash
php artisan config:clear
```

## Checkout Templates

![Checkout Template](https://raw.githubusercontent.com/glennraya/xendivel/main/docs/image_assets/checkout-template.png)

Xendivel ships with a complete, fully working checkout template for cards and eWallet payments. The template include various variants such as **ReactJS component**, **ReactJS+TypeScript** component, and a regular **Blade** template and **VanillaJS**.

You can choose between the currently available template variants, you can even create your own.

### Blade Template

We offer a standard Blade template for the checkout example, using VanillaJS. There's a built-in route allowing you to test this template at `/xendivel/checkout/blade`. You can access it through a URL like `https://your-domain.test/xendivel/checkout/blade`.

> [!Note]
> When you run the command `php artisan vendor:publish --tag=xendivel` the checkout blade template will be on your `/resources/views/vendor/xendivel/checkout.blade.php` directory.

### ReactJS + TypeScript component

Xendivel also have a checkout template component for **ReactJS** or **React+TypeScript** for those who are using front-end frameworks like React instead of regular Blade template.

```bash
php artisan vendor:publish --tag=xendivel-checkout-react-typescript

php artisan vendor:publish --tag=xendivel-checkout-react
```

These will be published under `/resources/js/vendor/xendivel/Checkout.tsx` for React+TypeScript or  `/resources/js/vendor/xendivel/Checkout.jsx` for plain ReactJS.

> [!IMPORTANT]
> After publishing either one of these templates, please make sure you filled up the `public key` section on these React templates. Since this is a public key, it's perfectly safe to publish it directly on your templates.

```javascript
// Set your 'public' key here.
Xendit.setPublishableKey(
    'your-public-key',
)
```

These templates demonstrate card tokenization, credit/debit card, and eWallet payments. They serve to guide your payment collection process for implementation in your front-end stack. Alternatively, use them as fully functional standalone templates if you wish.

## Usage

### Card Payments

#### Card Details Tokenization

Xendit uses tokenization to securely handle credit or debit card details. This process involves using Xendit's JavaScript library to convert sensitive card information like the number, expiry date, and CVV into secure tokens before they are sent to your back-end. This method ensures that the actual card details are not transmitted, enhancing the safety and confidentiality of your customer's card information.

For more details, refer to Xendit's documentation below:

https://docs.xendit.co/credit-cards/integrations/tokenization

Xendivel offers easy-to-use templates in **ReactJS, React+TypeScript, and Blade**, providing ready-to-use checkout components for card/eWallet transactions. These templates offer a robust foundation for payment processing. For further information, see the [Checkout templates](#checkout-templates) section.

#### Charge Credit Or Debit Cards

The `Xendivel::payWithCard` function accepts the incoming request payload with the `token_id`, `amount`, and `authentication_id`:

Example Front-end POST Request Using Axios

```javascript
axios.post('/pay-with-card', {
    amount: 1200,
    token_id: 'card-token', // From card tokenization process.
    authentication_id: 'auth-id', // From authentication process.
    // Additional optional parameters:

// external_id: 'your-custom-external-id',

// descriptor: "Merchant Business Name",

// currency: 'PHP',

// metadata: {
    //     store_owner: 'Glenn Raya',
    //     nationality: 'Filipino',
    //     product: 'MacBook Pro 16" M3 Pro',
    //     other_details: {
    //         purpose: 'Work laptop',
    //         issuer: 'Xendivel LTD',
    //         manufacturer: 'Apple',
    //         color: 'Silver'
    //     }
    // }

// billing_details: {
    //     given_names: 'Glenn',
    //     surname: 'Raya',
    //     email: 'glenn@example.com',
    //     mobile_number: '+639171234567',
    //     phone_number: '+63476221234',
    //     address:{
    //         street_line1: 'Ivory St. Greenfield Subd.',
    //         street_line2: 'Brgy. Coastal Ridge',
    //         city: 'Balanga City',
    //         province_state: 'Bataan',
    //         postal_code: '2100',
    //         country: 'PH'
    //     }
    // },
})
// ...
```

Then, in your Laravel route/controller

`POST` Request:

```php
use GlennRaya\Xendivel\Xendivel;

Route::post('/pay-with-card', function (Request $request) {
    $payment = Xendivel::payWithCard($request)
        ->getResponse();

return $payment;
});
```

The `getResponse()` function ensures that you get a JSON response:

```json
{
  "status": "CAPTURED",
  "authorized_amount": 5198,
  "capture_amount": 5198,
  "currency": "PHP",
  "metadata": {},
  "credit_card_token_id": "656ed874edab5300169c3092",
  "business_id": "6551f678273a62fd8d86e25a",
  "merchant_id": "104019905",
  "merchant_reference_code": "656ed874edab5300169c3091",
  "external_id": "43565633-dd58-47ae-bbe6-648f78d6652c",
  "eci": "02",
  "charge_type": "SINGLE_USE_TOKEN",
  "masked_card_number": "520000XXXXXX1005",
  "card_brand": "MASTERCARD",
  "card_type": "CREDIT",
  "ucaf": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",
  "descriptor": "XDT*JSON FAKERY",
  "authorization_id": "656ed87c23f3c20015e2fb95",
  "bank_reconciliation_id": "7017631974056110603955",
  "issuing_bank_name": "PT BANK NEGARA INDONESIA TBK",
  "cvn_code": "M",
  "approval_code": "831000",
  "created": "2023-12-05T07:59:58.453Z",
  "id": "656ed87e23f3c20015e2fb96",
  "card_fingerprint": "61d6ed632aa321002350e0b2"
}

```

Xendit accepts optional parameters such as **`billing_details`**, **`metadata`**,  **`external_id`**, **`currency`**,  and **`descriptor`** as demonstrated in the Axios request above. Please refer to Xendit's documentation to learn more about these parameters:

https://developers.xendit.co/api-reference/#create-charge

> You can also forward an invoice in PDF format as an email attachment to your customer's email address. Details about this process are covered in the [PDF Invoicing](#pdf-invoicing) section.

##### External ID
Xendit requires the inclusion of an `external_id` parameter in each credit/debit card charge. By default, Xendivel simplifies this process by generating a unique external ID using Ordered UUID v4 automatically for you.

https://laravel.com/docs/13.x/strings#method-str-ordered-uuid

Nevertheless, if you choose to create your own `external_id` for some reason, you can achieve this by setting the `auto_id` option in the `xendivel.php` config file to `false`.

Config file: `config/xendivel.php`

```php
 'auto_id' => false,
```

Subsequently, ensure that you manually provide your custom `external_id` for each card charge request.

#### Get Card Charge Transaction

To retrieve the details of the card charge object, you must provide the `id` of the card charge (which should come from your database or your Xendit dashboard) as the first parameter, and the string `card` as the second parameter.

`GET` Request:

```php
use GlennRaya\Xendivel\Xendivel;

Route::get('/payment', function () {
    // card charge id example: 659518586a863f003659b718
    $response = Xendivel::getPayment('card-charge-id', 'card')
        ->getResponse();

return $response;
});
```

This endpoint will return a JSON response that shows important details like the `status` of the card charge, `charge_type`, `card_type`, `card_brand`, etc.

```json
{
  "created": "2020-01-08T04:49:08.815Z",
  "status": "CAPTURED",
  "business_id": "5848fdf860053555135587e7",
  "authorized_amount": 10000,
  "external_id": "test-pre-auth",
  "merchant_id": "xendit",
  "merchant_reference_code": "598942aabb91a4ec309e9a35",
  "card_type": "CREDIT",
  "masked_card_number": "400000XXXXXX0002",
  "charge_type": "SINGLE_USE_TOKEN",
  "card_brand": "VISA",
  "bank_reconciliation_id": "5132390610356134503009",
  "capture_amount": 9900,
  "descriptor": "My new store",
  "id": "659518586a863f003659b718"
}
```

#### Authorize Card / Hold Funds

If your checkout needs to place a card hold first and only capture it later after an admin or CRM review, use `Xendivel::authorizeCard()` instead of `payWithCard()`.

```php
use GlennRaya\Xendivel\Xendivel;
use Illuminate\Http\Request;

Route::post('/authorize-card', function (Request $request) {
    $payment = Xendivel::authorizeCard($request)
        ->getResponse();

return $payment;
});
```

The request payload is the same as `payWithCard()`. The difference is that Xendivel sends the card charge as a manual capture authorization, so Xendit returns an `AUTHORIZED` status instead of immediately charging the customer.

> [!IMPORTANT]
> Card authorizations expire after 7 days on Xendit. Capture or reverse the authorization before it expires.

#### Capture Authorized Card Charge

To capture a previously authorized card charge, first load the card payment using `getPayment($chargeId, 'card')`, then call `captureCardCharge($amount)`.

```php
use GlennRaya\Xendivel\Xendivel;
use Illuminate\Http\Request;

Route::post('/capture-card-charge', function (Request $request) {
    $payment = Xendivel::getPayment($request->charge_id, 'card')
        ->captureCardCharge((int) $request->amount)
        ->getResponse();

return $payment;
});
```

You may capture the full amount or a smaller amount, but the capture amount must not exceed the amount that was originally authorized by Xendit.

#### Void Card Authorization

If you need to release the hold instead of charging the card, call `voidCardAuthorization()` on the loaded card payment.

```php
use GlennRaya\Xendivel\Xendivel;
use Illuminate\Http\Request;

Route::post('/void-card-authorization', function (Request $request) {
    $payment = Xendivel::getPayment($request->charge_id, 'card')
        ->voidCardAuthorization($request->external_id)
        ->getResponse();

return $payment;
});
```

When `auto_id` is enabled, Xendivel automatically generates the reversal `external_id` for you. If `auto_id` is disabled, make sure you provide your own unique `external_id` when voiding the authorization.

#### Test The Full Hold Flow In The Checkout Demo

Xendivel's Blade, React, and React + TypeScript checkout examples now include a card payment mode switch:

- `Charge now` keeps the existing immediate charge flow.
- `Authorize hold` creates the authorization first, then shows demo controls for capture and auth reversal.

After a successful authorization response, the demo checkout will display the authorized charge ID, authorized amount, external ID, and buttons to capture or void the authorization so you can test the full hold-authorize-charge lifecycle end to end.

#### Multi-Use Card Token

It's a common practice in e-commerce platforms to offer customers the convenience of saving their credit/debit card details for future use, eliminating the need for repetitive data entry during subsequent payments.

This functionality is achieved through the card tokenization process. If you've examined the [checkout templates](#checkout-templates) included with Xendivel, you'll find that this process has already been implemented for you.

Example JSON response for multi-use card token:

```json
{
  "status": "CAPTURED",
  "authorized_amount": 5198,
  "capture_amount": 5198,
  "currency": "PHP",
  "metadata": {},
  "credit_card_token_id": "65715e52689dc6001715bc57",
  "business_id": "6551f678273a62fd8d86e25a",
  "merchant_id": "104019905",
  "merchant_reference_code": "65715e530e502a00161aa2d9",
  "external_id": "f4270ddb-650d-4973-8786-1f5b4c048c76",
  "eci": "02",
  "charge_type": "MULTIPLE_USE_TOKEN",
  "masked_card_number": "520000XXXXXX1005",
  "card_brand": "MASTERCARD",
  "card_type": "CREDIT",
  "ucaf": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",
  "descriptor": "XDT*JSON FAKERY",
  "authorization_id": "65715e5d689dc6001715bc5b",
  "bank_reconciliation_id": "7019285426096226603954",
  "issuing_bank_name": "PT BANK NEGARA INDONESIA TBK",
  "cvn_code": "M",
  "approval_code": "831000",
  "created": "2023-12-07T05:55:43.603Z",
  "id": "65715e5f689dc6001715bc60",
  "card_fingerprint": "61d6ed632aa321002350e0b2"
}

```
>[!IMPORTANT ]
>When `charge_type` is `MULTIPLE_USE_TOKEN`, you should make sure that you save the `credit_card_token_id` to your database. You will use this token to charge the card again in the future without re-entering the card details again using the same endpoint use the initially charge the card.

### eWallet Payments
Xendivel is compatible with all eWallet payment channels supported by Xendit. For further details, refer to the documentation at https://docs.xendit.co/ewallet, and explore Xendit's API reference at https://developers.xendit.co/api-reference/#create-ewallet-charge.

#### Charge eWallet

Example Axios post request:

```javascript
axios
    .post('/pay-via-ewallet', {
        // You can test different failure scenarios by using the 'magic amount' from Xendit.
        amount: parseInt(amount),
        currency: 'PHP',
        checkout_method: 'ONE_TIME_PAYMENT',
        channel_code: 'PH_GCASH',
        channel_properties: {
            success_redirect_url:
                'https://your-domain.test/xendivel/payment/success',
            failure_redirect_url:
                'https://your-domain.test/xendivel/payment/failed',
        },
    })
    .then(response => {
        // Upon successful request, you will be redirected to the eWallet's checkout url.
        console.log(response.data)
        window.location.href =
            response.data.actions.desktop_web_checkout_url
    })
    /// ...
```

Then, on your Laravel route or controller:

`POST` Request:

```php
use GlennRaya\Xendivel\Xendivel;

Route::post('/pay-via-ewallet', function (Request $request) {
    $response = Xendivel::payWithEwallet($request)
        ->getResponse();

return $response;
});
```

In the example Axios request above you will be redirected to the eWallet payment provider's checkout page to complete the payment authorization there. If you are on development mode, you will see something like this:

![eWallet Payment Authorization Page](https://raw.githubusercontent.com/glennraya/xendivel/main/docs/image_assets/ewallet-authorization.png)

The resulting JSON response would look like this:

```json
{
    "created": "2023-12-09T07:51:17.926Z",
    "business_id": "6551f678273a62fd8d86e25a",
    "event": "ewallet.capture",
    "data": {
        "id": "ewc_5b2ad2c6-11a3-410a-b5ab-b41d16e39879",
        "basket": null,
        "status": "SUCCEEDED",
        "actions": {
            "qr_checkout_string": null,
            "mobile_web_checkout_url": "https://ewallet-mock-connector.xendit.co/v1/ewallet_connector/checkouts?token=clq1oqg032dn7a8hko1g",
            "desktop_web_checkout_url": "https://ewallet-mock-connector.xendit.co/v1/ewallet_connector/checkouts?token=clq1oqg032dn7a8hko1g",
            "mobile_deeplink_checkout_url": null
        },
        "created": "2023-12-09T07:51:06.63582Z",
        "updated": "2023-12-09T07:51:17.780894Z",
        "currency": "PHP",
        "customer": null,
        "metadata": null,
        "voided_at": null,
        "capture_now": true,
        "customer_id": null,
        "void_status": null,
        "callback_url": "https://pktuw9nrxn.sharedwithexpose.com/xendit/webhook",
        "channel_code": "PH_GCASH",
        "failure_code": null,
        "reference_id": "90c0c5f5-c6f0-4f2e-bf6c-f23763911f8a",
        "charge_amount": 1000,
        "capture_amount": 1000,
        "checkout_method": "ONE_TIME_PAYMENT",
        "refunded_amount": null,
        "payment_method_id": null,
        "channel_properties": {
            "failure_redirect_url": "https://package.test/xendivel/payment/failed",
            "success_redirect_url": "https://package.test/xendivel/payment/success"
        },
        "is_redirect_required": true,
        "payer_charged_amount": null,
        "shipping_information": null,
        "payer_charged_currency": null
    },
    "api_version": null
}

```

Upon the successful completion of the payment, you will be redirected to the designated success or failure page URL as specified in your axios request parameters (`success_redirect_url` or `failure_redirect_url`). If you do not provide those URLs, Xendivel will use its built-in return pages at `/xendivel/payment/success` and `/xendivel/payment/failed`.

You may also set default return URLs in your `.env` file:

```ini
XENDIVEL_SUCCESS_REDIRECT_URL=https://your-domain.test/payment/success
XENDIVEL_FAILURE_REDIRECT_URL=https://your-domain.test/payment/failed
```

These return pages are only for the customer's browser after payment authorization. Your application should still treat Xendit's webhook event, or an explicit payment status lookup, as the source of truth for the final payment status.

#### eWallet Charge Reference ID

Like the card charge, Xendit requires the inclusion of `reference_id` on the eWallet charge payload. Xendivel also handles this for you automatically by including Ordered UUID V4 on each payload upon request.

If you wish to add your own implementation for `reference_id`, like in the card payment, set the `auto_id` to `false` from your config file:

Config file: `config/xendivel.php`

```php
 'auto_id' => false,
```

And make sure you provide your own `reference_id` for every eWallet charge request:

```javascript
axios
    .post('/pay-via-ewallet', {
        // You can test different failure scenarios by using the 'magic amount' from Xendit.
        reference_id: 'your-own-reference-id',
        amount: parseInt(amount),
        currency: 'PHP',
        // Other params...
    })
    .then(response => {
        // Upon successful request, you will be redirected to the eWallet's checkout url.
        console.log(response.data)
        window.location.href =
            response.data.actions.desktop_web_checkout_url
    })
    /// ...
```

#### Responding to eWallet Charge Webhook Event

Before your app can receive webhook callbacks from Xendit. Please make sure that you properly setup a webhook endpoint from your Xendit's dashboard under **eWallet Payment Status**:

https://dashboard.xendit.co/settings/developers#webhooks

This is required for both development and production. For this purpose you can use tools like [Ngrok](https://ngrok.com) or [Expose](https://expose.dev) so your local project (`localhost`) can receive webhook callbacks from Xendit.

By default, Xendivel will listen to `xendit/webhook` URL for callbacks as defined in Xendivel's config file whenever you make an eWallet charge, refund, or void transactions. You have the option to change the default webhook URL if you prefer:

`config/xendivel.php`

```php
'webhook_url' => '/xendit/webhook', // You can change this to whatever you like.
```

Then, after you published Xendivel's webhook event listeners from [here](#publish-config-and-assets),  you should register the events and listener to your event service provider located in `app\Providers\EventServiceProvider.php`:

```php
use App\Events\eWalletEvents;
use App\Listeners\eWalletWebhookListener;

protected $listen = [
    // ...

eWalletEvents::class => [
        eWalletWebhookListener::class,
    ],
];
```

After this, you can now respond to the callback event from Xendit after a successful eWallet charge from the webhook listener located in `app/Listener/eWalletWebhookListener.php`:

```php
public function handle(eWalletEvents $event)
{
    // You can inspect the returned data from the webhoook in your logs file
    // storage/logs/laravel.log
    logger('Webhook data received: ', $event->webhook_data);

// if($event->webhook_data['data']['status'] === 'SUCCEEDED') {
    //     $invoice_data = [
    //         // Invoice data...
    //     ];

//     $email_invoice = new Xendivel();
    //     $email_invoice->emailInvoiceTo('glenn@example.com', $invoice_data)
    //         ->send();
    // }
}
```

You can now perform other tasks based on the payload of the callback such as interacting with your database, call other APIs, send an email, etc.

> [!IMPORTANT]
> Xendit will send a webhook event everytime you perform an eWallet charge, refund, or void transaction to the same webhook endpoint.

#### Exclude Xendit's Webhook Callback from CSRF Protection

You should also make sure you allow Xendit's callback from your CSRF protection, so any webhook callback Xendit sends to your application will be accepted by your routes. You can exclude the routes by adding their URIs to the `$except` property of the `VerifyCsrfToken` middleware:

```php
<?php

namespace App\Http\Middleware;

use Illuminate\Foundation\Http\Middleware\VerifyCsrfToken as Middleware;

class VerifyCsrfToken extends Middleware
{
  /**
    * The URIs that should be excluded from CSRF verification.
    *
    * @var  array
    */

protected  $except  = [
        '/xendit/*',
        'https://your-domain.com/xendit/*',
    ];
}
```

#### Get eWallet Charge

Fetch the details of an eWallet charge. The `Xendivel::getPayment` function accepts the **eWallet charge ID** as the first parameter, and the type of charge which is **ewallet** as the second parameter.

`GET` Request:

```php
use GlennRaya\Xendivel\Xendivel;

Route::get('/get-ewallet-charge', function (Request $request) {
	$response = Xendivel::getPayment('ewc_65cbfb33-a1ea-4c32-a6f3-6f8202de9d6e', 'ewallet')
	    ->getResponse();

return $response;
});
```

The JSON response would look similar to this:

```json
{
  "id": "ewc_bb8c3po-c3po-r2d2-c3po-r2d2c3por2d2",
  "business_id": "5f218745736e619164dc8608",
  "reference_id": "test-reference-id",
  "status": "PENDING",
  "currency": "IDR",
  "charge_amount": 1000,
  "capture_amount": 1000,
  "refunded_amount": null,
  "checkout_method": "ONE_TIME_PAYMENT",
  "channel_code": "ID_SHOPEEPAY",
  "channel_properties": {
    "success_redirect_url": "https://dashboard.xendit.co/register/1"
  },
  "actions": {
    "desktop_web_checkout_url": null,
    "mobile_web_checkout_url": null,
    "mobile_deeplink_checkout_url": "https://deeplinkcheckout.this/",
    "qr_checkout_string": "ID123XenditQRTest321DI"
  },
  "is_redirect_required": true,
  "callback_url": "https://calling-back.com/xendit/shopeepay",
  "created": "2017-07-21T17:32:28Z",
  "updated": "2017-07-21T17:32:28Z",
  "void_status": null,
  "voided_at": null,
  "capture_now": true,
  "customer_id": null,
  "payment_method_id": null,
  "failure_code": null,
  "basket": null,
  "metadata": {
    "branch_code": "tree_branch"
  }
}
```

#### Void eWallet Charge

`POST` Request:

```php
use GlennRaya\Xendivel\Xendivel;

Route::post('/ewallet/void', function(Request $request) {
    // Example eWallet charge ID: ewc_e743d499-baa1-49f1-96c0-cc810890739b
    $response = Xendivel::void($request->ewallet_charge_id)
        ->getResponse();

return $response;
});
```

With this Void API, you can nullify a successfully processed eWallet payment, ensuring that the entire original amount is refunded to the end user.

Voiding an eWallet charge is defined as the cancellation of eWallet payments created within the same day and before the **cutoff time of 23:50:00 (UTC+07:00 for Indonesia eWallets/ UTC+08:00 for Philippines eWallets)**.

-   Void API will only work for charges created via the `/ewallets/charges` API with `SUCCEEDED` status
-   Void API will return `PENDING` `void_status` in API response upon execution. A follow-up webhook will be sent to your system's URL when void has been processed successfully.

**To cancel eWallet payments after the aforementioned cutoff time, the [Refund API](#refunds) should be used.**

### QR Code Payments

Xendivel supports Xendit's QR Code payments, where you generate a QR code that the customer scans with their banking or eWallet app to pay. This uses Xendit's [Payments API](https://docs.xendit.co/payments-and-disbursements/create-payment-request) (`/payment_requests`), which is active by default on your account — no separate channel activation is required.

QR codes come in two types:

- **DYNAMIC** - A fixed amount is encoded into the QR code (Xendit `ONE_TIME_USE`). Best for one-off checkout payments. The `amount` is **required**.
- **STATIC** - A reusable QR code where the customer enters the amount themselves (Xendit `MULTIPLE_USE`). The `amount` is **omitted**.

The QR channel and currency default to `QRPH` and `PHP` (configurable via `qr_channel_code` and `qr_currency` in `config/xendivel.php`, or per-request). Use the channel that matches your account, e.g. `QRIS`/`IDR` for Indonesia or `QRPROMPTPAY`/`THB` for Thailand.

QR code payments are **asynchronous**. You create the QR code, display the returned `qr_string` to the customer as a scannable image, and Xendit notifies your application of the payment result through a [webhook callback](#responding-to-qr-payment-webhook-event).

#### Generate QR Code

Example Axios post request:

```javascript
axios
    .post('/create-qr-code', {
        amount: parseInt(amount),
        type: 'DYNAMIC',
        currency: 'PHP',
    })
    .then(response => {
        // The qr_string is nested under payment_method.qr_code.channel_properties.
        const qrString =
            response.data.payment_method.qr_code.channel_properties.qr_string

// response.data.id (pr-...) is what you poll for the payment status.
        // response.data.payment_method.reference_id is used to simulate a payment.
        console.log(qrString)
    })
    /// ...
```

Then, on your Laravel route or controller:

`POST` Request:

```php
use GlennRaya\Xendivel\Xendivel;

Route::post('/create-qr-code', function (Request $request) {
    $response = Xendivel::createQrCode($request)
        ->getResponse();

return $response;
});
```

The resulting JSON response would look like this:

```json
{
    "id": "pr-47667629-c68f-40d0-ad21-3e202d033b08",
    "reference_id": "9b1f0c8a-1234-4d2e-9f3a-7c6b5a4d3e2f",
    "amount": 1500,
    "currency": "PHP",
    "status": "PENDING",
    "payment_method": {
        "id": "pm-9c948f06-88e8-4ed8-9767-1cf446adf0dc",
        "type": "QR_CODE",
        "reference_id": "860b1496-a16c-4af3-be01-f74f195668b9",
        "reusability": "ONE_TIME_USE",
        "status": "ACTIVE",
        "qr_code": {
            "amount": 1500,
            "currency": "PHP",
            "channel_code": "QRPH",
            "channel_properties": {
                "qr_string": "00020101021226...6304ABCD",
                "expires_at": "2024-06-06T08:06:17.926Z"
            }
        }
    },
    "created": "2024-06-06T07:51:17.926Z",
    "updated": "2024-06-06T07:51:17.926Z"
}
```

Render the `qr_string` into a scannable image on your frontend using any QR rendering library (for example [`qrcodejs`](https://github.com/davidshimjs/qrcodejs)). The bundled [checkout templates](#checkout-templates) include a working QR Code tab that does exactly this.

> [!NOTE]
> By default, Xendivel generates the `reference_id` for you as an Ordered UUID v4. To supply your own, set `auto_id` to `false` in `config/xendivel.php` and include an `external_id` in the request, just like card and eWallet charges — Xendivel maps it to Xendit's `reference_id`.

> [!NOTE]
> In Xendit's test/development mode the returned `qr_string` is a placeholder (`some-random-qr-string`); a real, scannable QR string is returned in live mode.

#### Get QR Code Status

Fetch a QR payment request and its current status by its payment request `id` (`pr-...`). The top-level `status` flips from `PENDING` to `SUCCEEDED` once the customer has paid.

`GET` Request:

```php
use GlennRaya\Xendivel\Xendivel;

Route::get('/qr-code/{id}', function (string $id) {
    $response = Xendivel::getQrCode($id)
        ->getResponse();

return $response;
});
```

> [!IMPORTANT]
> Poll on the payment request `id` (`pr-...`) returned by `createQrCode`, and treat the top-level `status` of `SUCCEEDED` (and the [QR payment webhook](#responding-to-qr-payment-webhook-event)) as the source of truth for a settled payment.

#### Simulate QR Payment

While in Xendit's test/development mode, you can simulate a customer paying a QR code so you can test the full flow without a real scan. You can pass either the QR reference returned at `payment_method.reference_id` or the payment request `id` (`pr-...`) — Xendivel resolves a `pr-...` id to its QR reference for you:

`POST` Request:

```php
use GlennRaya\Xendivel\Xendivel;

Route::post('/qr-code/{id}/simulate', function (Request $request, string $id) {
    $response = Xendivel::simulateQrPayment($id, (int) $request->amount)
        ->getResponse();

return $response;
});
```

This triggers Xendit to mark the QR code as paid (the payment request `status` becomes `SUCCEEDED`) and to send the payment webhook to your configured URL.

#### Responding to QR Payment Webhook Event

QR codes settle through Xendit's Payments API, so make sure you set up a webhook endpoint from your Xendit dashboard under the **Payment** (`payment.succeeded`) callback type:

https://dashboard.xendit.co/settings/developers#webhooks

This is required for both development and production. For local development you can use tools like [Ngrok](https://ngrok.com) or [Expose](https://expose.dev) so your local project (`localhost`) can receive webhook callbacks from Xendit.

By default, Xendivel listens for QR payment callbacks on the `xendit/qr/webhook` URL. You can change this in Xendivel's config file:

`config/xendivel.php`

```php
'qr_webhook_url' => '/xendit/qr/webhook', // You can change this to whatever you like.
```

Then, after you published Xendivel's webhook event listeners from [here](#publish-config-and-assets), register the QR event and listener in your event service provider located in `app\Providers\EventServiceProvider.php`:

```php
use App\Events\QrPaymentEvents;
use App\Listeners\QrPaymentWebhookListener;

protected $listen = [
    // ...

QrPaymentEvents::class => [
        QrPaymentWebhookListener::class,
    ],
];
```

After this, you can respond to the callback event from Xendit in the webhook listener located in `app/Listeners/QrPaymentWebhookListener.php`:

```php
public function handle(QrPaymentEvents $event)
{
    // You can inspect the returned data from the webhook in your logs file
    // storage/logs/laravel.log
    logger('QR payment webhook data received: ', $event->webhook_data);

// Xendit's Payments API nests the payment under a "data" key and reports
    // "SUCCEEDED" once the QR payment is settled.
    $status = $event->webhook_data['data']['status'] ?? null;

if ($status === 'SUCCEEDED') {
        // Mark the order as paid, send a receipt, fulfill the purchase, etc.
    }
}
```

> [!IMPORTANT]
> Remember to also exclude the QR webhook URL from CSRF protection. If you kept the default `/xendit/qr/webhook` path, the `/xendit/*` entry shown in [Exclude Xendit's Webhook Callback from CSRF Protection](#exclude-xendits-webhook-callback-from-csrf-protection) already covers it.

### PDF Invoicing

![Invoice Template](https://raw.githubusercontent.com/glennraya/xendivel/main/docs/image_assets/invoice.png)

Xendivel has the ability to generate professional and customizable PDF Invoices. You can preview the default invoice template by going to the route `/xendivel/invoice/template`.

```
https://your-domain.test/xendivel/invoice/template
```

> [!Note]
> Remember to replace the `your-domain.test` with your domain.

PDF invoices are generated using standard **Laravel Blade** templates and Xendivel will convert this to PDF invoice for you. Since invoices are just regular Blade templates, you can pass data to the template just like you would on a [Laravel Blade](https://laravel.com/docs/13.x/blade#displaying-data) file. The default invoice template uses plain, print-friendly CSS for reliable rendering with Browsershot and Chrome.

#### Generate PDF Invoice

```php
use GlennRaya\Xendivel\Invoice;

Route::get('/xendivel/invoice/generate', function () {
    $invoice_data = [
        'invoice_number' => 1000023,
        'card_type' => 'VISA',
        'masked_card_number' => '400000XXXXXX0002',
        'merchant' => [
            'name' => 'Xendivel LLC',
            'address' => '152 Maple Avenue Greenfield, New Liberty, Arcadia USA 54331',
            'phone' => '+63 971-444-1234',
            'email' => 'xendivel@example.com',
        ],
        'customer' => [
            'name' => 'Victoria Marini',
            'address' => 'Alex Johnson, 4457 Pine Circle, Rivertown, Westhaven, 98765, Silverland',
            'email' => 'victoria@example.com',
            'phone' => '+63 909-098-654',
        ],
        'items' => [
            ['item' => 'iPhone 15 Pro Max', 'price' => 1099, 'quantity' => 5],
            ['item' => 'MacBook Pro 16" M3 Max', 'price' => 2499, 'quantity' => 3],
            ['item' => 'Apple Pro Display XDR', 'price' => 5999, 'quantity' => 2],
            ['item' => 'Pro Stand', 'price' => 999, 'quantity' => 2],
        ],
        'tax_rate' => .12,
        'tax_id' => '123-456-789',
        'footer_note' => 'Thank you for your recent purchase with us! We are thrilled to have the opportunity to serve you and hope that your new purchase brings you great satisfaction.',
    ];

return Invoice::make($invoice_data)
        ->save();
});
```

As you can see, the `Invoice::make` function accepts an associative array that contains the information you want to appear on the invoice, typically coming from your database. By default, it will be stored in the `/storage/app/invoices` directory of your Laravel app. You can change the location where you want to save your invoices by modifying the `invoice_storage_path` option in your Xendivel config file.

```
'invoice_storage_path' => storage_path('/app/invoices/')
```

> [!IMPORTANT]
> You should ensure the proper permission is set to the directory of your choice so Xendivel can store the invoice there.

#### Download PDF Invoice

You can immediately download the invoice to your customer's local machine instead of storing it your Laravel app's storage directory by calling the `download()` function:

```php
use GlennRaya\Xendivel\Invoice;

Route::get('/xendivel/invoice/download', function () {
    $invoice_data = [
        // Invoice data...
    ];

return Invoice::make($invoice_data)
	    ->download();
});
```

#### Invoice Paper Size

By default, Xendivel will generate PDF invoices in standard **A4** paper size. Xendivel passes the `paperSize()` value to Browsershot and also writes the matching dimensions to the PDF template's `@page size` rule.

Xendivel supports these invoice paper sizes:

```
Letter: 8.5in  x  11in
Legal: 8.5in  x  14in
A4: 8.27in  x  11.7in
```

#### Change Invoice Paper Size

You can change the invoice size by invoking the `paperSize()` function when generating or downloading an invoice and specify the name of the paper size as the parameter:

```php
use GlennRaya\Xendivel\Invoice;

Route::get('/xendivel/invoice/download', function () {
    $invoice_data = [
        // Invoice data...
    ];

return Invoice::make($invoice_data)
        ->paperSize('A4')
        ->download();
});
```

In this example, we can modify the invoice's paper size by invoking the `paperSize('A4')` function and indicating the desired paper size as its parameter.

If the `paperSize()` value includes an orientation word, `orientation()` still wins. For example, `paperSize('A4 landscape')->orientation('portrait')` generates a portrait A4 invoice.

#### Change Invoice Orientation

Your sentence is already well-constructed, but here's a slightly refined version:

You can also modify the orientation of the invoice; by default, it's in `portrait`. You can change it to `landscape` using the `orientation()` function.

```php
use GlennRaya\Xendivel\Invoice;

Route::get('/xendivel/invoice/download', function () {
    $invoice_data = [
        // Invoice data...
    ];

return Invoice::make($invoice_data)
        ->paperSize('A4')
        ->orientation('landscape')
        ->download();
});
```

#### Invoice Filename

Whenever Xendivel generates, downloads or email an invoice to your customers, Xendivel will assign a unique filename using UUID v4 and appending the `-invoice.pdf` at the end of the filename. Here's an example:

```
c7ff9fa5-b629-4fc9-8e61-bd203c91ca65-invoice.pdf
```

If you want to customize the filenaming convention of Xendivel, you can easily do so by using the `fileName()` function of the `Invoice` class:

```php
use GlennRaya\Xendivel\Invoice;

Route::get('/xendivel/invoice/download', function () {
    $invoice_data = [
        // Invoice data...
    ];

return Invoice::make($invoice_data)
        ->paperSize('A4')
        ->orientation('landscape')
        ->fileName('my-awesome-invoice-filename')
        ->download();
});
```

Now the generated invoice will have a filename that looks like:

```
my-awesome-invoice-filename-invoice.pdf
```

#### Customizing PDF Invoice Template

As previously mentioned, the PDF invoice template is essentially a standard **Laravel Blade** component. It is a conventional HTML/PHP file styled with plain, print-friendly CSS. Browsershot renders with Chrome, so browser-supported CSS and image assets can be used as long as the browser runtime can access them.

Publish the invoice template to your `views` directory:

```bash
php artisan vendor:publish --tag=xendivel-invoice
```

> [!NOTE]
> When you published Xendivel's assets from the **Publish Assets** section, your invoice template is already published in `resources/views/vendor/xendivel/invoice.blade.php`.

This command will publish the `invoice.blade.php` to your `resources/views/vendor/xendivel` directory. Upon inspecting the file, you will notice the `$invoice_data` variable. This variable contains the associative array that you passed to the view from previous examples.

Example section from the invoice template:

```php
{{-- Other data... --}}
<table class="invoice-items">
    <thead>
        <tr>
            <th class="invoice-col-description">Description</th>
            <th class="invoice-col-qty">Qty</th>
            <th class="invoice-col-price">Unit Price</th>
            <th class="invoice-col-subtotal">Subtotal</th>
        </tr>
    </thead>
    <tbody>
        @php
            $total_price = 0;
        @endphp
        @foreach ($invoice_data['items'] as $item)
            @php
                $total_price += $item['price'] * $item['quantity'];
            @endphp
            <tr>
                <td class="invoice-col-description">{{ $item['item']}}</td>
                <td class="invoice-col-qty">{{ $item['quantity'] }}</td>
                <td class="invoice-col-price">${{ number_format($item['price'], 2) }}</td>
                <td class="invoice-col-subtotal">
                    ${{ number_format($item['price'] * $item['quantity'], 2) }}
                </td>
            </tr>
        @endforeach
    </tbody>
</table>
{{-- Other data... --}}
```

Since this is just a regular HTML/Blade template, there's no limit to the customizations you can make. You can define your own plain CSS styles, modify the data being rendered, and add images to the template. Xendivel will automatically convert this template into a PDF file upon generation, downloading, or when sent via email attachment.

#### Sending PDF Invoice As Email Attachment

It's a common practice that, following a purchase on an e-commerce website or app, customers receive an email detailing their transaction, accompanied by an attached invoice. Xendivel makes it easy to send an invoice to your customers after completing the purchase.

#### Sending PDF Invoice For Card Payments

```php
use GlennRaya\Xendivel\Xendivel;

Route::post('/checkout-email-invoice', function (Request $request) {
    $invoice_data = [
        'invoice_number' => 1000023,
        'card_type' => 'VISA',
        'masked_card_number' => '400000XXXXXX0002',
        'merchant' => [
            'name' => 'Stark Industries',
            'address' => '152 Maple Avenue Greenfield, New Liberty, Arcadia USA 54331',
            'phone' => '+63 971-444-1234',
            'email' => 'xendivel@example.com',
        ],
        'customer' => [
            'name' => 'Mr. Glenn Raya',
            'address' => 'Alex Johnson, 4457 Pine Circle, Rivertown, Westhaven, 98765, Silverland',
            'email' => 'victoria@example.com',
            'phone' => '+63 909-098-654',
        ],
        'items' => [
            ['item' => 'MacBook Pro 16" M3 Max', 'price' => $request->amount, 'quantity' => 1],
        ],
        'tax_rate' => .12,
        'tax_id' => '123-456-789',
        'footer_note' => 'Thank you for your recent purchase with us! We are thrilled to have the opportunity to serve you and hope that your new purchase brings you great satisfaction.',
    ];

$payment = Xendivel::payWithCard($request)
        ->emailInvoiceTo('glenn@example.com', $invoice_data)
        ->send()
        ->getResponse();

return $payment;
});
```

In this example, the `emailInvoiceTo()` function accepts the email address where you want to send the invoice as the first parameter, and the `$invoice_data` that holds the details about the invoice as the second parameter. The `send()` function will instruct Xendivel to send the email.

##### Email Subject and Message

![Email Invoice](https://raw.githubusercontent.com/glennraya/xendivel/main/docs/image_assets/email-invoice.png)

The above image is an example of the email with the PDF invoice attached that Xendivel will send by default. You can customize the subject and the email message itself:

##### Customize Subject

To change the default email's subject, you can use the `subject()` function:

```php
use GlennRaya\Xendivel\Xendivel;

Route::post('/checkout-email-invoice', function (Request $request) {
    $invoice_data = [
        // Invoice data...
    ];

$payment = Xendivel::payWithCard($request)
        ->emailInvoiceTo('glenn@example.com', $invoice_data)
        ->subject('Thank you for your purchase!')
        ->send()
        ->getResponse();
    });
```

##### Customize Message
To change the default email's message, you can use the `message()` function:

```php
use GlennRaya\Xendivel\Xendivel;

Route::post('/checkout-email-invoice', function (Request $request) {
    $invoice_data = [
        // Invoice data...
    ];

$payment = Xendivel::payWithCard($request)
        ->emailInvoiceTo('glenn@example.com', $invoice_data)
        ->subject('Thank you for your purchase!')
        ->message('We appreciate your business and look forward to serving you again. We have attached your invoice.')
        ->send()
        ->getResponse();
});
```

#### Sending PDF Invoice For eWallet Payments

When employing eWallet payments, the process of sending email invoices differs slightly. As your application must respond to a webhook callback for eWallet payments, it becomes necessary to incorporate the email invoice logic directly within the webhook listener.

Navigate to the `App/Listeners/eWalletWebhookListener.php` file and locate the `handle()` method. Within this method, implement the email invoice logic to ensure seamless integration with eWallet payments.

```php
use GlennRaya\Xendivel\Xendivel;

public function handle(eWalletEvents $event)
{
    // You can inspect the returned data from the webhoook in your logs file
    // storage/logs/laravel.log
    logger('Webhook data received: ', $event->webhook_data);

// $invoice_data = [
        // Invoice data...
    // ];

if($event->webhook_data['data']['status'] === 'SUCCEEDED') {
        $email_invoice = new Xendivel();
        $email_invoice->emailInvoiceTo('glenn@example.com', $invoice_data)
            ->send();
    }
}
```

Remember, when initiating an eWallet payment charge request, you have the option to include a `metadata` property.

Example:

```javascript
axios.post('/charge-ewallet', {
    amount: 1200,
    currency: 'PHP',
    checkout_method: 'ONE_TIME_PAYMENT',
    channel_code: 'PH_GCASH',
    channel_properties: {
        success_redirect_url: 'https://your-domain.test/xendivel/payment/success',
        failure_redirect_url: 'https://your-domain.test/xendivel/payment/failed',
    },

metadata: {
        customer_id: 17,
        name: 'Glenn Raya',
        email: 'glenn@example.com'
    }
})
```

This allows you to include supplementary information with the payment. Meaning you can include your customer's ID, email address, phone numbers, etc. Enabling you to leverage it later when processing the webhook data.

Xendit API Reference:
https://developers.xendit.co/api-reference/#create-ewallet-charge

### Queue Invoice Email

Xendivel has the ability to queue email jobs for background processing, enhancing the responsiveness of your Laravel app by handling email tasks seamlessly in the background.

All you need to do is simple set the `queue_email` option from your `xendivel.php` config file to `true`.

```php
'queue_email' => true,
```

Of course, you need to make sure that you properly setup your Laravel queue driver and there's a queue worker running:

https://laravel.com/docs/13.x/queues#main-content

#### Run Queue Worker

```ini
php artisan queue:work
```

> [!IMPORTANT]
> Always make sure you run a **queue worker** when you configure Xendivel to send the email jobs to queue, otherwise no email will be sent.

> [!IMPORTANT]
> Also remember, whenever you change the email templates that comes with Xendivel, Please be sure that you restart your queue workers so it could use your newly updated email templates.

### Refunds

Xendivel supports the refund API for both cards and eWallet payments and also has the ability to notify your customers about successful refunds.

#### Refund for Card Payments

The make refunds for payments via credit or debit cards, first you must get the charge transaction using the `getPayment()` method. The first parameter is the `id` of the charge, and the second parameter should be `card`.

Then, the `refund()` method's parameter value is the amount to be refunded. And of course, the `getResponse()` method is used to return the response from the API.

`POST` request:

```php
use GlennRaya\Xendivel\Xendivel;
use Illuminate\Http\Request;

Route::post('/refund', function (Request $request) {
	// Example charge id: 6593a0fb82742f0056f779fd

$response = Xendivel::getPayment($request->charge_id, 'card')
        ->refund(3500)
        ->getResponse();

return $response;
});
```

The response from this call should looks like this:

```json
{
    "credit_card_charge_id": "656eb63c23f3c20015e2f4eb",
    "amount": 5198,
    "external_id": "375b897a-8b75-4b94-a802-29a60febf589",
    "status": "REQUESTED",
    "merchant_reference_code": "656eb63123f3c20015e2f4e6",
    "uuid": "70941a1a-a2d4-4547-bb30-e3d4c163cf04",
    "currency": "PHP",
    "client_type": "API_GATEWAY",
    "created": "2023-12-05T05:50:38.701Z",
    "updated": "2023-12-05T05:50:38.701Z",
    "id": "656eba2eedab5300169c2b19",
    "fee_refund_amount": 0,
    "user_id": "6551f678273a62fd8d86e25a"
}
```

You can always check your Xendit's dashboard for all transactions made: https://dashboard.xendit.co/home

#### Refund for eWallet Payments

Requesting refunds for eWallet payments is almost the same as for the card refunds API. The only difference is the eWallet charge ID of course and the type of the refund which is `ewallet`

`POST` request

```php
use GlennRaya\Xendivel\Xendivel;
use Illuminate\Http\Request;

Route::post('/refund', function (Request $request) {
	// Example charge id: ewc_b5baef87-d7b5-4d5c-803b-b31e80529147

$response = Xendivel::getPayment($request->charge_id, 'ewallet')
+       ->refund(3500)
+       ->getResponse();

return $response;
});
```

#### Get Refund Details

Whether the refunds are successful or not, the details of the transactions are still recorded on your Xendit's admin account.

##### Get eWallet Refund Details

Get the status and details of a specific eWallet refund by its charge and refund ID:

`GET` request:

```php
use GlennRaya\Xendivel\Xendivel;

Route::get('/get-ewallet-refund', function () {
    $response = Xendivel::getEwalletRefund('ewc_65cbfb33-a1ea-4c32-a6f3-6f5202dx9d6e', 'ewr_a96f9a27-8838-43bf-88f0-c0ade0aeeee3')
        ->getResponse();

return $response;
});
```

Typically, the charge and refund ID should be stored to your database. This can be done when you received the webhook callback from Xendit.

#### List All eWallet Refunds

Get the details of all eWallet refunds associated with a single eWallet charge transaction by the charge ID by using the `getListOfEwalletRefunds()` method and passing the eWallet `charge_id`:

`GET` request:

```php
use GlennRaya\Xendivel\Xendivel;

Route::get('/ewallet-refund-list', function () {
    $response = Xendivel::getListOfEwalletRefunds('ewc_65cbfb33-a1ea-4c32-a6f3-9f8201de9d6a')
        ->getResponse();

return $response;
});
```

This will output a JSON response with a collection of refund transactions and status of each refund:

```json
{
    "data": [
        {
            "id": "ewr_a96f9a27-8838-43bf-88f0-c0ade0aeeee3",
            "charge_id": "ewc_65cbfb33-a1ea-4c32-a6f3-6f8202de9d6e",
            "status": "SUCCEEDED",
            "currency": "PHP",
            "channel_code": "PH_GCASH",
            "capture_amount": 1000,
            "refund_amount": 1000,
            "failure_code": null,
            "reason": "OTHERS",
            "refund_amount_to_payer": null,
            "payer_captured_amount": null,
            "payer_captured_currency": null,
            "created": "2023-12-28T07:47:40.24517Z",
            "updated": "2023-12-28T07:47:45.253443Z"
        }
    ]
}
```

#### Email Refund Confirmation

##### Card Refund Email Notification

Xendivel has the capability to automatically send an email to your customers following a refund request. This is achieved by invoking the `refund()` function first, and subsequently triggering the `emailRefundConfirmationTo()` function.

```php
use GlennRaya\Xendivel\Xendivel;

return $response;
});
```

You can also customize the `subject` and `message`:

```php
use GlennRaya\Xendivel\Xendivel;

Route::get('/refund', function () {
    $response = Xendivel::getPayment('6595d0fg82741f0011f778fd', 'card')
        ->refund(3500)
        ->emailRefundConfirmationTo('glenn@example.com')
        ->subject('Your refund is on the way!')
        ->message('We have successfully processed your refund! It should reflect on your account within 3 banking days.')
        ->send()
        ->getResponse();

return $response;
});
```

### Webhook

#### Listen to Webhook Event

As of the moment only the eWallet **charges**, **refund**, and **void** transactions can receive a webhook callback event from Xendit and are discussed in these sections [Responding to eWallet Charge Webhook Event](#responding-to-ewallet-charge-webhook-event)

> [!Note]
> When a webhook callback failed to reach your server, Xendit will retry sending the webhook again. Please refer to Xendit's docs regarding "Delivery attempts and Retries": https://developers.xendit.co/api-reference/#delivery-attempts-and-retries

#### Webhook Verification

Xendivel handles webhook verification for you automatically everytime Xendit sends a callback to your webhook endpoints. All you need to do is simply include your accounts unique webhook verification token on your `.env` file:

```ini
XENDIT_WEBHOOK_VERIFICATION_TOKEN=your-webhook-verification-token
```

You can obtain your webhook verification token from your dashboard under **Webhooks** section.

https://dashboard.xendit.co/settings/developers#webhooks

If the value of your webhook verification token doesn't match with the one Xendit attached in the request header of the webhook named `x-callback-token`, Xendivel will reject the webhook callback and throw a `403` access denied http exception. This means that the request doesn't originate from Xendit.

If you don't want to verify if the webhook callback is from Xendit, you can disable this feature by setting the `verify_webhook_signature` to `false` in Xendivel's config file:

Config file `config/xendivel.php`

```php
'verify_webhook_signature' => false,
```

>[!IMPORTANT]
>Verifying webhook origin is optional but it is **HIGHLY RECOMMENDED** for security reasons. This is to ensure that the webhook callback event legitimately comes from Xendit and not from third-parties or illegitimate services.

## Deploying to Production

When it's time to deploy your Laravel app, setting the `APP_ENV` from your `.env` file to `production` will disable the following Xendivel routes:

- `/xendivel/invoice/template` — The example invoice template.
- `/xendivel/checkout/blade` — The example checkout page.
- `/xendivel/invoice/generate` — Generate example PDF invoice.
- `/xendivel/invoice/download` — Download example PDF invoice.

These built-in Xendivel routes are meant for development purposes only. You should publish the checkout and invoice template to your views directory to use them on your Laravel app.

### Xendit Production Keys

When deploying to production, you should switch your Xendit's `secret_key`, `public_key`, and `webhook_verification_token` to production keys.

```ini
XENDIT_SECRET_KEY=your-production-secret-key
XENDIT_PUBLIC_KEY=your-production-public-key
XENDIT_WEBHOOK_VERIFICATION_TOKEN=your-production-webhook-verification-token
```

## Tests

Xendivel uses a package-local Pest and Orchestra Testbench setup so the package can be tested directly from its own repository.

Run the package test suite from `packages/glennraya/xendivel`:

```bash
composer validate --strict
composer test
```

To run the focused PDF tests only:

```bash
./vendor/bin/pest --configuration phpunit.xml.dist tests/Unit/InvoicePdfTest.php
```

Xendivel now supports Laravel 13 officially while still supporting Laravel 10 through 12. Laravel 13 installability can be validated with Composer dry-runs in a temporary consumer project using a path repository for `glennraya/xendivel`.

xendivel

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README