README

📌 概述

此包简化了将 PayFluid 支付集成到您的应用程序的过程。它支持 PayFluid 提供的所有端点。

生成安全的凭证。
生成支付链接以收集付款。
验证发送到您的重定向 URL 和回调 URL 的付款详情。
获取先前做出的付款的状态。
自定义支付页面，并自定义支付链接的行为。

🚜 工作原理

以下是通常的工作流程

创建支付链接
将用户重定向到支付页面
用户完成支付
用户被重定向到您的重定向 URL，并带有付款状态
验证付款状态
如果付款成功，向您的用户提供价值

就这些了！！

📚 内容

📌 概述
🚜 工作原理
️❗️ 注意
⏳ 安装
👼🏽 基本用法
💪🏽 高级用法
- 自定义支付页面和链接
✌🏽️ 小贴士和技巧
- 从 URL 传递和检索会话值
⚠️ 问题
👊🏽 贡献

❗️ 注意

注意：请注意，您的宿主设备的 IP 地址（您从中发出请求的地方）必须由 PayFluid 白名单批准才能使这些操作生效。

⏳ 安装

您需要 composer 来安装此包。您可以在这里获取它

composer require gitplus/payfluid

👼🏽 基本用法

请注意，为了简洁，故意省略了这些示例中的错误处理。

1. 生成支付链接。

这是一个快速入门指南，帮助您快速开始。

<?php

require("vendor/autoload.php");

use Gitplus\PayFluid\PayFluid;
use Gitplus\PayFluid\Payment;

try {
    // Create a new PayFluid client instance. The fourth(4th) parameter is
    // a boolean that indicates whether you are in live or test mode.
    // 'TRUE' for live mode, 'FALSE' for test mode.
    $payfluid = new PayFluid($clientId, $encryptionKey, $apiKey, $testOrLiveMode);
    
    // Get secure credentials to authenticate with the server.
    // The returned $credentials object here has your 'session' value.
    // It is a good idea to store it for later. You will need it to verify payments.
    $credentials = $payfluid->getSecureCredentials($phoneNumber);
    
    // Create a new payment object and set the required and any optional fields.
    // You can chain the methods.
    $payment = new Payment();
    $payment->amount(1.0)                               // (Required) The amount to charge.
        ->email($email)                                 // (Required) Customer's email address.
        ->phone($phoneNumber)                           // (Required) Customer's phone number.
        ->name($name)                                   // (Required) Customer's name.
        ->reference(bin2hex(random_bytes(5)))           // (Required) A unique alphanumeric string; 10 characters max.
        ->redirectUrl("https://your/redirect/url")      // (Required) Your user will be redirected here after paying.
        ->currency("GHS")                               // (Required but ignorable) Currency for the payment. Defaults to "GHS".
        ->language("en")                                // (Required but ignorable) Language for payment page. Defaults to "en". Other values: "fr"
        ->description("Enter description for the payment")      // (Optional) A description for the transaction; 40 characters max.
        ->callbackUrl("https://your/callback_or_webhook/url")   // (Optional) This is your webhook.
        ->otherInfo("Any extra information");                   // (Optional) Any extra information.
    
    // You can now get a payment link object.
    // Use both the payment object and secure credentials to get a payment link.
    $paymentLink = $payfluid->getPaymentLink($credentials, $payment);
    
    // You can then retrieve the web url and redirect your user to that location.
    // 
    // NOTE:
    // The $paymentLink object will also have your 'session' and 'payReference' values.
    // It is a good idea to store these values for later. You will need them to
    // verify payments or to retrieve the status of a particular payment later.
    $paymentLink->webUrl;
} catch (\Throwable $e) {
    // Handle error
    echo "Generating payment url failed: " . $e->getMessage();
}

2. 在您的重定向 URL 上验证交易。

当详情发送到您的重定向 URL 时，您可以这样验证支付。

<?php

require("vendor/autoload.php");

use Gitplus\PayFluid\PayFluid;

if ($_SERVER["REQUEST_METHOD"] === "GET") {
    try {
        // The request from PayFluid to your redirect URL will come with a 'qs' query parameter.
        // Don't worry about calling urldecode() on the 'qs' query parameter. It is handled internally.
        $qs = $_GET["qs"];
       
        // Use qs and your session value to verify the payment.
        // You can get your session value from two(2) places:
        //      1. From the $credentials object you got when you called the getSecureCredentials() method.
        //      2. From the $paymentLink object you got when you called the getPaymentLink() method
        //      It is a good idea to have stored these values somewhere earlier.
        //
        // The $paymentStatus object returned will have details on whether the transaction was successful or not.
        $paymentStatus = PayFluid::verifyPayment($qs, $session);
        
        // If statusCode = '0' then the payment was successful. Any other value
        // means the transaction failed. The statusString field will explain what
        // the code means.
        if ($paymentStatus->statusCode === "0") {
            // You can convert the payment status to a JSON string and perhaps store it for future reference
            $statusAsJson = $paymentStatus->toJson();
            
            // You can also retrieve it as an array if you want
            $statusAsArray = $paymentStatus->toArray();
            
            echo "Payment successful";
        } else {
            echo "Payment failed: " . $paymentStatus->statusString;
        }
    } catch (\Throwable $e) {
        echo "Verifying payment failed: " . $e->getMessage();
    }   
}

3. 在您的回调/网络钩子 URL 上验证交易。

当详情发送到您的回调/网络钩子 URL 时，您可以这样验证支付。

<?php

require("vendor/autoload.php");

use Gitplus\PayFluid\PayFluid;

if ($_SERVER["REQUEST_METHOD"] === "POST") {
    try {
        // Read JSON body from request
        $payload = json_decode(file_get_contents("php://input"));
    
        // NOTE:
        // The $session is from either your $secureCredentials or $paymentLink objects created earlier.
        // The $transactionDetails object returned has details on the success or otherwise of the payment.
        $statusCode = PayFluid::verifyPayment($payload, $session);
        
        // If statusCode = '0' then the payment was successful. Any other value
        // means the transaction failed. The statusString field will explain what
        // the code means.
        if ($paymentStatus->statusCode === "0") {
            // You can convert the payment status to a JSON string and perhaps store it for future reference
            $statusAsJson = $paymentStatus->toJson();
            
            // You can also retrieve it as an array if you want
            $statusAsArray = $paymentStatus->toArray();
            
            echo "Payment successful";
        } else {
            echo "Payment failed: " . $paymentStatus->statusString;
        }
    } catch (\Throwable $e) {
        echo "Verifying payment failed: " . $e->getMessage();
    }
}

4. 检查或确认先前付款的状态。

您可以这样联系 PayFluid 服务器以了解特定付款的状态。

<?php

require("vendor/autoload.php");

use Gitplus\PayFluid\PayFluid;

try {
    // Create a new PayFluid client instance.
    $payfluid = new PayFluid($clientId, $encryptionKey, $apiKey, $testOrLiveMode);
    
    // getPaymentStatus() will return a PaymentStatus object with details information on the status of the payment.
    // The $payReference is from the $paymentLink object you created earlier.
    // The $session is from either the $paymentLink or $credentials objects you created earlier.
    $paymentStatus = $payfluid->getPaymentStatus($payReference, $session);
    
    // If statusCode = '0' then the payment was successful. Any other value
    // means the transaction failed. The statusString field will explain what
    // the code means.
    if ($paymentStatus->statusCode === "0") {
        // You can convert the payment status to a JSON string and perhaps store it for future reference
        $statusAsJson = $paymentStatus->toJson();
        
        // You can also retrieve it as an array if you want
        $statusAsArray = $paymentStatus->toArray();
 
        echo "Payment successful";
    } else {
        echo "Payment failed: " . $paymentStatus->statusString;
    }
} catch (\Throwable $e) {
    // Handle error
    echo "Getting payment status failed: " . $e->getMessage();
}

💪🏽 高级用法

1. 自定义支付页面和链接行为。

⚠️ ⚠️ 实验（可能不会工作）。您已被警告 ⚠️ ⚠️

PayFluid 给您一些灵活性。您可以自定义您获得的 web url 的行为，也可以自定义将呈现给您的用户的支付页面的外观。以下是一个示例，说明您如何实现这一点。

<?php

require("vendor/autoload.php");

use Gitplus\PayFluid\PayFluid;
use Gitplus\PayFluid\Payment;
use Gitplus\PayFluid\Customization;
use Gitplus\PayFluid\CustomerInput;

try {    
    // Create a new customization object.
    $customization = new Customization();
    $customization->editAmount(true)            // The payment amount can be edited by the user
        ->minimumAmount(1.0)                    // Enforce the minimum amount to pay
        ->maximumAmount(30.0)                   // Enforce the maximum amount to pay
        ->borderTheme("#a3ffee")                // Set a color for the page
        ->receiptMessage("Thank you for your purchase")    // Override the message sent in receipt
        ->receiptFeedbackPhone("233XXXXXXX")               // Override the phone number that gets the receipt
        ->receiptFeedbackEmail("user@domain.com")          // Override the email that receives the receipt
        ->daysUntilLinkExpires(3)                          // Determine how long the payment link should be valid for
        ->canPayMultipleTimes(true)                        // Payment links are one time. This will make the link reusable
        ->displayPicture("https://link/to/publicly/accessible/image");  // Set your own image to be displayed on the payment page.
        
    // You can take your customization further.
    // PayFluid gives you the flexibility to even ask for more information on the
    // payment page. You do this by creating input fields. The fields will be
    // rendered on the payment page for the customer to provide answers to.
    // To achieve this you need to create CustomerInput objects and add
    // them to your customization object.
    
    // Create your first input. This will be a text input.
    $textInput = new CustomerInput();
    $textInput->label("Church Membership ID") // The label for the input
        ->placeholder("Membership ID #")      // The placeholder for the input
        ->type(CustomerInput::TYPE_TEXT)      // The type of input
        ->required(true);                     // Indicate whether the input is required or not.
        
    // Create another input but this time it will be a select dropdown.
    $selectInput = new CustomerInput();
    $selectInput->label("Offering Type")      // Label for the input field
        ->placeholder("Offering Type 2")      // Placeholder value for the field
        ->type(CustomerInput::TYPE_SELECT)    // Set the input as a select dropdown
        ->setOption("key", "value")           // Set the options that will be in the dropdown               
        ->setOption("key2", "value2");        // You can set more options for the dropdown
      
    // Add your inputs to your customization object
    $customization
        ->withCustomerInput($textInput)
        ->withCustomerInput($selectInput);
     
    // Now create a payment object and customize it with the customization.
    $payment = new Payment();
    $payment->amount(1.0)
        ->email($email)
        ->phone($phoneNumber)
        ->name($name)
        ->reference(bin2hex(random_bytes(5)))
        ->description("Enter description for the payment")
        ->redirectUrl("https://your/redirect/url")
        ->callbackUrl("https://your/callback_or_webhook/url")
        ->otherInfo("Any extra information")
        ->customize($customization);    // Add the customization you created
    
    // Create the PayFluid client instance.
    $payfluid = new PayFluid($clientId, $encryptionKey, $apiKey, $testOrLiveMode);
    
    // Generate credentials.
    // Remember the returned $credentials object here has your session value.
    // It is a good idea to store this value because you will need it to verify payments later.
    $credentials = $payfluid->getSecureCredentials($phoneNumber);
    
    // Get payment link.
    // Again the $paymentLink also has both your 'session' and 'payReference' values.
    // You will need them later for verification.
    $paymentLink = $payfluid->getPaymentLink($credentials, $payment);
    
    // Redirect the user to your customized payment page.
    $paymentLink->webUrl;
} catch (\Throwable $e) {
    // Handle error
    echo "Generating payment url failed: " . $e->getMessage();
}

✌🏽️ 小贴士

1. 从重定向或回调 URL 传递和检索会话值。

如果您发现难以存储您的会话值，您可以通过重定向或回调 URL 传递它。

<?php

require("vendor/autoload.php");

use Gitplus\PayFluid\PayFluid;

$payfluid = new PayFluid($clientId, $encryptionKey, $apiKey, $testOrLiveMode);
$credentials = $payfluid->getSecureCredentials($phone);

$payment = new Payment();
$payment->amount(1)
    ->description("Payment for something awesome")
    ->email($email)
    ->phone($phone)
    ->name($name)
    ->otherInfo("Some additional information here")
    ->reference(bin2hex(random_bytes(5)))
    ->redirectUrl("https://your/redirect/url/with/session/appended?session=" . $credentials->session)
    ->callbackUrl("https://your/callback/url/with/session/appended?session=" . $credentials->session);

// You can later retrieve them when the redirect or callback hits your endpoint.
$session = $_GET["session"];

⚠️ 问题

如果您遇到任何问题或问题，请随时在此处报告

👊🏽 贡献

欢迎贡献和改进

gitplus / payfluid

维护者

详细信息