README

Paystack-PHP

About

A clean, simple, yet, comprehensive Paystack Library for seamlessly managing your online transactions, transfers, and refunds with ease in PHP!

This library adopts best programming practices to provide an easy way to carry out any form of transaction available on the Paystack API.

Requirements

Minimum of PHP 7.2

Installation

To install using composer, invoke the command below:

composer require aweklin/paystack

You can also clone this repository using the command below:

git clone https://github.com/aweklin/Paystack-PHP

Initializing the Library

Before you can use this library, you first need to initialize it in your program entry point, perhaps the index.php file. Simply use this line below to initialize the library.

First, include the autoload file where you want to use it


      include_once 'path_to_klin_paystack/autoload.php';

Then, reference the namespace at the top of the file


    use Aweklin\Paystack\Paystack;

Next, initialize the Library with your secret key


    Paystack::initialize('your_api_secret_key_here');

Important Notes:

Note that every requests made returns a uniform response

You can invoke $result->hasError() to determine if your request returns with an error and you can subsequently call $result->getMessage() for the success or error message. In addition, $result->getData() contains data from Paystack.

When listing records, note that you can specify additional two parameters, which are: $pageNumber and $pageSize. However, this is not applicable to Paystack::getBanks and Paystack::getProviders.

Where currency is required part of parameters, you can specify one of the enums: Paystack::CURRENCY_NGN, Paystack::CURRENCY_GHS, and Paystack::CURRENCY_USD.

When supplying date values, please use the yyyy-MM-dd format.

Transactions

Transaction listing

To list all your transactions, invoke


$transactionList = Paystack::getTransactions();
if ($transactionList->hasError()) {
  echo $transactionList->getMessage();
} else {
  var_dump ($transactionList->getData());
}

Or, specify the page number and page size


  $transactionList = Paystack::getTransactions($pageNumber, $pageSize);
  if ($transactionList->hasError()) {
    echo $transactionList->getMessage();
  } else {
    var_dump ($transactionList->getData());
  }

To list all your transactions by status, invoke


  $transactionList = Paystack::getTransactions($status);
  if ($transactionList->hasError()) {
    echo $transactionList->getMessage();
  } else {
    var_dump ($transactionList->getData());
  }

Or, specify page number and page size


  $transactionList = Paystack::getTransactions($status, $pageNumber, $pageSize);
  <br>
  if ($transactionList->hasError()) {
    echo $transactionList->getMessage();
  } else {
    var_dump ($transactionList->getData());
  }

$status can be one of Transaction::STATUS_SUCCESS, Transaction::STATUS_FAILED, or Transaction::STATUS_ABANDONED

To list all your transactions by date range, invoke


  $transactionList = Paystack::getTransactions($startDate, $endDate);
  <br>
  if ($transactionList->hasError()) {
    echo $transactionList->getMessage();
  } else {
    var_dump ($transactionList->getData());
  }

Date format: yyyy-MM-dd, example: '2020-09-25'

To list all your transactions by by other parameter(s), invoke


  $transactionParameter = new TransactionParameter();      
  $transactionParameter<br>
        ->setCustomerId(111222333)<br>
        ->setStatus(Transaction::STATUS_SUCCESS)<br>
        ->setAmount(1000)<br>
        ->setCurrency(Paystack::CURRENCY_NGN);<br>
  $transactionList = Paystack::getTransactions($transactionParameter);
  if ($transactionList->hasError()) {
    echo $transactionList->getMessage();
  } else {
    var_dump ($transactionList->getData());
  }

Note that you can set only one or more than one parameter to filter transactions as show above. The TransactionParameter object allows you to chain parameters.

The setStatus(?) method can take one of the enums: Transaction::STATUS_SUCCESS, Transaction::STATUS_FAILED, Transaction::STATUS_ABANDONED.

Also, the setCurrency(?) method accepts one of the enums: Paystack::CURRENCY_NGN, Paystack::CURRENCY_GHS, and Paystack::CURRENCY_USD

Transaction initiation

You can initiate a transaction by simply passing an email and amount.

Initiating payment with email and amount

This allows you to generate an authorization url, with which the user can use to complete his payment.

Example


$result = Paystack::initiateTransaction(VALID_EMAIL, VALID_AMOUNT);
if ($result->hasError()) {
  echo $result->getMessage();
} else {
  var_dump ($result->getData());
}

Initiating payment with email, amount, and reference

You can also include a reference number for your transaction:


$result = Paystack::initiateTransaction(VALID_EMAIL, VALID_AMOUNT, 'ref_no');
if ($result->hasError()) {
  echo $result->getMessage();
} else {
  var_dump ($result->getData());
}

Initiating payment with email, amount, and currency

You can also include a currency for your transaction:


$result = Paystack::initiateTransaction(VALID_EMAIL, VALID_AMOUNT, 'currency');
if ($result->hasError()) {
  echo $result->getMessage();
} else {
  var_dump ($result->getData());
}

Initiating payment with email, amount, and custom_fields

You can also include an array of custom fields as shown below:


$result = Paystack::initiateTransaction(VALID_EMAIL, VALID_AMOUNT, ['name' => 'Akeem Aweda', 'profession' => 'Software Engineer']);
if ($result->hasError()) {
  echo $result->getMessage();
} else {
  var_dump ($result->getData());
}

Initiating payment with email, amount, reference, currency and custom fields

You can also include reference, currency and an array of custom fields as shown below:


$result = Paystack::initiateTransaction(VALID_EMAIL, VALID_AMOUNT, 'reference', 'currency', ['name' => 'Akeem Aweda', 'profession' => 'Software Engineer']);
if ($result->hasError()) {
  echo $result->getMessage();
} else {
  var_dump ($result->getData());
}

Creating a transaction charge

You can initiate a transaction by creating a transaction charge via Bank, Mobile Money, Transfer, QR Code, or USSD API.

Initiating mobile money payment

Allows you to carry out a mobile money transaction based on available providers.

Example


$mobileMoney = new MobileMoneyPayment('email@domain.com', 5000, 'NGN', '07020000000', 'Airtel');
$chargeResult = Paystack::initiateTransaction($mobileMoney);
if ($chargeResult->hasError()) {
  echo $chargeResult->getMessage();
} else {
  var_dump ($chargeResult->getData());
}

Initiating bank payment

Allows you to carry out a bank transaction either via USSD or by transfer.

Example


$bankPayment = new BankPayment('email@domain.com', 5000, '058', VALID_ACCOUNT_NUMBER);
$chargeResult = Paystack::initiateTransaction($bankPayment);
if ($chargeResult->hasError()) {
  echo $chargeResult->getMessage();
} else {
  var_dump ($chargeResult->getData());
}

Initiating USSD payment

This Payment method is specifically for Nigerian customers. Nigerian Banks provide USSD services that customers use to perform transactions, and we've integrated with some of them to enable customers complete payments.

The Pay via USSD channel allows your Nigerian customers to pay you by dialling a USSD code on their mobile device. This code is usually in the form of * followed by some code and ending with #. The user is prompted to authenticate the transaction with a PIN and then it is confirmed.

Example


$ussdPayment = new USSDPayment(VALID_EMAIL, VALID_AMOUNT, USSDPayment::BANK_GUARANTEE_TRUST);
$chargeResult = Paystack::initiateTransaction($ussdPayment);
if ($chargeResult->hasError()) {
  echo $chargeResult->getMessage();
} else {
  var_dump ($chargeResult->getData());
}

Initiating QR Code payment

The QR option generates a QR code which allows customers to use their bank's mobile app to complete payments. We currently have only Visa QR option available. We'll have more options later.

When the customer scans the code, they authenticate on their bank app to complete the payment. When the user pays, a response will be sent to your webhook. This means that you need to have webhooks set up on your Paystack Dashboard.

Example


$qrCodePayment = new QRCodePayment(VALID_EMAIL, VALID_AMOUNT, QRCodePayment::PROVIDER_VISA);
$chargeResult = Paystack::initiateTransaction($qrCodePayment);
if ($chargeResult->hasError()) {
  echo $chargeResult->getMessage();
} else {
  var_dump ($chargeResult->getData());
}

Initiating a recurring payment

Allows you to process a recurring payment by charging the authorization code earlier received.

Please note that this requires a valid authorization code.

Example


$recurringPayment = new RecurringPayment(VALID_EMAIL, VALID_AMOUNT, VALID_AUTHORIZATION_CODE);
$chargeResult = Paystack::initiateTransaction($recurringPayment);
if ($chargeResult->hasError()) {
  echo $chargeResult->getMessage();
} else {
  var_dump ($chargeResult->getData());
}

Completing transaction with OTP

Concludes a payment process initiated via bank payment method.

Example


$chargeResult = Paystack::completeTransactionWithOTP($reference, $otp);
if ($chargeResult->hasError()) {
  echo $chargeResult->getMessage();
} else {
  var_dump ($chargeResult->getData());
}

Transaction verification

To verify a transaction, you need to first obtain a transaction reference to be used for the check.

Example


$verificationResult = Paystack::verifyTransaction('abcd');
if ($verificationResult->hasError()) {
  echo $verificationResult->getMessage();
} else {
  var_dump ($verificationResult->getData());
}

Refunds

Allows you create and manage transaction refunds.

Initiating a refund for a given transaction reference.

Example


$refundResult = Paystack::initiateRefund($reference);
if ($refundResult->hasError()) {
  echo $refundResult->getMessage();
} else {
  var_dump ($refundResult->getData());
}

Checking refund status

It may take up to 24 hours for your refund to be concluded. To check if your refund was successful, invoke


$refundCheck = Paystack::getRefund($reference);
if ($refundCheck->hasError()) {
  echo $refundCheck->getMessage();
} else {
  var_dump ($refundCheck->getData());
}

Listing your refunds

Return all refunds from inception till date.


$refundList = Paystack::getRefunds();
if ($refundList->hasError()) {
  echo $refundList->getMessage();
} else {
  var_dump ($refundList->getData());
}

Listing your refunds by date range


$refundList = Paystack::getRefundsByDates($startDate, $endDate);
if ($refundList->hasError()) {
  echo $refundList->getMessage();
} else {
  var_dump ($refundList->getData());
}

Listing your refunds by other parameters


$transactionParameter = new RefundParameter();
$transactionParameter->setCurrency(Paystack::CURRENCY_NGN);
$refundList = Paystack::getRefundsBy($transactionParameter);
if ($refundList->hasError()) {
  echo $refundList->getMessage();
} else {
  var_dump ($refundList->getData());
}

Transfers

Allows you send money.

Transfer to beneficiary

Initiates a single transfer request to a beneficiary.

Status of transfer object returned will be pending if OTP is disabled. In the event that an OTP is required, status will read otp.

Please note that the beneficiary must have been previously added to your beneficiary list, please refer to Misc section.

Example


$transferResult = Paystack::initiateTransferToBeneficiary(VALID_BENEFICIARY_CODE, VALID_AMOUNT, 'reference', Paystack::CURRENCY_NGN, 'Testing transfer.');
if ($transferResult->hasError()) {
  echo $transferResult->getMessage();
} else {
  var_dump ($transferResult->getData());
}

Note that the reference is optional, so it can be empty (to allow Paystack generate a transaction reference for you, and it's part of the $transferResult->getData() data).

Transfer to bank account

Initiates a single transfer request to an account number.

Note that this method will have to validate the account number, create the beneficiary, then transfer to the beneficiary.

Status of transfer object returned will be pending if OTP is disabled. In the event that an OTP is required, status will read otp.

Example


$transferResult = Paystack::initiateTransferToAccount($accountNumber, $accountName, $bankCode, $amount, $reference, $currency, $remark);
if ($transferResult->hasError()) {
  echo $transferResult->getMessage();
} else {
  var_dump ($transferResult->getData());
}

* @param string $accountNumber Receiver's account number.
* @param string $accountName Receiver's account name.
* @param string $bankCode Receiver's bank code. You can get the list of Bank Codes by calling the `Aweklin\Paystack\Core\DataProvider::getBanks()` method.
* @param float $amount Amount to be transferred.
* @param string $reference If specified, the field should be a unique identifier (in lowercase) for the object. Only -,_ and alphanumeric characters allowed.
* @param string $currency Three-letter ISO currency.
* @param string $remark The reason for the transfer.

Bulk transfer

Initiates a bulk transfer request.

You need to disable the Transfers OTP requirement to use this endpoint.

Example


$transferResult = Paystack::initiateBulkTransfers($transfers, $currency);
if ($transferResult->hasError()) {
  echo $transferResult->getMessage();
} else {
  var_dump ($transferResult->getData());
}

$transfers is an array of \Aweklin\Paystack\Models\PaymentTransfer`, each containing: amount, recipient, and reference.

Conclude transfer with OTP

Finalizes an initiated transfer with OTP.

Example


$transferResult = Paystack::completeTransferWithOTP($transferCode, $otp);
if ($transferResult->hasError()) {
  echo $transferResult->getMessage();
} else {
  var_dump ($transferResult->getData());
}

Resend transfer OTP

Generates a new OTP and sends to customer in the event they are having trouble receiving one.

Example


$transferResult = Paystack::resendTransferOTP($transferCode);
if ($transferResult->hasError()) {
  echo $transferResult->getMessage();
} else {
  var_dump ($transferResult->getData());
}

Disable transfer OTP

In the event that you want to be able to complete transfers programmatically without use of OTPs, this method helps disable that….with an OTP.

Please note that this will send you an OTP and you are to call the `finalizeDisableOTP()` method to conclude operation.

Example


$transferResult = Paystack::disableOTP();
if ($transferResult->hasError()) {
  echo $transferResult->getMessage();
} else {
  var_dump ($transferResult->getData());
}

Complete disable transfer OTP

Finalizes the request to disable OTP on your transfers.

Example


$transferResult = Paystack::finalizeDisableOTP($otp);
if ($transferResult->hasError()) {
  echo $transferResult->getMessage();
} else {
  var_dump ($transferResult->getData());
}

Enable transfer OTP

In the event that a customer wants to stop being able to complete transfers programmatically, this endpoint helps turn OTP requirement back on.

Example


$transferResult = Paystack::enableOTP();
if ($transferResult->hasError()) {
  echo $transferResult->getMessage();
} else {
  var_dump ($transferResult->getData());
}

Listing your transfers

Return all transfers from inception till date.


$transferList = Paystack::getTransfers();
if ($transferList->hasError()) {
  echo $transferList->getMessage();
} else {
  var_dump ($transferList->getData());
}

Listing your transfers by date range


$transferList = Paystack::getTransfersByDates($startDate, $endDate);
if ($transferList->hasError()) {
  echo $transferList->getMessage();
} else {
  var_dump ($transferList->getData());
}

Get details of a transfer


$transferDetails = Paystack::getTransfer($id);
if ($transferDetails->hasError()) {
  echo $transferDetails->getMessage();
} else {
  var_dump ($transferDetails->getData());
}

Misc

Get account balance


$result = Paystack::getBalance();
if ($result->hasError()) {
  echo $result->getMessage();
} else {
  var_dump ($result->getData());
}

Get list of banks

Get a list of all Nigerian banks and their properties


$result = Paystack::getBanks();
if ($result->hasError()) {
  echo $result->getMessage();
} else {
  var_dump ($result->getData());
}

Get providers

Get a list of all providers for Dedicated NUBAN


$result = Paystack::getProviders();
if ($result->hasError()) {
  echo $result->getMessage();
} else {
  var_dump ($result->getData());
}

Validate BVN

Validates the given Bank Verification Number, BVN against the account number and bank code provided.


$result = Paystack::verifyBVN(VALID_BVN, VALID_BANK_CODE_FOR_BVN_VERIFICATION, VALID_ACCOUNT_NUMBER);
if ($result->hasError()) {
  echo $result->getMessage();
} else {
  var_dump ($result->getData());
}

Get account balance.

Get a customer's information by using the Bank Verification Number.


$result = Paystack::getBVNDetails($bvn);
if ($result->hasError()) {
  echo $result->getMessage();
} else {
  var_dump ($result->getData());
}

Get account balance.

Confirm an account belongs to the right customer.


$result = Paystack::getAccountDetails(string $accountNumber, string $bankCode);
if ($result->hasError()) {
  echo $result->getMessage();
} else {
  var_dump ($result->getData());
}

Adding transfer beneficiary

Creates a new recipient. A duplicate account number will lead to the retrieval of the existing record.


$beneficiaryCreationResult = Paystack::createBeneficiary(VALID_ACCOUNT_NUMBER, VALID_BANK_CODE_FOR_BVN_VERIFICATION, VALID_ACCOUNT_NAME);
if ($beneficiaryCreationResult->hasError()) {
  echo $beneficiaryCreationResult->getMessage();
} else {
  var_dump ($beneficiaryCreationResult->getData());
}

Updating transfer beneficiary

Updates recipient. A duplicate account number will lead to the retrieval of the existing record.


$beneficiaryUpdateResult = Paystack::updateBeneficiary(VALID_BENEFICIARY_ID, VALID_ACCOUNT_NAME, VALID_EMAIL, 'A sample test account');
if ($beneficiaryUpdateResult->hasError()) {
  echo $beneficiaryUpdateResult->getMessage();
} else {
  var_dump ($beneficiaryUpdateResult->getData());
}

Listing transfer beneficiaries

Returns all beneficiaries created from inception till date.


$beneficiaries = Paystack::getBeneficiaries();
if ($beneficiaries->hasError()) {
  echo $beneficiaries->getMessage();
} else {
  var_dump ($beneficiaries->getData());
}

Listing transfer beneficiaries created between two dates

Returns all beneficiaries created between two dates.


$beneficiaries = Paystack::getBeneficiariesByDates($startDate, $endDate);
if ($beneficiaries->hasError()) {
  echo $beneficiaries->getMessage();
} else {
  var_dump ($beneficiaries->getData());
}

Get details of a beneficiary.


$beneficiaryDetails = Paystack::getBeneficiary(VALID_BENEFICIARY_ID);
if ($beneficiaryDetails->hasError()) {
  echo $beneficiaryDetails->getMessage();
} else {
  var_dump ($beneficiaryDetails->getData());
}

Testing

This project has been developed with TDD. Over 95% of the code has been unit tested and improved overtime. With the unit testing in place, developers using this library can equally learn how to use it simply by reading through the tests written.

To run the unit tests in this project, kindly open the config.php file inside the tests folder and set the appropriate values for all the constants before running your tests. If you need some help on this, kindly contact akeem@aweklin.com.

Contributions

This project is open to professionals to contribute & report issues for us to make it better together. Security issues should be reported privately, via email, to akeem@aweklin.com.

License

This project is under license from MIT. For more details, see the LICENSE file.

Made with ❤️ by Akeem Aweda

aweklin / paystack

Maintainers

Details

README

Paystack-PHP

About

Requirements

Installation

Usage

Initializing the Library

Important Notes:

Transactions

Transaction listing

Transaction initiation

Initiating payment with email and amount

Initiating payment with email, amount, and reference

Initiating payment with email, amount, and currency

Initiating payment with email, amount, and custom_fields

Initiating payment with email, amount, reference, currency and custom fields

Creating a transaction charge

Initiating mobile money payment

Initiating bank payment

Initiating USSD payment

Initiating QR Code payment

Initiating a recurring payment

Completing transaction with OTP

Transaction verification

Refunds

Initiating a refund for a given transaction reference.

Example $refundResult = Paystack::initiateRefund($reference); if ($refundResult->hasError()) { echo $refundResult->getMessage(); } else { var_dump ($refundResult->getData()); }

Checking refund status

Listing your refunds

Listing your refunds by date range

Listing your refunds by other parameters

Transfers

Transfer to beneficiary

Transfer to bank account

Bulk transfer

Conclude transfer with OTP

Resend transfer OTP

Disable transfer OTP

Complete disable transfer OTP

Enable transfer OTP

Listing your transfers

Listing your transfers by date range

Get details of a transfer

Misc

Get account balance

Get list of banks

Get providers

Validate BVN

Get account balance.

Get account balance.

Adding transfer beneficiary

Updating transfer beneficiary

Listing transfer beneficiaries

Listing transfer beneficiaries created between two dates

Get details of a beneficiary.

Testing

Contributions

License

Example
`$refundResult = Paystack::initiateRefund($reference); if ($refundResult->hasError()) { echo $refundResult->getMessage(); } else { var_dump ($refundResult->getData()); }`