README

A Laravel payment gateway package for iPaymu Public API v2 integration.

Features

• Payment initiation (hosted Redirect flow)
• Independent transaction verification via the Check Transaction API
• Secure callback route with single-use keys and idempotent forwarding
• Configurable via environment variables
• Built on rublex/laravel-core-gateway contracts

Installation

composer require rublex/laravel-ipaymu-gateway

Configuration

Publish the configuration file:

php artisan vendor:publish --provider="Ipaymu\IpaymuServiceProvider" --tag="ipaymu-config"

Add credentials to your .env file:

IPAYMU_BASE_URL=https://sandbox.ipaymu.com
IPAYMU_VA=
IPAYMU_API_KEY=

Use https://my.ipaymu.com for production. The VA and API Key are found in the Integration menu of your iPaymu dashboard and differ between sandbox and production.

Quick Start

use Ipaymu\Services\IpaymuGatewayService;
use Rublex\CoreGateway\Data\DynamicDataBag;
use Rublex\CoreGateway\Data\PaymentRequestData;

$gateway = app(IpaymuGatewayService::class);

$result = $gateway->initiate(new PaymentRequestData(
    gatewayCode: $gateway->code(),
    orderId: 'INV-1774369486',
    amount: '150000',
    currency: 'IDR',
    callbackUrl: 'https://example.com/payment/final-callback',
    meta: new DynamicDataBag([
        'return_url' => 'https://example.com/thank-you',
        'cancel_url' => 'https://example.com/cancelled',
        'buyer_name' => 'Putu Made',
        'buyer_email' => 'buyer@example.com',
        'buyer_phone' => '081234567890',
    ])
));

// PaymentInitResultData:
//   status()           => PaymentStatus::PENDING
//   transactionId()    => iPaymu SessionID
//   redirectUrl()      => hosted payment page URL (redirect the payer here)
//   gatewayReference() => provider reference, when present
//   meta()             => responseCode / responseMessage
//   raw()              => full provider payload

Redirect the payer to redirectUrl(). iPaymu notifies the package callback route when the payment completes; the verified outcome is then forwarded to your callbackUrl.

Currency

iPaymu settles in IDR only. initiate() throws a ValidationException for any other currency. The amount is expected to already be denominated in IDR and is rounded to a whole rupiah (IDR has no minor units).

Signatures

Two distinct mechanisms are involved — do not confuse them:

• Request — HMAC-SHA256(stringToSign, API_KEY) where stringToSign = "METHOD:VA:lower(sha256(jsonBody)):API_KEY". The exact JSON string that is signed is the body that is sent.
• Callback — HMAC-SHA256(json(ksort(payload)), VA). Verified opportunistically; the authoritative check is a server-to-server call to the Check Transaction API (POST /api/v2/transaction).

Backward Compatibility

• verifyPayment() and getPaymentStatus() are explicit package methods and still throw not-implemented exceptions — status is confirmed internally via the Check Transaction API during callback handling.

Documentation

For installation and usage instructions, see USAGE.md.

License

This package is open-sourced software licensed under the MIT license.