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 "Authorization: Bearer <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 Authorization 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 "Authorization: Bearer <sk_test_YOUR_KEY_HERE>" \
  -H "Content-Type: application/json" \
  -d '{"user_ref": "user_789", "currency": "NGN"}'

Expected response:

{
  "data":
  {
    "ID":"25a793b6-ca5a-49d0-b74a-20731426e0eb",
    "PartnerID":"fec4e29a-dc37-4857-9383-01924a61070f",
    "UserRef":"user_789",
    "Currency":"NGN",
    "Status":"pending",
    "AccountNumber":"",
    "AccountName":"",
    "BankCode":"",
    "BankName":"",
    "MFBReference":"",
    "AccountStatus":"provisioning",
    "Metadata":{},
    "CreatedAt":"2026-08-13T23:33:33.718717+01:00",
    "UpdatedAt":"2026-08-13T23:33:33.718717+01:00"
  }
}

Save the ID (25a793b6-ca5a-49d0-b74a-20731426e0eb), 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 "Authorization: Bearer <sk_test_YOUR_KEY_HERE>" \
  -H "Content-Type: application/json" \
  -d '{"userRef": "user_456", "currency": "NGN"}'

Note the second wallet's id (e.g. c6935d70-f090-488a-9f49-147607b2d4f7).

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

curl -X POST https://api.paykore.dev/sandbox/wallets/25a793b6-ca5a-49d0-b74a-20731426e0eb/fund \
  -H "Authorization: Bearer <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 "Authorization: Bearer <sk_test_YOUR_KEY_HERE>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-transfer-002" \
  -d '{
    "source_wallet": "d516e617-df5a-4bbc-800c-c4ff19ad047c",
    "dest_wallet": "25a793b6-ca5a-49d0-b74a-20731426e0eb",
    "amount": 500000,
    "reference": "test-transfer-002"
  }'

Expected response:

{
  "data":
  {
    "id":"93d10a16-17da-48ab-ab09-8ca70331946c",
    "partner_id":"fec4e29a-dc37-4857-9383-01924a61070f",
    "reference":"test-transfer-002",
    "type":"p2p_transfer",
    "status":"completed",
    "amount":500000,
    "currency":"NGN",
    "source_wallet":"d516e617-df5a-4bbc-800c-c4ff19ad047c",
    "dest_wallet":"25a793b6-ca5a-49d0-b74a-20731426e0eb",
    "source_account":null,
    "dest_account":null,
    "fee_breakdown":{
      "customerFee":2500,
      "merchantFee":0,
      "platformFee":2500,
      "mfbCost":0,
      "netAmount":497500
      },
    "split_config":null,
    "mfb_reference":"sandbox_book_c91ae4f0-533e-4e7a-83fa-181c6b8aad23",
    "psp_reference":"",
    "psp_meta":null,
    "idempotency_key":"test-transfer-002",
    "description":"",
    "metadata":{},
    "failed_reason":"",
    "completed_at":"2026-08-14T19:05:29.640959571+01:00",
    "created_at":"2026-08-14T19:05:16.9709+01:00",
    "updated_at":"2026-08-14T19:05:16.9709+01:00"
  }
}
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/25a793b6-ca5a-49d0-b74a-20731426e0eb \
  -H "Authorization: Bearer <sk_test_YOUR_KEY_HERE>"

Expected response:

{
  "data":
  {
    "balance_kobo":497500,
    "wallet":
    {
      "ID":"25a793b6-ca5a-49d0-b74a-20731426e0eb",
      "PartnerID":"fec4e29a-dc37-4857-9383-01924a61070f",
      "UserRef":"user_789",
      "Currency":"NGN",
      "Status":"active",
      "AccountNumber":"9996025648",
      "AccountName":"USER_789 / PAYKORE SANDBOX",
      "BankCode":"090270",
      "BankName":"Anchor Microfinance Bank (Sandbox)",
      "MFBReference":"sandbox_acct_7fe1edcf-3243-4d05-8dc5-634a170dbb0e",
      "AccountStatus":"active",
      "Metadata":{},
      "CreatedAt":"2026-08-13T23:33:33.718717+01:00",
      "UpdatedAt":"2026-08-13T23:33:37.410097+01:00"
    }
  }
}

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 "Authorization: Bearer <sk_test_YOUR_KEY_HERE>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://webhook.site/dae64561-c9ff-4108-84e1-d0596011fd0d",
    "events": ["transfer.completed", "transfer.failed", "wallet.activated"]
  }'

Expected response:

{
  "data":
  {
    "created_at":"2026-08-19T17:35:40.716404+01:00",
    "events":["transfer.completed","transfer.failed","wallet.activated"],
    "failure_count":0,
    "id":"95f74251-8ca9-46e4-8cda-33dd1ed6387b",
    "is_active":true,
    "last_success_at":null,
    "partner_id":"fec4e29a-dc37-4857-9383-01924a61070f","secret":"sk_wh_c997e5b1bccfa2f56e323abaa04193298d54e2a287d6845ce9ed03466714c198",
    "url":"https://webhook.site/dae64561-c9ff-4108-84e1-d0596011fd0d"
  }
}

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.