README

Gr4vy 提供通过一个统一的 API 集成任何支付功能。更多详情，请访问 gr4vy.com。

安装

Gr4vy PHP SDK 可以通过 Composer 进行安装。

composer require gr4vy/gr4vy-php

入门指南

要发出第一个 API 调用，您需要 请求 设置一个 Gr4vy 实例。请联系我们的销售团队获取演示。

一旦您设置了 Gr4vy 账户，您需要前往 集成 面板并生成一个私有密钥。我们建议将此密钥存储在安全位置，但在本代码示例中，我们只是从磁盘读取文件。

<?php
require __DIR__ . '/../vendor/autoload.php';

$privateKeyLocation = __DIR__ . "/private_key.pem";

$config = new Gr4vy\Gr4vyConfig("[YOUR_GR4VY_ID]", $privateKeyLocation);

try {
    $result = $config->listBuyers();
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling listBuyers: ', $e->getMessage(), PHP_EOL;
}

环境

SDK 默认环境为 "sandbox"，要将交易发送到生产环境，请在 Gr4vyConfig 中设置环境。

$config = new Gr4vy\Gr4vyConfig("[YOUR_GR4VY_ID]", $privateKeyLocation, false, "sandbox");

$config = new Gr4vy\Gr4vyConfig("[YOUR_GR4VY_ID]", $privateKeyLocation, false, "production");

Gr4vy Embed

要为 Gr4vy Embed 创建令牌，请调用 config->getEmbedToken() 函数，并传入金额、货币、可选的买家信息和可选的 Gr4vy Embed 结算会话。

//A checkout session allows multiple transaction attempts to be tied together
$checkoutSession = $config->newCheckoutSession();

echo $config->getEmbedToken(
  array(
    "amount"=> 200,
    "currency" => "USD",
    "buyer_id"=> "d757c76a-cbd7-4b56-95a3-40125b51b29c"
  ), 
  $checkoutSession["id"]
);

或者，通过单个调用生成结算会话和 Embed 令牌

echo $config->getEmbedTokenWithCheckoutSession(
  array(
    "amount"=> 200,
    "currency" => "USD",
    "buyer_id"=> "d757c76a-cbd7-4b56-95a3-40125b51b29c"
  )
);

现在您可以将此令牌传递到前端，以便使用它来验证 Gr4vy Embed。

可以使用 buyerId 和 buyerExternalIdentifier 字段来允许令牌拉取用户的先前存储的支付方式。在以这种方式使用之前，必须先创建买家。

$config = new Gr4vy\Gr4vyConfig("[YOUR_GR4VY_ID]", $privateKeyLocation);

$buyer_request = array("external_identifier"=>"412231123","display_name"=>"Tester T.");
$buyer = $config->addBuyer($buyer_request);

$embed = array("amount"=> 200, "currency" => "USD", "buyer_id"=> $buyer["id"]);
$embedToken = $config->getEmbedToken($embed);

结算会话

结算会话可以在多个 Embed 会话之间使用，以跟踪重试或购物车更新。为此，可以在多个 getEmbedToken 调用中使用相同的 checkoutSessionId。

注意：结算会话自创建起有效期为 1 小时。

$config->getEmbedToken(
  array(
    "amount"=> 200,
    "currency" => "USD",
    "buyer_id"=> "d757c76a-cbd7-4b56-95a3-40125b51b29c"
  ), 
  $storedCheckoutSessionId
);

初始化

客户端可以使用 Gr4vy ID（gr4vyId）和私有密钥进行初始化。

$config = new Gr4vy\Gr4vyConfig("acme", $privateKeyLocation);

或者，您可以将服务器的 host 设置为直接使用。

$config = new Gr4vy\Gr4vyConfig("acme", $privateKeyLocation);
$config->setHost("https://api.acme.gr4vy.app");

您的 API 密钥可以在管理面板的 集成 选项卡上创建。

多商户

在多商户环境中，可以通过将 merchantAccountId 传递给 Config 来设置商户账户 ID。

$config = new Gr4vy\Gr4vyConfig("[YOUR_GR4VY_ID]", $privateKeyLocation, false, "sandbox", "default");

$config = new Gr4vy\Gr4vyConfig("[YOUR_GR4VY_ID]", $privateKeyLocation, false, "sandbox", "my_merchant_account_id");

进行 API 调用

此库方便地将每个 API 路径映射到单独的函数。例如，GET /buyers?limit=100 将是

$result = $config->listBuyers(100);

要创建或更新资源，应在请求中发送一个包含请求数据的 array。

$buyer_request = array("external_identifier"=>"412231123","display_name"=>"Tester T.");
$buyer = $config->addBuyer($buyer_request);

同样，要更新买家，您需要传入 BuyerUpdateRequest。

$buyer_update = array("external_identifier"=>"testUpdateBuyer");
$result = $config->updateBuyer($result["id"], $buyer_update);

生成 API 携带令牌

SDK 可以用来为其他请求库创建 API 访问令牌。

$bearerToken = Gr4vyConfig::getToken($privateKeyLocation, array("*.read", "*.write"))->toString();

第一个参数是私有密钥的位置。第二个参数是令牌作用域的数组。

生成的令牌可以用作 HTTP 请求头中的携带令牌。

Authorization: Bearer <bearerToken>

日志记录 & 调试

SDK 使得请求和响应能够方便地输出到控制台。

$debugging = true;
$config = new Gr4vyConfig(self::$gr4vyId, self::$privateKeyLocation, $debugging);

这将打印请求的调试输出到控制台。

开发

测试

要运行测试，存储蜘蛛环境的私有密钥，然后运行以下命令。

composer install
./vendor/bin/phpunit test/

发布

本项目通过Packagist进行发布。新版本通过创建新的Git标签来发布。

许可证

此库采用MIT许可证发布。