Accepting Payments with Paystack

The Paystack add-on sends your customers to Paystack's secure payment page to pay, then brings them back to your site to see their receipt. Paystack is built for businesses in Africa and is a good fit if you're based in Nigeria, Ghana, South Africa, Kenya or Côte d'Ivoire.

Paystack takes payments in Nigerian naira (NGN), Ghanaian cedi (GHS), South African rand (ZAR), Kenyan shillings (KES), West African CFA francs (XOF) and, for some accounts, US dollars. Each Paystack account works in its own country's currency, so set your store currency in Sunshine > Settings to one your Paystack account can take. Customers can pay by card and, depending on your country, by bank transfer, USSD, mobile money and other methods Paystack offers.

Installing the Add-on

If you have a Pro, Plus or Basic license, go to Sunshine > Add-ons and turn on Paystack. Sunshine downloads it, adds its license key and activates it for you. The steps are in Install add-ons for Pro/Plus/Basic licenses.

If you bought the add-on on its own, follow Install individually purchased add-on, then enter its key in Sunshine > Settings > Licenses. See License Keys if the key won't activate.

Getting Your Paystack API Keys

Sunshine connects to Paystack with API keys, which are long codes that let your site create payments in your Paystack account. Paystack gives you two pairs: a secret key and a public key for live payments, and another pair for test payments.

1. Log in to your Paystack Dashboard
2. Go to Settings, then API Keys & Webhooks
3. Copy the Secret Key (it starts with sk_live_ or sk_test_) and the Public Key (it starts with pk_live_ or pk_test_)

Your test keys are there as soon as you sign up. Live keys only take real payments once Paystack has activated your business, so finish their sign-up steps before you switch Sunshine to Live.

Keep your secret key private. Anyone who has it can make changes in your Paystack account.

Setting Up Paystack in Sunshine

1. Go to Sunshine > Settings > Payments
2. Turn on Paystack with the toggle, then click Configure
3. Set Mode to Live
4. Paste your live keys into Live Secret Key and Live Public Key
5. Click Save Changes

Here is every setting on the Paystack screen:

• Name: What customers see as the payment option at checkout. Leave it blank to show "Paystack".
• Description: The short line under the name at checkout. Leave it blank to show "Pay with credit card". If you've turned on other ways to pay in Paystack, like bank transfer or mobile money, you may want to change this.
• Fees: Add an extra charge when customers pay this way, as a percentage or a fixed amount, with a Fee Name and Fee Amount. See Payment Gateway Fees.
• Mode: Live takes real payments. Test uses Paystack's test mode, where no real money moves. Paystack starts in Test mode until you change it.
• Live Secret Key and Live Public Key: Your live keys. Shown when Mode is Live.
• Test Secret Key and Test Public Key: Your test keys. Shown when Mode is Test.

Sunshine talks to Paystack with the secret key, so that's the one that has to be right for payments to work.

Testing with Paystack

Paystack's test mode lets you go through the whole checkout without paying anything.

1. In Sunshine, set Mode to Test, paste your test keys into Test Secret Key and Test Public Key, and click Save Changes
2. Place an order on your site and choose Paystack
3. On Paystack's page, pay with one of the test cards from Paystack's test payments guide

Try a successful payment and a cancelled one so you can see both paths described below. Orders placed in Test mode are marked Test in your order list. Set Mode back to Live and save when you're done testing.

What Customers See at Checkout

On the payment step, customers choose Paystack (or the name you gave it). The button reads Continue to payment details, since the payment itself happens on Paystack's site.

When they click it, Sunshine saves the order as Pending Payment and sends them to Paystack's payment page with the order total, the currency and their email address. They pay there with any of the methods your Paystack account offers.

What Happens When Customers Come Back

When the payment goes through

Paystack sends the customer back to your site, and Sunshine asks Paystack about the payment before doing anything else. It checks that the payment was successful, that it's the payment made for this order, and that it's for the full order total in the order's currency.

If it all matches, the order is marked New, the cart is emptied, the receipt emails go out and the customer lands on their receipt page.

If something doesn't match, or Paystack says the payment didn't go through, the order stays Pending Payment and isn't marked paid. The customer sees "Could not verify payment status" on the checkout page, and a note on the order explains what Sunshine found.

When the customer cancels

Paystack's payment page has a link to cancel and go back. When a customer uses it, Sunshine first asks Paystack whether the order was paid anyway, in case they paid in another tab. If it was, the order is finished as normal.

Otherwise, the order is marked Cancelled with the note "Customer cancelled the Paystack payment", and the customer goes back to the checkout page with the message "Payment has been cancelled". Their cart is still there. If they try again, Sunshine starts a new order, and the cancelled one stays in your order list for your records.

Payment Notices from Paystack

Some payment services send your site a separate notice (a webhook) about each payment. Sunshine doesn't use Paystack's webhooks, so you don't need to enter anything in the Webhook URL field in your Paystack settings. Sunshine checks each payment with Paystack directly when the customer comes back to your site.

This means the customer coming back is what finishes the order. If a customer pays and then closes the tab before Paystack sends them back, the order stays on Pending Payment. See An order is stuck on Pending Payment below for how to finish it.

Receipts

Sunshine holds back the customer receipt and the admin receipt emails until Paystack confirms the payment. That way nobody gets a receipt for an order that was never paid. Once the payment is confirmed, both emails go out once.

On the order screen, the Paystack tab shows the Transaction ID, which links straight to the payment in your Paystack Dashboard, and the Transaction Fees Paystack charged for it.

Refunds

Refunding from the order screen

You can refund a Paystack payment from your WordPress admin.

1. Open the order in Sunshine > Orders
2. In the Order Actions panel, choose Refund payment in Paystack
3. Leave Full refund ticked to refund everything that's left, or untick it and enter the amount
4. Click Apply

A full refund marks the order Refunded. A partial refund is recorded on the order and comes off its total, but the order keeps its status. You can make more partial refunds later, up to what's left.

Sunshine doesn't email the customer about a Paystack refund, so let them know yourself. If Paystack turns the refund down, Sunshine shows Paystack's reason at the top of the order screen and adds it to the order notes.

Refunding in the Paystack Dashboard

You can also refund a payment in your Paystack Dashboard, but Paystack doesn't tell Sunshine about it. The order in Sunshine won't show the refund, so change its status to Refunded by hand if you refunded the whole thing.

How Amounts Are Sent

Paystack wants every amount in the currency's smallest unit, such as kobo for naira or cents for rand, so ₦5,000.00 is sent as 500000. Sunshine does this for you, for payments and refunds, including West African CFA francs, which Paystack handles the same way. There's nothing to set up.

Admin Payment Problem Email

Sunshine can email you when a Paystack payment can't be accepted for an order. That covers two cases:

• The payment didn't match the order. It was for a different amount or currency, or it belonged to a different order. The order is left unpaid and a note explains why, for example "Paystack payment not accepted, order left unpaid: the payment was in USD but the order is in NGN".
• The payment was declined. Paystack said the payment didn't go through, for example because it failed or the customer abandoned it, and the customer came back to your site anyway.

A customer clicking the cancel link on Paystack's page doesn't send this email.

This email is off until you turn it on.

1. Go to Sunshine > Settings > Email and open Admin Payment Problem
2. Tick Enabled
3. Add one or more addresses in Recipient(s), or leave it empty to send to your site's admin email
4. Under Send when, tick "A payment didn't match the order" and "A payment was declined or cancelled at the payment service"

See Emails for all the options.

Troubleshooting

"Unsupported currency"

Your store currency isn't one your Paystack account can take. Change the currency in Sunshine > Settings to match your Paystack account, or ask Paystack to turn on the currency you need.

Customers are sent straight back to checkout without paying

This usually means Paystack didn't accept your keys. Check that:

• The keys are in the fields for the mode you're using: live keys (sk_live_) in the Live fields, test keys (sk_test_) in the Test fields
• Mode matches the keys you pasted, and you clicked Save Changes
• There are no spaces before or after the keys
• Your Paystack business has been activated, if you're in Live mode

If customers see "Unknown error occured" instead, Paystack refused the payment for another reason. Turn on logging (see below) and place a test order to see Paystack's full answer.

"Could not verify payment status"

Sunshine asked Paystack about the payment and it didn't check out, so the order wasn't marked paid. Open the order and read its notes to see why, then look up the payment in your Paystack Dashboard. If the customer was charged but shouldn't have been, refund them in Paystack. If you're happy to accept it, follow the steps in the next section to finish the order.

An order is stuck on Pending Payment

The customer most likely closed the tab before Paystack sent them back, or left without paying. Look for the payment in your Paystack Dashboard under Transactions. If it was paid:

1. Open the order in Sunshine > Orders
2. Change its status to New and save the order
3. In the Order Actions panel, choose Resend order email to customer and click Apply to send their receipt

An order finished this way doesn't have the Paystack transaction ID saved on it, so if you ever need to refund it, do that in your Paystack Dashboard.

"Could not refund payment in Paystack"

The order doesn't have a Paystack transaction ID saved, usually because it was marked paid by hand. Refund it in your Paystack Dashboard instead.

If you need more detail about what happened, turn on logging and try another test order.