README

这是Alma的官方PHP API客户端。

此PHP API客户端已在成千上万的电子商务网站上投入生产使用，并提供了构建完整集成所需的所有端点。然而，它尚未实现此处记录的完整Alma API。如果您需要使用尚未实现的某些端点，请随时联系！或者，更好的是，提交一个PR :))

安装

Alma PHP API客户端库针对所有最近支持的PHP版本进行了测试。强烈推荐使用现代的支持版本。

Composer

您通常通过Composer安装此包

composer require alma/alma-php-client

没有Composer

转到发布版，并获取最新发布库版本的alma-php-client.zip文件。
将库解压到您的 vendors 目录中。
要求包含的Composer的autoload文件

require_once "path/to/alma-php-client/vendor/autoload.php";

然后您应该能够像使用Composer安装的Alma一样使用Alma。

典型用法

使用API客户端的示例。（有关更多信息，请参阅API文档）

1. 以测试模式实例化客户端

$alma = new Alma\API\Client($apiKey, ['mode' => Alma\API\Client::TEST_MODE]);

2. 检查资格

// ...
$amountInCents = 150000; // 1500 euros
$customerBillingCountry = ""; // can be an empty string but NOT null
$customerShippingCountry = "FR"; // billing_address has priority over shipping_address (if not empty)
try {
    $eligibilities = $alma->payments->eligibility(
        [
            'purchase_amount' => $amountInCents,
            'billing_address' => [ // (optional) useful to check eligibility for a specific billing country
                'country' => $customerBillingCountry // can be an empty string but not null
            ],
            'shipping_address' => [ // (optional) useful to check eligibility for a specific shipping country
                'country' => $customerShippingCountry
            ],
            'queries'         =>
                [
                    [
                        'installments_count' => 1,
                        'deferred_days'      => 30,
                    ],
                    [
                        'installments_count' => 2,
                    ],
                    [
                        'installments_count' => 3,
                    ],
                    [
                        'installments_count' => 4,
                    ],
                    [
                        'installments_count' => 10,
                    ],
                ],
        ],
        $raiseOnError = true // throws an exception on 4xx or 5xx http return code
                             // instead of just returning an Eligibility Object with isEligible() === false
    );
} catch (Alma\API\RequestError $error) {
    header("HTTP/1.1 500 Internal Server Error");
    die($error->getMessage());
}

foreach($eligibilities as $eligibility) {
    if (!$eligibility->isEligible()) {
        die('cart is not eligible');
    }
}
// ...

3. 检查可用的费用计划和构建支付表单

// ...
echo "<form>";
echo "<h2>Available feePlans are:</h2>";
foreach($alma->merchants->feePlans($kind = FeePlan::KIND_GENERAL, $installmentsCounts = "all", $includeDeferred = true) as $feePlan) {
    if (!$feePlan->allowed) {
        continue;
    }
    printf('<label for="%s">Pay in %s by %s installments count</label>', $feePlan->getPlanKey(), $feePlan->getDeferredDays(), $feePlan->getInstallmentsCount());
    printf('<input id="radio-%s" type="radio" name="fee-plan" value="%s">', $feePlan->getPlanKey(), $feePlan->getPlanKey());
}
echo "<button type=\"submit\">Submit</button>";
echo "</form>";
// ...

您可以选择使用资格来完成这项工作，但这段代码允许您更好地了解费用计划的定义。

4. 构建支付计划

// ...
function formatMoney(int $amount) {
    return sprintf("%.2f %s", round(intval($amount) / 100, 2), "€");
}
function formatPercent(int $amount) {
    return sprintf("%.2f %s", round(intval($amount) / 100, 2), "%");
}
// ...
foreach($eligibilities as $eligibility) {
    // display following payment plan (or not eligible message) on feePlan selection using javascript.
    printf('<div id="table-%s">', $eligibility->getPlanKey());
    if (!$eligibility->isEligible()) {
        echo "This fee plan is not eligible!";
        echo "</div>";
        continue;
    }
    if (!$paymentPlans = $eligibility->getPaymentPlan()) {
        echo "No payment plan found for current eligibility! (that should not happen)";
        echo "</div>";
        continue;
    }
    echo "<ul>";
    foreach ($paymentPlans as $paymentPlan) {
        $planDefinition     = sprintf(
            "<li>You will pay %s on %s including %s fees & %s of interest</li>",
            formatMoney($paymentPlan['total_amount']),
            (new DateTime())->setTimestamp($paymentPlan['due_date'])->format('Y-m-d'),
            formatMoney($paymentPlan['customer_fee']),
            formatMoney($paymentPlan['customer_interest'])
        );
    }
    echo "</ul>";
    echo "    <div>";
    echo "    Annual Interest Rate:" . formatPercent($eligibility->getAnnualInterestRate()) . "<br>";
    echo "    Order Amount:" . formatMoney($amountInCents);
    echo "    Total Cost Amount:" . formatMoney($eligibility->getCustomerTotalCostAmount());
    echo "    </div>";
    echo "</div>";
}
// ...

5. 创建支付并将客户重定向到支付页面

// ...
$payment = $alma->payments->createPayment(
    [
        'origin'   => 'online',
        'payment'  =>
            [
                'return_url'         => '<where_the_customer_will_be_redirect_after_alma_checkout>',
                'ipn_callback_url'   => '<your_ipn_callback_url>',
                'purchase_amount'    => 150000,
                'installments_count' => 4,
                'custom_data'        =>
                    [
                        'my_very_important_key' => '<the_context_custom_value>',
                    ],
                'locale'             => 'fr',
                'billing_address'    =>
                    [
                        'first_name'  => 'John',
                        'last_name'   => 'Doe',
                        'email'       => 'john-doe@yopmail.fr',
                        'line1'       => '1 rue de Rome',
                        'postal_code' => '75001',
                        'city'        => 'Paris',
                        'country'     => 'FR',
                    ],
                'shipping_address'   =>
                    [
                        'first_name'  => 'John',
                        'last_name'   => 'Doe',
                        'email'       => 'john-doe@yopmail.fr',
                        'line1'       => '1 rue de Rome',
                        'postal_code' => '75001',
                        'city'        => 'Paris',
                        'country'     => 'FR',
                    ],
            ],
        'customer' =>
            [
                'first_name' => 'John',
                'last_name'  => 'Doe',
                'email'      => 'john-doe@yopmail.fr',
                'phone'      => '06 12 34 56 78',
                'addresses'  =>
                    [
                        [
                            'first_name' => 'John',
                            'last_name'  => 'Doe',
                            'email'      => 'john-doe@yopmail.fr',
                            'phone'      => '06 12 34 56 78',
                        ],
                    ],
            ],
    ]
);

// store $payment->id and link it to the customer order here ;)

header('Location: ' . $payment->url);
exit();
// ...

6. 通过IPN接收关于支付验证的通知

（可以在创建支付时提供或在Alma仪表板上静态定义）

// ...
if (!isset($_GET['pid']) || empty($_GET['pid'])) {
     header("HTTP/1.1 400 Bad Request");
     die();
}
// retrieve your local order by payment id
$order = getOrderByPaymentId($_GET['pid'])
if (!$order) {
     header("HTTP/1.1 404 Not Found");
     die();
}

// check $payment->state & do the order / customer stuff you want here :D

header("HTTP/1.1 200");
exit();
// ...

7. 获取支付信息并显示状态

// ...
$payment = $alma->payments->fetch($paymentId);
switch($payment->state) {
    case Alma\API\Entities\Payment::STATE_IN_PROGRESS: break;
    case Alma\API\Entities\Payment::STATE_PAID: break;
}
// ...

许可证

Alma PHP客户端在MIT许可证下发布。

alma/alma-php-client

维护者

详细信息