Skip to main content

Quickstart

Get a wallet created and a transfer made in under 5 minutes.

Prerequisites

Step 1 — Get your API key​

  1. Log in to app.paykore.dev
  2. Go to Settings → API Keys
  3. Click Create Key, select Sandbox
  4. Copy the key — it will only be shown once

Your sandbox key looks like this:

sk_test_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
danger

Never expose your secret key in frontend code or commit it to Git. Store it in an environment variable (PAYKORE_API_KEY) and read it server-side only.

Step 2 — Make your first request​

Verify your key works with the health endpoint:

curl https://api.paykore.dev/health \
  -H "X-API-Key: sk_test_YOUR_KEY_HERE"

Expected response:

{
  "status": "ok",
  "timestamp": "2025-06-01T10:00:00Z"
}

If you get a 401, double-check the key and ensure you're using the X-API-Key header.

Step 3 — Create a wallet​

Every user in your app needs a wallet. You create it once using your own user ID as the userRef. PayKore stores the mapping — you never need to manage wallet IDs yourself.

curl -X POST https://api.paykore.dev/v1/wallets \
  -H "X-API-Key: sk_test_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"userRef": "user_123", "currency": "NGN"}'

Expected response:

{
  "id": "wlt_9f3kA2mXpQ",
  "userRef": "user_123",
  "currency": "NGN",
  "balance_kobo": 0,
  "balance_naira": "0.00",
  "status": "active",
  "nuban": "0123456789",
  "bank_name": "PayKore MFB",
  "created_at": "2025-06-01T10:01:00Z",
  "meta": {
    "request_id": "req_7hJkL9mNpQ"
  }
}

Save the id (wlt_9f3kA2mXpQ) — you'll need it for transfers.

tip

userRef is your own internal user ID. Use whatever identifier you already have (UUID, database ID, etc.). PayKore never assigns user IDs — that's your system's job.

Step 4 — Transfer between wallets​

Create a second wallet for another user, then send money between them.

Create wallet B:

curl -X POST https://api.paykore.dev/v1/wallets \
  -H "X-API-Key: sk_test_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"userRef": "user_456", "currency": "NGN"}'

Note the second wallet's id (e.g. wlt_3pRsT7uVwX).

Fund wallet A (sandbox only — simulates an inbound bank transfer):

curl -X POST https://api.paykore.dev/v1/wallets/wlt_9f3kA2mXpQ/fund \
  -H "X-API-Key: sk_test_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"amount_kobo": 1000000, "note": "Test funding"}'

This credits 1000000 kobo (₦10,000) to wallet A.

Transfer from A to B:

curl -X POST https://api.paykore.dev/v1/transfers/p2p \
  -H "X-API-Key: sk_test_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-transfer-001" \
  -d '{
    "from_wallet_id": "wlt_9f3kA2mXpQ",
    "to_wallet_id": "wlt_3pRsT7uVwX",
    "amount_kobo": 500000,
    "note": "Payment for invoice #42"
  }'

Expected response:

{
  "id": "tx_4qYzA1bCdE",
  "type": "p2p_transfer",
  "status": "completed",
  "from_wallet_id": "wlt_9f3kA2mXpQ",
  "to_wallet_id": "wlt_3pRsT7uVwX",
  "amount_kobo": 500000,
  "amount_naira": "5000.00",
  "fee_breakdown": {
    "customer_fee_kobo": 2500,
    "platform_fee_kobo": 2500,
    "mfb_cost_kobo": 0,
    "net_amount_kobo": 500000
  },
  "created_at": "2025-06-01T10:03:00Z",
  "meta": {
    "request_id": "req_2kMnO5pQrS"
  }
}
note

The Idempotency-Key header makes transfers safe to retry. If you send the same key twice, the second request returns the original response without creating a duplicate transaction. Always use a unique key per transfer attempt.

The fee_breakdown shows 500000 kobo (₦5,000) transferred. The 0.5% fee (2500 kobo / ₦25) is deducted from wallet A on top of the transfer amount.

Step 5 — Check a wallet balance​

curl https://api.paykore.dev/v1/wallets/wlt_9f3kA2mXpQ \
  -H "X-API-Key: sk_test_YOUR_KEY_HERE"

Expected response:

{
  "id": "wlt_9f3kA2mXpQ",
  "userRef": "user_123",
  "currency": "NGN",
  "balance_kobo": 497500,
  "balance_naira": "4975.00",
  "status": "active",
  "nuban": "0123456789",
  "bank_name": "PayKore MFB"
}

Wallet A started with 1000000 kobo (₦10,000), sent 500000 kobo (₦5,000), and paid 2500 kobo (₦25) in fees — leaving 497500 kobo (₦4,975).

tip

All amounts in PayKore are in kobo (the smallest Nigerian currency unit). 100 kobo = ₦1. The API always returns both balance_kobo (integer, for calculations) and balance_naira (string, for display).

Step 6 — Register a webhook​

Register a webhook URL so PayKore can notify your server when transactions complete.

For testing, get a free endpoint at webhook.site — it gives you a unique URL that logs every request.

curl -X POST https://api.paykore.dev/v1/webhooks \
  -H "X-API-Key: sk_test_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://webhook.site/your-unique-id",
    "events": ["transfer.completed", "transfer.failed", "wallet.funded"]
  }'

Expected response:

{
  "id": "wh_5rTuV2wXyZ",
  "url": "https://webhook.site/your-unique-id",
  "events": ["transfer.completed", "transfer.failed", "wallet.funded"],
  "secret": "whsec_a1b2c3d4e5f6...",
  "status": "active",
  "created_at": "2025-06-01T10:05:00Z"
}

Save the secret — you'll use it to verify incoming webhook signatures. See the Webhooks guide for verification details.

Now repeat the transfer from Step 4. You should see a transfer.completed event appear at your webhook.site URL within seconds.

What's next?​

  • Authentication → — Understand API key types, rotation, and security best practices.
  • Wallets → — Full wallet lifecycle: create, fund, freeze, close, and list.
  • Webhooks → — Handle events reliably with retries and signature verification.