Payments

Use the default gateway (PAYMENT_GATEWAY / config) or call driver(...) explicitly. Amounts are in major currency units unless a gateway note says otherwise.

use Alphabalex\PaymentMadeEasy\Facades\Payment;

// Default driver (same payload shape as your configured gateway)
$response = Payment::initializePayment([
    'email'        => 'customer@example.com',
    'amount'       => 5000.00,
    'reference'    => 'ORDER_123',
    'callback_url' => 'https://yoursite.com/payment/callback',
    'metadata'     => ['order_id' => '123', 'customer_id' => '456'],
]);

// Other drivers — same general flow; see Gateway-Specific Notes for redirects and quirks
Payment::driver('flutterwave')->initializePayment([
    'email'    => 'customer@example.com',
    'amount'   => 5000.00,
    'name'     => 'John Doe',
    'phone'    => '+2348123456789',
    'currency' => 'NGN',
]);

Payment::driver('stripe')->initializePayment([
    'email'    => 'customer@example.com',
    'amount'   => 50.00,
    'currency' => 'usd',
]);

Payment::driver('seerbit')->initializePayment([
    'email'    => 'customer@example.com',
    'amount'   => 5000.00,
    'currency' => 'NGN',
    'name'     => 'John Doe',
    'phone'    => '+2348123456789',
]);

// Paystack — hosted checkout
$response = Payment::driver('paystack')->initializePayment([
    'email'        => 'customer@example.com',
    'amount'       => 5000.00,
    'reference'    => 'ORDER_123',
    'callback_url' => 'https://yoursite.com/payment/callback',
    'metadata'     => ['order_id' => '123'],
]);

// Redirect customer to $response['data']['authorization_url']

// Verify after callback
$verification = Payment::driver('paystack')->verifyPayment('ORDER_123');

// Payment details by reference
$payment = Payment::driver('paystack')->getPayment('ORDER_123');

// Refund
$refund = Payment::driver('paystack')->refundPayment('ORDER_123', 2500.00); // partial
$full   = Payment::driver('paystack')->refundPayment('ORDER_123');           // full

// List transactions
$txns = Payment::driver('paystack')->getTransactions(['per_page' => 50, 'page' => 1]);

---

Convenience Payment Flow (pay())

Every driver exposes a pay() method that handles multi-step payment flows behind a single call — redirects, OTP authentication, SDK client secrets, and async polling.

use Alphabalex\PaymentMadeEasy\Facades\Payment;

// Hosted checkout (Paystack, Flutterwave, Seerbit, Squad, OPay, Budpay, Remita, PayPal, Paddle)
$result = Payment::driver('paystack')->pay([
    'email'  => 'customer@example.com',
    'amount' => 5000.00,
]);
// $result['status'] === 'redirect'
// $result['auth_url'] → redirect customer here
// $result['reference'] for later verification

// Client-side SDK (Stripe, Razorpay)
$result = Payment::driver('stripe')->pay([
    'email'    => 'customer@example.com',
    'amount'   => 5000.00,
    'currency' => 'NGN',
]);
// $result['status'] === 'sdk'
// $result['client_secret'] → pass to Stripe.js

// Card-on-file (Paystack, Flutterwave)
$result = Payment::driver('paystack')->pay([
    'email'              => 'customer@example.com',
    'amount'             => 5000.00,
    'authorization_code' => 'AUTH_xxxxx',
], function (array $response) {
    // Called on success — fulfill the order
});
// $result['status'] === 'completed' | 'failed'

// OTP flow (Interswitch)
$result = Payment::driver('interswitch')->pay(
    ['email' => 'customer@example.com', 'amount' => 5000.00],
    function (array $initResponse): ?string {
        // Collect OTP from user (email/SMS/API input)
        return $this->requestOtpFromUser($initResponse);
    }
);
// $result['status'] === 'otp_required' | 'completed' | 'failed' | '3ds_required'

// Async push (MPesa, MTN MoMo)
$result = Payment::driver('mpesa')->pay([
    'phone'  => '254712345678',
    'amount' => 500,
]);
// $result['status'] === 'processing'
// $result['checkout_request_id'] for polling

Return Structure

Field	Type	Description
response	array	Raw gateway response
success	bool	Payment confirmed successful
status	string	See below
reference	string	Transaction reference

Plus a driver-specific field:

Flow	Drivers	Extra Field
Hosted redirect	Paystack, Flutterwave, Seerbit, Squad, OPay, Budpay, Remita, PayPal, Paddle	auth_url / link / checkout_url
Client-side SDK	Stripe, Razorpay	client_secret / order_id
Async push	Interswitch, MPesa, MTN MoMo	checkout_request_id / reference_id

Status Values

Status	Meaning	Next Action
completed	Payment confirmed	Done
redirect	Hosted checkout	Redirect user to checkout URL
sdk	Client-side SDK needed	Pass secret/order to JS SDK
processing	Async, awaiting confirmation	Poll or wait for callback
otp_required	Interswitch OTP needed	Collect OTP and retry
3ds_required	Visa 3D Secure	Redirect to 3DS page
failed	Error or declined	Check response

Auto-Verify

Pass _auto_verify => true in $data to automatically call verifyPayment() after redirect/SDK flows:

// In callback controller after user returns from checkout
$result = Payment::driver('paystack')->pay([
    'email'        => 'user@example.com',
    'amount'       => 5000,
    '_auto_verify' => true,
], function ($response) {
    // Payment confirmed — fulfill the order
});

---