G
All docs
Payments
Updated 2026-04-28
6 min read

Koko BNPL setup

Get your merchant credentials, RSA key pair, and plugin info from paykoko.com and connect Koko to your storefront.

Koko lets your customers split a purchase into 3 (or 6, for some accounts) interest-free payments. You get paid the full amount up front; Koko collects from the customer over time. Adding it can lift your conversion on bigger-ticket items.

What you'll need

  • A Koko merchant account.
  • About 30 minutes (key generation takes a few minutes).
  • Patience — Koko's setup involves uploading a security key file, which we'll walk through step by step.

Step 1 — Apply with Koko

  1. Go to paykoko.com and apply for a merchant account.
  2. Send them your business documents. Approval usually takes 5-10 working days.
  3. Once approved, Koko gives you access to their merchant dashboard.

Step 2 — Copy your Merchant ID and API Key

  1. Sign in to the Koko merchant dashboard.
  2. Open Integrations → API Keys.
  3. Copy your Merchant ID (32 characters, looks like a long jumble of letters and numbers).
  4. Copy your API Key.

Step 3 — Generate your security key pair

Koko uses a security technique called RSA keys to make sure messages between Koko and your store can't be faked. You need two files: a Private Key (you keep) and a Public Key (you give to Koko).

Some merchant accounts are issued these by Koko directly — check your welcome email. If you got them, skip to Step 4. Otherwise, ask Koko support to generate them for you, or follow these instructions on a Mac/Linux terminal:

# Run these in a terminal
openssl genrsa -out koko_private.pem 2048
openssl rsa -in koko_private.pem -pubout -out koko_public.pem

Two files appear: koko_private.pem and koko_public.pem. Open them in any text editor (TextEdit, Notepad).

Step 4 — Upload your Public Key to Koko

  1. In the Koko dashboard, go to Integrations → Public Key.
  2. Open koko_public.pem in a text editor and copy everything — including the lines that say -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----.
  3. Paste it into Koko and save.

Step 5 — Set up the webhook

Koko notifies your store when a customer completes a payment. Tell Koko where to send those notifications.

Webhook URL

https://gannako.com/api/webhooks/koko
  1. In Koko's dashboard, look for Integrations → Response URL or Callback URL.
  2. Paste the URL above.
  3. Save.

Step 6 — Paste everything into Gannako

  1. Open Settings → Payments → Koko in your Gannako admin.
  2. Click the API Credentials tab.
  3. Paste your Merchant ID (32 characters).
  4. Paste your API Key.
  5. Open koko_private.pem in a text editor, copy everything (including the BEGIN/END lines), and paste into the Private Key field.
  6. Do the same with koko_public.pem for the Public Key field.
  7. Leave Plugin Name as customapi and Plugin Version as 1.0.1 unless Koko told you different values.
  8. Click Save.

Step 7 — Choose installment plans

  1. Open the Installments tab.
  2. Tick which terms to offer at checkout. Standard accounts only have 3 months — most merchants leave only 3 selected. If your account is on Koko PRISM, also tick 6.
  3. Pick a default. The customer can still change it on Koko's page.

Step 8 — Test, then go live

  1. Leave Test Mode on. Sandbox URL is qaapi.paykoko.com. Place a test order using Koko's sandbox test data (they email this to you).
  2. Confirm the order shows as Paid in your admin.
  3. Switch Test Mode off. Production URL is prodapi.paykoko.com. Run a real order on a small item.
All docs