README

A comprehensive Laravel SDK for integrating with the Rootline Payment API. This package provides easy-to-use classes for handling payments and generating reports.

Features

• Payment Management: Create, retrieve, update, cancel, capture, and refund payments
• Reporting: Generate transaction and settlement reports
• Laravel Integration: Seamless integration with Laravel applications
• Error Handling: Comprehensive error handling and logging
• Type Safety: Full PHP 8.0+ type hints and return types

Installation

Via Composer

composer require eriknohlmans/rootline-sdk

Publish Configuration

php artisan vendor:publish --tag=rootline-config

Configuration

Add your Rootline API credentials to your .env file:

ROOTLINE_API_SECRET=your_secret_token_here
ROOTLINE_BASE_URL=https://api.rootline.com

Note: The Rootline API uses header-based authentication with X-Api-Key. Only the API secret token is required.

The configuration file will be published to config/rootline.php where you can customize additional settings.

Usage

Basic Usage

use Rootline\RootlineSdk\RootlineSdk;

// Get the SDK instance from the container
$rootline = app(RootlineSdk::class);

// Or use the alias
$rootline = app('rootline');

Payment Operations

Create a Payment

$paymentData = [
    'amount' => 1000, // Amount in cents
    'currency' => 'USD',
    'description' => 'Payment for services',
    'customer_email' => 'customer@example.com',
    // ... other payment data
];

$payment = $rootline->createPayment($paymentData);

Create a Payment with Builder (Recommended)

The SDK provides a fluent builder for creating complex payment requests with splits:

use Rootline\RootlineSdk\Builders\PaymentBuilderFactory;

// Simple payment
$payment = PaymentBuilderFactory::payment()
    ->amount(1000)
    ->currency('USD')
    ->description('Payment for services')
    ->customerEmail('customer@example.com')
    ->customerName('John Doe')
    ->reference('ORDER-123')
    ->build();

// Payment with splits
$split = PaymentBuilderFactory::split()
    ->type('merchant')
    ->amount(800)
    ->description('Merchant portion');

$paymentWithSplit = PaymentBuilderFactory::payment()
    ->amount(1000)
    ->currency('USD')
    ->description('Payment with split')
    ->customerEmail('customer@example.com')
    ->split($split)
    ->build();

// Using with SDK
$paymentResult = $rootline->createPaymentWithBuilder(function($builder) {
    $split = PaymentBuilderFactory::split()
        ->type('merchant')
        ->amount(800)
        ->description('Merchant portion');
    
    $builder
        ->amount(1000)
        ->currency('USD')
        ->description('Payment via SDK builder')
        ->customerEmail('customer@example.com')
        ->split($split);
});

#### Multiple Splits

The builder supports multiple splits for complex payment structures:

// Create multiple splits $merchantSplit = PaymentBuilderFactory::split()

->accountId('acc_merchant_123')
->amount(900)
->reference('MERCHANT-123')
->description('Merchant portion');

$platformSplit = PaymentBuilderFactory::split()

->accountId('acc_platform_456')
->amount(100)
->reference('PLATFORM-123')
->description('Platform fee');

$paymentWithSplits = PaymentBuilderFactory::payment()

->amount(1000)
->currency('USD')
->description('Payment with multiple splits')
->customerEmail('customer@example.com')
->addSplit($merchantSplit)
->addSplit($platformSplit)
->build();

Custom API Secrets

You can set a custom API secret for individual payments using the builder:

// Set custom API secret for this specific payment
$payment = PaymentBuilderFactory::payment()
    ->amount(1000)
    ->currency('USD')
    ->description('Payment with custom API secret')
    ->customerEmail('customer@example.com')
    ->apiSecret('custom_secret_token_123')
    ->build();

// Using with SDK and custom API secret
$paymentResult = $rootline->createPaymentWithBuilderAndSecret(
    function($builder) {
        $builder
            ->amount(1000)
            ->currency('USD')
            ->description('Payment with custom API secret')
            ->customerEmail('customer@example.com');
    },
    'custom_secret_token_456'
);

This is useful when you need to use different API credentials for different payments or when you don't want to rely on the global configuration.

Available Builder Methods

Payment Builder Methods:

• amount(int $amount) - Set payment amount in cents
• currency(string $currency) - Set currency code (e.g., USD, EUR)
• description(string $description) - Set payment description
• reference(string $reference) - Set payment reference
• customerEmail(string $email) - Set customer email
• customerName(string $name) - Set customer name
• customerPhone(string $phone) - Set customer phone
• customerAddress(array $address) - Set customer address
• metadata(array $metadata) - Set custom metadata
• webhookUrl(string $url) - Set webhook URL
• returnUrl(string $url) - Set return URL
• cancelUrl(string $url) - Set cancel URL
• expiresAt(string $timestamp) - Set expiration timestamp
• apiSecret(string $apiSecret) - Set custom API secret for this payment
• split(SplitBuilder $split) - Set single payment split
• addSplit(SplitBuilder $split) - Add a split to the payment
• splits(array $splits) - Set multiple splits at once

Split Builder Methods:

• accountId(string $accountId) - Set the unique identifier for the account object (required)
• amount(int $amount) - Set split amount in cents (required)
• reference(string $reference) - Set your own reference to identify the payment split (required)
• description(string $description) - Set optional description for the payment split
• fees(array $fees) - Set fees applied to the split payment
• releaseFundsAt(string $releaseFundsAt) - Set when funds should be released
• splits(array $splits) - Set instructions for distributing payment amounts to recipient accounts

Retrieve a Payment

$payment = $rootline->getPayment('payment_id_here');

Update a Payment

$updateData = [
    'description' => 'Updated description',
    // ... other fields to update
];

$payment = $rootline->updatePayment('payment_id_here', $updateData);

Cancel a Payment

$payment = $rootline->cancelPayment('payment_id_here');

Capture a Payment

$captureData = [
    'amount' => 1000, // Amount to capture in cents
    // ... other capture data
];

$payment = $rootline->capturePayment('payment_id_here', $captureData);

Refund a Payment

$refundData = [
    'amount' => 500, // Amount to refund in cents
    'reason' => 'Customer request',
    // ... other refund data
];

$payment = $rootline->refundPayment('payment_id_here', $refundData);

Using Individual Classes

You can also use the Payment and Report classes directly:

// Payment class
$payment = $rootline->payment();
$result = $payment->create($paymentData);

// Report class
$report = $rootline->report();
$transactions = $report->transactions(['date_from' => '2024-01-01']);
$settlements = $report->settlements(['settlement_id' => 'settlement_123']);

Reporting

Transaction Reports

$filters = [
    'date_from' => '2024-01-01',
    'date_to' => '2024-01-31',
    'status' => 'completed',
    // ... other filters
];

$transactions = $rootline->getTransactionReports($filters);

Settlement Reports

$filters = [
    'date_from' => '2024-01-01',
    'date_to' => '2024-01-31',
    'settlement_id' => 'settlement_123',
    // ... other filters
];

$settlements = $rootline->getSettlementReports($filters);

API Endpoints

Payment Endpoints

• POST /v1/payments - Create a new payment
• GET /v1/payments/{id} - Retrieve a payment
• PUT /v1/payments/{id} - Update a payment
• POST /v1/payments/{id}/cancel - Cancel a payment
• POST /v1/payments/{id}/capture - Capture a payment
• POST /v1/payments/{id}/refund - Refund a payment

Report Endpoints

• GET /v1/reports/transactions - Get transaction reports
• GET /v1/reports/settlements - Get settlement reports

Error Handling

The SDK includes comprehensive error handling:

try {
    $payment = $rootline->createPayment($paymentData);
} catch (\Exception $e) {
    // Handle API errors
    Log::error('Payment creation failed: ' . $e->getMessage());
}

All API errors are logged automatically for debugging purposes.

Testing

Run the test suite:

composer test

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

This package is open-sourced software licensed under the MIT license.

Support

For support, please refer to the Rootline API documentation or create an issue in this repository.