README

Official PHP client library for the SurePay Merchant API.

Requirements

• PHP 8.1+
• ext-curl
• ext-json
• Zero non-stdlib dependencies

Install

composer require surepay-one/sdk

Quick start

use SurePay\SurePay;
use SurePay\Request\CreateDepositRequest;
use SurePay\Request\CreatePayoutRequest;

$client = SurePay::builder(
    getenv('SUREPAY_API_KEY'),    // tpay_live_... or tpay_test_...
    getenv('SUREPAY_API_SECRET'), // tpay_sec_... — enables auto HMAC signing
)->build();

// Check wallet balance
$balance = $client->balance->get();
echo "Available: {$balance->available} VND\n";

// Create a deposit order (thu hộ)
$deposit = $client->deposits->create(
    CreateDepositRequest::builder(100_000)
        ->withRequestId('ORD-20260610-001')
        ->build()
);
echo "Checkout URL: {$deposit->checkoutUrl}\n";

// Create a payout (chi hộ)
try {
    $payout = $client->payouts->create(
        CreatePayoutRequest::builder(500_000, 'VCB', '1234567890', 'NGUYEN VAN A', 'Salary June 2026')
            ->build()
    );
    echo "Payout ID: {$payout->id}\n";
} catch (SurePayException $e) {
    if ($e->isInsufficientBalance()) {
        echo "Not enough balance — top up first\n";
    }
}

Configuration

$client = SurePay::builder($apiKey, $apiSecret)
    ->baseUrl('https://api.surepay.one/merchant/v1') // override for local/staging
    ->timeout(15)                                     // seconds
    ->maxRetries(3)                                   // retries on 5xx and network errors
    ->build();

Authentication

Every request requires an API key sent as an X-API-Key header. When apiSecret is provided to builder(), every outgoing request is automatically signed with HMAC-SHA256 — the X-Signature and X-Timestamp headers are attached with no extra code needed.

API reference

Balance

$client->balance->get()

Get current wallet balance. Requires: balance:read scope.

$balance = $client->balance->get();
// $balance->balance   — total wallet balance in VND
// $balance->hold      — reserved for in-flight transactions
// $balance->available — balance - hold
// $balance->currency  — always "VND"

Deposits

$client->deposits->list(params)

Paginated list of deposit (thu hộ) orders. Requires: deposits:read scope.

use SurePay\Params\DepositsListParams;

$result = $client->deposits->list(
    DepositsListParams::create()
        ->page(1)
        ->pageSize(20)
        ->status('success')       // pending|processing|success|failed|expired|cancelled
        ->fromDate('2026-06-01')  // YYYY-MM-DD
        ->toDate('2026-06-30')
);
// $result->items      — Deposit[]
// $result->total      — total matching records
// $result->totalPages — total pages

$client->deposits->create(req)

Create a new deposit order. Returns a checkoutUrl (redirect) and qrCode (VietQR). Requires: deposits:write scope.

use SurePay\Request\CreateDepositRequest;

$deposit = $client->deposits->create(
    CreateDepositRequest::builder(100_000)         // amount in VND, required
        ->withRequestId('ORD-20260610-001')        // your order ID — optional, for idempotency
        // Chính chủ verification — all optional:
        ->withSenderBankId('970436')
        ->withSenderBankName('Vietcombank')
        ->withSenderAccount('1234567890')
        ->withSenderName('NGUYEN VAN A')
        ->build()
);
echo $deposit->checkoutUrl;
echo $deposit->qrCode;

Response fields:

$client->deposits->get(id)

Fetch a single deposit order by UUID. Requires: deposits:read scope.

$deposit = $client->deposits->get('uuid-here');
// $deposit->status: 'pending' | 'success' | ...

Payouts

$client->payouts->list(params)

Paginated list of payout (chi hộ) orders. Requires: payouts:read scope.

use SurePay\Params\PayoutsListParams;

$result = $client->payouts->list(
    PayoutsListParams::create()
        ->page(1)
        ->pageSize(20)
        ->status('success')   // pending|processing|success|failed
        ->fromDate('2026-06-01')
        ->toDate('2026-06-30')
);

$client->payouts->create(req)

Initiate a payout bank transfer. Funds are deducted from your wallet immediately on success. Requires: payouts:write scope.

Payouts are irreversible once status moves past pending. Verify bank details with $client->bankInquiry->verify() first.

use SurePay\Request\CreatePayoutRequest;

$payout = $client->payouts->create(
    CreatePayoutRequest::builder(
        500_000,        // amount in VND, required
        'VCB',          // bank code, required (VCB, MB, TCB, ACB, ...)
        '1234567890',   // bank account, required
        'NGUYEN VAN A', // full name in UPPERCASE, required
        'Salary June'   // description / transfer memo, required
    )
    ->withBankName('Vietcombank') // optional
    ->build()
);

$client->payouts->get(id)

Fetch a single payout by UUID. Requires: payouts:read scope.

$payout = $client->payouts->get('uuid-here');
// $payout->status: 'pending' | 'success' | ...

Bank Inquiry

$client->bankInquiry->verify(req)

Look up the account holder name for a bank account. Call this before creating a payout to confirm the recipient. Requires: payouts:read scope.

use SurePay\Request\BankInquiryRequest;

$result = $client->bankInquiry->verify(
    BankInquiryRequest::of('VCB', '1234567890')
);
echo "Account name: {$result->accountName}\n";

Idempotency

Pass an idempotency key as the second argument to any create() method. The key is forwarded as an Idempotency-Key header — safe to retry on network errors without risk of duplicate transactions.

$deposit = $client->deposits->create(
    CreateDepositRequest::builder(100_000)->withRequestId('ORD-001')->build(),
    'ORD-001'  // idempotency key
);

Webhook verification

Every inbound webhook event from SurePay is HMAC-signed. Pass the raw request body string (before any JSON parsing) to $client->webhooks->verify():

// Laravel example
Route::post('/webhook/surepay', function (Request $request) {
    $body = $request->getContent();

    if (!$client->webhooks->verify($body)) {
        abort(401, 'Invalid signature');
    }

    $event = json_decode($body, true);

    match ($event['event']) {
        'deposit.success', 'deposit.failed' => handleDeposit($event),
        'payout.success',  'payout.failed'  => handlePayout($event),
        default => null,
    };

    return response()->noContent();
});

Or pass the X-Surepay-Signature header value explicitly:

$sig   = $request->header('X-Surepay-Signature');
$valid = $client->webhooks->verifyWithSignature($body, $sig);

Error handling

use SurePay\Exception\SurePayException;

try {
    $payout = $client->payouts->create($req);
} catch (SurePayException $e) {
    // Convenience helpers
    if ($e->isNotFound())            { /* 404 not_found */ }
    if ($e->isRateLimit())           { /* 429 rate_limit_exceeded */ }
    if ($e->isInsufficientBalance()) { /* 422 insufficient_balance */ }
    if ($e->isDuplicate())           { /* 409 duplicate_request */ }

    // Full details
    printf("HTTP %d  code=%s  %s\n",
        $e->getHttpStatus(), $e->getErrorCode(), $e->getMessage());
}

Error codes:

HMAC signing

When apiSecret is set, all requests are signed automatically. The signing algorithm for manual use:

signingString = UNIX_TIMESTAMP . "\n" . METHOD . "\n" . PATH . "\n" . hex(sha256(body))
signature     = "sha256=" . hex(hash_hmac('sha256', signingString, apiSecret))

Attach as headers: X-Signature: <signature> and X-Timestamp: <unix_timestamp>.

Signatures expire after 300 seconds — generate per-request, never cache or reuse.

License

MIT