Gonon Tripay SDK

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
  • Payment Channels
    • Get Payment Channels
  • Fee Calculator
    • Calculate Fees
  • Instructions
    • Get Payment Instructions
  • Closed Transaction
    • Create Transaction
    • Get Transaction Detail
  • Open Payment
    • Create Open Payment
    • Get Open Payment Detail
  • Webhook / Callback
    • Process Callback
• 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.