buckaroo/laravel

Laravel Wrapper package for Buckaroo Payments Gateway

2.0.1 2024-11-01 08:45 UTC

Requires

• php: >=8.0
• buckaroo/sdk: ^1.10.0
• illuminate/support: ^9.0|^10.0|^11.0
• laravel/framework: ^9.0|^10.0|^11.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.13
• graham-campbell/testbench: ^5.0
• laravel/pint: ^1.16
• phpunit/phpunit: ^9.5
• vlucas/phpdotenv: ^5.5

MIT

• Buckaroo

README

Laravel Buckaroo Payment Integration

Table of Contents

• Introduction
• Prerequisites
• Installation
  • Step 1: Install the Package
  • Step 2: Publish Configuration and Assets
  • Step 3: Run Migrations
  • Step 4: Obtain Your Website and Secret Keys
  • Step 5: Configure Environment Variables
• Configuration
  • Transaction Model Override
  • Customizing Routes
• Usage
  • Initializing the Buckaroo Client
  • Starting a Payment Transaction
    • Using Payload Array
    • Using Setter Methods
  • Direct Usage with Buckaroo Wrapper
  • Other Services
• Additional Information
• Contributing
• Versioning
• Support
• License

Introduction

Welcome to the Laravel Buckaroo Payment Integration package! This package offers a seamless integration of Buckaroo payment services into your Laravel application, enabling you to handle payments, refunds, captures, and authorization cancellations effortlessly.

The package is designed to be highly customizable, allowing developers to override and extend functionalities based on their requirements, making it flexible and adaptable for various use cases.

Prerequisites

Ensure you have the following requirements before proceeding:

• PHP: Version 8.0 or higher
• Laravel Framework: Compatible with your Laravel version
• Buckaroo Account:
  • Dutch
  • English
• SSL/TLS Toolkit: An updated OpenSSL or any other SSL/TLS toolkit

Installation

Follow these steps to install and set up the Laravel Buckaroo Payment Integration package.

Step 1: Install the Package

Use Composer to install the package:

composer require buckaroo/laravel

Step 2: Publish Configuration and Assets

Publish the package's configuration and assets using Artisan:

php artisan vendor:publish --provider="Buckaroo\Laravel\BuckarooServiceProvider"

This command will create configuration, migration, and route files in your Laravel project.

Step 3: Run Migrations

Execute the migrations to set up the required database tables:

php artisan migrate

Step 4: Obtain Your Website and Secret Keys

To integrate Buckaroo, you’ll need your Website Key and Secret Key. Obtain these from your Buckaroo account:

• Website Key: Retrieve Here
• Secret Key: Retrieve Here

Step 5: Configure Environment Variables

Add the following environment variables to your .env file:

BPE_WEBSITE_KEY=your_website_key
BPE_SECRET_KEY=your_secret_key
BPE_MODE=test or live

• BPE_WEBSITE_KEY: Replace your_website_key with your Website Key.
• BPE_SECRET_KEY: Replace your_secret_key with your Secret Key.
• BPE_MODE: Set to test for testing or live for production.

These settings allow the Buckaroo Client to initialize automatically during your application’s boot process.

Configuration

The package offers a variety of configuration options to suit different use cases.

Transaction Model Override

By default, the package uses the BuckarooTransaction model to handle transactions. However, if you want to override this with your custom model, you can configure it in config/buckaroo.php:

'transaction_model' => YourCustomTransactionModel::class,

The default value is:

'transaction_model' => Buckaroo\Laravel\Models\BuckarooTransaction::class,

This allows you to maintain control over transaction handling and extend the functionality as needed.

Customizing Routes

The package provides predefined routes for handling payment operations. If you prefer to customize these routes, you can configure the following options in config/buckaroo.php:

'routes' => [
    'load' => env('BPE_LOAD_ROUTES', true),
    'prefix' => env('BPE_ROUTE_PATH', 'buckaroo'),
],

• load: Set this to false to prevent the package from automatically loading routes if you intend to define them yourself.
• prefix: Change the prefix to customize the route paths (default is buckaroo).

By adjusting these settings, you have full control over the routing structure in your application.

Usage

Initializing the Buckaroo Client

The Buckaroo client can be initialized automatically using the .env variables or manually if needed:

use Buckaroo\Laravel\Facades\Buckaroo;
use Buckaroo\Transaction\Config\DefaultConfig;

Buckaroo::api()->setBuckarooClient(
    new DefaultConfig(
        websiteKey: config('buckaroo.website_key'),
        secretKey: config('buckaroo.secret_key'),
        mode: config('buckaroo.mode'),
        returnURL: route('buckaroo.return'),
        pushURL: route('buckaroo.push'),
    )
);

Starting a Payment Transaction

You can initiate a payment transaction using the PayService and PaymentMethodFactory.

Using Payload Array

use Buckaroo\Laravel\Api\PayService;
use Buckaroo\Laravel\Handlers\PaymentMethodFactory;

$paymentSessionService = PayService::make(
    PaymentMethodFactory::make('noservice')->setPayload([
        'currency' => 'EUR',
        'amountDebit' => 100,
        'order' => '000-ORD',
        'invoice' => '000-INV',
        'description' => 'This is a description',
        'continueOnIncomplete' => '1',
        'servicesSelectableByClient' => 'ideal,bancontactmrcash',
    ])
);

Using Setter Methods

$paymentSessionService = PayService::make(
    PaymentMethodFactory::make('noservice')
        ->setCurrency('EUR')
        ->setAmountDebit(100)
        ->setOrder('000-ORD')
        ->setInvoice('000-INV')
        ->setDescription('This is a description')
        ->setContinueOnIncomplete('1')
        ->setServicesSelectableByClient('ideal,bancontactmrcash')
);

Direct Usage with Buckaroo Wrapper

You can interact directly with the Buckaroo API using the built-in wrapper for greater control and flexibility:

use Buckaroo\Laravel\Facades\Buckaroo;

$response = Buckaroo::api()->method('{SERVICE_CODE}')->{ACTION}([
    'currency' => 'EUR',
    'amountDebit' => 100,
    'order' => '000-ORD',
    'invoice' => '000-INV',
    'description' => 'This is a description',
]);

• Replace {SERVICE_CODE} with the payment method/service code (e.g., 'ideal').
• Replace {ACTION} with the desired action (pay, refund, etc.).

Example for an iDEAL payment:

$response = Buckaroo::api()->method('ideal')->pay([
    'currency' => 'EUR',
    'amountDebit' => 100,
    'order' => '000-ORD',
    'invoice' => '000-INV',
    'description' => 'Payment for Order 000-ORD',
]);

Other Services

The package provides additional services with similar logic:

• RefundService
• CaptureService
• CancelAuthorizeService

These services follow the same structure as PayService and can be used similarly to manage various payment actions.

Additional Information

• Full Documentation: Explore our documentation on dev.buckaroo.nl.

Contributing

We welcome contributions! Please follow our Contribution Guidelines when contributing to the project.

Versioning

We use Semantic Versioning:

• MAJOR: Breaking changes requiring caution
• MINOR: New features that do not affect backward compatibility
• PATCHES: Bug fixes and minor improvements

Support

For support, reach out via:

• Support Portal: Contact Support
• Email: [e-mail]
• Phone: [phone]

License

Laravel Buckaroo Wrapper is open-source software licensed under the MIT license.