README

本软件包为 Laravel 应用程序提供与 AmeriaBank VPOS 的简单方便集成。

🚀 安装

通过 Composer 安装该软件包。

composer require ayvazyan10/ameriabankvpos

发布配置文件和数据库迁移。

php artisan vendor:publish --provider="Ayvazyan10\AmeriaBankVPOS\AmeriaBankVPOSServiceProvider"

这将在您的应用程序中创建 [config/ameriabankvpos.php] 和 [database/migrations] 文件。

php artisan migrate

⚙️ 配置

发布配置文件后，您应在 config/ameriabankvpos.php 文件或 .env 文件中设置您的 AmeriaBank VPOS 凭据/选项。

AMERIABANKVPOS_CLIENT_ID=your_client_id
AMERIABANKVPOS_USERNAME=your_username
AMERIABANKVPOS_PASSWORD=your_password
AMERIABANKVPOS_BACK_URL=your_back_url_route_name
AMERIABANKVPOS_TEST_MODE=true_or_false
AMERIABANKVPOS_CURRENCY=your_currency
AMERIABANKVPOS_LANGUAGE=your_language

📚 使用

以下是如何在 Laravel 应用程序中使用 AmeriaBankVPOS 门面或辅助函数的示例。

use Ayvazyan10\AmeriaBankVPOS\Facades\AmeriaBankVPOS;

// Process the payment with facade and redirect to AmeriaBank payment interface
$initPayment = AmeriaBankVPOS::pay($amount, $orderId, array $options);
// or with helper
// Process the payment with helper and get success response to redirect AmeriaBank payment interface
$initPayment = ameriabank()->pay($amount, $orderId, array $options);

if($initPayment['status'] === "SUCCESS") {
    // If you need to store payment id in your database
    // For get full response use: $initPayment['response'];
    $paymentId = $initPayment['paymentId'];
    // Redirect to AmeriaBank payment interface
    return redirect($initPayment['redirectUrl']);
}

// Check the payment status and return the transaction details
$response = AmeriaBankVPOS::check($request);

// or with helper

$response = ameriabank()->check($request);

// Retrieve data from the transaction
if ($response['status'] === 'SUCCESS') {
    $transaction = $response['transaction'];

    $order_id = $transaction->order_id;
    $user_id = $transaction->user_id;
    $payment_id = $transaction->payment_id;
    $provider = $transaction->Provider;
    // more fields as needed ...
    // you can find all fields in ameriabank_transactions table
}

📋 状态

此软件包将支付状态作为字符串返回到响应数组的 status 键。可能的状态有：

SUCCESS：支付已批准并可处理。
FAIL：支付失败或被拒绝。

⚡ 所有方法

public function cancelPayment(int|string $paymentId): array;

public function check($request): array;

public function getPaymentDetails(int|string $paymentId): array;

public function pay(int|float $amount, int $orderId, array $options = []): array;

public function refund(int|string $paymentId, int|float $refundAmount): array;

public function makeBindingPayment(int|float $amount, int $orderId, array $options = []): array;

public function getBindings(): array;

public function deactivateBinding(string $cardHolderId): array;

public function activateBinding(string $cardHolderId): array;

📖 示例

以下是一些在不同场景下使用软件包的示例。

示例 1：简单支付

use Ayvazyan10\AmeriaBankVPOS\Facades\AmeriaBankVPOS;

$amount = 100; // minimum amount while testing is 10 AMD
$orderId = 1; // in test mode order id should be from 2923001 to 2924000
$description = 'Test Payment'; // optional

$initPayment = AmeriaBankVPOS::pay($amount, $orderId, ['Description' => $description]);

if($initPayment['status'] === "SUCCESS") {
    // If you need to store payment id in your database
    // For get full response use: $initPayment['response'];
    $paymentId = $initPayment['paymentId'];
    // Redirect to AmeriaBank payment interface
    return redirect($initPayment['redirectUrl']);
}

示例 2：具有自定义货币和语言的支付，也重定向到不同的页面

use Ayvazyan10\AmeriaBankVPOS\Facades\AmeriaBankVPOS;

// NOTE. Array is optional and default data injecting from configuration file

$amount = 100;
$orderId = 1;
$description = 'Test Payment'; // optional
$currency = '840'; // optional - currency ISO code (current:USD)
$language = 'en'; // optional
$BackURL = route('my.rounte.name'); // or just url: "https://...."
$opaque = 'Some additional information';

$initPayment = AmeriaBankVPOS::pay($amount, $orderId, [
    'Currecny' => $currency,
    'Language' => $language,
    'BackURL' => $BackURL,
    'Opaque' = $opaque,
]);

if($initPayment['status'] === "SUCCESS") {
    // If you need to store payment id in your database
    // For get full response use: $initPayment['response'];
    $paymentId = $initPayment['paymentId'];
    // Redirect to AmeriaBank payment interface
    return redirect($initPayment['redirectUrl']);
}

示例 3：处理支付响应

use Ayvazyan10\AmeriaBankVPOS\Facades\AmeriaBankVPOS;
use Illuminate\Http\Request;

// In your controller method, where you handle the payment response
public function handlePaymentResponse(Request $request)
{
    $response = AmeriaBankVPOS::check($request);

    if ($response['status'] === 'SUCCESS') {
        // Handle successful payment
        $transaction = $response['transaction'];
        // You can retrieve additional transaction data as needed
        // For example: $transaction->order_id, $transaction->user_id, etc.
    } else {
        // Handle failed payment
        // Also can retrieve additional transaction data as needed
    }
}

示例 4：获取支付详情

use Ayvazyan10\AmeriaBankVPOS\Facades\AmeriaBankVPOS;
use Exception;

// In your controller method or anywhere else
public function giveMeID($payment_id)
{
    try {
        // Actual payment ID to be retrieved
        $paymentDetails = AmeriaBankVPOS::getPaymentDetails($paymentId);
        
        // Will return details in array
        // Handle payment details as needed
        // For example: $paymentDetails['ApprovedAmount'], $paymentDetails['Description'], etc...
    } catch (Exception $e) {
        // Handle exception as needed
        // For example: Log the error or return an error response
    }
}

示例 5：部分退款特定支付

use Ayvazyan10\AmeriaBankVPOS\Facades\AmeriaBankVPOS;
use Exception;

// In your controller method or anywhere else
public function refundPayment($paymentId, $refundAmount)
{
    try {
        // Refund a specific payment partially
        $refundDetails = AmeriaBankVPOS::refund($paymentId, $refundAmount);
        
        // Will return refund status and details in array
        // Handle refund details as needed
        // For example: $refundDetails['status'], $refundDetails['response']['ResponseCode'], etc...
    } catch (Exception $e) {
        // Handle exception as needed
        // For example: Log the error or return an error response
    }
}

此方法发送 API 请求以部分退款特定支付。它需要两个参数

$paymentId：要退款的支付 ID。此参数是必需的，可以是整数或字符串值。$refundAmount：要退款的金额。此参数是必需的，可以是整数或浮点值。方法返回一个关联数组，包含两个键

"status"：指示退款操作的状态。可能的值是 "SUCCESS" 或 "FAIL"。 "response"：包含来自 API 的响应数据。如果退款操作成功，响应数据将包含关于退款金额的详细信息，否则将包含错误消息。如果 API 请求期间发生错误，该方法将抛出一个异常，其中包含描述错误的消息。

示例 6：取消支付

use Ayvazyan10\AmeriaBankVPOS\Facades\AmeriaBankVPOS;
use Exception;

// In your controller method or anywhere else
public function cancelPayment($paymentId)
{
    try {
        // Cancel a specific payment
        $cancellationDetails = AmeriaBankVPOS::cancelPayment($paymentId);
        
        // Will return cancellation status and details in array
        // Handle cancellation details as needed
        // For example: $cancellationDetails['status'], $cancellationDetails['response']['ResponseCode'], etc...
    } catch (Exception $e) {
        // Handle exception as needed
        // For example: Log the error or return an error response
    }
}

在此示例中，调用 cancelPayment 方法时使用 $paymentId 参数。在 try 块内，调用 AmeriaBankVPOS::cancelPayment() 方法，并提供付款 ID 以启动付款取消操作。该方法返回一个关联数组，包含两个键："status" 和 "response"。这些键分别包含取消状态和详细信息。

调用 cancelPayment 方法后，您可以按需处理返回的详细信息。例如，您可以通过 "status" 键检查取消操作是否成功，并使用 "response" 键获取关于取消操作的更多详细信息。如果在 API 请求期间抛出异常，catch 块将被执行，您可以根据需要处理错误，例如记录它或返回错误响应。

示例 7：绑定支付（订阅用户卡）

use Ayvazyan10\AmeriaBankVPOS\Facades\AmeriaBankVPOS;
use Exception;

// In your controller method or anywhere else
public function payForBinding()
{
    // We passing CardHolderID and say with it that this payment need to subscribe
    // for first time
    ameriabank()->pay(10, '3073028', [
        'BackURL' => 'http://127.0.0.1:8000/my-back-route',
        'CardHolderID' => 'EXAMPLEUNIQUESTRING'
    ]);
    
    // After that we can use EXAMPLEUNIQUESTRING to charge user card 
    // with simple post request

    try {
       $resp = ameriabank()->makeBindingPayment(10, '3073035', [
        'CardHolderID' => 'EXAMPLEUNIQUESTRING'
       ]);
       
       dd($resp); // Will return binding payment details in array
       // if all is ok. We charged user card.
    } catch (Exception $e) {
        // Handle exception as needed
        // For example: Log the error or return an error response
    }
}

🛠️ 扩展和定制

如果您需要扩展或定制软件包行为，可以创建自己的类，该类扩展 AmeriaBankVPOS 类并按需覆盖方法。确保更新 config/app.php 中的 AmeriaBankVPOS 别名以指向您的自定义类。

贡献

请参阅contributing.md以获取详细信息和工作待办事项清单。

安全

如果您发现任何与安全相关的问题，请发送电子邮件至ayvazyan403@gmail.com，而不是使用问题跟踪器。

作者

Razmik Ayvazyan

许可协议

MIT。请参阅许可文件以获取更多信息。

ayvazyan10 / ameriabankvpos

维护者

详细信息