README

这是一个Flutterwave的PHP SDK包装器。

1. 开始使用
2. API参考

包含的服务

• 账户
  • 获取所有账户的余额
  • 获取特定账户的余额
• OTP
  • 创建（可选发送）一个OTP
  • 验证OTP
• 支付计划
  • 创建支付计划
  • 获取所有计划
  • 获取特定计划
  • 更新计划
  • 取消计划
• 结算
  • 获取所有结算记录
  • 获取特定结算记录
• 标准支付集成
  • 启动一次性支付
  • 启动周期性支付（涉及将付款人订阅到支付计划）
• 订阅
  • 获取所有订阅列表
  • 获取特定计划的全部订阅
  • 获取特定用户的全部订阅
  • 获取用户在计划中的订阅
  • 获取特定订阅
  • 取消订阅
  • 激活订阅
• 验证
  • 验证交易

需求

• PHP >= 7.1
• ext-json
• ext-openssl
• ext-mbstring
• ext-openssl
• ext-iconv
• ext-curl
• guzzlehttp/guzzle: "^7.1"

安装

composer require phelix/flutterwave

如何测试

要测试该包，请将src目录下的"LoadEnv.php.example"文件复制到"LoadEnv.php"，填写所需的配置值，然后运行以下命令：

vendor/bin/phpunit test

文档

docs文件夹包含每个类、方法、属性、命名空间等的技术文档。为了使您能够参考以了解类的作用、函数的作用或方法参数的含义，文档为每个提供了详细的描述。

由于这是一个Flutterwave API的包装器，您可以从Flutterwave API参考页面获取更多详细信息。

此SDK版本不包括“包含的服务”部分中未列出的服务。

1. 账户

处理账户余额

<?php 

    use Phelix\Flutterwave\Flutterwave;
    use Phelix\Flutterwave\Account;
    use Phelix\Flutterwave\Exceptions\FlutterwaveException;

    try {
    
        // We initialize Flutterwave. Only the secret key is compulsory. The rest are optional.
        $flutterwave = new Flutterwave($_ENV["FLUTTER_WAVE_SECRET_KEY"], $_ENV["FLUTTER_WAVE_ENCRYPTION_KEY"], $_ENV["FLUTTER_WAVE_PUBLIC_KEY"]);
        
        $flutterwave->init();

        $account = new Account($flutterwave);
        
        //1. Get balances for all accounts
        $balances = $account->getAllBalances();
        
        // 2. Get balance for a specific account (identified by currency)
        $kes_account_balance = $account->getAccountBalance("KES");

    } catch (FlutterwaveException $exception) {
        print $exception->getMessage();
        // log and/or handle exceptions here
    }
        

1. 一次性PIN（OTP）

在您使用flutterwave生成和验证OTP的地方使用此功能

<?php 

    use Phelix\Flutterwave\Flutterwave;
    use Phelix\Flutterwave\OTP;
    use Phelix\Flutterwave\Exceptions\FlutterwaveException;

    try {
    
        // We initialize Flutterwave. Only the secret key is compulsory. The rest are optional.
        $flutterwave = new Flutterwave($_ENV["FLUTTER_WAVE_SECRET_KEY"], $_ENV["FLUTTER_WAVE_ENCRYPTION_KEY"], $_ENV["FLUTTER_WAVE_PUBLIC_KEY"]);
        
        $flutterwave->init();

        $otp = new OTP($flutterwave);
        
        //1. Use this to generate and send an OTP to a customer
        $otp_response = $otp->createOTP("Joehn Doe","john.doe@example.com" ,"0112345678", "JP Enterprises", 5, ['whatsapp', 'sms'], 60, true);
        
        // 2. Use this to verify/validate an OTP
        $otp_val = $otp->validateOTP("otp_reference", 12345);

    } catch (FlutterwaveException $exception) {
        print $exception->getMessage();
        // log and/or handle exceptions here
    }

3. 支付计划

用于处理支付计划

<?php 

    use Phelix\Flutterwave\Flutterwave;
    use Phelix\Flutterwave\PaymentPlan;
    use Phelix\Flutterwave\Exceptions\FlutterwaveException;

    try {
    
        // We initialize Flutterwave. Only the secret key is compulsory. The rest are optional.
        $flutterwave = new Flutterwave($_ENV["FLUTTER_WAVE_SECRET_KEY"], $_ENV["FLUTTER_WAVE_ENCRYPTION_KEY"], $_ENV["FLUTTER_WAVE_PUBLIC_KEY"]);
        
        $flutterwave->init();

        $plan = new PaymentPlan($flutterwave);
        
        //1. Use this to create a plan. (This creates a plan named "Test Plan" for KES 1000 to be deducted monthly for 12 months
        $response = $plan->createPlan("KES", "Test Plan", 1000, "monthly", 12);
        
        // 2. Use this to list all your plans
        $plans = $plan->getPlans();
        
        // 3. Use this to get a specific plan
        $plan = $plan->getOnePlan(1);
        
        // 4. Use this to update name of a plan
        $update = $plan->updatePlan(1, "New Name");
        
        // 5. Use this to cancel a plan
        $cancelled = $plan->cancelPlan(1);
        
    } catch (FlutterwaveException $exception) {
        print $exception->getMessage();
        // log and/or handle exceptions here
    }

4. 结算

当处理商家与dlutterwave之间的结算时使用此功能

<?php 

    use Phelix\Flutterwave\Flutterwave;
    use Phelix\Flutterwave\Settlement;
    use Phelix\Flutterwave\Exceptions\FlutterwaveException;

    try {
    
        // We initialize Flutterwave. Only the secret key is compulsory. The rest are optional.
        $flutterwave = new Flutterwave($_ENV["FLUTTER_WAVE_SECRET_KEY"], $_ENV["FLUTTER_WAVE_ENCRYPTION_KEY"], $_ENV["FLUTTER_WAVE_PUBLIC_KEY"]);
        
        $flutterwave->init();

        $settlement = new Settlement($flutterwave);
        
        //1. Use this to get the list of all settlements
        $response = $settlement->getSettlements();
        
        // 2. Use this to get one settlement
        $response = $settlement->getOneSettlement(1);
        
    } catch (FlutterwaveException $exception) {
        print $exception->getMessage();
        // log and/or handle exceptions here
    }

5. 标准集成

用于Flutterwave标准集成。在启动支付的部分使用此功能。有关更多详细信息，请参阅此处。

<?php 
    
    use Phelix\Flutterwave\Flutterwave;
    use Phelix\Flutterwave\Standard;
    use Phelix\Flutterwave\Exceptions\FlutterwaveException;

    try {
    
        // We initialize Flutterwave. Only the secret key is compulsory. The rest are optional.
        $flutterwave = new Flutterwave($_ENV["FLUTTER_WAVE_SECRET_KEY"], $_ENV["FLUTTER_WAVE_ENCRYPTION_KEY"], $_ENV["FLUTTER_WAVE_PUBLIC_KEY"]);
        
        $flutterwave->init();

        $standard = new Standard($flutterwave);
        
        //1. Use this to initiate a one time payment
        $response = $standard
                    ->setCustomizations("JP Enterprises", "Subsidiary of JP Holdings", "https://helixjuma.com.com/avatar.png")
                    ->setCustomer("Jane Doe", "jane.doe@doedom.com", "+254701234456")
                    ->setTransactionReference("1234REFJANEDOE")
                    ->setCurrency("KES")
                    ->setAmount(1000)
                    ->setMetaData(["category_id" => 1, 'transaction_type' => "payment_for_doedom"])
                    ->setRedirectURL("https://phelixjuma.com/flutterwave-ipn")
                    ->payViaCard() // Use this to pay via card. To use other payment options, check docs for all the other options
                    ->initiateOneTimePayment();
        
        // 2. Use this to initiate a recurrent payment (ie user is subscribed to a payment plan)
        $response = $standard
                    ->setCustomizations("JP Enterprises", "Subsidiary of JP Holdings", "https://helixjuma.com.com/avatar.png")
                    ->setCustomer("Jane Doe", "jane.doe@doedom.com", "+254701234456")
                    ->setTransactionReference("1234REFJANEDOE")
                    ->setCurrency("KES")
                    ->setAmount(1000)
                    ->setMetaData(["category_id" => 1, 'transaction_type' => "payment_for_doedom"])
                    ->setRedirectURL("https://phelixjuma.com/flutterwave-ipn")
                    ->setPaymentPlan(8021) // this is where we set the payment plan id
                    ->payViaCard() // Use this to pay via card. To use other payment options, check docs for all the other options
                    ->initiateRecurrentPayment();
        
        /**
         * After a transaction is initiated above, you get a link that you are supposed to redirect the user to. 
         * Redirect the user to the link where they will do the payments afterwhich Flutterwave redirects them to your redirect url set above
         * Sample redirect from Flutterwave looks like: https://phelixjuma.com/flutterwave-ipn?status=successful&tx_ref=1234&transaction_id=1686665
         * Check section below on how to handle and complete transaction in the IPN page.   
         */
    } catch (FlutterwaveException $exception) {
        print $exception->getMessage();
        // log and/or handle exceptions here
    }

6. IPN（支付验证）

在您的IPN（启动支付时设置的跳转URL）中使用此功能

<?php 
        
    use Phelix\Flutterwave\Flutterwave;
    use Phelix\Flutterwave\Verification;
    use Phelix\Flutterwave\Exceptions\FlutterwaveException;
    
    try {
        
        // We initialize Flutterwave. Only the secret key is compulsory. The rest are optional.
        $flutterwave = new Flutterwave($_ENV["FLUTTER_WAVE_SECRET_KEY"], $_ENV["FLUTTER_WAVE_ENCRYPTION_KEY"], $_ENV["FLUTTER_WAVE_PUBLIC_KEY"]);
        
        $flutterwave->init();

        $verification = new Verification($flutterwave);
        
        // Your IPN will have query parameters added by Flutterwave. An example is as shown:
        //  https://phelixjuma.com/flutterwave-ipn?status=successful&tx_ref=1234&transaction_id=1686665
        
        // At this stage, you must verify the transaction before confirming that it is successful. Don't just assume it is successful
        // due to the status parameter in the url
        
        $transactionId = sanitize($_GET['transaction_id']); // sanitize() is an arbitrary function. Use your implementation
        $transactionReference = sanitize($_GET['tx_ref']); // sanitize() is an arbitrary function. Use your implementation
        
         // Get the transaction you had initiated by doing a query to your database. getTransaction() is an arbitrary function. 
        $transaction = getTransaction($transactionReference);
        
        if ($transaction) {
            
            $response = $verification->verify($transactionId, $transactionReference, $transaction['currency'], $transaction['amount']);
            
            // Response is an array of the format $response = ['verified' => true|false,'message' => "response message", 'data'=> <response data>];
            
            if ($response['verified'] !== false) {
                // Verified transaction. Update transaction as successful
            } else {
                // Transaction not verified. Get actual status from $response['data']['status']. Check Flutterwave docs for more details.
            }
            
        } else {
            // transaction does not exist. Possibly a modified IPN. Log the attempt.
        }
    } catch (FlutterwaveException $exception) {
        print $exception->getMessage();
        // log and/or handle exceptions here
    }

7. 订阅

用于订阅

<?php 
        
    use Phelix\Flutterwave\Flutterwave;
    use Phelix\Flutterwave\Subscription;
    use Phelix\Flutterwave\Exceptions\FlutterwaveException;
    
    try {
    
        // We initialize Flutterwave. Only the secret key is compulsory. The rest are optional.
        $flutterwave = new Flutterwave($_ENV["FLUTTER_WAVE_SECRET_KEY"], $_ENV["FLUTTER_WAVE_ENCRYPTION_KEY"], $_ENV["FLUTTER_WAVE_PUBLIC_KEY"]);
        
        $flutterwave->init();

        $subscription = new Subscription($flutterwave);
            
        // 1. Use this to get subscriptions
        $response = $subscription->getSubscriptions();
        
        // 2. Use this to get subscriptions for a plan. Check docs for the other parameters eg pagination
        $response = $subscription->getPlanSubscriptions(1020);
        
        // 3. Use this to get a user's plan subscription. Check docs for the other parameters eg pagination
        $response = $subscription->getUserPlanSubscriptions(8021, "janedoe@doedom.com");
        
        // 4. Get all subscriptions for a user. Check docs for the other parameters eg pagination
        $response = $subscription->getUserSubscriptions("janedoe@doedom.com");
        
        // 5. Get a specific subscription
        $response = $subscription->getOneSubscription(1);
        
        // 6. Cancel a subscription
        $response = $subscription->cancelSubscription(1);
        
        // 7. Activate a subscription
        $response = $subscription->activateSubscription(1);
        
    } catch (FlutterwaveException $exception) {
        print $exception->getMessage();
        // log and/or handle exceptions here
    }

6. 响应和错误代码

所有响应和错误代码与Flutterwave类似。有关错误代码的详细信息，请参阅此处。

通常，所有/大多数响应都遵循以下标准结构：

    $response = [
        "success" => true|false,
        "message" => "",
        "data" => []
    ];

在某些情况下，还会包括元数据，例如获取项目列表时所示：

    $response = [
        "status" => 'success',
        "message" => "",
        "data" => [],
        "meta  => [
            "page_info" => [
                "total" => 44,
                "current_page" => 1,
                "total_pages" => 5
             ]
    ];

信用

• 来自Kuza Lab Ltd的Phelix Juma (jumaphelix@kuzalab.com)