Download the PHP package rainwaves/paystack-payment without Composer

Paystack Payment Package

This is a Laravel package for integrating with the Paystack payment gateway. It supports customer creation, recurring plans, single payments, transaction verification, webhook verification, and refunds.

The package includes request validation guards before outbound calls and returns DTOs with transaction details that are useful to Rainwaves host applications.

Installation

You can install the package via Composer:

For package development:

Configuration

Publish the config file in your Laravel application:

Set the Paystack credentials in your .env file:

• PAYSTACK_SECRET_KEY=
• PAYSTACK_PUBLIC_KEY=
• PAYSTACK_WEBHOOK_SECRET=
• PAYSTACK_CALLBACK_URL=
• PAYSTACK_CANCEL_URL=
• PAYSTACK_CURRENCY=ZAR
• PAYSTACK_TIMEOUT=15
• PAYSTACK_RETRY=2

Example config:

Compatibility

• PHP: 8.2+
• Laravel: 12.x

Versioning

Package versions should be published with Git tags, not by setting a version field in composer.json.

Recommended first stable release:

• v1.0.0

Currency Rule

Keep the currency rule simple:

• the package should use the currency configured for the Paystack portfolio
• set that default in paystack.paystack.currency
• pass a currency in the DTO only when you need to override the configured default
• all amounts sent to Paystack must be in minor units

Examples:

• ZAR 125.50 must be sent as 12550
• USD 25.00 must be sent as 2500

If your product catalog stores prices in USD but the customer is checking out against a ZAR Paystack portfolio, convert the amount before calling the package and send the final Paystack currency amount in minor units.

Usage

The main interface exposed by the package is rainwaves\PaystackPayment\Contracts\PaymentGatewayInterface.

Laravel

Single Payments

For one-time payments, initialize checkout without a planCode:

Subscriptions

For subscriptions, create the Paystack plan first, then initialize checkout with the returned planCode:

Optional Fields

• CheckoutInitializationData::$callbackUrl
• CheckoutInitializationData::$planCode
• CheckoutInitializationData::$customerCode
• CheckoutInitializationData::$metadata
• CheckoutInitializationData::$currency
• PlanData::$description
• PlanData::$invoiceLimit
• PlanData::$metadata
• PlanData::$currency
• RefundData::$amountInMinor
• RefundData::$currency
• RefundData::$reason
• RefundData::$customerNote
• RefundData::$merchantNote

Validation Rules

The package validates common request mistakes before sending anything to Paystack:

• checkout amount must be greater than zero
• plan amount must be greater than zero
• refund amount must be greater than zero when provided
• checkout and customer emails must be valid email addresses
• checkout references, plan names, and plan intervals cannot be blank

Validation failures throw rainwaves\PaystackPayment\Exceptions\InvalidPaymentRequestException.

Verification Details

verifyTransaction() returns more than the basic status fields. In addition to the reference and amount, the DTO can include:

• customerEmail
• customerName
• authorizationReusable
• paidAt
• feesInMinor
• channel
• gatewayResponse

Example:

Webhooks

The package verifies the Paystack webhook signature using the configured webhook secret:

Webhook helpers are available on the verification DTO:

Notes

• The package returns DTOs so host applications can map provider responses into their own persistence and business logic.
• Single-payment and subscription activation flows remain the responsibility of the host application.
• Refund orchestration and local state transitions belong in the host application layer.

Production Checklist

Before tagging a production release, run the checklist in docs/sandbox-smoke-test.md.

The first release notes are in docs/release-notes-v1.0.0.md.