README

ZfrPaymill是一个基于Guzzle的现代PHP库，用于Paymill支付系统。

注意：此库不包含测试，主要是因为我不确定如何为API包装器编写测试。不要犹豫，来帮忙吧 ;-).

依赖关系

• Guzzle: >= 3.5

安装

官方只支持使用Composer安装ZfrPaymill

php composer.phar require zfr/zfr-paymill:1.*

教程

首先，您需要实例化Paymill客户端，传递您的私人API密钥（您可以在Paymill设置中找到它）

$client = new PaymillClient('my-api-key');

当前支持的API版本是2.0。

如何使用它？

使用客户端很简单。例如，下面是如何创建一个新报价的示例

$details = $client->createOffer(array(
    'name'     => 'MyOffer',
    'amount'   => 500,
    'currency' => 'EUR',
    'interval' => '1 MONTH'
));

参数与官方文档中的一对一映射（如有任何参考，您也可以检查ZfrPaymill\Client\ServiceDescription\Paymill-2.0.php文件）。要了解响应的外观，请参阅官方API参考。

对于大多数get方法，您必须传递一个id参数，如下所示

$details = $client->getClient(array('id' => 'my-client-id'));

异常

ZfrPaymill尽力抛出有用的异常。可能发生两种类型的异常

• Guzzle异常：默认情况下，Guzzle在发送实际请求之前，根据在服务描述中定义的规则自动验证参数。如果您遇到这些异常，您的代码可能存在问题。
• ZfrPaymill异常：这些异常在Paymill侧发生错误时抛出。每个异常都实现了ZfrPaymill\Exception\ExceptionInterface。

以下都是异常

• ZfrPaymill\Exception\UnauthorizedException：您的API密钥可能不正确...
• ZfrPaymill\Exception\TransactionErrorException：交易无法完成。
• ZfrPaymill\Exception\NotFoundException：当客户端接收到404异常时抛出。
• ZfrPaymill\Exception\ValidationErrorException：您的发送数据中存在一些错误。
• ZfrPaymill\Exception\ServerErrorException：Paymill可能出错...

使用

try {
    $client->createTransaction(array(
        'amount'   => 4000,
        'currency' => 'EUR',
        'token'    => '1234'
    ));
} catch (\ZfrPaymill\Exception\TransactionErrorException $exception) {
    // Seems the transaction failed, let's see why:
    $why = $exception->getMessage();

    // Let's also get the response to have more info:
    $response = $exception->getResponse();
} catch (\Exception $exception) {
    // Catch any other exception...
}

对于交易/退款/预先授权方法，Paymill可能会在发生错误的情况下返回状态码200。Paymill将此错误存储在响应中的response_code属性中。但是，ZfrPaymill会自动检查此属性是否已设置，并抛出TransactionErrorException，这样您就不需要自行检查，只需捕获异常即可。

高级使用

监听器

由于ZfrPaymill基于Guzzle，您可以利用其所有功能。例如，您可以通过在客户端上调用addSubscriber方法来添加各种事件的监听器。

完整参考

以下是一个所有方法的完整列表，包括参数名称的官方文档链接

与支付相关的函数

• array createPayment(array $args = array()) 文档
• array deletePayment(array $args = array()) 文档
• array getPayment(array $args = array()) 文档
• array getPayments(array $args = array()) 文档

预授权相关方法

• array createPreauthorization(array $args = array()) 文档
• array deletePreauthorization(array $args = array()) 文档
• array getPreauthorization(array $args = array()) 文档
• array getPreauthorizations(array $args = array()) 文档

交易相关方法

• array createTransaction(array $args = array()) 文档
• array getTransaction(array $args = array()) 文档
• array getTransactions(array $args = array()) 文档
• array updateTransaction(array $args = array()) 文档

退款相关方法

• array getRefund(array $args = array()) 文档
• array getRefunds(array $args = array()) 文档
• array refundTransaction(array $args = array()) 文档

客户端相关方法

• array createClient(array $args = array()) 文档
• array deleteClient(array $args = array()) 文档
• array getClient(array $args = array()) 文档
• array getClients(array $args = array()) 文档
• array updateClient(array $args = array()) 文档

报价相关方法

• array createOffer(array $args = array()) 文档
• array deleteOffer(array $args = array()) 文档
• array getOffer(array $args = array()) 文档
• array getOffers(array $args = array()) 文档
• array updateOffer(array $args = array()) 文档

订阅相关方法

• array createSubscription(array $args = array()) 文档
• array deleteSubscription(array $args = array()) 文档
• 获取订阅数组 getSubscription(array $args = array()) 文档
• 获取订阅数组 getSubscriptions(array $args = array()) 文档
• 更新订阅数组 updateSubscription(array $args = array()) 文档

WEBHOOK 相关方法

• 创建WEBHOOK数组 createWebhook(array $args = array()) 文档
• 删除WEBHOOK数组 deleteWebhook(array $args = array()) 文档
• 获取WEBHOOK数组 getWebhook(array $args = array()) 文档
• 获取WEBHOOK数组 getWebhooks(array $args = array()) 文档
• 更新WEBHOOK数组 updateWebhook(array $args = array()) 文档