README

此库提供了对 Transact Pro 网关 API v3 发送请求的能力。

安装

使用以下命令安装最新版本

$ composer require transact-pro/gw3-client

基本用法

表单内部

在网关端保持卡片输入表单，客户端必须被重定向到网关。

<?php

use TransactPro\Gateway\Gateway;
use TransactPro\Gateway\Responses\Constants\Status;

$gw = new Gateway('<API BASE URL>/v3.0');

// Setup gateway authorization credentials
$gw->auth()
    ->setAccountGUID("3383e58e-9cde-4ffa-85cf-81cd25b2423e")
    ->setSecretKey('super-secret-key');

// Create transaction object
$sms = $gw->createSms();

// Set required fields
$sms->money()
    ->setAmount(100)
    ->setCurrency('USD');

$sms->customer()
    ->setEmail("email@domain.com")
    ->setPhone("2445224657");

$sms->order()
    ->setMerchantTransactionID('A-345S')
    ->setDescription('Order #A-345S payment');

// Process payment via gateway inside form
$sms->insideForm();

// Build transaction object to request
$smsRequest = $sms->build();

// Process transaction to gateway
$response = $gw->process($smsRequest);

// Parse Gateway response as a payment response
$paymentResponse = $sms->parseResponse($response);
if (!empty($paymentResponse->error)) {
    throw new \RuntimeException("GW error: {$paymentResponse->error->message}");
}

// Redirect user to received URL
if ($paymentResponse->gw->statusCode === Status::CARD_FORM_URL_SENT) {
    header("Location: {$paymentResponse->gw->redirectUrl}");
}

服务器到服务器

在商户端保持卡片输入表单并通过 API 处理。

<?php

use TransactPro\Gateway\Gateway;
use TransactPro\Gateway\Responses\Constants\Status;

$gw = new Gateway('<API BASE URL>/v3.0');

// Setup gatewayl authorization credentials
$gw->auth()
    ->setAccountGUID("3383e58e-9cde-4ffa-85cf-81cd25b2423e")
    ->setSecretKey('super-secret-key');

// Create transaction object
$sms = $gw->createSms();

// Set required fields
$sms->paymentMethod()
    ->setPAN('4295550031781065')
    ->setExpire('06/18')
    ->setCVV('683')
    ->setCardHolderName('John Doe');
$sms->money()
    ->setAmount(100)
    ->setCurrency('USD');

// Build transaction object to request
$smsRequest = $sms->build();

// Process transaction to gateway
$response = $gw->process($smsRequest);

// Parse Gateway response as a payment response
$paymentResponse = $sms->parseResponse($response);
echo $paymentResponse->gw->statusCode === Status::SUCCESS ? "SUCCESS" : "FAILED";

文档

此 README 介绍了库的使用方法。

操作

可以通过 $gw->create<operation name>() 方法进行操作。

可用操作

• 交易
  • CANCEL
  • DMS CHARGE
  • DMS HOLD
  • MOTO DMS
  • MOTO SMS
  • INIT RECURRENT DMS
  • RECURRENT DMS
  • INIT RECURRENT SMS
  • RECURRENT SMS
  • REFUND
  • REVERSAL
  • SMS
  • Credit
  • P2P
  • B2P
• 信息
  • HISTORY
  • RECURRENTS
  • REFUNDS
  • RESULT
  • STATUS
  • LIMITS
• 验证
  • 3-D Secure 注册
  • 完整卡片验证
• 令牌化
  • 创建支付数据令牌
• 回调处理
  • 验证回调数据签名
• 报告
  • 以 CSV 格式获取交易报告

使用此库的模式可以描述如下

<?php

use TransactPro\Gateway\Gateway;

$gw = new Gateway('<API BASE URL>/v3.0');

// first, you need to setup authorization.
// you can change authorization data in runtime.
// Thus, following operations will work under
// new authorization.
$gw->auth()
    ->setAccountGUID("3383e58e-9cde-4ffa-85cf-81cd25b2423e")
    ->setSecretKey('super-secret-key');

$operation = $gw->createOPERATION();

// here you setup your request through public methods
// that expose you blocks of information, that you can fill for the
// operation of your choice.

// build() will prepare `Request` object that `$gw` will use
// for the request.
$operationRequest = $operation->build();

// process() will perform provided request to the gateway
// `$response` will have response data (headers, body).
$response = $gw->process($operationRequest);

// parse received raw response to an appropriate class
$parsedResponse = $operation->parseResponse($response);

卡片验证

<?php

use TransactPro\Gateway\DataSets\Command;

// create a payment to init card verification process
$message->command()->setCardVerificationMode(Command::CARD_VERIFICATION_MODE_INIT);

// complete card verification
$operation = $gw->createCardVerification();
$operation->data()->setGatewayTransactionID($initialResponseGatewayTransactionId);
$operationRequest = $operation->build();
$response = $gw->process($request);
echo $response->getStatusCode() === 200 ? 'SUCCESS' : 'FAILURE';

// send a payment with flag to accept only verified cards
$message->command()->setCardVerificationMode(Command::CARD_VERIFICATION_MODE_VERIFY);

支付数据令牌化

<?php

use TransactPro\Gateway\DataSets\Command;

// option 1: create a payment with flag to save payment data
$message->command()->setPaymentMethodDataSource(Command::DATA_SOURCE_SAVE_TO_GATEWAY);

// option 2: send "create token" request with payment data
$operation = $gw->createToken();
$operation->paymentMethod()
    ->setPAN('<card number>')
    ->setExpire('<card expiry>')
    ->setCardHolderName('<cardholder name>');
$operation->money()
    ->setCurrency('<desired currency>');
$operationRequest = $operation->build();
$response = $gw->process($request);

// send a payment in "token usage" mode with flag to load payment data by token
$message->useToken();
$message->command()
    ->setPaymentMethodDataSource(Command::DATA_SOURCE_USE_GATEWAY_SAVED_CARDHOLDER_INITIATED)
    ->setPaymentMethodDataToken('<initial gateway-transaction-id>');

$response = $gw->process($message);
$paymentResponse = $message->parseResponse($response);
if (
    !empty($paymentResponse->error) &&
    $paymentResponse->error->code === ErrorCode::EEC_ACQUIRER_SOFT_DECLINE &&
    !empty($paymentResponse->gw->redirectUrl)
) {
    header("Location: {$paymentResponse->gw->redirectUrl}");
}

回调验证

<?php

use TransactPro\Gateway\Responses\GatewayResponse;
use TransactPro\Gateway\Responses\CallbackResult;
use TransactPro\Gateway\Http\Crypto\ResponseDigest;

// verify data digest
$responseDigest = new ResponseDigest($_POST['sign'] ?? '');
$responseDigest->setOriginalUri($paymentResponse->getDigest()->getUri());       // optional, set if available
$responseDigest->setOriginalCnonce($paymentResponse->getDigest()->getCnonce()); // optional, set if available
$responseDigest->setBody($_POST['json'] ?? '');
$responseDigest->verify("3383e58e-9cde-4ffa-85cf-81cd25b2423e", "super-secret-key");

// parse callback data as a payment response
$callbackResponse = GatewayResponse::createFromJSON($_POST['json'] ?? '', CallbackResult::class);
echo $callbackResponse->gw->statusText;

加载交易报告

<?php

use TransactPro\Gateway\Interfaces\ResponseInterface;

// NB. Merchant GUID/secret must be used instead of account GUID/secret!
$gw->auth()
    ->setMerchantGUID('8D80-921D-BB99-45ED')
    ->setSecretKey('super-secret-key');

$message = $gw->createReport();
$message->filterData()
    ->setDtCreatedFrom(time() - 86400)
    ->setDtFinishedTo(time());

$request = $message->build();
$response = $gw->process($request);

// get raw body
$reportCSV = $response->getBody();

// get parsed body as iterator where each row is an associative array
// with keys from the first line and values are from all other lines
$csvResponse = $message->parseResponse($response);
print_r($csvResponse->getHeaders());
foreach ($csvResponse as $key => $value) {
    print_r($value);
}

自定义

如果您需要访问不同的 API URL，可以通过以下方式在 Gateway 构造函数中设置

<?php

use TransactPro\Gateway\Gateway;

$gw = new Gateway('https://customurl.com');

此外，您可以根据您的需求自定义客户端。默认情况下，使用 Http\Client\Client 类。它在底层使用 cURL。它实现了 HttpClientInterface。您可以创建自己的（或配置默认的）并将其设置到网关中。

<?php

use TransactPro\Gateway\Gateway;

$httpClient = new MyClient(); // implements HttpClientInterface

$gw = new Gateway('<API BASE URL>/v3.0');
$gw->setHttpClient($httpClient);

// use it!
// ...

如果您需要从网关加载 HTML 表单而不是将持卡人浏览器重定向，可以使用特殊操作类型

// execute a payment
$paymentResponse = $operation->parseResponse($response);

$retrieveFormOperation = $gw->createRetrieveForm($paymentResponse);
$retrieveFormRequest = $retrieveFormOperation->build();
$htmlResponse = $gw->process($retrieveFormRequest);
$rawHtml = $htmlResponse->getBody();

异常

库可以抛出的主要异常是 GatewayException。以下异常是 GatewayException 的子类

• RequestException - 如果请求失败，将抛出。
• ValidatorException - 如果请求缺少某些数据，将抛出。
• ResponseException - 如果响应解析/验证失败（损坏的响应），将抛出。
• DigestMissingException - 如果响应缺少授权头（损坏的响应），将抛出。
• DigestMismatchException - 如果响应摘要验证失败（损坏的响应），将抛出。

有用的常量

\TransactPro\Gateway\Responses\Constants\ErrorCode - 错误代码 \TransactPro\Gateway\Responses\Constants\Status - 交易状态 \TransactPro\Gateway\Responses\Constants\CardFamily - 卡片家族

关于

需求

• 此库与 PHP 7.0 或更高版本兼容。

提交错误和功能请求

错误和功能请求在 GitHub 上跟踪

许可证

此库根据 MIT 许可证授权 - 详细信息请参阅 LICENSE 文件。