Search by

tingee / sdk-php

tingeehub

Tingee Open API SDK for PHP

0.4.0 2026-11-09 06:52 UTC

This package is auto-updated.

Last update: 2026-11-09 08:28:44 UTC


README

SDK chính thức tích hợp Tingee Open API cho PHP 8.0+

Packagist PHP License: ISC

Cài đặt

composer require tingee/sdk-php

Bắt đầu nhanh

<?php
require_once 'vendor/autoload.php';

use Tingee\Sdk\TingeeClient;

$client = new TingeeClient(
    secretKey:   $_ENV['TINGEE_SECRET_KEY'],
    clientId:    $_ENV['TINGEE_CLIENT_ID'],
    environment: 'prod',  // 'prod' | 'uat', mặc định 'prod'
    timeout:     90,      // giây, mặc định 90
    // baseUrl: 'https://uat-open-api.tingee.vn', // tùy chọn, ghi đè environment
);

$result = $client->merchant->getPaging(
    filter: null, sorting: null, skipCount: 0, maxResultCount: 10
);

if ($result->isSuccess()) {
    print_r($result->getData());
} else {
    echo "Lỗi {$result->getCode()}: {$result->getMessage()}";
}

Cấu hình

Tham số Kiểu Mặc định Mô tả
secretKey string — Bắt buộc. Secret key từ Tingee Dashboard
clientId string — Bắt buộc. Client ID từ Tingee Dashboard
environment string 'prod' 'prod' | 'uat'
timeout int 90 Timeout (giây)
baseUrl string|null — Ghi đè URL (bỏ qua environment)

Laravel

// AppServiceProvider.php
$this->app->singleton(TingeeClient::class, fn () => new TingeeClient(
    secretKey:   config('services.tingee.secret_key'),
    clientId:    config('services.tingee.client_id'),
    environment: config('services.tingee.environment', 'prod'),
));

Gọi API

Các phương thức được nhóm theo tính năng ($client-><group>-><method>()):

// Merchant — lấy danh sách
$result = $client->merchant->getPaging(
    filter: null, sorting: null, skipCount: 0, maxResultCount: 10
);
if ($result->isSuccess()) {
    foreach ($result->getData()->items as $merchant) echo $merchant->name . PHP_EOL;
}

// Shop — lấy danh sách
$result = $client->shop->getPaging(
    filter: null, sorting: null, skipCount: 0, maxResultCount: 10
);

// Direct Debit
$sub = $client->directDebit->getSubscriptionStatus(
    requestId: 'uuid-here',
    subscriptionId: 'uuid-here',
    tokenRef: 'token-ref'
);

Lưu ý: SDK trả về TingeeApiResponse với code và message. Dùng isSuccess() hoặc kiểm tra getCode() === '00' để xác định thành công — SDK không tự throw khi code !== '00'.

Xác thực Webhook

// index.php / route handler
$signature = $_SERVER['HTTP_X_SIGNATURE']          ?? '';
$timestamp  = $_SERVER['HTTP_X_REQUEST_TIMESTAMP'] ?? '';
$body       = json_decode(file_get_contents('php://input'), true);

$result = $client->verifyWebhookSignature($signature, $timestamp, $body);

if ($result->isError()) {
    http_response_code(401);
    echo json_encode(['error' => $result->message]);
    exit;
}

// Xử lý giao dịch...
echo json_encode(['received' => true]);
// Laravel
Route::post('/webhook/tingee', function (Request $request, TingeeClient $client) {
    $result = $client->verifyWebhookSignature(
        $request->header('x-signature'),
        $request->header('x-request-timestamp'),
        $request->all()
    );
    if ($result->isError()) abort(401, $result->message);
    // Xử lý...
    return response()->json(['received' => true]);
});

Xác thực URL webhook

Khi lưu URL webhook trên Tingee, hệ thống gửi một request xác thực vào URL đó:

{ "event": "url-validation", "plainToken": "<chuỗi ngẫu nhiên>", "timestamp": 1730000000000 }

Endpoint phải trả về HTTP 200 với { "plainToken": "...", "encryptedToken": "..." }, trong đó encryptedToken = HMAC-SHA256(secretToken, plainToken) dạng hex. secretToken là secret của API Key loại Xác thực webhook đang bật (tạo trong mục API Credentials).

SDK làm sẵn bước này: hàm trả về body cần phản hồi, hoặc null nếu không phải request xác thực. Gọi trước khi verify chữ ký, vì body xác thực không có các trường giao dịch.

use Tingee\Sdk\Signature\TingeeSigner;

Route::post('/webhook/tingee', function (Request $request) {
    $validation = TingeeSigner::createUrlValidationResponse($_ENV['TINGEE_WEBHOOK_SECRET'], $request->getContent());
    if ($validation !== null) {
        return response()->json($validation);
    }

    // Verify chữ ký & xử lý giao dịch như bình thường...
});

Nếu dùng chung khóa với client: $client->createUrlValidationResponse($request->getContent()).

Bank Constants

use Tingee\Sdk\Types\BankNameEnum;
use Tingee\Sdk\Types\BankConstants;

BankConstants::getBin(BankNameEnum::VIETCOMBANK)       // "970436"
BankConstants::getShortName(BankNameEnum::VIETCOMBANK) // "Vietcombank"
BankConstants::getFullName(BankNameEnum::VIETCOMBANK)  // "Ngân hàng TMCP Ngoại Thương Việt Nam"

Xem thêm