Accept Payments

In A Nutshell
In a nutshell
To accept a payment, create a transaction using our API, our client Javascript library, Popup JS, or our SDKs. Every transaction includes a link that can be used to complete payment.

Paystack Popup provides a simple and convenient payment flow for web. It can be integrated in five easy steps, making it the easiest way to start accepting payments. See demo of the payment methods on the checkout here.

Collect customer information

To initialize the transaction, you'll need to pass information such as email, first name, last name amount, transaction reference, etc. Email and amount are required. You can also pass any other additional information in the metadata object field. Here is the full list of parameters you can pass:

ParamRequired?Description
keyYesYour public key from Paystack. Use test key for test mode and live key for live mode
emailYesEmail address of customer
amountYesAmount (in the lowest currency value - kobo, pesewas or cent) you are debiting customer. Do not pass this if creating subscriptions.
refNoUnique case sensitive transaction reference. Only -,., =and alphanumeric characters allowed. If you do not pass this parameter, Paystack will generate a unique reference for you.
currencyNoCurrency charge should be performed in. It defaults to your integration currency.
channelsNoAn array of payment channels to control what channels you want to make available to the user to make a payment with. Available channels include; ['card', 'bank', 'ussd', 'qr', 'mobile_money', 'bank_transfer']
metadataNoObject containing any extra information you want recorded with the transaction. Fields within the custom_field object will show up on customer receipt and within the transaction information on the Paystack Dashboard.
labelNoString that replaces customer email as shown on the checkout form
callbackNoFunction that runs when payment is successful. This should ideally be a script that uses the verify endpoint on the Paystack API to check the status of the transaction.
onCloseNoJavascript function that is called if the customer closes the payment window instead of making a payment.
For Split Payment transactions
subaccountYesThe code for the subaccount that owns the payment. e.g. ACCT_8f4s1eq7ml6rlzj
transaction_chargeNoA flat fee to charge the subaccount for this transaction (in kobo, pesewas or cents). This overrides the split percentage set when the subaccount was created. Ideally, you will need to use this if you are splitting in flat rates (since subaccount creation only allows for percentage split).
bearerNoDecide who will bear Paystack transaction charges between account and subaccount. Defaults to account.
For Subscriptions transactions
planYesPlan code generated from creating a plan. This makes the payment become a subscription payment.
quantityNoUsed to apply a multiple to the amount returned by the plan code above.

The customer information can be retrieved from your database if you already have it stored, or from a form like in the example below:

1 <form id="paymentForm">
2 <div class="form-group">
3 <label for="email">Email Address</label>
4 <input type="email" id="email-address" required />
5 </div>
6 <div class="form-group">
7 <label for="amount">Amount</label>
8 <input type="tel" id="amount" required />
9 </div>
10 <div class="form-group">
11 <label for="first-name">First Name</label>
12 <input type="text" id="first-name" />
13 </div>
14 <div class="form-group">
15 <label for="last-name">Last Name</label>
16 <input type="text" id="last-name" />
17 </div>
18 <div class="form-submit">
19 <button type="submit" onclick="payWithPaystack()"> Pay </button>
20 </div>
21</form>
22
23<script src="https://js.paystack.co/v1/inline.js"></script>

In this sample, notice how:

  1. The Paystack inline javascript is included using a script tag. This is how you import Paystack into your code.
  2. The amount here can be hardcoded if you want to charge a specific amount.
  3. The Pay button has been tied to an onClick function called payWithPaystack. This is the action that causes the Paystack popup to load.
Helpful Tip
If you don't collect email addresses from your customer, you can generate an email address using the information you have alongside your website url. E.g, if you only collect phone numbers from your customers, you can create email addresses like [email protected]

Initialize transaction

When you have all the details needed to initiate the transaction, the next step is to tie them to the javascript function that passes them to Paystack and displays the checkout popup modal.

1var paymentForm = document.getElementById('paymentForm');
2paymentForm.addEventListener('submit', payWithPaystack, false);
3function payWithPaystack() {
4 var handler = PaystackPop.setup({
5 key: 'YOUR_PUBLIC_KEY', // Replace with your public key
6 email: document.getElementById('email-address').value,
7 amount: document.getElementById('amount').value * 100, // the amount value is multiplied by 100 to convert to the lowest currency unit
8 currency: 'NGN', // Use GHS for Ghana Cedis or USD for US Dollars
9 firstname: document.getElementById('first-name').value,
10 lastname: document.getElementById('first-name').value,
11 reference: 'YOUR_REFERENCE', // Replace with a reference you generated
12 callback: function(response) {
13 //this happens after the payment is completed successfully
14 var reference = response.reference;
15 alert('Payment complete! Reference: ' + reference);
16 // Make an AJAX call to your server with the reference to verify the transaction
17 },
18 onClose: function() {
19 alert('Transaction was not completed, window closed.');
20 },
21 });
22 handler.openIframe();
23}
Important notes
  1. The key field here takes your Paystack _public_ key.
  2. The amount field has to be converted to the lowest currency unit by multiplying the value by 100. So if you wanted to charge N50 or $50 or GHS50, you have to multiply 50 * 100 and pass 5000 in the amount field.
  3. It's ideal to generate a unique reference from your system for every transaction to avoid duplicate attempts.
  4. The callback method is called when payment has been completed successfully on the Paystack checkout. See the next section to see for how to handle the callback.
  5. the onClose method is called if the user closes the modal without completing payment.

Handle the callback method.

The callback method is fired when the transaction is successful. This is where you include any action you want to perform when the transaction is successful.

The recommended next step here is to verify the transaction to confirm the status.

Helpful Tip
To verify the transaction, you have to set up a route or page on your server that you pass the transaction reference to. Then from your server, you call the Paystack verify endpoint to confirm the status of the transaction, and the response is returned to your frontend.

There are 2 ways you can call your server from the callback function

  1. Make an AJAX request to the endpoint on your server that handles the transaction verification
1callback: function(response){
2 $.ajax({
3 url: 'http://www.yoururl.com/verify_transaction?reference='+ response.reference,
4 method: 'get',
5 success: function (response) {
6 // the transaction status is in response.data.status
7 }
8 });
9}
  1. Redirect to the server URL by setting a window.location to the URL where the verification endpoint is set on your server.
1callback: function(response) {
2 window.location = "http://www.yoururl.com/verify_transaction.php?reference=" + response.reference;
3};
4// On the redirected page, you can call Paystack's verify endpoint.
Warning
Never call the Paystack API directly from your frontend to avoid exposing your secret key on the frontend. All requests to the Paystack API should be initiated from your server, and your frontend gets the response from your server.

Verify the Transaction

After payment is made, the next step is to verify the transaction. Here's how to verify transactions with Paystack.

Handle Webhook

When a payment is successful, Paystack sends a charge.success webhook event to your webhook URL. You can learn more here.

Redirect

Here, you call the Initialize TransactionAPI from your server to generate a checkout link, then redirect your users to the link so they can pay. After payment is made, the users are returned to your website at the callback_url

Warning
Confirm that your server can conclude a TLSv1.2 connection to Paystack's servers. Most up-to-date software have this capability. Contact your service provider for guidance if you have any SSL errors.

Collect customer information

To initialize the transaction, you'll need to pass information such as email, first name, last name amount, transaction reference, etc. Email and amount are required. You can also pass any other additional information in the metadata object field.

The customer information can be retrieved from your database, session or cookie if you already have it stored, or from a form like in the example below.

1<form action="/save-order-and-pay" method="POST">
2<input type="hidden" name="user_email" value="<?php echo $email; ?>">
3<input type="hidden" name="amount" value="<?php echo $amount; ?>">
4<input type="hidden" name="cartid" value="<?php echo $cartid; ?>">
5<button type="submit" name="pay_now" id="pay-now" title="Pay now">Pay now</button>
6</form>

Initialize transaction

When a customer clicks the payment action button, initialize a transaction by making a POST request to our API. Pass the email, amount and any other parameters to the Initialize TransactionAPI endpoint.

If the API call is successful, we will return an authorization URL which you will redirect to for the customer to input their payment information to complete the transaction.

Important notes

  1. The amount field has to be converted to the lowest currency unit by multiplying the value by 100. So if you wanted to charge N50 or $50 or GHS50, you have to multiply 50 * 100 and pass 5000 in the amount field.
  2. We used the cart_id from the form above as our transaction reference. You should use a unique transaction identifier from your system as your reference.
  3. We set the callback_url in the transaction_data array. If you don't do this, we'll use the one that is set on your dashboard. Setting it in the code allows you to be flexible with the redirect URL if you need to
  4. If you don't set a callback URL on the dashboard or on the code, the users will not be redirected back to your site after payment.
  5. You can set test callback URLs for test transactions and live callback URLs for live transactions.
1<?php
2 $url = "https://api.paystack.co/transaction/initialize";
3
4 $fields = [
5 'email' => "[email protected]",
6 'amount' => "20000"
7 ];
8
9 $fields_string = http_build_query($fields);
10
11 //open connection
12 $ch = curl_init();
13
14 //set the url, number of POST vars, POST data
15 curl_setopt($ch,CURLOPT_URL, $url);
16 curl_setopt($ch,CURLOPT_POST, true);
17 curl_setopt($ch,CURLOPT_POSTFIELDS, $fields_string);
18 curl_setopt($ch, CURLOPT_HTTPHEADER, array(
19 "Authorization: Bearer SECRET_KEY",
20 "Cache-Control: no-cache",
21 ));
22
23 //So that curl_exec returns the contents of the cURL; rather than echoing it
24 curl_setopt($ch,CURLOPT_RETURNTRANSFER, true);
25
26 //execute post
27 $result = curl_exec($ch);
28 echo $result;
29?>

Verify Transaction

If the transaction is successful, Paystack will redirect the user back to a callback_url you set. We'll append the transaction reference in the URL. In the example above, the user will be redirected to http://your_website.com/postpayment_callback.php?reference=YOUR_REFERENCE.

So you retrieve the reference from the URL parameter and use that to call the verify endpoint to confirm the status of the transaction. Learn more about verifying transactions.

It's very important that you call the Verify endpoint to confirm the status of the transactions before delivering value. Just because the callback_url was visited doesn't prove that transaction was successful.

Handle Webhook

When a payment is successful, Paystack sends a charge.success webhook event to webhook URL that you provide. Learn more about using webhooks.

Mobile SDKs

You can integrate Paystack directly into your Android or iOS app using our mobile SDK. For mobile frameworks like Ionic or React Native, please find the libraries here.

Parameters List