README

A robust, framework-agnostic PHP SDK for interacting with the Midtrans Payment Gateway. Built on top of gonon/core, providing type safety, robust HTTP communication, and complete independence from any specific web framework (like Laravel or Symfony).

Table of Contents

1. Features
2. Requirements
3. Installation
4. Configuration
5. Snap API (Payment Links)
   • Create Redirect URL
   • Create Snap Token
6. Core API (Direct Charges)
   • Supported Payment Methods
   • Bank Transfer (Virtual Account)
   • Credit Card
   • E-Wallet (GoPay / ShopeePay)
   • Convenience Store (Indomaret / Alfamart)
7. Transaction Management
   • Check Status
   • Cancel Transaction
   • Approve / Deny
   • Expire Transaction
8. Notifications (Webhooks)
9. Exception Handling
10. Testing
11. License

Features

• Framework Agnostic: Seamlessly integrates with Laravel, Symfony, Slim, or plain vanilla PHP.
• Strictly Typed: Eliminates ambiguous array payloads. All requests and responses are encapsulated in strictly-typed, immutable DTOs (Data Transfer Objects).
• Unified Client: A single, clean MidtransClient instance utilizing gonon/core and PSR-18 standard HTTP adapters (with built-in exponential backoff retries).
• Secure Webhooks: Includes a built-in NotificationParser that securely validates Midtrans SHA512 signatures to prevent malicious spoofing.

Requirements

• PHP >= 8.2
• gonon/core

Installation

Install the package via Composer:

composer require gonon/midtrans

Configuration

To begin interacting with Midtrans, you need to instantiate the MidtransConfig and pass it to the MidtransClient.

use Gonon\Midtrans\Config\MidtransConfig;
use Gonon\Midtrans\Client\MidtransClient;
use Gonon\Core\Configuration\Environment;

// 1. Define your configuration
$config = new MidtransConfig(
    serverKey: 'SB-Mid-server-YOUR_SERVER_KEY',
    clientKey: 'SB-Mid-client-YOUR_CLIENT_KEY', // Optional, required for frontend integrations
    environment: Environment::Sandbox,          // Use Environment::Production for live apps
    timeout: 30                                 // Optional, HTTP timeout in seconds
);

// 2. Initialize the client
$client = new MidtransClient($config);

Snap API (Payment Links)

The Snap API is the fastest way to accept payments. It provides a ready-to-use checkout interface hosted by Midtrans.

Create Redirect URL

Generates a URL that you can redirect your customers to for payment.

use Gonon\Midtrans\DTO\Snap\CreateSnapTransactionRequest;
use Gonon\Midtrans\DTO\Shared\TransactionDetails;
use Gonon\Midtrans\DTO\Shared\CustomerDetails;
use Gonon\Midtrans\DTO\Snap\Callbacks;

$request = new CreateSnapTransactionRequest(
    transactionDetails: new TransactionDetails(
        orderId: 'ORDER-' . time(),
        grossAmount: 150000
    ),
    customerDetails: new CustomerDetails(
        firstName: 'John',
        lastName: 'Doe',
        email: 'john@example.com',
        phone: '08123456789'
    ),
    callbacks: new Callbacks(
        finish: 'https://yourwebsite.com/payment/success'
    )
);

$snapResponse = $client->snap()->createRedirectUrl($request);

echo $snapResponse->redirectUrl; // Redirect user to this URL

Create Snap Token

Generates a token used to open the Snap popup modal directly on your frontend via snap.js.

// Assuming the same $request object from above...
$snapResponse = $client->snap()->createToken($request);

echo $snapResponse->token; // Pass this token to your frontend JavaScript

Core API (Direct Charges)

If you are building your own checkout page and do not want to use the Snap popup, you can interact directly with the Midtrans Core API.

Supported Payment Methods

Bank Transfer (Virtual Account)

use Gonon\Midtrans\DTO\Core\CreateChargeRequest;
use Gonon\Midtrans\DTO\Core\BankTransferDetails;
use Gonon\Midtrans\DTO\Shared\TransactionDetails;

$request = new CreateChargeRequest(
    paymentType: 'bank_transfer',
    transactionDetails: new TransactionDetails('ORDER-CORE-123', 50000),
    bankTransfer: new BankTransferDetails(
        bank: 'bca'
    )
);

$response = $client->charge()->charge($request);

echo $response->transactionId;
echo $response->transactionStatus; // e.g., 'pending'

Credit Card

Note: For Credit Cards, you must first obtain a token_id from your frontend using midtrans-new-3ds.min.js.

use Gonon\Midtrans\DTO\Core\CreditCardDetails;
use Gonon\Midtrans\DTO\Shared\CustomerDetails;
use Gonon\Midtrans\DTO\Shared\TransactionDetails;
use Gonon\Midtrans\DTO\Core\CreateChargeRequest;

$request = new CreateChargeRequest(
    paymentType: 'credit_card',
    transactionDetails: new TransactionDetails('order102', 789000),
    customerDetails: new CustomerDetails(
        firstName: 'budi',
        lastName: 'pratama',
        email: 'budi.pra@example.com',
        phone: '08111222333'
    ),
    creditCard: new CreditCardDetails(
        tokenId: '<token_id from Get Card Token Step>',
        authentication: true
    )
);

$response = $client->charge()->charge($request);

E-Wallet (GoPay / ShopeePay)

use Gonon\Midtrans\DTO\Core\GopayDetails;
use Gonon\Midtrans\DTO\Core\ShopeepayDetails;

// GoPay Example
$gopayRequest = new CreateChargeRequest(
    paymentType: 'gopay',
    transactionDetails: new TransactionDetails('ORDER-GOPAY-123', 50000),
    gopay: new GopayDetails(
        enableCallback: true,
        callbackUrl: 'https://yourwebsite.com/gopay/callback'
    )
);

$response = $client->charge()->charge($gopayRequest);

// ShopeePay Example
$shopeepayRequest = new CreateChargeRequest(
    paymentType: 'shopeepay',
    transactionDetails: new TransactionDetails('ORDER-SHOPEEPAY-123', 50000),
    shopeepay: new ShopeepayDetails(
        callbackUrl: 'https://yourwebsite.com/shopeepay/callback'
    )
);

$response = $client->charge()->charge($shopeepayRequest);

Convenience Store (Indomaret / Alfamart)

use Gonon\Midtrans\DTO\Core\CstoreDetails;

$request = new CreateChargeRequest(
    paymentType: 'cstore',
    transactionDetails: new TransactionDetails('ORDER-CSTORE-123', 50000),
    cstore: new CstoreDetails(
        store: 'indomaret', // or 'alfamart'
        message: 'Payment for Order 123'
    )
);

$response = $client->charge()->charge($request);

Transaction Management

The TransactionResource allows you to manage existing transactions directly.

$orderId = 'ORDER-123';

Check Status

Check the real-time status of a transaction.

$status = $client->transactions()->status($orderId);
echo $status->transactionStatus; // 'settlement', 'pending', etc.

Cancel Transaction

Cancel a transaction before it is paid.

$cancelResult = $client->transactions()->cancel($orderId);

Approve / Deny

Approve or deny a Credit Card transaction flagged as challenge by the Fraud Detection System.

$client->transactions()->approve($orderId);
$client->transactions()->deny($orderId);

Expire Transaction

Force a pending transaction to expire immediately.

$client->transactions()->expire($orderId);

Notifications (Webhooks)

Midtrans will send asynchronous HTTP notifications to your server whenever a transaction status changes. To ensure the notification actually came from Midtrans and hasn't been tampered with, this SDK provides a secure NotificationParser.

use Gonon\Midtrans\Exceptions\NotificationException;

// Retrieve the raw JSON payload sent by Midtrans
$jsonPayload = file_get_contents('php://input');

try {
    // This strictly validates the SHA512 signature automatically using the serverKey configured in MidtransClient.
    // If the signature is invalid, it throws a NotificationException.
    $notification = $client->notifications()->parse($jsonPayload);
    
    $orderId = $notification->orderId;
    $status = $notification->transactionStatus;
    
    if ($status === 'settlement' || $status === 'capture') {
        // Safe to mark the order as paid in your database!
        echo "Payment successful for order: {$orderId}";
    } elseif ($status === 'cancel' || $status === 'deny' || $status === 'expire') {
        // Mark as failed
    }

    // Always return a 200 OK to Midtrans so they stop retrying
    http_response_code(200);
    echo "OK";
    
} catch (NotificationException $e) {
    // The signature was invalid or the JSON was malformed.
    // Do NOT process the order.
    http_response_code(403);
    echo "Invalid Signature: " . $e->getMessage();
}

Exception Handling

All exceptions thrown by this package implement a base MidtransException. Specific operations will throw domain-specific exceptions containing the status_message returned from Midtrans.

use Gonon\Midtrans\Exceptions\MidtransException;
use Gonon\Midtrans\Exceptions\ChargeException;
use Gonon\Midtrans\Exceptions\SnapException;

try {
    $snap->createToken($request);
} catch (SnapException $e) {
    // Handle Snap API specific failure
    echo $e->getMessage();
} catch (MidtransException $e) {
    // Catch-all for any Midtrans SDK exception
    echo $e->getMessage();
}

Testing

Run the automated test suite securely using PHPUnit:

composer test

To run static analysis using PHPStan (Level Max):

composer analyse

License

The MIT License (MIT). Please see the License File for more information.