Download the PHP package zainpay/sdk without Composer

Zainpay PHP SDK

A PHP API wrapper for Zainpay.

Table of content

• Zainpay PHP SDK
  • Table of content
  • Requirements
  • Installation
  • Installation Via Composer
  • Installation Via download
  • Usage
  • Card
  • Card Payment Initialization
  • Card Payment Verification
  • Card Payment Verification V2
  • Get Card Transactions By Zainbox
  • Reconcile Card Payment
  • Zainbox
  • Create Zainbox
  • Get All Zainboxes
  • Update Zainbox
  • Zainbox Profile and Current Billing Plan
  • Create Or Update Zainbox Settlement
  • Get Zainbox Settlement
  • Get Total Payment Collected By Zainbox
  • Get Total Payment Collected For All Zainboxes
  • Get Zainbox Transaction List
  • Get Zainbox Settlement Payments Hostory List
  • Get Zainbox Virtual Accounts
  • Virtual Account
  • Create Virtual Account
  • Get Virtual Account Balance
  • Update Virtual Account Status
  • All Virtual Account Balances of a Zainbox
  • Virtual Account Transactions
  • Get All Virtual Account By Zainbox
  • Transfer Verification
  • Deposit Verification
  • Deposit Verification V2
  • Repush Deposit Event
  • Reconcile Bank Deposit
  • Bank
  • Get Bank List
  • Name Enquiry
  • Fund Transfer

    Requirements

• Curl (Unless using Guzzle)
• PHP 7.4 or more recent version

Installation

Installation Via Composer

Installation Via download

Download a release version from the releases page. Extract, then:

Usage

This SDK ships with helper class that will help provide global settings for your SDK.
Further more, methods are provided to help overwrite the globally set configurations within the instantiated request object.
The idea of overriding is brought to you for safe usage of this SDK within async environment.

Example: Global settings

• Example showing how to set global token and mode that can be use throughout a class or system

  Example: Override global settings

• Example showing how to override token and mode

  Note: The Engine class takes in the following parameters:

• mode - These are constant values, if set to Engine::MODE_DEVELOPMENT, it will use the sandbox API, if set to Engine::MODE_PRODUCTION, it will use the production(live) API.

• token - This is your public key, which can be found on your dashboard.

• For more information about the services exposed by the SDK, please refer to the documentation.

  Response Methods

• Response->hasSucceeded() : check if the request has succeeded
• Response->hasFailed() : check if the request has failed
• Response->getStatus() : return response status
• Response->getCode() : return response code
• Response->getData() : return response data
• Response->getDescription() : return response description
• Response->getResponse() : return the whole response

• Response->getErrorMessage(): return error message when the response doesn't have a body

  How to use Responses:

• The example below shows how to access response using response methods;

  Response

  Accessing the response using the response methods

  $response->getStatus() :

  $response->getCode() :

  $response->getDescription() :

  $response->getData() :

Card

Card Payment Initialization

• This request enables a merchant to initialize a card payment.

• The data field of the response returned is a url which you can redirect your users to visit and make the payment.

  Response

Card Payment Verification

• The request can be used to verify a funds deposit or card payment Note: it returned only amountAfterCharges

  Response

Card Payment Verification V2

• The request can be used to verify a funds deposit or card payment Note: This has different response from the first one because it will enable you to view depositedAmount, txnChargesAmount and amountAfterCharges

  Response

Get Card Transactions By Zainbox

• The request can be used to get all card transaction for a particular zainbox

  Response

Reconcile Card Payment

• The request can be used in a scenario where payer has been debited and payment does not reflect on transactions list

  Response

Zainbox

Create Zainbox

• A zainbox is a virtual bucket that allows a merchant to create unlimited multiple virtual accounts.

• This request enables a merchant to create a zainbox.

  Response

Get All Zainboxes

• This request enables a merchant to get all your created zainboxes.

  Response

Update Zainbox

• Enables you to update zainbox details like callbackUrl, emailNotification & so on

• Note you cannot update zainboxCode.

  Response

Zainbox Profile and Current Billing Plan

• Get the complete profile of a Zainbox, including the Current Billing Plan for account to account and interBank transfers respectively

  Response

Create Or Update Zainbox Settlement

• This request enables a merchant to create a scheduled settlement for a zainbox. To create a scheduled settlement for a zainbox., please bear in mind that at any given time, a zainbox can only have one type of settlement.

Planned settlements are divided into three categories:

• T1: Transaction plus one working day The value of the T1 schedule. The period must always be on a daily basis.
• T2: Trasaction plus 7 days Transaction plus seven days for T7 schedule should be one of Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, or Sunday.
• T3: Transaction plus 30 days The schedule Period value for T30 should be 1 - 30 or lastDayOfMonth

*Important Note

• Days like February 28th and February 29th, as well as months with only 30 days, will be covered by lastDayOfMonth.

The payload's settlementAccountList parameter is an array/list of bank accounts with their corresponding settlement percentages.

• set status to false to disable the auto-settlement

Scenario:

• Let's say you have a zainbox with three virtual accounts, and you want to set it up so that the total deposits in these three virtual accounts are split between two accounts at every Transaction plus one day (T1). The first settlement account has 90% of the funds, whereas the second contains only 10%.

  Response

Get Zainbox Settlement

• This request enables a merchant to get settlement(s) tied to a zainbox

  Response

Get Total Payment Collected By Zainbox

• Get the sum of total amount collected by all virtual accounts for a particular zainbox in a particular period, for both transfer and deposit transactions

  Parameter: zainboxCode (Required), dateFrom (optional, if not provided, the system returns the data of the current month), dateTo (optional)

  Response

Get Total Payment Collected For All Zainboxes

• Get the sum of total amount collected by all virtual accounts for all zainboxes in a particular period, for both transfer and deposit transactions

  Response

Get Zainbox Transaction List

• This request enables you to Get a list of transactions from a particular zainbox

  Response

Get Zainbox Settlement Payments Hostory List

• This request enables you to Get a list of settlement payments from a particular zainbox

  Response

Get Zainbox Virtual Accounts

• This request enables you to get all virtual accounts linked to a zainbox.

  Response

Virtual Account

Create Virtual Account

• Create a virtual account. Map a virtual account to a zainbox. A zainbox can hold multiple virtual accounts.

  Response

Get Virtual Account Balance

• This request enables you to get the current wallet balance of a virtual account number

  Response

Update Virtual Account Status

• This request enables you to Activate or deactivate virtual account.

• NOTE: Setting the status field to true will activate the virtual account, while setting it to false will deactivate it.

  Important Note A deactivated virtual account will not be able to receive or transfer funds

  Response

All Virtual Account Balances of a Zainbox

• This request enables a merchant to fetches all current account balances for all virtual accounts in a zainbox.

  Response

Virtual Account Transactions

• This request eanbles you to get all transactions of an account

  Response

Get All Virtual Account By Zainbox

• Get all virtual accounts linked to a zainbox

  Response

Transfer Verification

• The request can be used to verify a posted transfer by its txnRef acquired after successful Funds Transfer

  Parameter: txnRef(required).

  Response

Deposit Verification

• The request can be used to verify a funds deposit or card payment Note: it returned only amountAfterCharges

  Response

Deposit Verification V2

• The request can be used to verify a funds deposit or card payment Note: This has different response from the first one because it will enable you to view depositedAmount, txnChargesAmount and amountAfterCharges

  Response

Repush Deposit Event

• The request can be used to repush webhook deposit event.

• Response

Reconcile Bank Deposit

• The request can be used to reconcile when payer has been debited or transferred the money but it does not appear on merchant transactions list.
• Note: Merchant can reconcile by using either depositReferenceNumber or depositAccountNumber

• Response

Bank

Get Bank List

• This request enables a merchant to get the list of banks supported by Zainpay.

  Response

Name Enquiry

• Use the bankCode acquired from the get bank list to validate a bank account number.

  Response

Fund Transfer

• Fund transfers can be made in the following ways:

  • Transferring money from one wallet to another
  • Make a bank account transfer from your wallet

  Zainpay infers your fund transfer type, so you don't have to specify it. The charges for each form of transfer are different. This charge can be obtained through your commercials.

  Important Note:

  • The amount should be converted to kobo decimalization. It is expected that neither float nor double values will be utilized in this case.

  Response

For detailed documentation visit the ZainPay Developer Documentation Page.