README

A modern, fully-typed Tripay Payment Gateway SDK for the Gonon ecosystem. It provides an object-oriented PHP API for interacting with Tripay's Closed and Open Payment APIs seamlessly.

Installation
Usage / Initialization
Methods' Signature and Examples
Exceptions
Contributing

Installation

composer require gonon/tripay

Requirements:

PHP 8.2 or higher
gonon/core ^1.0
gonon/http-symfony ^1.0

Usage

Configure the SDK using the TripayConfig class and initialize TripayClient. By default, the SDK automatically wires up a robust HTTP pipeline with retry strategies and logging.

use Gonon\Tripay\Config\TripayConfig;
use Gonon\Core\Configuration\Environment;
use Gonon\Tripay\Client\TripayClient;

$config = new TripayConfig(
    apiKey: 'your-api-key',
    privateKey: 'your-private-key',
    merchantCode: 'T1234',
    environment: Environment::Sandbox // Use Environment::Production for live
);

$tripay = new TripayClient($config);

Methods' Signature and Examples

Payment Channels

Get Payment Channels

Retrieve a list of all active payment channels available for your merchant account.

/**
 * @return \Gonon\Tripay\DTO\PaymentChannelData[]
 */
$channels = $tripay->paymentChannels()->list();

foreach ($channels as $channel) {
    echo "- {$channel->name} ({$channel->code})\n";
}

Fee Calculator

Calculate Fees

Calculate the estimated merchant and customer fee for a specific channel and amount.

use Gonon\Tripay\DTO\FeeCalculationRequest;

$request = new FeeCalculationRequest(
    amount: 150000, 
    code: 'OVO'
);

/**
 * @return \Gonon\Tripay\DTO\FeeCalculationData
 */
$fee = $tripay->calculator()->calculate($request);
echo "Total Fee: {$fee->totalFee}";

Instructions

Get Payment Instructions

Retrieve step-by-step payment instructions (ATM, Mobile Banking, Internet Banking) for a specific payment channel.

/**
 * @return \Gonon\Tripay\DTO\InstructionData[]
 */
$instructions = $tripay->instructions()->list(
    code: 'BRIVA', 
    payCode: '1234567890', 
    amount: 150000, 
    allowHtml: 0
);

foreach ($instructions as $instruction) {
    echo $instruction->title . "\n";
    foreach ($instruction->steps as $step) {
        echo "- {$step}\n";
    }
}

Closed Transaction

Create Transaction

Create a standard, one-time payment transaction.

use Gonon\Tripay\DTO\CreateTransactionRequest;

$request = new CreateTransactionRequest(
    method: 'BRIVA',
    merchantRef: 'INV-' . time(),
    amount: 150000,
    customerName: 'Budi Santoso',
    customerEmail: 'budi@example.com',
    customerPhone: '081234567890',
    orderItems: [
        [
            'sku' => 'PROD-01',
            'name' => 'Mechanical Keyboard',
            'price' => 150000,
            'quantity' => 1
        ]
    ],
    returnUrl: 'https://your-website.com/success',
    expiredTime: time() + 86400 // 24 hours
);

/**
 * @return \Gonon\Tripay\DTO\TransactionData
 */
$transaction = $tripay->transactions()->create($request);
echo "Checkout URL: " . $transaction->checkoutUrl;

Get Transaction Detail

Retrieve the current status of an existing closed transaction.

/**
 * @return \Gonon\Tripay\DTO\TransactionData
 */
$detail = $tripay->transactions()->detail('DEV-T1234567890');
echo "Status: " . $detail->status; // e.g. PAID, UNPAID, EXPIRED

Open Payment

(Note: The Open Payment API is only available in the Production environment)

Create Open Payment

Create a dynamic QRIS/Virtual Account that can accept arbitrary amounts multiple times.

use Gonon\Tripay\DTO\CreateOpenPaymentRequest;

$request = new CreateOpenPaymentRequest(
    method: 'QRIS2',
    merchantRef: 'DONATION-001',
    customerName: 'Anonymous Donor'
);

/**
 * @return \Gonon\Tripay\DTO\OpenPaymentData
 */
$openPayment = $tripay->openPayments()->create($request);
echo "QR URL: " . $openPayment->qrUrl;

Get Open Payment Detail

Retrieve the current status and historical payments for an open payment.

/**
 * @return \Gonon\Tripay\DTO\OpenPaymentData
 */
$detail = $tripay->openPayments()->detail('uuid-string-here');
echo "Status: " . $detail->status;

Webhook / Callback

Process Callback

Securely parse and verify the HMAC signature of incoming webhooks from Tripay.

// 1. Get raw input and header
$rawPayload = file_get_contents('php://input'); 
$signatureHeader = $_SERVER['HTTP_X_CALLBACK_SIGNATURE'] ?? '';

try {
    // 2. Pass to the SDK processor
    /**
     * @return \Gonon\Tripay\DTO\CallbackData
     */
    $callback = $tripay->webhook()->process($rawPayload, $signatureHeader);

    // 3. Handle the event
    if ($callback->event === 'payment_status' && $callback->status === 'PAID') {
        echo "Invoice {$callback->merchantRef} is Paid!";
    }

    echo json_encode(['success' => true]);
} catch (\Gonon\Tripay\Exceptions\WebhookSignatureException $e) {
    http_response_code(403);
    echo json_encode(['success' => false, 'error' => 'Invalid signature']);
}

Exceptions

The SDK throws specific exceptions depending on the failure type, making it easy to catch and handle errors.

Gonon\Tripay\Exceptions\TripayException
The base interface implemented by all exceptions in the SDK.
Gonon\Tripay\Exceptions\TransactionException
Thrown when a transaction-related API call fails (e.g. invalid amount, validation errors from Tripay).
Gonon\Tripay\Exceptions\WebhookSignatureException
Thrown when the X-Callback-Signature header does not match the computed HMAC SHA-256 payload, indicating a potentially forged request.
Gonon\Tripay\Exceptions\WebhookPayloadException
Thrown when the incoming JSON payload is malformed or missing required keys.

Contributing

We welcome contributions to the Gonon Tripay SDK! Please see CONTRIBUTING.md for details on our coding standards and how to submit pull requests.

gonon/tripay

包简介

README 文档