README

Official PHP client for the Yupay merchant API. Zero dependencies (uses ext-curl), PHP 8.1+.

Install

composer require yupay/yupay-php

Or drop the src/ folder into your project and require the files directly (PSR-4 namespace Yupay\).

Quickstart

use Yupay\Yupay;
use Yupay\Exceptions\YupayException;

$yupay = new Yupay(getenv('YUPAY_API_KEY'), [
    'base_url' => 'https://app.yupay.id/api/v1', // your Yupay instance
]);

try {
    $charge = $yupay->createCharge(
        ['amount' => 50000, 'method' => 'qris'],
        idempotencyKey: 'order-1001',
    );

    echo $charge['payment_no'];          // PAY-260626-AB12CD
    echo $charge['status'];              // pending
    print_r($charge['artifact']);        // qr_string / va_number / redirect_url …
} catch (YupayException $e) {
    error_log($e->getMessage());
    print_r($e->validationErrors());     // field errors on HTTP 422
}

Methods

$yupay->createCharge(array $params, ?string $idempotencyKey = null): array;
$yupay->retrieveCharge(string $paymentNo): array;
$yupay->refundCharge(string $paymentNo, ?int $amount = null, ?string $reason = null): array;
$yupay->balance(): array;
$yupay->paymentChannels(?string $category = null, bool $includeInactive = false): array;

All return the decoded JSON as an array; all throw Yupay\Exceptions\YupayException on error ($e->statusCode, $e->response, $e->validationErrors()).

Webhooks

Verify and decode an incoming webhook in one call. Pass the raw request body.

use Yupay\Webhook;
use Yupay\Exceptions\YupayException;

$payload = file_get_contents('php://input');
$sig     = $_SERVER['HTTP_X_YUPAY_SIGNATURE'] ?? '';

try {
    $event = Webhook::constructEvent($payload, $sig, getenv('YUPAY_WEBHOOK_SECRET'));
} catch (YupayException $e) {
    http_response_code(400);
    exit('invalid signature');
}

if ($event['event'] === 'payment.succeeded') {
    $payment = $event['data'];
    // fulfill order $payment['payment_no'] … (dedupe on $event['id'])
}

http_response_code(200);
echo 'ok';

See examples/ for a full charge flow and a webhook endpoint.