README

maib-api

本文件内容

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

简介

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

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

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

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

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

需求

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

安装

运行 composer require maib/maibapi ^3.0

使用前

要启动支付交易，您需要获得 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 交易有 2 个步骤。
- 第一步是在 Maib 服务器上注册交易，并使用 registerSmsTransaction 方法获取 TRANSACTION_ID。
- 第二步是将用户重定向到 Maib 支付网关 URL，使用 TRANSACTION_ID。
- 当交易完成时，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 个字符）
  - error - 如果出现错误

  // 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 交易有 3 个步骤。
- 第一步是在 Maib 服务器上注册交易，并使用 registerDmsAuthorization 方法获取 TRANSACTION_ID。
- 第二步是将用户重定向到 Maib 支付网关 URL，使用 TRANSACTION_ID。
- 当交易被应用后，麦宝支付网关将用户重定向到您的回调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 个字符）
  - error - 如果出现错误

  // 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 - 隐藏的卡号
  - error - 如果出现错误

  // 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 - 尝试使用错误的卡方案（Dinners club, American Express）进行3D secure授权
  - RRN - 从Card Suite Processing RTPS返回的检索参考号
  - APPROVAL_CODE - 从Card Suite Processing RTPS返回的审批代码（最多6个字符）
  - CARD_NUMBER - 隐藏的卡号
  - AAV - AAV商户名称中hash值验证失败的结果（仅在失败时）
  - RECC_PMNT_ID - 重复支付（如果可用）在支付服务器中的标识。
  - RECC_PMNT_EXPIRY - 重复支付（如果可用）在支付服务器中的到期日期，格式为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 - 交易已被撤销
    - 失败 - 反转交易失败（交易状态保持不变）
  - 结果代码 - 由Card Suite处理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 - 由Card Suite处理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，以提供运营支持。信件中应指出以下信息

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

维护者

当前维护者

Indrivo

maib / maibapi

维护者

详情

README

maib-api

本文件内容

简介

需求

安装

使用前

用法

故障排除

维护者