Paystack

A ruby gem for easy integration of Paystack.

Installation

Add this line to your application's Gemfile:

gem 'paystack'

And then execute:

$ bundle

Or install it yourself as:

$ gem install paystack

Basic Usage

Instantiate Paystack Object

    paystackObj = Paystack.new(public_key, secret_key)

A secure way is to set your public and private keys as environmental variables PAYSTACK_PUBLIC_KEY and PAYSTACK_PRIVATE_KEY respectively. Then you instantiate without parameters

	paystackObj =  Paystack.new

It throws a PaystackBadKeyError when either of the keys are invalid or cannot be found as environment variables.

Initialize transaction and get Authorization URL

	transactions = PaystackTransactions.new(paystackObj)
	result = transactions.initializeTransaction(
		:reference => "blablablabla-YOUR-UNIQUE-REFERENCE-HERE",
		:amount => 300000,
		:email => "[email protected]",
		)
	auth_url = result['data']['authorization_url']

NOTE: Amount is in kobo i.e. 100000 = 100000 kobo = 1000 naira

Charge using Authorization code for returning customers

	result = transactions.chargeAuthorization(
		"WwdkojpoAJo", 				# Authorization code
		"[email protected]", 		# Customer email
		2000000, 					# Amount
		:reference => "blablablabla-YOUR-UNIQUE-REFERENCE-HERE"
		)

Transactions

List transactions

	page_number = 1
	transactions = PaystackTransactions.new(paystackObj)
	result = transactions.list(page_number) 	#Optional `page_number` parameter

Get a transaction

	transaction_id = "123456778"
	transactions = PaystackTransactions.new(paystackObj)
	result = transactions.get(transaction_id)

Verify a transaction

	transaction_reference = "blablablabla-YOUR-VALID-UNIQUE-REFERENCE-HERE"
	transactions = PaystackTransactions.new(paystackObj)
	result = transactions.verify(transaction_reference)

Get transaction totals

	transactions = PaystackTransactions.new(paystackObj)
	result = transactions.totals()

Customers

List Customers

	page_number = 1
	customers = PaystackCustomers.new(paystackObj)
	result = customers.list(page_number) 	#Optional `page_number` parameter,  50 items per page
	customers_list = result['data']

Get a customer

	customer_id = "123456778"
	customers = PaystackCustomers.new(paystackObj)
	result = customers.get(customer_id)
	customer =  result['data']

Create new customer

	customers = PaystackCustomers.new(paystackObj)
	result = customers.create(
		:first_name => "Victor",
		:last_name => "Ikoro",
		:phone => "+234707666669"
		:email => "[email protected]"
	)

Update customer details

	customer_id = "123456778"
	customers = PaystackCustomers.new(paystackObj)
	# Updating last name and email of customer
	result = customers.update(
		customer_id,
		:last_name => "Ikorodu",
		:email => "[email protected]"
	)

Plans

List Plans

	page_number = 1
	plans = PaystackPlans.new(paystackObj)
	result = plans.list(page_number) 	#Optional `page_number` parameter,  50 items per page
	plans_list = result['data']

Get plan detail

	plan_id = "123456778"
	plans = PaystackPlans.new(paystackObj)
	result = plans.get(plan_id)
	plan =  result['data']

Create new plan

	plans = PaystackPlans.new(paystackObj)
	result = plans.create(

				:name => "Test Plan",
				:description => "Dev Test Plan",
				:amount => 30000, #in KOBO
				:interval => "monthly", #monthly, yearly, quarterly, weekly etc
				:currency => "NGN"
			)

Update plan details

	plan_id = "123456778"
	plans = PaystackPlans.new(paystackObj)
	result = plans.update(
			plan_id,
			:name => "Test Plan Updated",
			:amount => 500000, #in KOBO
			:interval => "weekly"
			)

Subscriptions

Create new subscription

	subscriptions = PaystackSubscriptions.new(paystackObj)
	result = subscriptions.create(

				:customer => "[email protected]",
				:plan => "123557", #plan id
				:amount => 30000 #in KOBO
			)

Get subscription detail

	subscription_id = "123456778"
	subscriptions = PaystackSubscriptions.new(paystackObj)
	result = subscriptions.get(subscription_id)
	subscription =  result['data']

Enable subscription

	subscriptions = PaystackSubscriptions.new(paystackObj)
	result = subscriptions.enable(
				:code => "12328833",
				:token => "EWFWKFJWE" #user email token
			)

Disable subscription

	subscriptions = PaystackSubscriptions.new(paystackObj)
	result = subscriptions.disable(
				:code => "12328833",
				:token => "EWFWKFJWE" #user email token
			)

Split Payments

This Gem is also aware of the API calls that allow you to perform split payments on Paystack. The Paystack documentation on split payments can get you started. Below are some sample calls for subaccounts and banks.

Banks

List Banks

	page_number = 1
	banks = PaystackBanks.new(paystackObj)
	result = banks.list(page_number) 	#Optional `page_number` parameter,  50 items per page
	banks_list = result['data']

Subaccounts

List Subaccounts

	page_number = 1
	subaccounts = PaystackSubaccounts.new(paystackObj)
	result = subaccounts.list(page_number) 	#Optional `page_number` parameter,  50 items per page
	subaccounts_list = result['data']

Get a subaccount

	subaccount_id = "123456778"
	subaccounts = PaystackSubaccounts.new(paystackObj)
	result = subaccounts.get(subaccount_id)
	subaccount =  result['data']

Create new subaccount

	subaccounts = PaystackSubaccounts.new(paystackObj)
	result = subaccounts.create(
		:business_name => "Madam Ikoro Holdings",
		:settlement_bank => "Providus Bank",
		:account_number => "1170766666",
		:percentage_charge => 3.2
	)

Update subaccount details

	subaccount_id = "123456778"
	subaccounts = PaystackSubaccounts.new(paystackObj)
	# Updating primary contact name and email of subaccount
	result = subaccounts.update(
		subaccount_id,
		:primary_contact_name => "Victoria Ikorodu",
		:primary_contact_email => "[email protected]"
	)

Settlements

Fetch settlements made to your bank accounts and the bank accounts for your subaccounts

List settlements

	settlements = PaystackSettlements.new(paystackObj)
	results = settlements.list
	settlements_list = result['data']

Transfers

The funds transfers feature enables you send money directly from your paystack balance to any Nigerian Bank account. The Paystack documentation on transfers can get you started.

Balance

Check Paystack Balance

	balance = PaystackBalance.new(paystackObj)
	result = balance.get
	account_balance = result['data']

Transfers

Initialize a transfer

	transfer = PaystackTransfers.new(paystackObj)
	results = transfers.initializeTransfer(
		:source => "balance", # Must be balance
		:reason => "Your reason",
		:amount => 30000, # Amount in kobo
		:recipient =>  recipient_code, # Unique recipient code
		)

Bulk transfer

	transfer = PaystackTransfers.new(paystackObj)
	results = transfers.initializeBulkTransfer(
		:source => "balance", # Must be balance
		:transfer => [
			{
				:reason => "Your reason",
				:amount => 30000, # Amount in kobo
				:recipient =>  recipient_code, # Unique recipient code
			},
			{
				:reason => "Your reason",
				:amount => 30000, # Amount in kobo
				:recipient =>  recipient_code, # Unique recipient code
			},
		]
	)

List transfers

	page_number = 1
	transfers = PaystackTransfers.new(paystackObj)
	result = transfers.list(page_number) 	#Optional `page_number` parameter

Get a transfer

	transfer_code = "TRF_uniquecode"
	transfer = PaystackTransfers.new(paystackObj)
	result = transfer.get(transfer_code)

Finalize a transfer

	transfer = PaystackTransfers.new(paystackObj)
	results = transfer.authorize(
		:transfer_code => "TRF_blablabla", # Must be balance
		:otp => "12350",
		)

Transfer Recipients

Create new recipient

	recipient = PaystackRecipients.new(paystackObj)
	result = recipient.create(
		:type => "nuban", #Must be nuban
		:name => "Test Plan",
		:description => "Bla-bla-bla",
		:account_number => 0123456789, #10 digit account number
		:bank_code => "044", #monthly, yearly, quarterly, weekly etc
		:currency => "NGN",

	)

List transfer recipients

	page_number = 1
	recipients = PaystackRecipients.new(paystackObj)
	result = recipients.list(page_number) #Optional `page_number` parameter,  50 items per page
	recipients_list =  result['data']

Transfer Control

Resend OTP

	transfer_code = "TRF_asdfghjkl"	#A unique Transfer code is generated when transfer is created
	transfer = PaystackTransfers.new(paystackObj)
	result = transfer.resendOtp(transfer_code)

Disable OTP for transfers

	transfer = PaystackTransfers.new(paystackObj)
	result = transfer.disableOtp
	#OTP is sent to the registered phone number of the account

Confirm disabling of OTP for transfers

	otp = "12345"
	transfer = PaystackTransfers.new(paystackObj)
	# Updating primary contact name and email of subaccount
	result = transfer.confirmDisableOtp(
		:otp => otp, #Must be valid OTP sent to the registered phone number
	)

Enable OTP for transfers

	transfer = PaystackTransfers.new(paystackObj)
	result = transfer.enableOtp

Refunds

Create a refund

 refund = PaystackRefunds.new(paystackObj)

 #full refund
 transaction = {transaction: transaction_reference}
 refund.createRefund(transaction) #must be a valid transaction reference or transaction id

 #partial refund
 transaction = {transaction: transaction_reference, amount: 5000} # minimum amount 50 NGN or 5000 kobos
 refund.createRefund(transaction)

List refunds

	page_number = 1
 	refund = PaystackRefunds.new(paystackObj)
	refund.list(page_number) # page_number is optional

Fetch refund

 	refund = PaystackRefunds.new(paystackObj)
	refund.get(refund_id) # returned at the time of creating a refund

Static methods

PaystackTransactions, PaystackCustomers, PaystackPlans, PaystackSubaccounts, PaystackRefunds, PaystackBanks , PaystackSubscriptions , PaystackSettlements, PaystackBalance, and PaystackTransfers methods can be called statically, You just need to pass the paystack object as the first parameter e.g. verify method in PaystackTransactions can be called like this

	transaction_reference = "blablablabla-YOUR-VALID-UNIQUE-REFERENCE-HERE"
	result = PaystackTransactions.verify(paystackObj, transaction_reference)
	puts result['message']

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/IkoroVictor/paystack-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.