Download the PHP package daanrijpkema/bluem-php without Composer

On this page you can find all versions of the php package daanrijpkema/bluem-php. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Example code of daanrijpkema/bluem-php

Informations about the package bluem-php

Bluem

Bluem-php for Payment, Mandates, iDIN & IBAN-Name check

A PHP interface for utilizing the Bluem services ePayments, eMandates, iDIN and/or IBAN-Name check. Utilize this library to write your own applications in PHP that communicate with Bluem, without having to handle the flow yourself.

Utilized by other applications as well:

Table of Contents

2.4 is coming soon

A new version of the PHP library will be released in the coming 1-2 months. Starting this release, PHP 8.1 is the minimum required version for this library.

Requirements

Getting started

Install the library through Composer. Run Composer to install this library and dependencies from your project folder.

Refer to the examples for a full example implementation that you can base your own integration on.

Please contact us if you have any questions regarding the examples or the implementation of the library in your project.

Notes per version

Version 2.3.2.4 (latest)

Version 2.3.2.3

Updated certificates.

Version 2.3.2.2

Updated BIC epayments list.

Version 2.3.2

Added BIC to mandate request.

Version 2.3.1

Added BIC to identity request.

Version 2.3

Added PHP 8+ support.

Version 2.2

Webhooks and new payment methods

Version 2.1

Major improvement in code style.

Versions before 2.1

Version 2.0.12

Allowing the verification if the current IP is based in the Netherlands utilizing a geolocation integration *(IP-API).

This feature can be used to determine whether to use iDIN identity checking in any application, as this supports only Dutch banks.

Version 2.0.2:

Triodos Bank, BIC TRIONL2U no longer supported for Identity requests as of 1 june 2021. See: https://www.triodos.nl/veelgestelde-vragen/kan-ik-idin-gebruiken?id=4de127e85eee

Version 2.0.1:

Major release with more stability, validation and features.

Please note: The main Integration class is called Bluem, so to include it, use:

Or use a class alias to ensure code functioning. This is a refactor since version 1.x.

Furthermore, all generally available functions are still available.

No earlier changelog was recorded. Please refer to the commit log for more information.

Testing

For improving future features, unit testing is introduced since november 2021.

Tests are located in the tests folder To run tests:

Testing is done given a .env file. Please ensure that a filled .env file is available. A .env.example file is provided to help you configure it.

Description of the base tests:

Frequently asked questions

I get the message "Unauthorized: Check your account credentials". What should I do?
Please ensure that your SenderID, BrandID and Tokens for Test and/or Production environments are set correctly. Usually this message retains to an invalid configuration OR an unactivated account. If you have checked that the credentials are correct, but you still receive this message, please contact your Bluem account manager.

Can I connect the Identity service with a payment service like E-Mandates or iDEAL so the user is only redirected once?

Configuration

Include the required autoload functions of Composer in your code, if you did not do so already through other dependencies.

Then you can retrieve an object to utilize all functions as below. It is suggested to save these configuration settings in a database or settings handler, so they can be stored by the user instead of in code.

If parts of the Bluem object are not instantiated correctly, the instantiation might throw an exception.

General concept

This library makes it easy to perform communication with Bluem for its services (ePayments, eMandates, iDIN and IBAN-Name Check). The flow for each service is similar and thus easy to understand once you understand and implement one of them.

  1. TransactionRequest (from the website to Bluem): Your application creates a request object, sends it to Bluem servers with authentication.
  2. TransactionResponse (including TransactionURL) (from Bluem to site): Your application receives a response with a URL as entry point into the Bluem environment, if the request was successful.
  3. Bluem Environment: Redirect client to TransactionURL, client (via the checkout) to bank, confirm transaction, back to Merchant (via MerchantReturnURL with eMandates, and via DebtorReturnURL with Payments/Identity), this is trigger for StatusRequest The user is redirected to the response URL at the Bluem servers. In this Bluem environment, the user performs a payment/mandate signing or identity/iDIN check and returns to a predefined URL.
  4. StatusRequest (from the website to Bluem): Using this same package one can check the Status of a request using a second endpoint (given an ID and entranceCode of the transaction defined at the creation of the request). This is vital, as it allows you to change the status of an order or check within your site or app based on transaction status retrieved from Bluem. It is recommended to do this check when the user comes back to your site/app directly after handling the transaction at Bluem AND using a webhook functionality.
  5. StatusUpdate (from Bluem to the website): This response object that comes back from a callback or webhook, contains an updated status that you can process within your application. For example: when the user has paid or verified, and you have to change a product, order or process' status and go to a next step.
  6. Webhook: The webhook functionality allows Bluem to directly and safely push status changes and transaction results to your site or app. Therefore, your orders and transactions will always get updated to the corresponding statuses, no matter what your user does after visiting the Bluem transaction page.

The Webhook is only needed for ePayments and eMandates: online stores/portals that need to know directly the status, for those cases that client closes the browser at a bank after successful confirmation of transaction. Webhook not needed for iDIN as with iDIN the client ALWAYS comes back to website after successful identification. See the Webhook paragraph for implementation instructions.

Please note that the flow for the IBAN-Name check is shorter: a TransactionRequest is performed. The results return as a TransactionResponse. This is because the end-user is not needed; the call is straight to the Bank Database, that provides in the TransactionResponse the IBAN-Name check results.

Preselecting a bank for Payment requests using debtorWallet

Note: This is relevant for bank-based transactions and services:

It is possible to preselect a Bank within your own application for Payments, based on an IssuerID (BIC/Swift code) when creating a Mandate, Payment or Identity request. This can be used if you want to user to select the given bank in your own interface and skip the bank selection within the Bluem portal interface. This reduces the amount of steps required by performing the selection of the bank within your own application and interface by utilizing the preselection feature from the PHP library on the request object as so:

Parameter has to be a valid BIC code of a supported bank. An invalid BIC code will trigger an exception. Please note that supported BICs differ per service as not every bank offers the same services! The supported BIC codes per service can also be requested from a Bluem object, given the service context. As appendix to this Documentation file, you can find a full list of all BICs per context.

Illustrated here is that a list of BICs per context can also be retrieved programmatically:

Input of a different context will trigger an exception. If valid, the result is an array of Bluem\BluemPHP\BIC objects with attributes IssuerID and IssuerName: the BIC and Bank name respectively. You can use this to populate your user interface.

Please note that the BIC list will vary when a different localInstrumentCode is configured. The localInstrumentCode CORE and B2B are supported by different banks. Based on your configuration, the right BIC list is loaded from context automatically and used to verify the debtorWallet.

This method can be used when creating iDIN and when creating iDEAL requests; you could store the selected bank (“Issuer”) on user level and use it when creating a request for your user.

Using different Payment transaction methods

Important note: ensure you have the right BrandID set up for specific payment methods. Refer to your account manager to retrieve a list of the specific BrandIDs per payment method

You can allow the PayPal and Creditcard payment methods by selecting these within the request object before sending it.

To use iDeal, (default option). A BIC can be provided. If left empty, bank selection will occur in the Bluem portal.

To use PayPal, give in a PayPal account email address. The email is also not required.

To use Creditcards, you can set the credit card details as follows (not required)

or

To use Sofort, use the following method:

To use Carte Bancaire, use the following method:

These methods will throw an exception if required information is missing.

Once the request executes, the link to the transaction will send you to the Bluem Portal with the corresponding interface and flow.

Webhooks

Webhooks exist for Payments, eMandates and Identity. They trigger during requests to the Bluem flow and send data to your application. They are vital to ensure all processes are always completed, even if the customer/user does not reach your regular callback method(s) in your flow.

Activate the endpoints by creating an endpoint for testing and production environments. They then need to be configured on Bluem's side and implemented on the client side.

1. How to implement

Create an HTTP-reachable endpoint for TEST and PRODUCTION environments. Examples are:

Call the Webhook() function within that endpoint:

Refer to the examples/payments-webhook.php for a more in-depth example implementation and retrieval of the data when a webhook is received in your application.

You can utilize the following functions on the callback object to get the data from the webhook and process the relevant data.

Note: Most functions return string values, unless otherwise specified.

Functions available in all services:

Payments specific functions:

EMandates specific functions:

Identity specific functions:

2. How to configure

Communicate the endpoint URLs to [email protected] to have these URLs be configured in your account. Please allow for a few working days for this to be configured. We will follow up as soon as the endpoints have been added.

3. Verify that it works

You can POST to your own endpoints to verify that it works. Please contact us for a sample Webhook call that you can use for your service.

Support for webhooks

We can help you troubleshoot any problems you might face after creating the endpoints. We can also help you verify that data gets sent properly. Please contact us if you need help in this regard.

Payments

The following attributes in the config are vital for proper eMandate functionality:

Creating a payment transaction

The Payments service is like the eMandates service, but utilises other parameters. Here is an example:

Requesting a payment status

Similarly to requesting a Mandate status (see below):

Tip for testing with payments

You can, in Bluem test mode, place iDEAL orders of a specific amount, to get a certain status back. This way you can see how it works if a payment succeeds, or if it fails. The available statuses are:

Adding additional data to a request

You can add additional information to a request object before performing it, which can be useful. The data will be stored within the ViaMijnBank Portal for further administrative purposes.

Providing an unknown key or invalid formatted value will cause an exception.

The key options are:

EmailAddress

Include an email address of the customer.

MobilePhoneNumber

Include an email address of the customer.

CustomerProvidedDebtorIBAN

Include an additional Debtor IBAN address of the customer.

CustomerNumber

Include a customer number.

CustomerName

Include a customer name.

AttentionOf

Include a customer title or name of person to be addressed.

Salutation

Include a customer title or name of person to be saluted.

CustomerAddressLine1

Include a first part of an address of the customer.

CustomerAddressLine2

Include a second part of an address of the customer.

DebtorBankID

More instructions follow.

DynamicData

More instructions follow.

eMandates

Mandate specific configuration fields

The following attributes in the bluem_config are vital for proper eMandate functionality. Below is a short description what each configuration field means:

Creating an eMandate Transaction: helper functions

You need certain information to reference a transaction request: an ID (in this case the MandateID), and an entranceCode (basically a timestamp when you started the request). Creating this information can be done using helper functions. When creating a new transaction, the entranceCode and MandateID will be generated within the $bluem.

Generating a mandate ID:

Generating an entrance code:

Creating an eMandate transaction

The default transaction returns to a callback function at a specific URL that then automatically performs a Status Update and can perform further functionalities. It uses the merchantReturnURLBase attribute, set in the parameter when creating the $bluem object to know where to redirect to expect this function. This process automatically adds the mandateID as a GET parameter to the return URL, so it can be picked up for the Status Update.

Tip: you can also combine the creation and performance if the request in one function call, if you do not want to manipulate or read the request object beforehand:

If you do anything wrong, or you are unauthorized, the Response object will be of type Bluem\BluemPHP\ErrorBluemResponse and has an Error() function to retrieve a string of information regarding your error that you could display to your user or handle yourself.

An example about incorrect access token and Ids could be: "Unauthorized: check your access credentials".

Redirection after eMandate transaction creation

When you have performed a transaction request successfully, you receive a response object from Bluem. This object tells you where to redirect the user to, to actually perform the administrative steps at the Bluem portal.

Requesting an eMandate Transaction status

The possible statuses are Success, Processing, Pending, Cancelled, Open and Expired. Refer to the Bluem documentation for more specifics on these statuses.

Identity (iDIN)

Configuring iDIN

Make sure a IDINBrandID property is set in configuration to utilize iDIN in parallel to other Bluem services. The BrandID of different services might differ: e.g. CompanyPayment, CompanyMandate and CompanyIdentity. Set it like this:

Identity request types explained

Several possible IdentityRequests exist. One or more request types can be accessed simultaneously. On a successful response, the details within each type will be returned by the bank for further processing on your side. The possibilities are:

For information on these specific request types, a more comprehensive guide will follow soon. For now, contact your Bluem account manager for help in choosing the use case that matches your desired activities.

The three most commonly used cases with Identity requests are:

  1. Full identification (request 1 or multiple of: Name, Address, BirthDate, Gender, EmailAddress, PhoneNumber, CustomerID). This is used for KYC, Wwft, AML compliance and for Account Creation.
  2. Age verify 18+ (request AgeVerify) and cannot be combined with the other request categories.
  3. A safe login with iDIN (request CustomerIDLogin) and cannot be combined with the other request categories; Here you utilize iDIN login as an alternative safe login method next to a traditional username – password login. Please note that Safe login with iDIN requires the first time a Full identification.

Creating an identity request

Creating an Identity Transaction Request can be done after the Bluem object has been properly instantiated. Keep in mind that the BrandID has to be compatible with Identity requests. Usually the corresponding brand ID ends with “Identity” instead of for example "Mandate" or "Payment".

The $returnURL is vital, as Bluem will redirect the user to that location after the process completion. The next section deals with creating the callback function.

Handling the request from then is straightforward. Please note: save the returned information somewhere in the session or user data store, so you can easily refer to this identity request later. Note: It is recommended to store what request you have executed to know what to do with it later.

The Identity Response callback

Processing the callback function can be done after the Bluem object has been properly instantiated.

Now, based on the response, you can act:

Testing identity return statuses

When using specific entranceCodes for iDIN starting with a given prefix you will always get to a test status page of the bank where you can choose the status you want to receive back. You can easily utilize this feature by altering your request object.

Please note that this only works in the TEST environment.

Advanced note: This function prepends a string to your entranceCode. This might clip your original entranceCode if it exceeds the max length.

CustomerIDLoginRequest

It is also possible to use this library for performing a login request for your application, using a customized flow. Detailed instructions will follow here shortly.

IBAN-Name check

This service allows you to verify if a name and IBAN combination are matching and valid, which can be useful when you are validating user registration, input or within a checkout procedure. A simple example of such a request and its result can be found below:

Use-cases for IBAN-Name checking and Edge cases

More details on how to use IBAN-Name checking will follow shortly.

Important miscellaneous notes

Enable secure Webhook reception through a certificate check

To be able to use webhook functionality, retrieve a copy of the Webhook certificate provided by Bluem and put it in a folder named keys, writeable by the code in this library.

Appendices

List of all supported BICs per context

ePayments

Identity

Please note: Knab with BIC: KNABNL2H does not support eMandates CORE anymore as of 4th of October 2023.

Todo:

All versions of bluem-php with dependencies

PHP Build Version
Package Version
Requires php Version >=8.0
ext-dom Version *
ext-libxml Version *
ext-simplexml Version *
ext-curl Version *
ext-json Version *
ext-openssl Version *
selective/xmldsig Version ^3.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package daanrijpkema/bluem-php contains the following files

Loading the files please wait ....