Alma PHP API client
This is the official PHP API client for Alma.
This PHP API Client is being used in production on thousands of e-commerce websites and provides the necessary
endpoints to build a full-fledge integration.
It does not, however, implement the full Alma API as documented here yet.
If you find yourself needing to use some endpoints that are not yet implemented, feel free to reach out! (or even better, submit a PR :))
Installation
The Alma PHP API Client library requires at least PHP 5.6. A modern, supported PHP version is highly recommended.
Composer
You would normally install this package via Composer:
composer require alma/alma-php-client
Without Composer
- Head over to the releases and grab the
alma-php-client.zipfile of the latest published library version. - Unzip the library into your vendors directory.
- Require the included Composer's autoload file:
require_once "path/to/alma-php-client/vendor/autoload.php";- You should then be able to use Alma as if it was installed with Composer.
Typical usage
An example of using the API client. (check API documentation for further information)
1. instanciate client in test mode
$alma = new Alma\API\Client($apiKey, ['mode' => Alma\API\Client::TEST_MODE]);2. check eligibility
// ...
$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. check available fee plans and build payment form
// ...
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>";
// ...You can prefer use eligibilities to do this work but this part of code allow you to get more familiar with feePlans definitions.
4. build a payment plan
// ...
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. create a payment and redirecting a customer to the payment page
// ...
$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' => '[email protected]',
'line1' => '1 rue de Rome',
'postal_code' => '75001',
'city' => 'Paris',
'country' => 'FR',
],
'shipping_address' =>
[
'first_name' => 'John',
'last_name' => 'Doe',
'email' => '[email protected]',
'line1' => '1 rue de Rome',
'postal_code' => '75001',
'city' => 'Paris',
'country' => 'FR',
],
],
'customer' =>
[
'first_name' => 'John',
'last_name' => 'Doe',
'email' => '[email protected]',
'phone' => '06 12 34 56 78',
'addresses' =>
[
[
'first_name' => 'John',
'last_name' => 'Doe',
'email' => '[email protected]',
'phone' => '06 12 34 56 78',
],
],
],
]
);
// store $payment->id and link it to the customer order here ;)
header('Location: ' . $payment->url);
exit();
// ...6. receive notification about payment validation by IPN
(can be given on payment creation or statically defined in your Alma Dashboard)
// ...
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. retrieve payment information and display status
// ...
$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;
}
// ...License
Alma PHP Client is distributed under the MIT license.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent