ikorovictor/paystack-ruby

A ruby gem for easy integration of Paystack.

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 => "[phone]"
		: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.

paystack-ruby's Issues

MY RAILS APP IGNORES THE IF STATEMENT IN PAYSTACK CODE COMPLETELY

How to List South African banks

Hello, when I run the code to list banks, it lists only banks in Nigeria, how can I list banks in South Africa?

This is what I have

paystackObj = Paystack.new(ENV['PAYSTACK_PUBLIC_KEY'], ENV['PAYSTACK_PRIVATE_KEY'])
banks = PaystackBanks.new(paystackObj)
result = banks.list #Optional page_number parameter, 50 items per page
@banks_list = result['data']

Add Custom Field to Request and return it in Paystack response

Really nice gem. I am trying to add a custom attribute when initiating a payment and I want the attribute to be returned as part of the response data from paystack. I have tried a couple of methods to no avail.

transactions = PaystackTransactions.new(@paystack)
     result = transactions.initializeTransaction(
       amount: @amount,
       email: @email,
       custom_data: 'value' # value I wish to return as part of the response
     )
    

I am working with ruby 2.7 and rails 6

How to notify an action after Successful or Unsuccessful payment

I'm using Paystack-Ruby Gem for paystack Payment gateway 1st time.

I'm successful in loading the Paystack page where Customer can enter his/her card or bank detail. And pay the amount.

I'm using Paystack-Ruby Gem for paystack Payment gateway 1st time.

I'm successful in loading the Paystack page where Customer can enter his/her card or bank detail. And pay the amount.

But I'm unable to figure out How can I know transaction is performed?

How will I go to the next page?
When a Transaction is initiated I just have 3 things

1. Reference Number
2. Access Code
3. Paystack Authorization URL
   After that Paystack page is loaded. And I have a dead-end.

Your help will be appreciated.

Thanks.

How to associate my local product with paystack product_id/product_code

So I am trying to assign paystack product id to my local product but seems there's no static method to call from my app. Something like PaystackCustomers.new(), I was expecting to have PaystackProducts.new()..

New to paystack tho. thanks for helping out.

I can't figure out what ['data'] means

I can't figure out what ['data'] in this line of code means;
auth_url = result['data']['authorization_url']

['authorization_url'] is for positive response or success page but I have read through the docs and couldn't figure out what params am passing to 'data'.

Could you help me out? Am I missing anything??

RestClient::BadRequest (400 Bad Request):

Hi, i am getting a consistent (400 - Bad Request Error) on the initializeTransaction function. i am initializing in my controller. see screenshot.

[Escalated from Paystack Support] Create subscription gives 404

Apeel It sent:

I ran into some trouble trying to integrate paystack with my ruby on rails web app. I have installed the paystack gem and bundle installed it. I am trying to create a subscription for the web app. I was able to implement the customer creation method which works fine but the subscription method keeps on giving me a 404 HTTP client not found error.

Dependency on mime-types

I have mime-types 3.1 (in Gemfile.lock) and a lot of gems generally depend on anything above 1.16. Rails 5.0.0 allows 1.16 to 4.0. Is there any reason it's locked to between 3.0 and 1.16 or it's something that can be easily changed (to 4.0)?