PHPackages                             surepay-one/sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Payment Processing](/categories/payments)
4. /
5. surepay-one/sdk

ActiveLibrary[Payment Processing](/categories/payments)

surepay-one/sdk
===============

Official PHP SDK for the SurePay Payment Gateway API

v0.1.0(1mo ago)00MITPHPPHP >=8.1CI passing

Since Jun 10Pushed 1mo agoCompare

[ Source](https://github.com/surepay-one/surepay-php-sdk)[ Packagist](https://packagist.org/packages/surepay-one/sdk)[ RSS](/packages/surepay-one-sdk/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (1)Versions (2)Used By (0)

surepay-php-sdk
===============

[](#surepay-php-sdk)

Official PHP client library for the [SurePay](https://surepay.one) Merchant API.

[![CI](https://github.com/surepay-one/surepay-php-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/surepay-one/surepay-php-sdk/actions/workflows/ci.yml)[![Packagist](https://camo.githubusercontent.com/9f1ff993460cccb63901ae73b53aed58eac4ea7a71aeac5cd0d6d9a41f8870db/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f737572657061792d6f6e652f73646b)](https://packagist.org/packages/surepay-one/sdk)

Requirements
------------

[](#requirements)

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

Install
-------

[](#install)

```
composer require surepay-one/sdk
```

Quick start
-----------

[](#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
-------------

[](#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();
```

OptionDefaultDescription`baseUrl(string)``https://api.surepay.one/merchant/v1`Override base URL for local dev or staging`timeout(int)``30`HTTP request timeout in seconds`maxRetries(int)``3`Retry attempts on 5xx and network errorsAuthentication
--------------

[](#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
-------------

[](#api-reference)

### Balance

[](#balance)

#### `$client->balance->get()`

[](#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

[](#deposits)

#### `$client->deposits->list(params)`

[](#client-deposits-listparams)

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)`

[](#client-deposits-createreq)

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:**

FieldTypeDescription`id`stringSurePay transaction UUID`requestId`stringYour order ID`amount`intAmount in VND`status`stringpending, processing, success, failed, expired, cancelled`checkoutUrl`stringRedirect URL for payer`qrCode`stringVietQR data string`createdAt`stringISO 8601 timestamp`updatedAt`stringISO 8601 timestamp#### `$client->deposits->get(id)`

[](#client-deposits-getid)

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

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

---

### Payouts

[](#payouts)

#### `$client->payouts->list(params)`

[](#client-payouts-listparams)

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)`

[](#client-payouts-createreq)

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)`

[](#client-payouts-getid)

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

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

---

### Bank Inquiry

[](#bank-inquiry)

#### `$client->bankInquiry->verify(req)`

[](#client-bankinquiry-verifyreq)

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
-----------

[](#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
--------------------

[](#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
--------------

[](#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:**

HTTP`getErrorCode()`Meaning400`validation_error`Invalid request body or parameters401`unauthorized`Missing or invalid API key401`signature_invalid`HMAC signature failed or timestamp > 5 min403`permission_denied`API key lacks required scope403`ip_not_allowed`Request IP not in allowlist404`not_found`Resource not found409`duplicate_request`Idempotency key conflict422`insufficient_balance`Top up wallet first422`invalid_state_transition`Operation not allowed for current status429`rate_limit_exceeded`Slow down — back off and retry500`internal_error`Server errorHMAC signing
------------

[](#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: ` and `X-Timestamp: `.

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

License
-------

[](#license)

MIT

###  Health Score

33

—

LowBetter than 72% of packages

Maintenance90

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity32

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

46d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/292320180?v=4)[jamestran03](/maintainers/jamestran03)[@jamestran03](https://github.com/jamestran03)

---

Top Contributors

[![khaitrandinh](https://avatars.githubusercontent.com/u/94419745?v=4)](https://github.com/khaitrandinh "khaitrandinh (4 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/surepay-one-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/surepay-one-sdk/health.svg)](https://phpackages.com/packages/surepay-one-sdk)
```

###  Alternatives

[pagseguro/php

Biblioteca de integração com o PagSeguro

23260.3k6](/packages/pagseguro-php)[msilabs/bkash

bKash Payment Gateway API for Laravel Framework.

181.4k](/packages/msilabs-bkash)[binkode/laravel-paystack

A description for laravel-paystack.

112.1k](/packages/binkode-laravel-paystack)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)