README

与尼日利亚支付网关（Paystack 和 Rave）简单集成 - 此软件包简化了构建请求到这些 API 并获取响应以进行处理的流程。

要求、安装和配置

此软件包至少需要 php7.1

使用 Composer 进行安装

composer require kofi/ngpayments

此软件包使用 4 个配置值。您需要提供其中 2 个配置值，而软件包为其他两个提供了默认值。您可以使用 .env、PHP 常量或配置缓存来设置配置。

使用 .env（推荐）

NG_PAYMENT_PROVIDER=paystack 		        #if this variable is not set, paystack is the default
PAYSTACK_PUBLIC_KEY=**your public key** 	#the public key is required. 
PAYSTACK_PRIVATE_KEY=**your private key** 	#the private key is required
APP_ENV=production 				#if not set, this will default to testing

如果您使用 Rave（Flutterwave）而不是 Paystack，请将 PAYSTACK 前缀替换为 RAVE，并按如下方式设置您的支付提供程序

NG_PAYMENT_PROVIDER=rave 		#important, if you don't set this, it will default to paystack and search for Paystack keys
RAVE_PUBLIC_KEY=**your public key**
RAVE_PRIVATE_KEY=**your private key**
APP_ENV=production

在 config.php 文件中使用常量（不推荐）

define("NG_PAYMENT_PROVIDER", "rave");
define("RAVE_PUBLIC_KEY", "your rave public key");
define("RAVE_PRIVATE_KEY", "your rave private key");

缓存配置（适用于 Laravel 用户）

如果您正在使用 Laravel 的 artisan config:cache 命令在生产中缓存配置，则软件包将无法访问 .env 文件中的变量，因此您需要在您的服务提供程序中配置软件包。

首先将 .env 中的配置加载到 Laravel 的配置中，请访问 config/services.php 并执行此操作

'paystack' => [
   'public_key' => env('PAYSTACK_PUBLIC_KEY'), 
   'private_key' => env('PAYSTACK_PRIVATE_KEY')
 ];

然后在您的 AppServiceProvider 的 boot() 方法中（您也可以将其放置在任何其他服务提供程序中）执行此操作

public function boot(){
    //Create configuration
    $payment_provider_config = [
	    "provider" => "paystack", //If the provider is not set, default is Paystack
	    "public_key" => config("services.paystack.public_key"),
	    "secret_key" => config("services.paystack.private_key"),
	    "app_env" => config("app.env")
     ];

   //Tell the package to use this configuration
   PaymentProviderFactory::setPaymentProviderConfig($payment_provider_config);
}

配置 Http 异常和支付异常

默认情况下，对于软件包发出的请求，禁用 http 异常。但是，如果您想处理由 Guzzle Http 客户端抛出的 BadResponseException 异常，该异常由 4xx 和 5xx 级别的 http 响应抛出，您可以按这种方式启用 http 异常

PaymentProviderFactory::enableHttpExceptions();

设置请求参数

在将请求参数发送到配置的支付提供程序之前，此软件包为您提供了设置参数的一些灵活性。

例如，要使用 Paystack 向客户收费，例如 N7000，请按照以下步骤操作

$bill = new Bill("customer@email.com", 3000);     		//The Bill class always works with amounts in naira.
$payment_reference = $bill->charge()->getPaymentReference();
savePaymentReference($payment_reference); 			// save the generated reference to your database
$payment_page_url = $bill->getPaymentPageUrl(); 
header("Location: " . $payment_page_url);   			//redirect to Paystack's checkout page

使用 Bill 构造函数允许您设置请求所需的参数，但您可能还想发送一些额外的参数。例如，您可能想设置自己的支付参考，而不是使用 Paystack 为您生成的参考。在这种情况下，您可以执行以下操作之一

使用魔法设置方法

$bill = new Bill();
$bill->setCustomerEmail("customer@email.com")
     ->setReference("reference")
     ->setAmount(40000)
     ->setCallbackUrl($callback_url);
$payment_page_url = $bill->charge()->getPaymentPageUrl()
header("Location: ". $payment_page_url);

以这种方式设置的参数将自动以 snake_case 格式渲染并发送到配置的支付提供程序。

您可以使用 kebab-case 如此

$bill->setCallbackUrl($callback_url, 'kebab-case');

如果您不想应用任何类型的案例，则使用

$bill->setCallbackUrl($callback_url, 'none');

使用魔法属性

$bill = new Bill();
$bill->customer_email = "customer@email.com";
$bill->reference = "unique_reference";
$bill->callback_url = $callback_url;  

//if you are working with Paystack, 
//set the amount in kobo, 
//if you want to work with naira amounts (with Paystack)
//set the naira_amount property instead like so:
$bill->amount = 40000; 
$bill->naira_amount = 400;

$payment_page_url = $bill->charge()->getPaymentPageUrl()

//Redirect to the payment page. 
//If you are using a framework, use your framework's redirect method
header("Location: ". $payment_page_url);

使用参数的关联数组

$bill_data = [
    "customer_email" => "customer@email.com",
    "reference" => "unique_reference",
    "amount" => 4000,
    "callback_url" => $callback_url
];
$bill = new Bill($bill_data);

查看您要集成的提供程序的文档，了解有关各种端点的请求选项的更多信息。

账单

要向客户收取产品金额（例如 N7000），请按照以下步骤操作

1) 初始化支付并将客户重定向到支付页面

$bill = new Bill($customer_email, 7000); 
$reference = $bill->charge()->getPaymentReference(); //make sure to call the charge() method on bill first
savePaymentReferenceToDB($reference);
$payment_page_url = $bill->getPaymentPageUrl();
header("Location: ". $payment_page_url);

2) 验证客户是否支付了他们应支付的费用

通常，您会根据Paystack或Rave的请求执行此步骤，该请求是针对您在API仪表板中设置的回调URL或使用$bill->setCallbackUrl($url)请求的（有关更多信息，请参阅它们的文档）。

$reference = getPaymentReferenceFromSomewhere(); 
if(Bill::isPaymentValid($reference, 7000)){
    //send product to customer or activate account etc.
}

如果付款无效，默认情况下会抛出FailedPaymentException异常，您可以使用它来记录有关请求和从支付提供商收到的响应的详细信息

try{
  if(Bill::isPaymentValid($reference, 7000)){
    //do something
   }
}catch(FailedPaymentException $e){
  logFailedPayments($reference, $e->getResponse());
  //do any additional processing
}

如果您不想处理此类异常，可以使用以下方法禁用

PaymentProviderFactory::disablePaymentExceptions();

定期收费

Rave和Paystack都支持通过使用令牌进行定期收费。要使用定期收费向客户收费，您必须确保客户已至少向您支付一次，以便您的支付提供商可以生成用于未来收费的令牌。

要使用定期收费向客户收费，请按照以下步骤操作

1) 初始化Bill付款

$bill = new Bill($customer_email, 7000);
$reference = $bill->charge()->getPaymentReference();
$payment_page_url = $bill->getPaymentPageUrl();
redirect_to_url($payment_page_url) //if you are using a framework, use your framework's redirect method

2) 验证付款并存储来自支付提供商的授权代码或令牌

$authorization_code = Bill::getPaymentAuthorizationCode($reference, 7000); //This method validates the payment made by the customer and returns the authorization code (token) if the payment is valid

3) 创建AuthBill并在需要时向客户收费

请注意，您从提供商获得的授权代码仅对指定的客户电子邮件有效。

$auth_bill = new AuthBill($authorization_code, $customer_email, 3000); 
$reference = $auth_bill->charge(); //if the payment is successful, this returns a reference, if it fails, it returns null

分割收费

要与商家分享客户的付款，您需要首先为商家创建一个子账户，然后在向客户收费时使用子账户ID。有关子账户的更多信息，请参阅您的支付提供商的文档。

1) 创建并存储子账户

$subaccount = new Subaccount($business_name, $settlement_bank, $account_number, $percentage_charge); 

//the save method will create a subaccount 
//with your payment provider 
//and return the id or code of the created subaccount
$subaccount_id = $subaccount->save();

saveSubaccountIdToDatabase($subaccount_id)

要获取在创建子账户时使用的银行及其对应代码的列表，您可以调用Subaccount::fetchBanks()方法。

Paystack要求您在创建子账户时提供银行名称，而Rave要求您提供银行代码

与账单一样，您也可以使用魔术设置器和魔术属性来设置子账户的请求变量。

2) 使用创建的子账户分割账单

$subaccount_id = retrieveSubaccountIdFromDatabase()
$bill = new Bill($customer_email, 4000);
$reference = $bill->splitCharge($subaccount_id)->getPaymentReference();
$payment_page_url = $bill->getPaymentPageUrl();

您还可以使用子账户分割AuthBill付款

$subaccount_id = retrieveSubaccountIdFromDatabase()
$auth_bill = new AuthBill($authorization_code, $customer_email, 4000);
$reference = $auth_bill->splitCharge($subaccount_id);

3) 验证付款

$is_valid = Bill::isPaymentValid($reference, 4000);

计划和订阅

您还可以使用支付提供商创建支付计划并让客户订阅这些支付计划。

请注意，如果您这样做，客户将能够直接与Paystack或Rave取消订阅，因此您需要定期检查以确保客户在您提供价值之前未取消订阅。

1) 创建支付计划

$plan = new Plan("My Plan", 3000, "weekly");
$plan_id = $plan->save();

2) 将客户订阅到支付计划

$bill = new Bill($customer_email, 3000);            //the plan amount will always override the bill amount in this case
$reference = $bill->subscribe($plan_id)->getPaymentReference(); 
$payment_page_url = $bill->getPaymentPageUrl();   
header("Location: " . $payment_page_url);          //redirect to the payment page

与Paystack集成

当您在Paystack中创建计划或子账户时，Paystack会返回两种标识这些对象的方式：一个字母数字代码和一个ID。

当您调用$plan->save()或$subaccount->save()方法时，您将获得一个字母数字代码。原因在于，虽然您可以使用数字ID标识计划和子账户，但您不能使用该数字ID初始化付款。您需要代码。

因此，当您保存子账户或计划时，您将获得一个字母数字代码，然后您可以将其存储在数据库中以用于未来的交易。

与Rave集成

Rave中的子账户创建

与此包一起提供的Subaccount类在其构造函数中有4个默认参数

class Subaccount implements ApiDataMapperInterface
{
   ...
   public function __construct(
      $business_name = null,
      string $settlement_bank = null,
      string $account_number = null,
      $percentage_charge = null
   ){...}
   ...

在Rave的创建子账户端点的文档中，您会发现Rave要求您设置比这更多的参数。该包帮助您将split_type设置为percentage并将country设置为NG。$percentage_charge在构造函数中用于设置Rave所需的split_value。如果您想使用百分比分割，这是可以的。

使用Rave创建子账户时，您仍然需要自行设置business_mobile和business_email，以便在调用$subaccount->save()方法时成功创建子账户。因此，要使用Rave创建子账户，您应该这样做

$subaccount = new Subaccount("Business Name", $settlement_bank, $merchant_account_number, $percentage_charge);
$subaccount->business_mobile = $business_mobile;
$subaccount->business_email = $business_email;
$subaccount_id = $subaccount->save();

另外，请注意，当您保存子账户时，您将获得子账户的字母数字ID，您可以使用它稍后用Bill或AuthBill初始化支付。

kofi / ngpayments

维护者

详细信息