README

为REST API版本3编写的Forte客户端库

Forte API文档

https://restdocs.forte.net/

安装

运行以下命令将此库包含到您的项目中：

composer require rentpost/forte-payments-php

配置

首先，您需要创建一个配置文件，定义环境和它们的配置设置。以下是一个示例，我们展示了Symfony服务容器配置。但是，这里只是传递以下格式的数组：

[
  'environments' => [
    'sandbox' => [
      'access_id' => 'xxxxxxxx',
      'secure_key' => 'xxxxxxxx',
      ...
    ],
    'live' => [
      'access_id' => 'xxxxxxxx',
      'secure_key' => 'xxxxxxxx',
      ...
    ],
  ],
]

需要注意的是，Forte的沙盒环境对许多资源来说相当有限。因此，可以覆盖某些“子资源”（API资源/端点）使用哪个环境。

开发环境

以下是一个开发环境的示例Symfony服务容器yaml配置，使用一个“livetest”环境，并具有特定的子资源覆盖。

parameters:
  forte_api_client_settings:
    environments:
      sandbox:
        access_id: "%forte_api_default_access_id%"
        secure_key: "%forte_api_default_secure_key%"
        authenticating_organization_id: "%forte_api_default_authenticating_organization_id%"
        sandbox: "%forte_api_default_sandbox%"
        base_uri: ~
        debug: false
      livetest:
        access_id: "%forte_api_livetest_access_id%"
        secure_key: "%forte_api_livetest_secure_key%"
        authenticating_organization_id: "%forte_api_livetest_authenticating_organization_id%"
        sandbox: "%forte_api_livetest_sandbox%"
        base_uri: ~
        debug: false

生产环境

一个简单的生产环境Symfony服务容器配置，没有任何必要的覆盖。

parameters:
  forte_api_client_settings:
    environments:
      live:
        access_id: "%forte_api_default_access_id%"
        secure_key: "%forte_api_default_secure_key%"
        authenticating_organization_id: "%forte_api_default_authenticating_organization_id%"
        sandbox: "%forte_api_default_sandbox%"
        base_uri: ~
        debug: false

使用方法

以下是一个信用卡“销售”交易的示例。

PSR Logger

我们首先创建一个虚拟日志记录器。请随意使用任何PSR兼容的日志记录器。当配置中启用调试时，此日志记录器会被使用。否则，所有异常都将暴露出来，必须被捕获。

use Psr\Log\LoggerInterface;

namespace Acme\File;

class Logger implements LoggerInterface
{

  public function log($level, $message, array $context = []) {
    // Handle logging
  }

  // Other interface methods
}

创建交易

要使用，您需要调用Rentpost\ForteApi\Client\Factory::make方法，这将为您提供一个Rentpost\ForteApi\Client\ForteClient对象。该ForteClient对象提供了对所有“子资源”（Forte API端点/资源）的访问。

该库使用Model和Attribute对象来帮助进行验证和序列化。任何复杂值都将使用一个Attribute。一个Model是Forte API资源的对象表示，以及所有必需和可选参数。

use Acme\File\Logger as FileLogger;
use Rentpost\ForteApi\Attribute;
use Rentpost\ForteApi\Client\Factory as ForteApiClientFactory;
use Rentpost\ForteApi\Exception\Request\AbstractRequestException;
use Rentpost\ForteApi\Model;

// The first parameter is our settings array.  See the "Configuration" section
$settings = [
  'environments' => [
    'sandbox' => [
      'access_id' => 'xxxxxxxx',
      'secure_key' => 'xxxxxxxx',
      ...
    ],
    'live' => [
      'access_id' => 'xxxxxxxx',
      'secure_key' => 'xxxxxxxx',
      ...
    ]
  ],
];

$forteClient = new ForteApiClientFactory::make($settings, new FileLogger());

$organizationId = new Attribute\Id\OrganizationId('org_123456');
$locationId = new Attribute\Id\LocationId('loc_123456');

$card = new Model\Card();
$card->setCardType('visa')
  ->setNameOnCard('John Doe')
  ->setAccountNumber('1234567890')
  ->setExpireMonth('01')
  ->setExpireYear('2019')
  ->setCardVerificationValue('123');

$address = new Model\PhysicalAddress();
  ->setStreetLine1('123 Foo St.')
  ->setStreetLine2('Apt. 123')
  ->setLocality('New York') // City/town/village
  ->setRegion('NY') // State or province
  ->setPostalCode(new Attribute\PostalCode('12345'));

$transaction = new Model\Transaction();
$transaction->setAction('sale')
  ->setCard($card) // Or setEcheck for ACH
  ->setBillingAddress($address)
  ->setOrderNumber('PO-12345')
  ->setAuthorizationAmount(new Attribute\Money('100.00'))
  ->setCustomerIpAddress(new Attribute\IpAddress('192.168.0.1'));

try {
  $forteClient->useTransactions()->create(
    $organizationId,
    $locationId,
    $transaction
  );
} catch (AbstractRequestException $e) {
  $logger->log($e->getModel()->getResponse()->getResponseDesc());

  throw $e;
}

测试

此库使用make食谱来执行所有必要的命令。要查看食谱列表，只需执行make。

需求

在Forte的沙盒环境中运行测试不会返回许多资源的任何有意义的返回结果。因此，需要额外的“livetest”账户来运行各种测试。这是一个真实账户。您可以用生产账户代替（不建议）。但是，请注意，无论哪种情况，如果用于交易端点，都会涉及真实资金的转移。如果需要，Forte可以为您设置一个带有非常低交易限制的“livetest”账户，以防止错误。

以下开发composer包是进行自动测试所必需的。

"phpunit/phpunit"（版本7.0+）
"vladahejda/phpunit-assert-exception"用于assertException和相关特性

PHPUnit用于单元测试和集成测试（测试实际对Forte的API调用）

配置

集成测试需要一些设置。这是通过test/settings.php文件完成的。请参考test/settings.php.dist作为示例。

运行

在运行测试之前，您需要确保项目已初始化，并且通过Composer安装了供应商包。要这样做，首先运行make init。然后您可以按以下方式运行测试：

make test

问题/错误/问题

如果您有任何问题或问题，请随时对此存储库提出问题

待办事项

还有一些未完成/尚未支持的“子资源”类（即：Forte端点/资源）。这仅仅是因为我们还没有使用这些。如果您愿意，可以将这些提交为pull request，或者如有必要，提交问题票据。

贡献

欢迎新成员加入本项目。如果您有兴趣贡献，请发送一封礼貌的电子邮件到dev@rentpost.com

作者和维护者

Jacob Thomason jacob@rentpost.com
Sam Anthony sam@expertcoder.io

许可证

本库采用MIT许可证发布。

rentpost / forte-payments-php

维护者

详细信息