README

Bluem-php 用于支付、指令、iDIN 及 IBAN-Name 检查

A PHP 接口用于利用 Bluem 服务 ePayments、eMandates、iDIN 和/或 IBAN-Name 检查。利用此库用 PHP 编写自己的应用程序，无需自己处理流程。

也被其他应用程序使用

• WordPress 和 WooCommerce 插件，适用于 Bluem 客户。
• Magento2 模块，适用于 Bluem 客户。
• Bluem 客户的多个第三方客户应用程序。

目录

• 要求
• 入门指南
• 版本说明
  • 版本 2.3（最新版本）
  • 版本 2.2
  • 版本 2.1
  • 2.1 之前的版本
• 测试
  • 基本测试的说明
• 常见问题解答
• 配置
• 一般概念
• Webhooks
• 支付
  • 创建支付交易
  • 请求支付状态
  • 测试支付的技巧
  • 向请求添加额外数据
• eMandates
  • 指令特定配置字段
  • 创建 eMandate 交易：辅助函数
    • 创建 eMandate 交易
    • eMandate 交易创建后的重定向
  • 请求 eMandate 交易状态
• 身份（iDIN）
  • 配置 iDIN
  • 身份请求类型说明
  • 创建身份请求
  • 身份响应回调
  • 测试身份返回状态
  • CustomerIDLoginRequest
• IBAN-Name 检查
  • IBAN-Name 检查用例及边缘情况
• 重要杂项说明
  • 通过证书检查启用安全的 Webhook 接收
• 附录
  • 每个上下文支持的所有 BIC 列表

2.4 即将推出

在接下来的 1-2 个月内将发布 PHP 库的新版本。从本版本开始，PHP 8.1 是此库的最低要求版本。

要求

• 2024 年：从我们的发布 >= 2.4 开始，PHP 8.1 是此库的最低要求版本。以前的版本需要 PHP 8.0。

• 2023 年 4 月更新：从我们的发布 >= 2.3 开始，PHP 8.0 是此库的最低要求版本。以前的版本需要 PHP 7.4。

• 请使用主要 git 发布版为此插件的稳定版本。

• 有关其他依赖项，请参阅 composer.json 要求。

入门指南

通过 Composer 安装库。在您的项目文件夹中运行 Composer 以安装此库及其依赖项。

composer require bluem-development/bluem-php

有关完整示例实现，请参阅示例，您可以根据自己的集成进行修改。

如果您对示例或库在项目中的实现有任何疑问，请与我们联系。

版本说明

版本 2.3.2.4（最新版本）

• 将银行 'N26' 添加到 ePayments BIC 列表。
• 重构代码以兼容 Magento。

版本 2.3.2.3

更新证书。

版本 2.3.2.2

更新 BIC epayments 列表。

版本 2.3.2

已将BIC添加到指令请求中。

版本2.3.1

已将BIC添加到身份请求中。

版本2.3

添加了对PHP 8+的支持。

版本 2.2

Webhooks和新支付方式

• 添加了显式的Webhook功能及相关文档
• 支持PayPal、信用卡、SOFORT和Carte Bancaire

版本 2.1

代码风格有重大改进。

• 添加了用于检索配置值的$bluem->getConfig($key)方法。
• 添加了用于设置配置值的$bluem->setConfig($key, $value)方法。
• 添加了多个验证步骤
• 增加了更多单元测试覆盖率
• 分离了更多责任以提高代码清晰度

2.1 之前的版本

版本2.0.12

允许使用地理位置集成（IP-API）验证当前IP是否位于荷兰。

$bluem->VerifyIPIsNetherlands();
// returns bool true if NL or error, returns false if no error and other country.

此功能可用于确定是否在任何应用程序中使用iDIN身份验证，因为此功能仅支持荷兰银行。

版本2.0.2

自2021年6月1日起，不再支持Triodos Bank，BIC TRIONL2U作为身份请求。请参阅：[Triodos常见问题](https://www.triodos.nl/veelgestelde-vragen/kan-ik-idin-gebruiken?id=4de127e85eee)

• 如果您使用DebtorWallet的银行预选，您需要更新此库以确保Triodos不再是iDIN的选项。如果您不这样做，选择Triodos的客户将显示错误。

• 如果您使用Bluem门户，您不需要采取行动。此更改已在Bluem门户中应用。

版本2.0.1

主要版本，增加了更多稳定性、验证和功能。

请注意：主要集成类名为Bluem，因此要包含它，请使用

$bluem = new Bluem($config);

或者使用类别名以确保代码正常运行。这是从1.x版本开始的重构。

此外，所有通用功能仍然可用。

没有更早的变更日志。请参阅[提交日志](https://github.com/bluem-development/bluem-php/commits/master)以获取更多信息。

测试

为了改进未来的功能，自2021年11月以来引入了单元测试。

测试位于tests文件夹中。要运行测试

./vendor/bin/phpunit 

测试是在.env文件的基础上进行的。请确保有一个填充的.env文件可用。提供了一个.env.example文件来帮助您配置它。

基本测试的说明

• 测试是否可以创建请求
• 测试是否可以生成入口码

常见问题解答

我收到消息“未授权：检查您的账户凭证”。我该怎么办？
请确保您的SenderID、BrandID和测试和/或生产环境的令牌设置正确。通常此消息保留为无效配置或未激活的账户。如果您已检查凭证正确，但仍然收到此消息，请联系您的Bluem账户经理。

我可以将身份服务与像E-Mandates或iDEAL这样的支付服务连接起来，以便用户只需重定向一次吗？

• 不行，因为这些都是不同的过程。

配置

如果尚未通过其他依赖项完成，请将Composer所需的自定义加载函数包含到您的代码中。

// get composer dependencies
require_once __DIR__. '/vendor/autoload.php';

// then use the library in the top of your script(s).
use Bluem\BluemPHP\Bluem;

然后您可以使用以下方式获取一个对象来利用所有功能。建议将这些建置设置保存在数据库或设置处理程序中，以便用户可以存储它们而不是在代码中。

$config = new Stdclass();

// Fill in the string 'prod', 'test' or 'acc' for production, test or acceptance environment, respectively.
$config->environment = ...
v
// The sender ID, issued by Bluem. Starts with an S, followed by a number.
$config->senderID = ... 

// The access token to communicate with Bluem, for the test environment.
$config->test_accessToken = ... 

// The access token to communicate with Bluem, for the production environment.
$config->production_accessToken = ... 

// the merchant ID (for eMandates), to be found on the contract you have with the bank for receiving direct debit mandates.
$config->merchantID = ...

// The slug of the 'Thank You' page to which should be referred after completing process. If your Order ID is processed in the URL it will be filled in for you.
$config->thanksPage = ...
// Not applicable for IBAN-Name check

// What status would you like to get back for a TEST transaction or status request? Possible values: none, success, cancelled, expired, failure, open, pending
$config->expectedReturnStatus = ...
// Not applicable for IBAN-Name check

// What's your BrandID? Set at Bluem
$config->brandID = ...
// Not applicable for IBAN-Name check

// eMANDATES Specific:
// Brief description of the debt collection
$config->eMandateReason = ...

// Choose collection: CORE or B2B
$config->localInstrumentCode = ...

// URL to return to after finishing the process
$config->merchantReturnURLBase = ...;
// Not applicable for IBAN-Name check

$bluem = new Bluem($config);

如果Bluem对象的部分没有正确实例化，实例化可能会抛出异常。

一般概念

此库使得与Bluem的服务（ePayments、eMandates、iDIN和IBAN-Name Check）进行通信变得容易。每个服务的流程都类似，因此一旦您理解和实现了其中一个，就很容易理解。

1. TransactionRequest（从网站到Bluem）：您的应用程序创建一个请求对象，带有认证将其发送到Bluem服务器。
2. 交易响应（包括交易URL）（从Bluem到网站）：如果请求成功，您的应用程序将接收到一个包含URL的响应，作为进入Bluem环境的入口。
3. Bluem环境：将客户端重定向到交易URL，客户端（通过结账）到银行，确认交易，然后返回到商家（通过带有eMandates的商家返回URL，以及带有支付/身份的债务人返回URL），这是状态请求的触发器。用户将被重定向到Bluem服务器上的响应URL。在这个Bluem环境中，用户执行支付/授权签字或身份/iDIN检查，然后返回到一个预定义的URL。
4. 状态请求（从网站到Bluem）：使用这个相同的包，可以通过第二个端点（提供一个请求创建时定义的交易ID和入口码）来检查请求的状态。这是非常重要的，因为它允许您根据从Bluem获取的交易状态在您的网站或应用程序中更改订单或检查的状态。建议在用户在Bluem处理交易后直接回到您的网站/应用程序后进行此检查，并且使用webhook功能。
5. 状态更新（从Bluem到网站）：这个响应对象是从回调或webhook返回的，包含可以在您的应用程序中处理的新状态。例如：当用户付款或验证后，您需要更改产品、订单或处理的状态并进入下一步。
6. Webhook：webhook功能允许Bluem直接和安全地将状态更改和交易结果推送到您的网站或应用程序。因此，无论用户在访问Bluem交易页面后做什么，您的订单和交易都会更新到相应的状态。

Webhook仅适用于电子支付和eMandates：需要直接知道状态的在线商店/门户网站，对于客户在银行成功确认交易后关闭浏览器的那些情况。iDIN不需要webhook，因为iDIN的客户在成功识别后始终返回到网站。请参阅Webhook部分以获取实现说明。

请注意，IBAN-Name检查的流程更短：执行交易请求。结果以交易响应的形式返回。这是因为最终用户不需要；直接调用到银行数据库，该数据库在交易响应中提供IBAN-Name检查结果。

使用债务人钱包预选支付请求的银行

注意：这与基于银行的交易和服务相关。

您可以在自己的应用程序中为支付预选一个银行，基于创建授权、支付或身份请求时的发行者ID（BIC/Swift代码）。如果您想在您的界面中让用户选择给定的银行并跳过Bluem门户界面中的银行选择，可以使用此功能。这可以通过在请求对象上利用PHP库的预选功能，在您的应用程序和界面中执行银行选择，从而减少所需步骤。

$BIC = "INGBNL2A";
$request->selectDebtorWallet($BIC);

参数必须是受支持银行的合法BIC代码。无效的BIC代码将触发异常。请注意，支持的BIC代码因服务而异，因为并非每家银行都提供相同的服务！可以通过Bluem对象根据服务上下文请求每个服务的支持BIC代码。作为本文档文件的附录，您可以找到每个上下文的所有BIC的全列表。

以下是按上下文检索BIC列表的程序示例。

$MandatesBICs = $bluem->retrieveBICsForContext("Mandates"); // also specific to localInstrumentCode, see notes.
$PaymentsBICs = $bluem->retrieveBICsForContext("Payments");
$IdentityBICs = $bluem->retrieveBICsForContext("Identity");

不同上下文的输入将触发异常。如果有效，结果是包含具有属性IssuerID和IssuerName的Bluem\BluemPHP\BIC对象的数组：分别对应BIC和银行名称。您可以使用此信息来填充您的用户界面。

请注意，当配置不同的 localInstrumentCode 时，BIC 列表将会有所不同。本地仪器代码 CORE 和 B2B 由不同的银行支持。根据您的配置，正确的 BIC 列表将自动从上下文中加载并用于验证债务人钱包。

此方法可用于创建 iDIN 和创建 iDEAL 请求时；您可以将选定的银行（发行人）存储在用户级别，并在创建用户请求时使用它。

• 您可以在自己的网站/应用程序中告知用户为什么这是必要的，并引用新的法律和规则，或者参考新闻/公开声明。
• 您可以告知用户所需的麻烦程度：显示一段文本说明只需一分钟左右，并且它存储是为了您的方便：这确保了完整性和有效的网店体验。

使用不同的支付交易方法

重要提示：请确保为特定的支付方法设置了正确的品牌 ID。请参阅您的账户经理以获取每个支付方法的特定品牌 ID 列表。

您可以在发送请求之前，通过在请求对象中选择这些选项来允许 PayPal 和信用卡支付方式。

要使用 iDeal（默认选项），可以提供一个 BIC。如果留空，将在 Bluem 门户中进行银行选择。

$BIC = 'INGBNL2A';
$request = $request->setPaymentMethodToIDEAL($BIC); 

要使用 PayPal，请提供 PayPal 账户电子邮件地址。该电子邮件地址也不是必需的。

$payPalAccount = 'john.doe@gmail.com';
$request = $request->setPaymentMethodToPayPal($payPalAccount); 

要使用信用卡，您可以按以下方式设置信用卡详细信息（非必需）

$request = $request->setPaymentMethodToCreditCard();

或

$cardNumber = '1234000012340000';
$name = 'John Doe';
$securityCode = 123;
$expirationDateMonth = 11;
$expirationDateYear = 2025;

$request = $request->setPaymentMethodToCreditCard(
    $cardNumber,
    $name,
    $securityCode,
    $expirationDateMonth,
    $expirationDateYear
); 

要使用 Sofort，使用以下方法

$request = $request->setPaymentMethodToSofort(); 

要使用 Carte Bancaire，使用以下方法

$request = $request->setPaymentMethodToCarteBancaire(); 

如果缺少所需信息，这些方法将抛出异常。

一旦请求执行，交易链接将带您到带有相应界面和流程的 Bluem 门户。

Webhooks

支付、eMandates 和身份存在 Webhooks。它们在请求 Bluem 流时触发，并将数据发送到您的应用程序。它们对于确保所有流程始终完成至关重要，即使客户/用户没有达到您流程中的常规回调方法。

通过为测试和生产环境创建端点来激活端点。然后需要在 Bluem 端配置它们并在客户端实现。

1. 如何实现

为测试和生产环境创建一个 HTTP 可达的端点。示例包括

• https://example.com/webhook/test 或 https://example.com/webhook_test.php
• https://example.com/webhook/production
• 等。

在该端点内调用 Webhook() 函数

$bluem_object->setConfig("webhookDebug", false);
$webhook = $bluem_object->Webhook();

// implement this like you implemented the callback
// for the regular services in your application.
if ($webhook !== null) {     
    if ($webhook->getStatus() === "Success") {
        // deal with the successful callback
    }
    // elseif (...) {...etc
}

有关更深入的示例实现和接收 webhook 时在您的应用程序中检索数据的说明，请参阅 examples/payments-webhook.php。

您可以使用以下函数在回调对象中获取 webhook 的数据并处理相关数据。

注意：除非另有说明，否则大多数函数返回字符串值。

所有服务中可用的函数

$webhook->getEntranceCode();
$webhook->getPaymentReference();
$webhook->getCreationDateTime();
$webhook->getStatus();
$webhook->getDebtorReference();

支付特定函数

$transactionID = $webhook->getTransactionID();
$amount = $webhook->getAmount();
$amountPaid = $webhook->getAmountPaid();
$currency = $webhook->getCurrency();
$paymentMethod = $webhook->getPaymentMethod();

// note: these return a SimpleXML object
$paymentMethodDetails = $webhook->getPaymentMethodDetails(); 
$iDealDetails = $webhook->getIDealDetails();

// note: these are iDEAL specific
$debtorAccountName = $webhook->getDebtorAccountName();
$debtorIBAN = $webhook->getDebtorIBAN();
$debtorBankID = $webhook->getDebtorBankID();

eMandates 特定函数

$mandateID = $webhook->getMandateID();
$statusDateTime = $webhook->getStatusDateTime();
$originalReport = $webhook->getOriginalReport(); // note: returns raw XML cdata object that still needs to be parsed.
$acceptanceReport = $webhook->getAcceptanceReportArray(); // note: returns array with a lot of values that are of use.

身份特定函数

$requestType = $webhook->getRequestType();
$transactionID = $webhook->getTransactionID();
$debtorReference = $webhook->getDebtorReference();
$authenticationAuthorityID = $webhook->getAuthenticationAuthorityID();
$authenticationAuthorityName = $webhook->getAuthenticationAuthorityName();

// note: returns array with a lot of values that are of use.
$identityReportArray = $webhook->getIdentityReportArray(); 

2. 如何配置

将端点 URL 传达给 pluginsupport@bluem.nl 以将这些 URL 配置在您的账户中。 请允许几天时间进行此配置。我们将一俟端点添加即进行跟进。

3. 验证其是否工作

您可以通过向自己的端点 POST 来验证其是否工作。请与我们联系以获取可用于您服务的示例 Webhook 调用。

Webhook 支持

我们可以帮助您解决在创建端点后可能遇到的问题。我们还可以帮助您验证数据是否正确发送。如果您需要这方面的帮助，请与我们联系。

支付

以下配置中的属性对于eMandate的正确功能至关重要

• PaymentReference：在管理界面中可见的引用，可用于识别客户和/或交易详情。
• 金额
  • 金额可变
  • 最小金额
  • 最大金额
  • AmountArray,
• 设置并启用支付的有效brandID。

创建支付交易

支付服务类似于eMandate服务，但使用其他参数。以下是一个示例

$description = "Test payment"; // a concise description with possible references to order name and such.
$amount = 100.00;	 // as a float
$currency = "EUR"; // if set to null, will default to EUR as string
$debtorReference = "1234023"; 
$dueDateTime = null; // Set it automatically a day in advance. If you want to set it, use a datetime string in "YYYY-MM-DD H:i:s" format

$entranceCode = $bluem->CreateEntranceCode();

// To create AND perform a request:
$request = $bluem->CreatePaymentRequest(
    $description,
    $debtorReference,
    $amount,
    $dueDateTime,
    $currency,
    $entranceCode
);
// Or, to create and perform a request together in shorthand:
$response = $bluem->Payment(
    $description,
    $debtorReference,
    $amount,
    $dueDateTime,
    $currency
);

请求支付状态

类似于请求Mandate状态（见下文）

$statusResponse = $bluem->PaymentStatus($transactionID, $entranceCode);

if ($statusresponse->ReceivedResponse()) {

    $statuscode = ($statusresponse->GetStatusCode());

    // add your own logic in each case:
    switch ($statuscode) {
        case 'Success':
            // do something when the payment is successful directly
        case 'Processing':
        case 'Pending':
            // do something when the request is still processing (for example tell the user to come back later to this page)
            break;
        case 'Cancelled':
            // do something when the request has been canceled by the user.
            break;
        case 'Open':
            // do something when the request has not yet been completed by the user, redirecting to the transactionURL again.
            break;
        case 'Expired':
            // do something when the request has expired
            break;
        default:
            // unexpected status returned, show an error
            break;
    }

}

测试支付的技巧

在Bluem测试模式下，您可以放置特定金额的iDEAL订单，以获取某种状态。这样，您可以查看如果支付成功或失败的情况。可用状态包括

• 1.00（或任何其他值）成功
• 4.00开放
• 2.00已取消
• 3.00已过期
• 5.00失败
• 7.00系统内失败

向请求添加额外数据

您可以在执行之前向请求对象中添加额外的信息，这可能很有用。这些数据将被存储在ViaMijnBank Portal中，用于后续的行政目的。

$key = "EmailAddress";
$value = "john@doe.com";

// after instantiating the request
$request->addAdditionalData($key, $value);
// but before performing it

提供未知密钥或无效格式的值将导致异常。

密钥选项包括

EmailAddress

包括客户的电子邮件地址。

MobilePhoneNumber

包括客户的电子邮件地址。

CustomerProvidedDebtorIBAN

包括客户的额外债务人IBAN地址。

CustomerNumber

包括客户号码。

CustomerName

包括客户名称。

AttentionOf

包括客户头衔或要称呼的人的名字。

Salutation

包括客户头衔或要问候的人的名字。

CustomerAddressLine1

包括客户地址的第一部分。

CustomerAddressLine2

包括客户地址的第二部分。

DebtorBankID

更多说明如下。

DynamicData

更多说明如下。

eMandates

指令特定配置字段

以下bluem_config中的属性对于eMandate的正确功能至关重要。以下是每个配置字段含义的简要描述

• 本地工具代码（CORE，B2B）
• RequestType
  • 发行是默认的。修订/取消未使用。
• SequenceType
  • 一次性，或OOFF
  • 周期性，或 RCUR
• MandateID,
• MerchantID,
• MaxAmount（B2B）,
• ValidationReference

创建 eMandate 交易：辅助函数

您需要某些信息来引用交易请求：一个ID（在这种情况下是MandateID），以及一个entranceCode（基本上是您开始请求时的一个时间戳）。创建此信息可以使用辅助函数完成。创建新交易时，entranceCode和MandateID将在$bluem中生成。

生成Mandate ID

$mandateId = $bluem->CreateMandateId($order_id, $customer_id);

生成entrance code

$entranceCode = $bluem->CreateEntranceCode();

创建 eMandate 交易

默认交易返回到特定URL的回调函数，然后自动执行状态更新并可以执行其他功能。它使用在创建$bluem对象时设置的merchantReturnURLBase属性，以了解要重定向到的位置以执行此功能。此过程自动将mandateID作为GET参数添加到返回URL中，以便可以将其拾取以进行状态更新。

// default
$request = $bluem->CreateMandateRequest($customer_id,$order_id,"default");

// After creating any request, you will still have to perform the request:

$response = $bluem->PerformRequest($request);

提示：如果您不想在之前操作或读取请求对象，也可以在一个函数调用中合并请求的创建和执行。

$response = $bluem->Mandate($customer_id, $order_id,"default");

如果您做错了任何事情，或者您未经授权，则响应对象将为类型Bluem\BluemPHP\ErrorBluemResponse，并且具有一个Error()函数，可以检索有关您错误的信息字符串，您可以将其显示给用户或自行处理。

一个关于错误的访问令牌和ID的示例可能是："未授权：检查您的访问凭证"。

eMandate 交易创建后的重定向

当您成功执行交易请求时，您将从Bluem接收一个响应对象。该对象告诉您将用户重定向到哪个位置，以便在Bluem门户中实际执行管理步骤。

if ($response->ReceivedResponse()) {

	$entranceCode = $response->GetEntranceCode();
    // save the entranceCode in your data store

	$transactionURL = $response->GetTransactionURL();

    // TODO: redirect to the above transaction URL
    header("Location: ". $transactionURL); // or something of the sort.
} else {
    // TODO: no proper status given, show an error.
    exit("Error: " . $response->Error()); // for example
}

请求 eMandate 交易状态

$response = $bluem->MandateStatus(
    $existing_mandate_id,
    $existing_entrance_code
);
if (!$response->Status()) {
    // no valid response received
} else {
    if ($response->EMandateStatusUpdate->EMandateStatus->Status . "" === "Success") { // casting to string
        // successful status response
    } else {
        // different status response
    }
}

可能的状态有：成功、处理中、挂起、已取消、开放和过期。有关这些状态的更多详细信息，请参阅Bluem文档。

身份（iDIN）

配置 iDIN

请确保在配置中设置了IDINBrandID属性，以利用iDIN并行使用其他Bluem服务。不同服务的BrandID可能不同：例如，CompanyPayment、CompanyMandate和CompanyIdentity。设置方式如下：

$config->IDINBrandID = "CompanyIdentity";

身份请求类型说明

存在几种可能的IdentityRequests。可以同时访问一种或多种请求类型。在成功响应后，银行将返回每种类型的详细信息，以便您进一步处理。可能性如下：

[
	"CustomerIDRequest",
	"NameRequest",
	"AddressRequest",
	"BirthDateRequest",
	"AgeCheckRequest",
	"GenderRequest",
	"TelephoneRequest",
	"EmailRequest",
	"AgeCheckRequest",
    "CustomerIDLoginRequest"
]

有关这些特定请求类型的详细信息，将很快提供更全面的指南。目前，请联系您的Bluem账户经理，以帮助您选择符合您期望活动的用例。

与Identity请求最常用的三种情况是：

1. 完整身份验证（请求1或多个：姓名、地址、出生日期、性别、电子邮件地址、电话号码、客户ID）。这用于KYC、Wwft、AML合规性以及账户创建。
2. 18+年龄验证（请求AgeVerify）且不能与其他请求类别结合使用。
3. 使用iDIN的安全登录（请求CustomerIDLogin）且不能与其他请求类别结合使用；在这里，您将iDIN登录作为除传统用户名-密码登录之外的另一种安全登录方法。请注意，使用iDIN的安全登录需要第一次进行完整身份验证。

创建身份请求

在正确实例化Bluem对象之后，可以创建一个身份验证交易请求。请记住，BrandID必须与身份请求兼容。通常，相应的品牌ID以“Identity”结尾，而不是例如“Mandate”或“Payment”。

$returnURL至关重要，因为Bluem将在处理完成后将用户重定向到该位置。下一节将介绍创建回调函数。

$description = "Test identity"; // description shown to customer
$debtorReference = "1234"; // client reference/number
$returnURL = "https://yourdomain.com/integration/identity.php?action=callback"; 
// provide a link here to the callback function; either in this script or another script.

$request = $bluem->CreateIdentityRequest(
	["BirthDateRequest", "AddressRequest"],
	$description,
	$debtorReference,
	$returnURL
);

$response = $bluem->PerformRequest($request);

从那时起处理请求很简单。请注意：将返回的信息保存在会话或用户数据存储中，以便您可以轻松地稍后引用此身份请求。注意：建议存储您已执行的请求，以便稍后知道如何处理它。

if ($response->ReceivedResponse()) {

	$entranceCode = $response->GetEntranceCode();
	$transactionID = $response->GetTransactionID();
	$transactionURL = $response->GetTransactionURL();
	// save this somewhere in your data store

	$_SESSION['entranceCode'] = $entranceCode;
	$_SESSION['transactionID'] = $transactionID;
	$_SESSION['transactionURL'] = $transactionURL;

	// direct the user to this place
	header("Location: ".$transactionURL);

} else {
	// no proper response received, tell the user
}

身份响应回调

在正确实例化Bluem对象之后，可以处理回调函数。

// Retrieve from a store, preferably more persistent than session.
// The code below is purely for demonstrative purposes.

$transactionID = $_SESSION['transactionID'];
$entranceCode = $_SESSION['entranceCode'];


$statusResponse = $bluem->IdentityStatus(
    $transactionID,
    $entranceCode
);

现在，根据响应，您可以采取行动

if ($statusResponse->ReceivedResponse()) {

    $statusCode = ($statusResponse->GetStatusCode());

    switch ($statusCode) {
        case 'Success':
            // handle a success callback

            // retrieve a report that contains the information based on the request type:
            $identityReport = $statusResponse->GetIdentityReport();

            // this contains an object with key-value pairs of relevant data from the bank:
            /**
             * example contents:
             *  "DateTime": string(24) "2020-10-16T15:30:45.803Z"
             *  "CustomerIDResponse": string(21) "FANTASYBANK1234567890"
             *  "AddressResponse":
             *  object(Bluem\BluemPHP\IdentityStatusBluemResponse)#4 (5) {
             *      "Street": string(12) "Pascalstreet"
             *      "HouseNumber": string(2) "19"
             *      "PostalCode": string(6) "0000AA"
             *      "City": string(6) "Aachen"
             *      "CountryCode": string(2) "DE"
             *  }
             *  "BirthDateResponse": string(10) "1975-07-25"
             *  */
            // store information and process it.

            // You can for example use the BirthDateResponse to determine the age of the user and act accordingly.


            break;
        case 'Processing':
        case 'Pending':
            // do something when the request is still processing (for example tell the user to come back later to this page)
            break;
        case 'Cancelled':
            // do something when the request has been canceled by the user.
            break;
        case 'Open':
            // do something when the request has not yet been completed by the user, redirecting to the transactionURL again.
            break;
        case 'Expired':
            // do something when the request has expired
            break;
        default:
            // unexpected status returned, show an error
            break;
    }
} else {
    // no proper response received, tell the user
}

测试身份返回状态

当使用以给定前缀开始的特定entranceCodes进行iDIN时，您总是会到达银行的一个测试状态页面，您可以选择要返回的状态。您可以通过更改请求对象轻松利用此功能。

请注意，这仅在测试环境中有效。

$request->enableStatusGUI();

高级说明：此功能将字符串附加到您的entranceCode之前。如果超出最大长度，可能会截断原始entranceCode。

CustomerIDLoginRequest

还可以使用此库为您的应用程序执行登录请求，使用自定义流程。详细说明将很快在此处提供。

IBAN-Name 检查

此服务允许您验证姓名和IBAN组合是否匹配且有效，这在您正在验证用户注册、输入或结账过程中非常有用。以下是一个此类请求及其结果的简单示例

$iban = "NL99ABNA1234012428";
$name = "H. de Vries";
$debtorReference = "1234";

$request = $bluem->CreateIBANNameCheckRequest(
    $iban,
    $name,
    $debtorReference
);

$response = $bluem->PerformRequest($request);

switch ($response->GetIBANResult()) {
case 'INVALID':
    echo "IBAN $iban and name $name do not match";
    break;
case 'KNOWN':
    // handle how the response should be taken in
    break;
}

IBAN-Name 检查用例及边缘情况

如何使用IBAN-Name检查的更多详细信息将很快提供。

重要杂项说明

通过证书检查启用安全的 Webhook 接收

要使用webhook功能，请获取Bluem提供的Webhook证书的副本，并将其放入名为keys的文件夹中，该文件夹可由此库中的代码写入。

附录

每个上下文支持的所有 BIC 列表

ePayments

• ABN AMRO
  BIC: ABNANL2A
• ASN Bank
  银行识别码（BIC）: ASNBNL21
• bunq
  银行识别码（BIC）: BUNQNL2A
• ING
  银行识别码（BIC）: INGBNL2A
• Knab
  银行识别码（BIC）: KNABNL2H
• Rabobank
  银行识别码（BIC）: RABONL2U
• RegioBank
  银行识别码（BIC）: RBRBNL21
• SNS
  银行识别码（BIC）: SNSBNL2A
• Triodos Bank
  银行识别码（BIC）: TRIONL2U
• Van Lanschot
  银行识别码（BIC）: FVLBNL22
• Revolut
  银行识别码（BIC）: REVOLT21
• Yoursafe
  银行识别码（BIC）: BITSNL2A
• N26
  银行识别码（BIC）: NTSBDEB1
• Nationale-Nederlanden
  银行识别码（BIC）: NNBANL2G

eMandates CORE

• ABN AMRO
  BIC: ABNANL2A
• ASN Bank
  银行识别码（BIC）: ASNBNL21
• ING
  银行识别码（BIC）: INGBNL2A
• Rabobank
  银行识别码（BIC）: RABONL2U
• RegioBank
  银行识别码（BIC）: RBRBNL21
• SNS
  银行识别码（BIC）: SNSBNL2A
• Triodos Bank
  银行识别码（BIC）: TRIONL2U

eMandates B2B

• ABN AMRO
  BIC: ABNANL2A
• ING
  银行识别码（BIC）: INGBNL2A
• Rabobank
  银行识别码（BIC）: RABONL2U

身份

• ABN AMRO
  BIC: ABNANL2A
• ASN Bank
  银行识别码（BIC）: ASNBNL21
• bunq
  银行识别码（BIC）: BUNQNL2A
• ING
  银行识别码（BIC）: INGBNL2A
• Rabobank
  银行识别码（BIC）: RABONL2U
• RegioBank
  银行识别码（BIC）: RBRBNL21
• SNS
  银行识别码（BIC）: SNSBNL2A

请注意：截至2023年10月4日，Knab的银行识别码（BIC）为KNABNL2H不再支持eMandates CORE。

待办事项

• 添加改进的目录
• 实现 shields.io (https://github.com/badges/shields)