README

Laravel Tripay

An elegant, idiomatic Laravel integration for the official Gonon Tripay PHP SDK.

Requirements

• PHP 8.2+
• Laravel 11+
• gonon/tripay ^1.0

Installation

composer require gonon/laravel-tripay

Configuration

First, publish the configuration file to your application:

php artisan vendor:publish --tag="tripay-config"

or

php artisan vendor:publish --provider="Gonon\Tripay\Laravel\TripayServiceProvider"

This will create a config/tripay.php file in your application where you can customize the default settings.

Next, set up your .env with the credentials from your Tripay Merchant Dashboard:

TRIPAY_API_KEY=your_api_key
TRIPAY_PRIVATE_KEY=your_private_key
TRIPAY_MERCHANT_CODE=your_merchant_code
TRIPAY_PRODUCTION=false # Set to true for production

Usage (Facade)

The package provides an expressive Tripay facade that hooks directly into the underlying SDK. It handles all authentication, configuration, and signature generation behind the scenes seamlessly.

First, ensure you import the facade and necessary DTOs at the top of your classes:

use Gonon\Tripay\Laravel\Facades\Tripay;
use Gonon\Tripay\DTO\CreateTransactionRequest;

1. Fetching Payment Channels

Retrieve a list of available payment channels you can offer to your customers:

// Get all available payment channels
$channels = Tripay::paymentChannels()->list();

foreach ($channels as $channel) {
    echo $channel->code; // e.g., 'BRIVA', 'OVO'
    echo $channel->name;
    echo $channel->isActive ? 'Active' : 'Inactive';
}

2. Creating a Transaction (Closed Payment)

Create a transaction and automatically generate a checkout URL for the customer. The SDK will automatically generate the HMAC signature using your private key.

$payload = new CreateTransactionRequest(
    method: 'BRIVA',
    merchantRef: 'INV-12345',
    amount: 150000,
    customerName: 'John Doe',
    customerEmail: 'john.doe@example.com',
    customerPhone: '08123456789',
    orderItems: [
        [
            'sku'      => 'PROD-01',
            'name'     => 'Premium Package',
            'price'    => 150000,
            'quantity' => 1,
        ]
    ],
    returnUrl: route('payment.return')
);

try {
    $transaction = Tripay::transactions()->create($payload);
    
    // Redirect customer to the Tripay checkout page
    return redirect($transaction->checkoutUrl);
    
} catch (\Gonon\Tripay\Exceptions\TransactionException $e) {
    return back()->withError($e->getMessage());
}

3. Fetching Transaction Details

Retrieve the real-time status and details of a transaction using your merchant reference.

$transaction = Tripay::transactions()->detail('INV-12345');

echo $transaction->status; // 'PAID', 'UNPAID', 'EXPIRED', 'FAILED'
echo $transaction->amount;
echo $transaction->checkoutUrl;

4. Fee Calculator

Calculate the total fees for a specific payment channel before creating a transaction.

use Gonon\Tripay\DTO\FeeCalculationRequest;

$fees = Tripay::calculator()->calculate(
    new FeeCalculationRequest(amount: 150000, code: 'BRIVA')
);

echo $fees->totalFee;
echo $fees->feeMerchant;
echo $fees->feeCustomer;

5. Webhook Signature Verification

When Tripay sends a webhook notification to your application, you must verify the signature to ensure the payload is authentic.

use Illuminate\Http\Request;

public function handleWebhook(Request $request)
{
    $signature = $request->header('X-Callback-Signature');
    $payload = $request->getContent();

    // The webhook handler automatically uses your configured private key
    $isValid = Tripay::webhook()->verifySignature($signature, $payload);

    if (! $isValid) {
        abort(403, 'Invalid signature');
    }

    $event = json_decode($payload);

    if ($event->status === 'PAID') {
        // Update order status in your database
    }

    return response()->json(['success' => true]);
}

Advanced: Dependency Injection & Container

If you prefer passing the client via Dependency Injection instead of using the static Facade, the TripayClient is automatically bound to the Service Container as a singleton.

use Gonon\Tripay\Client\TripayClient;

class CheckoutController
{
    public function __construct(
        private readonly TripayClient $tripay
    ) {}

    public function process()
    {
        $channels = $this->tripay->paymentChannels()->all();
    }
}

You can also resolve the client manually using the app() helper anywhere in your application:

$tripay = app(\Gonon\Tripay\Client\TripayClient::class);
// or via the bound alias
$tripay = app('tripay');