Mollie API client for PHP

Accepting iDEAL, Apple Pay, Bancontact, SOFORT Banking, Creditcard, SEPA Bank transfer, SEPA Direct debit, PayPal, Belfius Direct Net, KBC/CBC, paysafecard, ING Home'Pay, Giftcards, Giropay, EPS and Przelewy24 online payments without fixed monthly costs or any punishing registration procedures. Just use the Mollie API to receive payments directly on your website or easily refund transactions to your customers.

Requirements

To use the Mollie API client, the following things are required:

• Get yourself a free Mollie account. No sign up costs.
• Now you're ready to use the Mollie API client in test mode.
• Follow a few steps to enable payment methods in live mode, and let us handle the rest.
• PHP >= 7.0
• Up-to-date OpenSSL (or other SSL/TLS toolkit)

For leveraging Mollie Connect (advanced use cases only), we recommend also installing our OAuth2 client.

Composer Installation

By far the easiest way to install the Mollie API client is to require it with Composer.

$ composer require mollie/mollie-api-php:^2.0

{
    "require": {
        "mollie/mollie-api-php": "^2.0"
    }
}

The version of the API client corresponds to the version of the API it implements. Check the notes on migration to see what changes you need to make if you want to start using a newer API version.

Manual Installation

If you're not familiar with using composer we've added a ZIP file to the releases containing the API client and all the packages normally installed by composer. Download the mollie-api-php.zip from the releases page.

Include the vendor/autoload.php as shown in Initialize example.

How to receive payments

To successfully receive a payment, these steps should be implemented:

1. Use the Mollie API client to create a payment with the requested amount, currency, description and optionally, a payment method. It is important to specify a unique redirect URL where the customer is supposed to return to after the payment is completed.

2. Immediately after the payment is completed, our platform will send an asynchronous request to the configured webhook to allow the payment details to be retrieved, so you know when exactly to start processing the customer's order.

3. The customer returns, and should be satisfied to see that the order was paid and is now being processed.

Find our full documentation online on docs.mollie.com.

Getting started

Initializing the Mollie API client, and setting your API key.

$mollie = new \Mollie\Api\MollieApiClient();
$mollie->setApiKey("test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM");

Creating a new payment.

$payment = $mollie->payments->create([
    "amount" => [
        "currency" => "EUR",
        "value" => "10.00"
    ],
    "description" => "My first API payment",
    "redirectUrl" => "https://webshop.example.org/order/12345/",
    "webhookUrl"  => "https://webshop.example.org/mollie-webhook/",
]);

After creation, the payment id is available in the $payment->id property. You should store this id with your order.

After storing the payment id you can send the customer to the checkout using the $payment->getCheckoutUrl().

header("Location: " . $payment->getCheckoutUrl(), true, 303);

This header location should always be a GET, thus we enforce 303 http response code

For a payment create example, see Example - New Payment.

Retrieving payments

We can use the $payment->id to retrieve a payment and check if the payment isPaid.

$payment = $mollie->payments->get($payment->id);

if ($payment->isPaid())
{
    echo "Payment received.";
}

Or retrieve a collection of payments.

$payments = $mollie->payments->page(); 

For an extensive example of listing payments with the details and status, see Example - List Payments.

Payment webhook

When the status of a payment changes the webhookUrl we specified in the creation of the payment will be called.
There we can use the id from our POST parameters to check te status and act upon that, see Example - Webhook.

Multicurrency

Since 2.0 it is now possible to create non-EUR payments for your customers. A full list of available currencies can be found in our documentation.

$payment = $mollie->payments->create([
    "amount" => [
        "currency" => "USD",
        "value" => "10.00"
    ],
    "description" => "Order #12345",
    "redirectUrl" => "https://webshop.example.org/order/12345/",
    "webhookUrl"  => "https://webshop.example.org/mollie-webhook/",
]);

After creation, the settlementAmount will contain the EUR amount that will be settled on your account.

Fully integrated iDEAL payments

If you want to fully integrate iDEAL payments in your web site, some additional steps are required. First, you need to retrieve the list of issuers (banks) that support iDEAL and have your customer pick the issuer he/she wants to use for the payment.

Retrieve the iDEAL method and include the issuers

$method = $mollie->methods->get(\Mollie\Api\Types\PaymentMethod::IDEAL, ["include" => "issuers"]);

$method->issuers will be a list of objects. Use the property $id of this object in the API call, and the property $name for displaying the issuer to your customer. For a more in-depth example, see Example - iDEAL payment.

Create a payment with the selected issuer:

$payment = $mollie->payments->create([
    "amount" => [
        "currency" => "EUR",
        "value" => "10.00"
    ],
    "description" => "My first API payment",
    "redirectUrl" => "https://webshop.example.org/order/12345/",
    "webhookUrl"  => "https://webshop.example.org/mollie-webhook/",
    "method"      => \Mollie\Api\Types\PaymentMethod::IDEAL,
    "issuer"      => $selectedIssuerId, // e.g. "ideal_INGBNL2A"
]);

The _links property of the $payment object will contain an object checkout with a href property, which is a URL that points directly to the online banking environment of the selected issuer. A short way of retrieving this URL can be achieved by using the $payment->getCheckoutUrl().

Refunding payments

The API also supports refunding payments. Note that there is no confirmation and that all refunds are immediate and definitive. refunds are supported for all methods except for paysafecard and gift cards.

$payment = $mollie->payments->get($payment->id);

// Refund € 2 of this payment
$refund = $payment->refund([
    "amount" => [
        "currency" => "EUR",
        "value" => "2.00"
    ]
]);

For a working example, see Example - Refund payment.

Enabling debug mode

When debugging it can be convenient to have the submitted request available on the ApiException.

In order to prevent leaking sensitive request data into your local application logs, debugging is disabled by default.

To enable debugging and inspect the request:

/** @var $mollie \Mollie\Api\MollieApiClient */
$mollie->enableDebugging();

try {
    $mollie->payments->get('tr_12345678');
} catch (\Mollie\Api\Exceptions\ApiException $exception) {
    $request = $exception->getRequest();
}

If you're logging the ApiException, the request will also be logged. Make sure to not retain any sensitive data in these logs and clean up after debugging.

To disable debugging again:

/** @var $mollie \Mollie\Api\MollieApiClient */
$mollie->disableDebugging();

Note that debugging is only available when using the default Guzzle http adapter (Guzzle6And7MollieHttpAdapter).

API documentation

If you wish to learn more about our API, please visit the Mollie Developer Portal. API Documentation is available in English.

Want to help us make our API client even better?

Want to help us make our API client even better? We take pull requests, sure. But how would you like to contribute to a technology oriented organization? Mollie is hiring developers and system engineers. Check out our vacancies or get in touch.

License

BSD (Berkeley Software Distribution) License. Copyright (c) 2013-2018, Mollie B.V.

Support

Contact: www.mollie.com — info@mollie.com — +31 20 820 20 70