Download the PHP package sirmekus/ego without Composer

About Ego

Ego ("money") is an all-in-one payment gateway library for the PHP (Laravel) community. It is designed to bring together all the possible payment gateways under one "umbrella" via a defined set of interfaces covering regular/day-to-day business/user goals.

With this library, you don't need to worry about switching between different payment gateways; just check it up here, and if it's available, via the guaranteed set of interfaces, use it straight away as it covers simple everyday use cases.

Note that the expected parameters required by your gateway of choice, when making a request via this package, should be sent as well.

For something more complex, you should consider using your preferred gateway's SDK (if available), extending our implementation, or creating a new implementation entirely for your use.

For this, I strongly encourage contributions, please. If you have ever worked with/on a particular payment gateway, please contribute by adding it here for other developers to use. Thank you.

Table of Contents

• Getting Started
• Available Interface Methods
• Available (Underlying) Gateway(s)
  • Paystack
    • Special Cases
  • Flutterwave
  • Stripe
    • Special Cases
  • Nomba
    • Configuration
    • Authentication
    • Special Cases
  • BudPay
    • Configuration
    • Authentication
    • Special Cases
• Webhook Strategy
• Contributing

This documentation will constantly be updated as more interfaces/methods or payment gateways are added.

Getting Started

Install the package like so:

This library obscures the underlying payment gateway by providing, instead, a "factory" for you to interact with. This "factory" also contains the common methods (interface) all the available payment gateways (here) should have, so you can still interact with the payment gateway.

To publish the default config file to customize, run:

Example usage:

The PaymentFactory class accepts two optional parameters:

• A PaymentGateway interface (or string indicating which payment gateway to use)
• A "configuration" key which specifies how the underlying payment gateway shall be configured (for authentication) to hit the appropriate API.

If none is specified, the default — gotten from the config file — is used.

Available Interface Methods

All of these methods are guaranteed to be accessible regardless of the payment gateway in use. However, you should know what payload parameters your chosen payment gateway expects and pass them when necessary.

Instead of manually crafting parameters, you can "build" them. For example, if your payment gateway expects: amount, currency, metadata, and reference, you can build them like so:

Methods starting with the set keyword are 'magical' and represent a payload item. The parameter acts as the value. When pay() or transfer() is called without any parameter, it takes from the payload already built using the magic methods.

Alternatively, if you already have an array (say from submitted form data), instead of building the payload manually, you can dump it into the library via prepareForPayment() or prepareForTransfer() and the library will automatically build it for you. Even if the array is nested, it will fetch the first matching key/value pair required to create a request payload. This means a model (cast to an array) can be passed to it as well.

NB: How the payload is built is dependent on the underlying payment gateway. A gateway may require 5 parameters while the contributor of that particular gateway (in this package) may only cater for 2 in prepareForPayment() or prepareForTransfer(). If the remaining parameters are important, it is recommended you set the payload manually instead.

Example:

The method will extract the minimal request parameters (or payload) needed to interact with the API endpoint of your preferred service provider or payment gateway.

Accessing Gateway-Specific Methods

If you need to call a method on the underlying gateway that is not part of the general interface, you can access the gateway instance directly:

Swapping Gateway Implementations

If you have a gateway class with custom logic, you can swap our implementation with yours in the providers section of the ego.php config file. It must implement PaymentGatewayInterface. One way to do it is to extend our class and override the methods you need.

Config File Structure

The typical structure of the ego.php config file is shown below. After publishing it, add the relevant environment variables to your .env file.

Available (Underlying) Payment Gateway(s)

Paystack

Once you know the typical request parameters expected by Paystack, you can plug them in directly into the appropriate method discussed above and use it straight away.

The following methods are available for Paystack in this package:

• All the methods defined in the interface

Paystack Special Cases

Case 1: Payment payload fields

When using prepareForPayment($array), the following will be extracted from the array passed in as a parameter:

• email
• amount
• currency
• channels
• callback_url (or callbackUrl)
• bearer
• metadata (or metaData)
• reference

When using prepareForTransfer($array), the following will be extracted:

• recipient_type
• account_name
• account_number
• bank_code
• reference
• amount
• description

Case 2: Authorization URL vs Authorization Code

On Paystack, you can charge customers by directing them to an authorization URL or by charging them directly via an authorization code. You don't need to worry about these details when using this package — the pay() method handles both.

To charge a customer via an authorization code, include a key named authorization_code in your payload/array. The default behaviour (when no authorization code is present) is to create a checkout link and redirect the user.

Case 3: Transfers

On Paystack, making a transfer/withdrawal to a bank account requires first creating a transfer recipient, which generates a unique code used to initiate the transfer.

This process is handled automatically when you use the transfer() method - you don't need to worry about it.

However, if you already have a transfer recipient code, simply include it in your payload as recipient_code and the package will skip the recipient creation step and initiate the transfer directly.

Flutterwave

Once you know the typical request parameters required by Flutterwave, you can plug them in directly into the appropriate method and use it straight away.

The following methods are available for Flutterwave in this package:

• All the methods defined in the interface

When using prepareForPayment($array), the following will be extracted:

• email
• amount
• currency
• tx_ref (or reference)
• redirect_url (or callback_url / callbackUrl)
• metadata (or metaData)

Stripe

Once you know the typical request parameters required by Stripe, you can plug them in directly into the appropriate method and use it straight away.

The following methods are available for Stripe in this package:

• All the methods defined in the interface

Stripe Special Cases

Case 1: Payment payload fields

When using prepareForPayment($array), the following will be extracted:

• email (or customer_email)
• amount
• currency — defaults to usd if not provided
• mode — defaults to payment if not provided
• description — used as the product name; defaults to "Account Funding"
• quantity — defaults to 1
• tx_ref (or reference) — mapped to client_reference_id
• redirect_url (or callback_url / callbackUrl) — mapped to success_url

Case 2: Transfers

Stripe transfers are sent to connected Stripe accounts (not directly to bank accounts). You must provide a destination (or destination_id) in your payload, which is the ID of the connected Stripe account to transfer funds to.

Case 3: Webhook verification

Stripe webhook verification requires a signing_secret configured in ego.credentials.stripe.signing_secret. Set the STRIPE_SIGNING_SECRET environment variable to the signing secret from your Stripe dashboard.

Nomba

Nomba is a Nigerian payment infrastructure provider. Once you know the typical request parameters it expects, you can plug them in directly and use it straight away.

The following methods are available for Nomba in this package:

• All the methods defined in the interface

Nomba Configuration

Add the following environment variables to your .env file:

All five values can be found in or generated from your Nomba Dashboard.

Nomba Authentication

Nomba uses OAuth2 client credentials for authentication. The package handles this automatically - you do not need to manage tokens yourself. When a request is made, the package:

1. Checks Laravel's cache for a valid access token.
2. If none exists (or it has expired), it requests a new one from Nomba using your client_id and secret_key.
3. Caches the new token for slightly less than its TTL to avoid edge-case expiry.

This means your app stays authenticated transparently across requests with zero manual token management.

Nomba Special Cases

Case 1: Payment payload fields

When using prepareForPayment($array), the following will be extracted:

Case 2: Authorization URL vs Tokenized Card Payment

Similar to Paystack, Nomba supports two payment flows:

• Authorization URL (default): A checkout link is created and the customer is redirected to it to complete payment. This is the default behaviour.
• Tokenized Card Payment: If you include a token key in your payload (a card token previously issued by Nomba), the customer is charged directly without a redirect.

The pay() method handles both flows automatically. The presence of a token in the payload is what triggers the direct charge.

Case 3: Verifying Payments

verifyPayment() accepts an optional $paymentType parameter to distinguish between different transaction types:

The returned array has the following structure:

Case 4: Transfers

When using prepareForTransfer($array), the following will be extracted:

Case 5: Account Number Lookup

Before making a transfer, you can verify a bank account number to confirm the account name:

Both accountNumber and bankCode are required. An exception is thrown if either is missing.

Case 6: Webhook Verification

Nomba signs its webhook payloads using HMAC-SHA256. The package verifies the signature automatically when you call verifyWebhook(). Ensure NOMBA_SIGNATURE_KEY is set in your .env file — this is the webhook signing secret from your Nomba dashboard.

The verification process:

1. Extracts key fields from the webhook payload (event_type, requestId, merchant and transaction details).
2. Concatenates them with the nomba-timestamp header value.
3. Computes an HMAC-SHA256 hash using your signature key and compares it against the nomba-signature header.

If the signatures do not match, an ApiException is thrown.

BudPay

BudPay lets you accept payments, verify transactions, validate bank accounts, and make single or bulk payouts. Once you know the typical request parameters required by BudPay, you can plug them into the appropriate method and use it straight away.

The following methods are available for BudPay in this package:

• All the methods defined in the interface
• getBanksByCurrency()
• calculateTransferFee()
• verifyPayment() for both transaction and payout verification
• bulk transfers via prepareForTransfer() + transfer()

BudPay Configuration

Add the following environment variables to your .env file:

You can get these values from your BudPay dashboard API credentials section.

BudPay Authentication

BudPay authenticates API requests with your secret key as a Bearer token. The package handles this automatically through the configured BUDPAY_SECRET_KEY.

For payout endpoints, BudPay also requires an HMAC-SHA-512 value in the Encryption header. The package automatically sorts the payout payload, signs it with BUDPAY_PUBLIC_KEY, and adds the Encryption header when you call transfer().

BudPay Special Cases

Case 1: Payment payload fields

BudPay Standard creates a hosted checkout URL by initializing a transaction. When using prepareForPayment($array), the following will be extracted:

Case 2: Verifying Payments

BudPay payment verification uses the transaction reference. verifyPayment() accepts a string reference or an array containing reference, data.reference, or transferDetails.paymentReference.

If you pass the optional $paymentType, it must be transaction or payout. null or leaving it empty defaults to transaction:

Case 3: Banks and Account Number Lookup

You can fetch the full BudPay bank list with getBanks() or fetch banks for a specific currency with getBanksByCurrency(). BudPay currently documents bank-list support for currencies such as NGN, USD, GHS, and KES.

or

Before making a payout, you can verify the recipient's account name:

Case 4: Transfer payload fields

BudPay supports single payouts to bank accounts. When using prepareForTransfer($array), the following will be extracted:

Case 5: Transfer Fees and Bulk Transfers

BudPay lets you calculate payout fees before sending money:

or

For bulk payouts, prepare a currency and an array of transfer items, then call prepareForTransfer() and transfer():

Case 6: Verifying Transfers

Single and bulk payouts can be verified with the BudPay payout reference returned by the transfer response:

Case 7: Webhook Verification

BudPay webhook verification in this package verifies the webhook by calling BudPay's API again and comparing the webhook reference and status with the verified response. The incoming request must be a POST, include a supported notify value (transaction, virtual_account, or payout), and contain a reference in data.reference, transferDetails.paymentReference, or reference.

For payout notifications, the package calls verifyPayment() with the payout route. For other supported notifications, it calls verifyPayment() for transaction verification. If the verified reference or status does not match the webhook payload, the request is rejected.

Webhook Strategy

Since this package implements a method that verifies webhook requests/payloads, one way of using the same route for all supported payment gateways is shown below:

Step 1: Create a dynamic route

The value assigned to the dynamic part of the URL above should match any of the supported payment gateways listed in the providers section of your ego.php config file.

Step 2: Handle the payload

With this, you have a single route that can handle any webhook. If you move from Gateway A to B, you won't have to create a new route or implement new gateway-specific handling.

Contributing

Please check the 'contrib' directory for more information. I really appreciate you for doing this.