README

Tinaba Pay SDK (PHP)

此包提供 PHP 对 Tinaba Pay API 的集成。此外，此包还可以作为 Laravel 包包含。

要求

• PHP >= 5.6.4
• GuzzleHttp 6
• Carbon
• illuminate/validation >= 5.4.0

如果您使用 composer，这些要求将自动安装

API 参考

这里 可以找到官方 API 文档。

快速入门

为了成功与 Tinaba Pay API 通信，您需要向 Tinaba 请求您的 商家 ID 和 密钥。

使用 Composer 安装

composer require tinaba/pay-sdk

配置客户端

要设置 API 客户端，您必须设置客户端配置

<?php

require 'vendor/autoload.php';

use \Tinaba\Pay\ApiContext;
use \Tinaba\Pay\Client;

$config = [
    'merchantId' => "TINABA_MERCHANT_ID",
    'secret' => 'TINABA_SECRET',
    'timeout' => 20 // request timeout in seconds
];

$context = new ApiContext($config);

$client = new Client($context);

沙盒模式

要在沙盒模式下操作，请将 sandbox 字段设置为 true，在实例化 ApiContext 对象时。

<?php

$config = [
    'sandbox' => true,
    'merchantId' => "TINABA_MERCHANT_ID",
    'secret' => 'TINABA_SECRET',
    'timeout' => 20 // request timeout in seconds
];

$context = new ApiContext($config);

$client = new Client($context);

示例

一旦您成功设置 SDK，您就可以开始向 Tinaba Pay 平台发出 API 调用。

初始化结账

<?php

$initCheckoutRequest = new InitCheckoutRequest();

$initCheckoutRequest->setExternalId('TR_01')
    ->setAmount('100') // Expressed in cents
    ->setCurrency('EUR')
    ->setDescription('Customized Mug purchase')
    ->setValidTo('10') // Expressed in minutes
    ->setCreationDateTime(Carbon::now())
    ->setPaymentMode(InitCheckoutRequest::MODE_ECOMMERCE)
    ->setNotificationUrl('https://example.com/TR_01/status')
    ->setNotificationHttpMethod('POST')
    ->setBackUrl('https://example.com/paymentcanceled')
    ->setSuccessUrl('https://example.com/paymentsuccess')
    ->setFailureUrl('https://example.com/paymentfailed');

// The API Client instantiated before
$response = $client->initCheckout($initCheckoutRequest);

echo "Payment code: " . $response->code;

可用的支付方式有

<?php

InitCheckoutRequest::MODE_PREAUTH;
InitCheckoutRequest::MODE_ECOMMERCE;
InitCheckoutRequest::MODE_MEDIA;

启用一键模式

要启用 一键 模式，您必须在初始化结账时将 sendReceiverAddress 设置为 true。

<?php

$initCheckoutRequest = new InitCheckoutRequest();

$initCheckoutRequest->setExternalId('TR_01')
    ->setAmount('100') // Expressed in cents
    ->setCurrency('EUR')
    ->setDescription('Customized Mug purchase')
    ->setValidTo('10') // Expressed in minutes
    ->setCreationDateTime(Carbon::now())
    ->setPaymentMode(InitCheckoutRequest::MODE_ECOMMERCE)
    ->setNotificationUrl('https://example.com/TR_01/status')
    ->setNotificationHttpMethod('POST')
    ->setBackUrl('https://example.com/paymentcanceled')
    ->setSuccessUrl('https://example.com/paymentsuccess')
    ->setFailureUrl('https://example.com/paymentfailed')
    ->setSendReceiverAddress(true);

// The API Client instantiated before
$response = $client->initCheckout($initCheckoutRequest);

echo "Payment code: " . $response->code;

如果启用 sendReceiverAddress，则在执行 VerifyCheckoutRequest 或收到 CheckoutStateCallback 时，您还将收到客户配送和账单详情。

确认已授权的结账

<?php

$request = new ConfirmPreauthorizedCheckoutRequest();

$request->setExternalId('TR_01')
    ->setAmount('100'); // Amount expressed in cents

$response = $client->confirmPreauthorizedCheckout($request);

验证结账状态

<?php

$request = new VerifyCheckoutRequest();

$request->setExternalId('TR_01');

$response = $client->verifyCheckout($request);

echo "The checkout status is " . $response->checkoutStatus;

执行完整/部分退款

<?php

$request = new RefundCheckoutRequest();

$request->setExternalId('TR_01');
$request->setAmount('100'); // Amount expressed in cents

$response = $client->refundCheckout($request);

获取生成的结账列表

<?php

$request = new GetCheckoutListRequest();

$request->setDateFrom('2018', '01', '01');
$request->setDateTo('2018', '02', '01');

$response = $client->getCheckoutList($request);

$checkoutList = $request->checkoutList;

foreach($checkoutList as $checkout) {

    echo "Found checkout with ID " . $checkout->externalId;

}

验证回调

<?php

// The request body as an associative array
$requestBody = json_decode($request->body, true);

$callbackRequest = CheckoutStateCallback::parse($request->body)

$valid = $client->verifyCallback($callbackRequest);

if($valid) {
    $successResponse = new CallbackSuccessResponse();

    // Return the response as json
    $responseBody = json_encode($successResponse->toArray());

    /*
     * Send the response as JSON with $responseBody as payload.
     * The following line is for example purpose only.
     */
    return response()->json($responseBody, 200);
}else {
    // Handle error
}

检查调用是否成功

<?php

if($response->status === TinabaResponse::STATUS_OK) {
    echo "Confirmation successful";
}else {
    echo "Confirmation failed with error code " . $response->errorCode;
}

Laravel 中使用

此包支持 Laravel 5.4+。

设置

在 config/app.php 文件的 providers 键下包含 TinabaPayServiceProvider。

<?php

// in config/app.php

'providers' => [

    // ... other providers
    \Tinaba\Pay\Laravel\TinabaPayServiceProvider::class,
],

在您的 config 目录中发布配置文件

$ php artisan vendor:publish --provider=\Tinaba\Pay\Laravel\TinabaServiceProvider

可选 在 config/app.php 的 aliases 键下添加别名

<?php

// in config/app.php

'aliases' => [
    // ... other aliases
    'TinabaPay' => \Tinaba\Pay\Laravel\Facades\TinabaPay::class,
],

使用

<?php

// Using the container
$response = app('tinaba.pay')->initCheckout($request);

// Using the Facade

$response = TinabaPay::initCheckout($request);