README

QuickBooks Payments PHP SDK

本SDK旨在通过提供一组简化操作的方法，方便开发者使用QuickBooks Payments API。它支持以下操作

标准OAuth 2.0和OpenID Connect协议
用于日志记录和错误处理的拦截器
标准支付API端点，包括请求/响应处理

如果您之前没有使用过QuickBooks Payments API，请访问我们的文档： https://developer.intuit.com/app/developer/qbpayments/docs/get-started

要求

PHP 7.2.0及更高版本。
QuickBooks Online支付API应用。

Composer

您可以通过Composer安装此包。运行以下命令

composer require quickbooks/payments-sdk

如果在Composer安装过程中遇到问题，请先尝试更新Composer

composer update

并查看指定版本是否解决了问题，例如

composer require quickbooks/payments-sdk 1.0.5

要使用此包，使用Composer的自动加载

require "vendor/autoload.php";

手动安装

如果您不想使用Composer，可以下载最新版本。然后，为了使用该包，请包含config.php文件。

require_once('/path/to/config.php');

依赖项

以下扩展对于正常工作是必需的

curl，尽管您可以选择使用自己的非cURL客户端
json

如果您指定了Guzzle客户端，那么也需要Guzzle。

如果您使用Composer，这些依赖项应该会自动处理。如果您手动安装，请确保这些扩展可用。

入门

要开始使用支付SDK，第一步是创建PaymentClient。必需的最小属性是access_token和environment。access_token是访问API的OAuth 2.0令牌，environment定义API端点的基本URL。这可以是sandbox或production。如果您没有提供这两个属性，PaymentClient仍然会创建，但是它将无法执行任何支付API调用。

$client = new PaymentClient([
 'access_token' => "your access token",
 'environment' => "sandbox" //  or 'environment' => "production"
]);

一旦创建Payment Client，您就可以开始向支付API端点发出API调用。简单用法如下

<?php
require "vendor/autoload.php";

use QuickBooksOnline\Payments\PaymentClient;
use QuickBooksOnline\Payments\Operations\ChargeOperations;


$client = new PaymentClient([
  'access_token' => "your access token",
  'environment' => "sandbox" //  or 'environment' => "production"
]);

$array = [
  "amount" => "10.55",
  "currency" => "USD",
  "card" => [
      "name" => "emulate=0",
      "number" => "4111111111111111",
      "address" => [
        "streetAddress" => "1130 Kifer Rd",
        "city" => "Sunnyvale",
        "region" => "CA",
        "country" => "US",
        "postalCode" => "94086"
      ],
      "expMonth" => "02",
      "expYear" => "2020",
      "cvc" => "123"
  ],
  "context" => [
    "mobile" => "false",
    "isEcommerce" => "true"
  ]
];
$charge = ChargeOperations::buildFrom($array);
$response = $client->charge($charge);

if($response->failed()){
    $code = $response->getStatusCode();
    $errorMessage = $response->getBody();
    echo "code is $code \n";
    echo "body is $errorMessage \n";
}else{
    $responseCharge = $response->getBody();
    //Get the Id of the charge request
    $id = $responseCharge->id;
    //Get the Status of the charge request
    $status = $responseCharge->status;
    echo "Id is " . $id . "\n";
    echo "status is " . $status . "\n";
}

如果请求成功，则getBody()函数将返回转换后的对象。上述示例将从$response->getBody()返回以下$responseCharge对象

class QuickBooksOnline\Payments\Modules\Charge#11 (19) {
  public $status =>
  string(8) "CAPTURED"
  public $amount =>
  string(5) "10.55"
  public $currency =>
  string(3) "USD"
  public $token =>
  NULL
  public $card =>
  class QuickBooksOnline\Payments\Modules\Card#12 (18) {
    public $updated =>
    NULL
    public $name =>
    string(9) "emulate=0"
    public $number =>
    string(16) "xxxxxxxxxxxx1111"
    public $address =>
    class QuickBooksOnline\Payments\Modules\Address#13 (5) {
      public $streetAddress =>
      string(13) "1130 Kifer Rd"
      public $city =>
      string(9) "Sunnyvale"
      public $region =>
      string(2) "CA"
      public $country =>
      string(2) "US"
      public $postalCode =>
      string(5) "94086"
    }
    public $commercialCardCode =>
    NULL
    ...

每个转换后的对象都将具有与我们API参考中所述相同的属性名称：https://developer.intuit.com/app/developer/qbpayments/docs/api/resources/all-entities/charges页面

调用可能会因为令牌过期、服务器故障或无效请求体等原因失败。您可以使用$response->failed()进行检查。请参阅我们的响应接口以获取支持的操作列表，以诊断失败的请求。

OAuth支持

开发者可以使用此库来处理OAuth 2.0协议。它支持

生成授权URL
生成授权码URL(string $scope, string $userDefinedState = "state") : string
获取OAuth 2.0 Bearer令牌
创建用于交换的请求(string $code) : RequestInterface
获取用户信息
创建用于获取用户信息的请求(string $accessToken) : RequestInterface
刷新OAuth 2.0令牌
创建刷新令牌的请求(string $refreshToken) : RequestInterface
撤销OAuth 2.0令牌
创建撤销令牌的请求(string $token)
从OAuth 1.0迁移令牌到OAuth 2.0 createRequestToMigrateToken(string $consumerKey, string $consumerSecret, string $oauth1AccessToken, string $oauth1TokenSecret, string $scopes) : RequestInterface

为了使用OAuth 2.0，开发者需要创建两个对象

OAuth2Authenticator：用于创建与OAuth 2.0相关的请求
PaymentClient：用于发送与OAuth 2.0相关的请求

支付SDK不提供解析OAuth 2.0响应的任何支持。由于OAuth 2.0请求的响应总是JSON格式，简单的json_decode($response->getBody(), true)即可。

示例

<?php
require "vendor/autoload.php";

use QuickBooksOnline\Payments\OAuth\OAuth2Authenticator;
use QuickBooksOnline\Payments\PaymentClient;

$client = new PaymentClient();
$oauth2Helper = OAuth2Authenticator::create([
  'client_id' => 'Your Client ID',
  'client_secret' => 'Your Client Secret',
  'redirect_uri' => 'The redirect URI under the app's Keys tab',
  'environment' => 'development' // or 'environment' => 'production' 
]);

//The scope for the token. 
$scope = "com.intuit.quickbooks.accounting openid profile email phone address";

$authorizationCodeURL = $oauth2Helper->generateAuthCodeURL($scope);
//Sample URL: https://appcenter.intuit.com/connect/oauth2?client_id=L0vmMZIfwUBfv9PPM96dzMTYATnLs6TSAe5SyVkt1Z4MAsvlCU&scope=com.intuit.quickbooks.accounting%20openid%20profile%20email%20phone%20address&redirect_uri=https%3A%2F%2Fdeveloper.intuit.com%2Fv2%2FOAuth2Playground%2FRedirectUrl&response_type=code&state=JBAJE

//Redirect User to the $authorizationCodeURL, and a code will be sent to your redirect_uri as query paramter
$code = $_GET['code'];
$request = $oauth2Helper->createRequestToExchange($code);
$response = $client->send($request);
if($response->failed()){
  $code = $response->getStatusCode();
  $errorMessage = $response->getBody();
  echo "code is $code \n";
  echo "body is $errorMessage \n";
}else{
  //Get the keys
  $array = json_decode($response->getBody(), true);
  $refreshToken = $array["refresh_token"];
  //AB11570127472xkApQcZmbTMGfzzEOgMWl2Br5h8IEgxRULUbO
}

操作

PHP支付SDK支持所有六个支付端点：BankAccounts、Cards、Charges、EChecks、Tokens、Transactions。这些可以在我们的QuickBooks Payments API Explorer中找到。

为了构造每个API端点的正文，开发者首先需要以数组格式构造请求正文，然后使用Operations的buildFrom方法将数组转换为对象。

例如，要将表示卡的数组转换为$card对象，请使用

CardOperations::buildFrom($cardarray);

所有支持的operations都可以在这里找到：Operations

对象创建后，可以使用它发送请求。所有端点的函数名都来源于API参考。例如，要创建一张卡，应使用

$client->createCard($card);

如果您想为请求提供自定义的Request-Id，请使用

$client->createCard($card, $requestId);

否则，系统将提供随机生成的请求ID。

要检查可用函数的列表，请参考此处：API端点操作

拦截器

拦截器用于拦截请求和响应。它可以用于记录请求或响应。这可以用作解决连接超时或令牌过期等问题的重试机制。

此SDK中提供的默认拦截器有

StackTraceLoggerInterceptor：类似于log4j，它将堆栈跟踪记录到日志文件。StackTraceLoggerIntercepto将所有内容记录到一个错误日志中。
RequestResponseLoggerInterceptor：它将在每次发送和接收时记录完整的请求和响应。它将隐藏OAuth 2.0令牌。RequestResponseLoggerInterceptor将在文件中记录每个请求，并在文件中记录每个响应。
ExceptionOnErrorInterceptor：如果请求失败，它将抛出异常。

根据需要，您可以通过继承InterceptorInterface来定义自己的拦截器以拦截请求和响应。

要更改发送给支付API的请求，请定义您的before(RequestInterface & $request, PaymentClient $client)方法。
要更改接收到的响应，请定义您的after(ResponseInterface & $response, PaymentClient $client)方法。
要拦截未修改的请求和响应，请定义您的intercept(RequestInterface $request, ResponseInterface $response, PaymentClient $client)方法。

要向客户端添加拦截器，请使用

$client->addInterceptor("interceptorName", new InterceptorImplementation());

要按名称删除拦截器，请使用

$client->removeInterceptor($name);

示例：要为SDK发送的每个实际请求和响应启用文件存储

$client->addInterceptor("requestresponselogger", new RequestResponseLoggerInterceptor("/your/directory/to/store/files", 'America/Los_Angeles'));

要为SDK发送的每个事务启用日志记录

$client->addInterceptor("tracelogger", new StackTraceLoggerInterceptor("/your/file/to/log/the/transaction", 'America/Los_Angeles'));

错误处理

默认情况下，每个$response对象都有一个failed()方法，用于判断请求是否成功。成功的请求定义为状态码为200/201。任何其他状态码都会导致$response->failed()方法返回true。如果请求失败，您可以使用我们提供的支持的诊断功能来获取更多信息。

问题

如果您发现SDK的任何错误，或想请求某个功能，请在https://help.developer.intuit.com/s/创建支持票据，或向我们发送拉取请求。贡献总是受欢迎的！

walter silva cruz / quickbooks-payments-sdk

维护者

详细信息