README

A fluent Laravel integration for Tap Payments API

Introduction

Laravel Tap Payments provides an expressive, fluent interface to Tap Payments billing services. It handles almost all of the boilerplate payment processing code you are dreading writing. In addition to basic charge management, the package can handle saved cards, webhooks, refunds, authorizations, and more.

Official Documentation

Documentation for the package can be found in the docs folder:

• Installation
• Configuration
• Charges
• Webhooks
• Saved Cards
• Billable Trait
• Testing
• Marketplace

Quick Start

Install the package via Composer:

composer require tappay/laravel-tap-payment

Publish the configuration:

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

Add your credentials to .env:

TAP_KEY=pk_test_your_publishable_key
TAP_SECRET=sk_test_your_secret_key
TAP_CURRENCY=SAR

Basic Usage

use TapPay\Tap\Facades\Tap;

// Create a charge
$charge = Tap::charges()->newBuilder()
    ->amount(100.00)              // Amount in currency units (100.00 SAR)
    ->currency('SAR')
    ->withCard()
    ->customer([
        'first_name' => 'John',
        'email' => 'john@example.com',
    ])
    ->redirectUrl('https://example.com/callback')
    ->create();

// Redirect to payment page
return redirect($charge->transactionUrl());

Billable Model

Add the Billable trait to your User model:

use TapPay\Tap\Concerns\Billable;
use TapPay\Tap\Contracts\Billable as BillableContract;

class User extends Authenticatable implements BillableContract
{
    use Billable;
}

Now charge users directly:

$user->charge(10000, 'SAR', [
    'source' => ['id' => 'src_card'],
    'redirect' => ['url' => route('payment.callback')],
]);

Available Services

Supported Payment Methods

Marketplace & Payment Splits

Split payments across multiple merchants:

use TapPay\Tap\Facades\Tap;
use TapPay\Tap\ValueObjects\Destination;

// Create a charge with payment splits
$charge = Tap::charges()->newBuilder()
    ->amount(100.00)
    ->withCard()
    ->destinations([
        Destination::make('merchant_123', 70.00),  // 70% to vendor
        Destination::make('merchant_456', 30.00),  // 30% platform fee
    ])
    ->redirectUrl('https://example.com/callback')
    ->create();

// Manage sub-merchants
$merchant = Tap::merchants()->create([
    'name' => 'Vendor Store',
    'email' => 'vendor@example.com',
    'country_code' => 'SA',
]);

// Track payouts
$payouts = Tap::payouts()->listByMerchant('merchant_123');

Authorizations (Two-Step Payments)

Hold funds without capturing immediately:

use TapPay\Tap\Facades\Tap;

// Create authorization with auto-capture after 24 hours
$auth = Tap::authorizations()->newBuilder()
    ->amount(5000)
    ->currency('SAR')
    ->source('src_card')
    ->autoCapture(24)                    // Auto-capture after 24 hours
    ->idempotent($order->id)             // Prevent duplicate authorizations
    ->redirectUrl('https://example.com/callback')
    ->create();

// Or auto-void if not captured
$auth = Tap::authorizations()->newBuilder()
    ->amount(5000)
    ->source('src_card')
    ->autoVoid(48)                       // Auto-void after 48 hours
    ->create();

// Manually void an authorization
Tap::authorizations()->void('auth_xxxxx');

// Bulk export authorizations
Tap::authorizations()->download(['status' => 'AUTHORIZED']);

Invoices

Create and manage payment invoices:

use TapPay\Tap\Facades\Tap;

// Create an invoice
$invoice = Tap::invoices()->create([
    'amount' => 100.00,
    'currency' => 'SAR',
    'customer' => ['id' => 'cus_xxxxx'],
]);

// Finalize a draft invoice
Tap::invoices()->finalize('inv_xxxxx');

// Send payment reminder
Tap::invoices()->remind('inv_xxxxx');

// Cancel an invoice
Tap::invoices()->cancel('inv_xxxxx');

Idempotency

Prevent duplicate charges with idempotent keys:

$charge = Tap::charges()->newBuilder()
    ->amount(10000)
    ->withCard()
    ->idempotent($order->id)             // Same key = same response within 24h
    ->redirectUrl($callbackUrl)
    ->create();

Works with charges, authorizations, and refunds. See Charges documentation for details.

Events

The package dispatches events you can listen to:

Example listener:

use TapPay\Tap\Events\PaymentSucceeded;
use TapPay\Tap\Events\PaymentFailed;

// In EventServiceProvider
protected $listen = [
    PaymentSucceeded::class => [
        SendPaymentConfirmation::class,
    ],
    PaymentFailed::class => [
        NotifyPaymentFailure::class,
    ],
];

Webhooks

Configure webhook handling in your config/tap.php:

'webhook' => [
    'secret' => env('TAP_WEBHOOK_SECRET'),
    'tolerance' => 300, // 5 minutes
    'allowed_resources' => ['charge', 'refund', 'customer'],
],

The package automatically:

• Validates webhook signatures using HMAC-SHA256
• Prevents replay attacks with timestamp tolerance
• Dispatches events for each webhook type

Security Features

• HMAC-SHA256 webhook signature validation
• Timing-safe signature comparison
• Open redirect protection on callbacks
• Input validation on all builder methods
• Sensitive parameter protection for API keys

Testing

# Run tests
composer test

# Run static analysis
composer analyse

# Run code style checks
composer lint

Contributing

Thank you for considering contributing to Laravel Tap Payments! The contribution guide can be found in the CONTRIBUTING.md file.

Code of Conduct

In order to ensure that the Laravel community is welcoming to all, please review and abide by the Code of Conduct.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

License

Laravel Tap Payments is open-sourced software licensed under the MIT license.