Laravel Payment Package Documentation

Overview

This Laravel package provides a flexible and extensible solution for integrating various payment gateways into your Laravel application. It offers a unified interface for handling different payment services, making it easier to manage multiple payment providers within your project.

Key Features

• Easy integration with multiple payment gateways
• Unified interface for common payment operations (pay, cancel, refund)
• Customizable configuration for each payment service
• Built-in model for storing payment records
• Extensible architecture for adding new payment services

Installation

To install the package, run the following command in your Laravel project:

composer require unusualify/payable

Configuration

After installation, publish the configuration file:

php artisan vendor:publish --provider="Unusualify\Payable\LaravelServiceProvider"

This will create a payable.php configuration file in your config directory.

In the payable.php configuration file, you need to specify a route name for return_url. In default it is set as payment.response. You should create a GET & POST routes for the same url and specify a a route name.

Usage

Basic Usage

To use a payment service:

use Unusualify\Payable\Payable;

$payable = new Payable('gateway_slug');
$result = $payable->pay($params);

Replace 'gateway_slug' with the slug of your desired payment gateway (e.g., 'stripe', 'paypal').

Available Methods

• pay($params): Process a payment
• cancel($params): Cancel a payment
• refund($params): Refund a payment
• formatPrice($price): Format the price according to the gateway's requirements
• formatAmount($amount): Format the amount according to the gateway's requirements

Storing Payment Records

The package includes a Payment model for storing payment records. You can access it like any other Eloquent model:

use Unusualify\Payable\Models\Payment;

$payment = Payment::create([
    'payment_gateway' => 'paypal',
    'order_id' => '12345',
    'amount' => 1000,
    'currency_id' => 'USD',
    'status' => 'pending',
    'email' => '[email protected]',
    // ... other fields
]);

Payment Payload Guide

When using the pay() method, you need to provide a properly structured payload. Here's an example of a complete payment payload:

$payload = [
    // Required fields
    'amount' => 1000,                           // Amount in the smallest currency unit (e.g., cents)
    'currency' => 'USD',                        // Currency code in ISO 4217 format
    'order_id' => uniqid(''),                // Unique order identifier
    
    // Locale and payment details
    'locale' => 'en',                           // User's locale
    'installment' => '1',                       // Number of installments (if supported)
    'payment_group' => 'PRODUCT',               // Payment category
    
    // Card information
    'card_name' => 'John Doe',                  // Cardholder name
    'card_no' => '4111111111111111',            // Card number (no spaces)
    'card_month' => '12',                       // Expiration month
    'card_year' => '2025',                      // Expiration year
    'card_cvv' => '123',                        // Security code
    
    // User information
    'user_name' => 'John',                      // User's first name
    'user_surname' => 'Doe',                    // User's last name
    'user_gsm' => '+1234567890',                // User's phone number
    'user_email' => '[email protected]',     // User's email
    'user_ip' => '127.0.0.1',                   // User's IP address
    
    // Billing/shipping information
    'company_name' => 'Example Corp',           // Company name
    'user_address' => '123 Main St',            // Street address
    'user_city' => 'New York',                  // City
    'user_country' => 'US',                     // Country
    'user_zip_code' => '10001',                 // Postal/ZIP code
    
    // Basket information
    'basket_id' => uniqid(),                    // Unique basket identifier
    'items' => [
        [
            'id' => '1',                        // Product ID
            'name' => 'Product Name',           // Product name
            'category1' => 'Category',          // Primary category
            'category2' => 'Subcategory',       // Secondary category
            'price' => 1000,                    // Product price
            'type' => 'VIRTUAL',                // Product type
        ],
        // Add more items as needed
    ],
    
    // Custom data (optional)
    'custom_data' => [
        'reference_id' => 'REF123',
        'notes' => 'Special instructions'
    ],
];

// Optional payment record attributes
$paymentPayload = [
    'price_id' => 1,                            // Reference to your price model
    'payment_service_id' => 2,                  // Payment service ID
    'currency_id' => 3,                         // Currency ID in your system
];

$payable = new Payable('gateway_slug');
$result = $payable->pay($payload, $paymentPayload);

Notes:

• The amount should be provided in the smallest currency unit (e.g., cents for USD/EUR, pence for GBP)
• Different payment gateways may require different fields. Check your specific gateway's documentation
• The paymentPayload parameter is optional and used to store additional data in the payment record

Troubleshooting

[This section would typically include common issues and their solutions.]

Contributing

[Contribution guidelines would go here.]

License

The MIT License (MIT). Please see License File for more information.