tingee / sdk-php
Tingee Open API SDK for PHP
Requires
- php: >=8.0
- ext-curl: *
- ext-json: *
- guzzlehttp/guzzle: ^7.5
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
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+
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ề
TingeeApiResponsevớicodevàmessage. DùngisSuccess()hoặc kiểm tragetCode() === '00'để xác định thành công — SDK không tự throw khicode !== '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"