README

maib-api

本文件内容

简介
要求
推荐模块
安装
使用前
使用方法
故障排除
维护者

简介

MAIB Payment PHP SDK 用于轻松将 MAIB Payment 集成到您的项目中。基于 Guzzle 库连接和处理与银行服务器的请求，以及 Monolog 库记录请求响应。

MAIB Payment PHP SDK 有两种支付方式。

一种是通过 SMS 交易（registerSmsTransaction）。当用户进行支付时，客户的资金立即从商户账户转账。这种方式推荐使用。
另一种是通过 DMS 交易（registerDmsAuthorization）。在您确认交易之前，客户的资金已在其账户中被锁定。这种方式通常用于长时间运输的情况。

该 Payment PHP SDK 包含 6 种处理支付的方法

注册交易。
注册 DMS 授权。
执行 DMS 交易。
获取交易结果。
交易撤销。
结束工作日。

要求

PHP: >=8.0.0
guzzlehttp/guzzle: ~7.0
guzzlehttp/guzzle-services: ~1.0
monolog/monolog: ^2.7

安装

运行 composer require cusursuz/maibapi

使用前

要启动支付交易，您需要获得 SSL 证书、通过 IP 获取访问权限并设置回调 URL。

需要给 maib 商务支持发送电子邮件：ecom@maib.md，请求中包括商户 IP 和回调 URL，以获取测试访问权限和证书。

获得证书后，您需要使用终端包 OpenSSL 生成私钥和公钥。

 # Public key chain:
   openssl pkcs12 -in certname.pfx -nokeys -out cert.pem
 # The private key without a password (decrypted):
   openssl pkcs12 -in certname.pfx -nocerts -nodes -out key.pem

需要将生成的密钥保存到服务器上的映射中，以供请求使用。

使用方法

需要包含所有库

  <?php

  namespace MyProject;

  require_once(__DIR__ . '/vendor/autoload.php');

  use Monolog\Handler\StreamHandler;
  use Monolog\Logger;
  use GuzzleHttp\Client;
  use GuzzleHttp\HandlerStack;
  use GuzzleHttp\Middleware;
  use GuzzleHttp\MessageFormatter;
  use Maib\MaibApi\MaibClient;

设置日志堆栈

  if ((isset($log_is_required) && $log_is_required)) {
      $log = new Logger('maib_guzzle_request');
      $log->pushHandler(new StreamHandler(__DIR__.'/logs/maib_guzzle_request.log', Logger::DEBUG));
      $stack = HandlerStack::create();
      $stack->push(
          Middleware::log($log, new MessageFormatter(MessageFormatter::DEBUG))
      );
  }

初始化 MaibCLient

  $options = [
    'base_uri' => MaibClient::MAIB_TEST_BASE_URI,
    'debug'  => false,
    'verify' => true,
    'cert'    => [MaibClient::MAIB_TEST_CERT_URL, MaibClient::MAIB_TEST_CERT_PASS],
    'ssl_key' => MaibClient::MAIB_TEST_CERT_KEY_URL,
    'config'  => [
      'curl'  =>  [
        CURLOPT_SSL_VERIFYHOST => 2,
        CURLOPT_SSL_VERIFYPEER => true,
      ]
    ]
  ];
  if (isset($stack)) {
      $options['handler'] = $stack;
  }
  $guzzleClient = new Client($options);
  $client = new MaibClient($guzzleClient);

准备支付参数

  // The Parameters required to use MaibClient methods
  $amount = 1; // The amount of the transaction
  $currency = 978; // The currency of the transaction - is the 3 digits code of currency from ISO 4217
  $clientIpAddr = '127.0.0.1'; // The client IP address
  $description = 'testing'; // The description of the transaction
  $lang = 'en'; // The language for the payment gateway

  // Other parameters
  $sms_transaction_id = null;
  $dms_transaction_id = null;
  $redirect_url = MaibClient::MAIB_TEST_REDIRECT_URL . '?trans_id=';
  $sms_redirect_url = '';
  $dms_redirect_url = '';

注册 SMS 交易 SMS 交易有两个步骤。
- 第一步是在 Maib 服务器上注册交易并使用 registerSmsTransaction 方法获取 TRANSACTION_ID。
- 第二步是将用户重定向到使用 TRANSACTION_ID 的 Maib 支付网关 URL。
- 当交易完成时，Maib 支付网关将用户重定向到您的回调 URL，您可以在那里获取交易状态。! TRANSACTION_ID 有 10 分钟的超时时间。
- 必需参数
  - $amount = 1; // 交易金额
  - $currency = 978; // 交易货币 - 是 ISO 4217 货币的 3 位代码
  - $clientIpAddr = '127.0.0.1'; // 客户 IP 地址
  - $description = 'testing'; // 交易描述
  - $lang = 'en'; // 支付网关的语言
- 响应：返回数组 TRANSACTION_ID
  - TRANSACTION_ID - 交易标识符（基于64的编码，28个字符）
  - 错误 - 发生错误时

  // The register sms transaction method
  $registerSmsTransaction = $client->registerSmsTransaction($amount, $currency, $clientIpAddr, $description, $lang);
  $sms_transaction_id = $registerSmsTransaction["TRANSACTION_ID"];
  $sms_redirect_url = $redirect_url . $sms_transaction_id;

注册 DMS 授权 DMS 交易有三个步骤。
- 第一步是在 Maib 服务器上注册交易并使用 registerDmsAuthorization 方法获取 TRANSACTION_ID。
- 第二步是将用户重定向到使用 TRANSACTION_ID 的 Maib 支付网关 URL。
- 当交易已应用后，Maib支付网关将用户重定向到您的回调URL，您可以在那里获取交易状态。
- 第三步是使用makeDMSTrans方法确认交易。
- 必需参数
  - $amount = 1; // 交易的金额。
  - $currency = 978; // 交易的货币 - 是ISO 4217货币的3位代码。
  - $clientIpAddr = '127.0.0.1'; // 客户端IP地址。
  - $description = 'testing'; // 交易的描述。
  - $lang = 'en'; // 支付网关的语言。
- 响应：返回数组 TRANSACTION_ID
  - TRANSACTION_ID - 交易标识符（基于64的编码，28个字符）
  - 错误 - 发生错误时

  // The register dms authorization method
  $registerDmsAuthorization = $client->registerDmsAuthorization($amount, $currency, $clientIpAddr, $description, $lang);
  $dms_transaction_id = $registerDmsAuthorization["TRANSACTION_ID"];
  $dms_redirect_url = $redirect_url . $dms_transaction_id;

执行DMS交易
- 必需参数
  - $dms_transaction_id;// 从registerDmsAuthorization获取的交易ID。
  - $amount = 1; // 交易的金额。
  - $currency = 978; // 交易的货币 - 是ISO 4217货币的3位代码。
  - $clientIpAddr = '127.0.0.1'; // 客户端IP地址。
  - $description = 'testing'; // 交易的描述。
  - $lang = 'en'; // 支付网关的语言。
- 响应：返回数组 RESULT, RESULT_CODE, BRN, APPROVAL_CODE, CARD_NUMBER, error
  - RESULT - 交易结果：OK - 成功的交易，FAILED - 失败的交易
  - RESULT_CODE - 从Card Suite Processing RTPS返回的交易结果代码（3位数字）
  - BRN - 从Card Suite Processing RTPS返回的检索参考号（12个字符）
  - APPROVAL_CODE - 从Card Suite Processing RTPS返回的批准代码（最多6个字符）
  - CARD_NUMBER - 隐藏的卡号
  - 错误 - 发生错误时

  // The execute dms transaction method
  $makeDMSTrans = $client->makeDMSTrans($dms_transaction_id, $amount, $currency, $clientIpAddr, $description, $lang);

获取交易结果您可以使用getTransactionResult方法自行获取交易状态。但请记住，交易ID有10分钟的超时时间。
- 必需参数
  - $transaction_id;// 从registerSmsTransaction或registerDmsAuthorization获取的交易ID。
  - $clientIpAddr = '127.0.0.1'; // 客户端IP地址。
- 响应：返回数组 RESULT, RESULT_PS, RESULT_CODE, 3DSECURE, RRN, APPROVAL_CODE, CARD_NUMBER, AAV, RECC_PMNT_ID, RECC_PMNT_EXPIRY, MRCH_TRANSACTION_ID
  - RESULT
    - OK - 成功完成的交易，
    - FAILED - 交易已失败，
    - CREATED - 交易刚在系统中注册，
    - PENDING - 交易尚未完成，
    - DECLINED - 交易被ECOMM拒绝，
    - REVERSED - 交易已被撤销，
    - AUTOREVERSED - 交易已被自动撤销，
    - TIMEOUT - 交易超时
  - RESULT_PS - 交易结果，支付服务器解释（仅在配置为返回ECOMM2特定详细信息时显示）
    - FINISHED - 成功完成支付，
    - CANCELLED - 已取消支付，
    - RETURNED - 已退回支付，
    - ACTIVE - 已注册但尚未完成的支付。
  - RESULT_CODE - 从Card Suite Processing RTPS返回的交易结果代码（3位数字）
  - 3DSECURE
    - AUTHENTICATED - 成功的3D Secure授权
    - DECLINED - 3D Secure授权失败
    - NOTPARTICIPATED - 持卡人不是3D Secure方案的成员
    - NO_RANGE - 卡不在发卡行定义的3D secure卡范围内
    - ATTEMPTED - 持卡人尝试使用ACS服务器进行3D secure授权
    - UNAVAILABLE - 持卡人3D secure授权不可用
    - ERROR - 从ACS服务器接收到的错误消息
    - SYSERROR - 3D secure授权以系统错误结束
    - UNKNOWNSCHEME - 3D secure授权尝试错误的卡方案（Dinners club, American Express）
  - RRN - 从Card Suite Processing RTPS返回的检索参考号
  - APPROVAL_CODE - 从Card Suite Processing RTPS返回的批准代码（最多6个字符）
  - CARD_NUMBER - 隐藏的卡号
  - AAV - AAV商家名称中哈希值验证失败的结果（仅在失败时）
  - RECC_PMNT_ID - 在支付服务器中（如果可用）的周期性支付（Reoccurring payment）标识。
  - RECC_PMNT_EXPIRY - 在支付服务器中（如果可用）的周期性支付（Reoccurring payment）到期日期，格式为YYMM。
  - MRCH_TRANSACTION_ID - 商户交易标识符（如果可用），用于支付 - 如果在支付注册时作为附加参数发送，则显示。
  - RESULT_CODE和3DSECURE字段仅用于信息，可能不会显示。
  - RRN和APPROVAL_CODE字段仅在成功交易时显示，用于信息目的，
  - 并便于在Card Suite Processing RTPS系统中跟踪交易。
  - error - 发生错误时
  - warning - 警告（为将来使用保留）。

  // The get transaction result method
  $getTransactionResult = $client->getTransactionResult($transaction_id, $clientIpAddr);

交易撤销具有执行部分或完全退回操作的能力。
- 必需参数
  - $transaction_id;// 从registerSmsTransaction或registerDmsAuthorization获取的交易ID。
  - $amount = 1; // 交易的金额。
- 响应：返回数组 RESULT, RESULT_CODE
  - RESULT
    - OK - 成功撤销交易
    - REVERSED - 交易已被撤销
    - FAILED - 撤销交易失败（交易状态保持不变）
  - RESULT_CODE - 从Card Suite Processing RTPS返回的撤销结果代码（3位数字）
  - error - 发生错误时
  - warning - 警告（为将来使用保留）。

  // The revert transaction method
  $revertTransaction = $client->revertTransaction($transaction_id, $amount);

关闭工作日执行自动关闭当天的操作，建议使用时间：23:59:00。
- 必需参数
  - 无需参数。
- 响应：返回数组 RESULT, RESULT_CODE, FLD_075, FLD_076, FLD_087, FLD_088
  - RESULT - OK - 成功结束营业日 FAILED - 失败结束营业日
  - RESULT_CODE - 卡套件处理 RTPS 返回的营业日代码（3位数字）
  - FLD_075 - 信用撤销数量（最多10位数字），仅在 result_code 以5开头时显示
  - FLD_076 - 负债交易数量（最多10位数字），仅在 result_code 以5开头时显示
  - FLD_087 - 信用撤销总金额（最多16位数字），仅在 result_code 以5开头时显示
  - FLD_088 - 负债交易总金额（最多16位数字），仅在 result_code 以5开头时显示

  //close business day
  $closeDay = $client->closeDay();

测试介质
- 商户：https://maib.ecommerce.md:21440/ecomm/MerchantHandler
- 客户端：https://maib.ecommerce.md:21443/ecomm/ClientHandler
- 测试证书位于 "src/MaibApi/cert/" 文件夹中
- 测试证书密码为 Za86DuC$
测试卡
- 卡号：5102180060101124
- 过期日期：06/28
- CVV：760

故障排除

所有交易都被视为成功，只有当你从 Maib 服务器收到你已知的格式可预测的响应时。如果你收到任何其他结果（无响应、连接被拒绝、其他情况），则存在问题。在这种情况下，有必要收集所有日志并通过电子邮件发送给 Maib：[ecom@maib.md](mailto:ecom@maib.md)，以提供操作支持。信件中应指出以下信息

商户名称
网站名称
执行错误交易的时间和日期
从服务器收到的响应

维护人员

当前维护人员

Indrivo

cusursuz / maibapi

维护者

详细信息