README

要求

PHP 5.6 或更高版本
JSON PHP 扩展
cURL PHP 扩展

安装

您可以使用composer安装PHP绑定

composer require gingerpayments/ginger-php

您也可以通过注册自动加载函数而不使用Composer来使用PHP绑定

spl_autoload_register(
    function($fqcn) {
        if (substr($fqcn, 0, 7) === 'Ginger\\') {
            return;
        }

        $pathToGinger = __DIR__ . '/relative/path/to/ginger';
        $class = substr($fqcn, 7);
        $path = sprintf('%s/src/%s.php', $pathToGinger, str_replace('\\', '/', $class));

        if (is_file($path)) {
            require_once $path;
        }
    }
);

或者，您可以仅包含由composer生成的自动加载器

require_once 'ginger-php/vendor/autoload.php';

入门指南

首先，使用您的API密钥和API端点创建一个新的API客户端

use \Ginger\Ginger;

$client = Ginger::createClient('https://api.example.com', 'your-api-key');

启动支付

您可以通过创建一个新的订单来启动新的支付

$order = $client->createOrder(
    [
        'merchant_order_id' => 'my-custom-order-id-12345',
        'currency' => 'EUR',
        'amount' => 2500, // Amount in cents
        'description' => 'Purchase order 12345',
        'return_url' => 'https://www.example.com',
        'transactions' => [
            [
                'payment_method' => 'credit-card'
            ]
        ]
    ]
);

创建订单后，会创建一个事务并将其与订单关联。您需要将用户重定向到事务的支付URL，如下所示

$paymentUrl = $order['order_url'];

还建议您将订单ID存储在某个地方，以便您可以稍后检索有关它的信息

$orderId = $order['id'];

有关订单的更多数据，请参阅您PSP提供的API文档，了解有关各种支付方式和选项的更多信息。

获取订单

如果您想检索现有订单，请使用客户端上的getOrder方法

$order = $client->getOrder($orderId);

这将返回包含所有订单信息的关联数组。

更新订单

某些字段不是只读的，您可以在订单创建后更新它们。您可以使用客户端上的updateOrder方法执行此操作

$order = $client->getOrder($orderId);
$order['description'] = "New Order Description";
$updatedOrder = $client->updateOrder($orderId, $order);

启动退款

您可以使用客户端上的refundOrder方法对现有订单进行退款

$refundOrder = $client->refundOrder($orderId, ['amount' => 123, 'description' => 'My refund']);

捕获订单事务

您可以使用captureOrderTransaction方法启动订单事务的捕获

$client->captureOrderTransaction($orderId, $transactionId);

获取iDEAL发行商

当您使用iDEAL支付方式创建订单时，您需要提供一个发行商ID。发行商ID是用户选择的银行的标识符。您可以使用getIdealIssuers方法检索所有可能的发行商

$issuers = $client->getIdealIssuers();

然后，您可以使用这些信息向用户提供一个可能的银行列表供选择。

获取货币列表

您可以使用以下请求检索ISO 4217格式的可用货币列表。

$currencies = $client->getCurrencyList();

对于您账户的每个可用支付方式，您都会收到一个包含可用ISO 4217货币的列表。

自定义请求

您可以使用send方法发送API接受的任何请求。例如，您可以使用以下方法而不是使用createOrder方法

$result = $client->send(
    'POST', // Request method
    '/orders', // API path
    $orderData // Data to send with the request; optional
);

然后，$result变量将包含API返回的解码JSON。

使用不同的CA包

如果您需要使用与系统或cURL安装附带的不同CA包，您可以提供自定义cURL选项来指示您的CA包的位置，如下所示

use \Ginger\Ginger;

$client = Ginger::createClient(
    'https://api.example.com',
    'your-api-key',
    [
        CURLOPT_CAINFO => '/path/to/ca-bundle.pem'
    ]
);

有关要使用哪些cURL选项的更多信息，请参阅PHP cURL文档。

自定义HTTP客户端

出于兼容性原因，此库附带自己的最小HTTP客户端。如果您想使用不同的HTTP客户端，您可以实施Ginger\HttpClient\HttpClient接口，然后构建自己的客户端

$myHttpClient = new MyHttpClient();
$client = new Ginger\ApiClient($myHttpClient);

请确保您的HTTP客户端为所有请求添加端点URL和API版本前缀，并使用HTTP基本认证通过API密钥进行认证。

API文档

有关完整的API文档，请参考您的PSP提供的资源。

gingerpayments / ginger-php

维护者

详细信息