README

FIB支付SDK提供与FIB支付系统的无缝集成，使开发者能够简化支付交易并方便地在他们的应用程序中处理安全退款。

FIB支付SDK

特性
安装
- Composer安装
- 替代安装（不使用Composer）
配置
使用
FIB支付文档
测试
贡献
许可
支持
致谢
版本控制
常见问题

特性

支付交易：使用FIB支付系统，让用户通过应用程序安全地进行支付，轻松处理交易。
退款处理：通过FIB支付系统安全地处理退款，在应用程序内高效管理交易。
检查支付状态：检查支付状态，确保准确跟踪交易。
取消支付：通过FIB支付系统安全地取消支付，提供灵活性和对支付交易的控制。

安装

要将SDK集成到项目中，请通过Composer进行安装

composer require First-Iraqi-Bank/fib-php-payment-sdk

替代安装（不使用Composer）

如果您的项目不希望使用Composer进行依赖管理，您可以按照以下步骤手动包含FIB支付SDK

克隆仓库：直接将FIB支付SDK仓库克隆到您的项目目录或任何首选位置

 git clone https://github.com/First-Iraqi-Bank/fib-php-payment-sdk.git

包含到您的项目中：将克隆的fib-php-payment-sdk目录复制或移动到您的项目结构中。您可以根据项目的需要将其放置在任何位置。
自动加载（如果适用）：如果您的项目使用自动加载，请确保SDK的src目录包含在您的自动加载配置中。例如，如果您使用PSR-4自动加载，您可能需要在composer.json或等效的自动加载设置中添加以下内容

{
    "autoload": {
        "psr-4": {
            "FIB\\PaymentSDK\\": "path/to/fib-php-payment-sdk/src"
        }
    }
}

使用：将SDK包含到您的项目中后，您可以直接在PHP文件中使用其类和功能。

注意

请确保SDK仓库URL（https://github.com/First-Iraqi-Bank/fib-php-payment-sdk.git）正确且可访问。
手动管理依赖项可能需要额外的工作来确保SDK与最新更改和修复保持更新。
尽可能使用Composer进行依赖管理，因为它简化了依赖管理并确保了与其他包的兼容性。

配置

要配置SDK，您需要设置以下环境变量

FIB_API_KEY：您的FIB支付API密钥。
FIB_API_SECRET：您的FIB支付API密钥。
FIB_BASE_URL：FIB支付API的基本URL（默认：https://api.fibpayment.com）。
FIB_GRANT_TYPE：用于与FIB支付API进行身份验证的授权类型（默认：client_credentials）。
FIB_REFUNDABLE_FOR：交易可以退款的期限（默认：P7D，代表7天）。
FIB_CURRENCY：用于FIB支付系统的交易货币（默认：IQD）。
FIB_CALLBACK_URL：处理来自FIB支付系统的支付通知的回调URL。
FIB_ACCOUNT：FIB支付账户标识符。

请确保在您的应用程序环境配置中适当设置这些环境变量。

SDK使用方法

以下是如何使用SDK的基本示例

确保安装了依赖项

请确保您已使用Composer安装了所有必需的依赖项。

      composer install

设置环境变量

在您的项目根目录下创建一个.env文件，并配置必要的环境变量。请参阅.env.example文件以获取所需的变量。

创建支付示例用法

要创建支付，请使用createPayment方法。此方法将返回支付详情，您可以将其存储在数据库或缓存中，以便稍后在其他功能中使用，例如处理回调URL、检查支付状态、取消支付和退款支付。

      <?php
    require_once __DIR__ . '/../vendor/autoload.php';
    
    use Dotenv\Dotenv;
    use FirstIraqiBank\FIBPaymentSDK\Services\FIBAuthIntegrationService;
    use FirstIraqiBank\FIBPaymentSDK\Services\FIBPaymentIntegrationService;
  
  // Load environment variables from the .env file
  $dotenv = Dotenv::createImmutable(__DIR__.'/..');
  $dotenv->load();
  
  // Function to create a payment and return its ID
  function createPayment(): string
  {
  // Initialize the authentication service
  $authService = new FIBAuthIntegrationService();
  
      // Initialize the payment integration service
      $paymentService = new FIBPaymentIntegrationService($authService);
      
      try {
        // Create a new payment
        $paymentResponse = $paymentService->createPayment(1000, 'https:///callback', 'Test payment description');
        $paymentData = json_decode($paymentResponse->getBody(), true);
        
         // This should typically be saved in a database or cache for real implementations
        // Payment details (example using an associative array)
        //    $paymentData = [
        //      'fib_payment_id' => $paymentData['paymentId'],
        //      'readable_code' => $paymentData['readableCode'],
        //      'personal_app_link' => $paymentData['personalAppLink'],
        //      'valid_until' => $paymentData['validUntil'],
        //    ];
        // Example: $databaseService->storePaymentDetails($paymentData);
        
        // Return the payment ID
        return $paymentData['paymentId'];
      } catch (Exception $e) {
        // Handle any errors
        throw new Exception("Error creating payment: " . $e->getMessage());
      }
  }

存储支付详情：一旦从createPayment方法收到支付详情，您可以将它们存储在数据库或缓存中。这允许您检索和使用这些详情以执行进一步的操作，如检查支付状态、处理退款或处理支付回调。
- 数据库：将支付详情保存到关系型数据库（例如MySQL、PostgreSQL）或NoSQL数据库（例如MongoDB）。
- 缓存：使用内存缓存（例如Redis、Memcached）来存储支付详情以便快速访问。
存储后返回支付详情，将其返回给最终用户。返回的详情包括
- fib_payment_id：支付的唯一标识符。
- readable_code：支付的易读代码。
- personal_app_link：最终用户在个人应用中继续支付的超链接。
- valid_until：支付的过期时间。

按照这些步骤，您可以确保支付详情安全存储并便于进一步处理。

检查支付状态

要检查支付状态，请使用checkPaymentStatus方法。此方法需要支付Id，该Id是在创建支付时返回的。

<?php
  require_once __DIR__ . '/../vendor/autoload.php';
  require_once __DIR__ . '/create_payment.php'; // Include the file with createPayment() function
  
  use Dotenv\Dotenv;
  use FirstIraqiBank\FIBPaymentSDK\Services\FIBAuthIntegrationService;
  use FirstIraqiBank\FIBPaymentSDK\Services\FIBPaymentIntegrationService;

// Load environment variables from the .env file
  $dotenv = Dotenv::createImmutable(__DIR__.'/..');
  $dotenv->load();
  
  try {
    // Get the payment ID
      $paymentId = retrievePaymentId();    
    // This $paymentId should be retrieved from your database or cache in real implementations
    // Example: $paymentId = $databaseService->retrievePaymentId();
    
    // Initialize the authentication service
    $authService = new FIBAuthIntegrationService();
    
    // Initialize the payment integration service
    $paymentService = new FIBPaymentIntegrationService($authService);
    
    // Check Payment Status
    $response = $paymentService->checkPaymentStatus($paymentId);
    echo "Payment Status: " . $response['status'] ?? null . PHP_EOL;
    
    // Example: Store payment details in a database or cache for real implementations
    // $databaseService->storePaymentDetails($paymentDetails);
    
  } catch (Exception $e) {
    echo "Error checking payment status: " . $e->getMessage() . PHP_EOL;
  }

退款支付

要退款支付，请使用refund方法。此方法也需要支付Id。

<?php
  require_once __DIR__ . '/../vendor/autoload.php';
  require_once __DIR__ . '/create_payment.php'; // Include the file with createPayment() function
  
  use Dotenv\Dotenv;
  use FirstIraqiBank\FIBPaymentSDK\Services\FIBAuthIntegrationService;
  use FirstIraqiBank\FIBPaymentSDK\Services\FIBPaymentIntegrationService;

// Load environment variables from the .env file
  $dotenv = Dotenv::createImmutable(__DIR__.'/..');
  $dotenv->load();
  
  try {
    // Get the payment ID
    $paymentId = retrievePaymentId();
    
    // This $paymentId should be retrieved from your database or cache in real implementations
    // Example: $paymentId = $databaseService->retrievePaymentId();
    
    // Initialize the authentication service
    $authService = new FIBAuthIntegrationService();
    
    // Initialize the payment integration service
    $paymentService = new FIBPaymentIntegrationService($authService);
    
    // Refund Payment
    $response = $paymentService->refund($paymentId);
    echo "Refund Payment Status: " . $response['status_code'] . PHP_EOL;

    
    // Example: update payment details in a database or cache for real implementations
    // $databaseService->updatePaymentDetails($paymentDetails);
    
  } catch (Exception $e) {
    echo "Error Refunding payment: " . $e->getMessage() . PHP_EOL;
  }

取消支付

要取消支付，请使用cancel方法。此方法需要支付Id。

<?php
  require_once __DIR__ . '/../vendor/autoload.php';
  require_once __DIR__ . '/create_payment.php'; // Include the file with createPayment() function
  
  use Dotenv\Dotenv;
  use FirstIraqiBank\FIBPaymentSDK\Services\FIBAuthIntegrationService;
  use FirstIraqiBank\FIBPaymentSDK\Services\FIBPaymentIntegrationService;

// Load environment variables from the .env file
  $dotenv = Dotenv::createImmutable(__DIR__.'/..');
  $dotenv->load();
  
  try {
    // Get the payment ID
    $paymentId = retrievePaymentId();
    
    // This $paymentId should be retrieved from your database or cache in real implementations
    // Example: $paymentId = $databaseService->retrievePaymentId();
    
    // Initialize the authentication service
    $authService = new FIBAuthIntegrationService();
    
    // Initialize the payment integration service
    $paymentService = new FIBPaymentIntegrationService($authService);
    
    // cancel Payment
    $response = $paymentService->cancel($paymentId);
    // Check if the cancellation was successful
    if (in_array($response->getStatusCode(), [200, 201, 202, 204])) {
      echo "Cancel Payment Status: Successful\n";
    } else {
      echo "Cancel Payment Status: Failed with status code " . $response->getStatusCode() . "\n";
    }
    
    
    // Example: update payment details in a database or cache for real implementations
    // $databaseService->updatePaymentDetails($paymentDetails);
    
  } catch (Exception $e) {
    echo "Error Refunding payment: " . $e->getMessage() . PHP_EOL;
  }

处理支付回调

要处理支付回调，确保您的应用程序具有FIB可以调用的POST API或URL，以通知您的应用程序有关支付状态更新。

回调URL要求您的回调URL应该能够处理包含两个属性的POST请求的请求体

id：这表示与回调相关的支付ID。Status：这表示支付的当前状态。有关更多详细信息，请参阅本文档的“检查支付状态”部分。返回的状态应与检查状态端点返回的数据结构相匹配。

use Psr\Http\Message\ServerRequestInterface as Request;
use Psr\Http\Message\ResponseInterface as Response;

// Define your callback endpoint
$app->post('/callback', function (Request $request, Response $response) {
    $payload = $request->getParsedBody();

    // Validate incoming payload
    $paymentId = $payload['id'] ?? null;
    $status = $payload['status'] ?? null;

    if (!$paymentId || !$status) {
        return $response->withStatus(400)->withJson([
            'error' => 'Invalid callback payload',
        ]);
    }

    // Process the callback
    try {
        $paymentService->handleCallback($paymentId, $status);
        //TODO: Implement your callback handling logic here

        return $response->withJson([
            'message' => 'Callback processed successfully',
        ]);
    } catch (Exception $e) {
        return $response->withStatus(500)->withJson([
            'error' => 'Failed to process callback: ' . $e->getMessage(),
        ]);
    }
});

注意

使用您的实际端点URL。
确保您的回调端点对FIB可访问并能优雅地处理错误。
在您的FIBPaymentIntegrationService类中实现handleCallback方法以内部处理支付状态更新。

FIB支付文档

有关FIB在线支付的全面详细信息，请参阅完整文档。

测试

为确保SDK正确运行，请使用PHPUnit运行测试。

vendor/bin/phpunit --testdox tests

贡献

欢迎贡献！请阅读CONTRIBUTING.md以了解我们的行为准则和提交拉取请求的流程。

许可

本项目采用MIT许可证。有关详细信息，请参阅LICENSE.md文件。

支持

有关支持，请联系support@fib-payment.com或访问我们的网站。

致谢

感谢FIB支付开发团队的贡献。此SDK使用cURL库进行API请求。

版本控制

我们使用语义版本控制（SemVer）原则进行后续版本（v0.2.0、v0.3.0等）的发布。有关可用的版本，请参阅此存储库的标签。

常见问题

问：我如何获取FIB支付系统的API密钥？

A：请通过 support@fib-payment.com 联系我们的支持团队以获取API密钥。

Q：我能否在生产环境中使用这个SDK？

A：是的，SDK是为生产环境设计的，但请确保您已正确配置，并获取了必要的凭证。

first-iraqi-bank / fib-php-payment-sdk

维护者

详细信息