Accept payments on your site

Create a checkout from your server, send your customer to the page, and Payfet tells you when the money lands.

How it works

1. Your server asks Payfet for a checkout, passing the amount and your own order reference.
2. Payfet returns a checkout_url. You send your customer there.
3. The page shows a bank account and the exact amount. Your customer transfers from their banking app.
4. Payfet confirms the transfer, credits your Payfet wallet, and calls your webhook.

Before you start

Get your API credentials from Payfet for Business → Settings → Token. Every request below sends all three:

X-Tenant-Token:  your access token
X-Tenant-Secret: your secret key
X-Tenant-BID:    your business id

These belong on your server only. Anyone holding them can create checkouts in your name, so never ship them to a browser or commit them to a repository.

Restrict them to your servers

Under Settings → IP allowlist you can list the addresses allowed to use these credentials. Both IPv4 and IPv6 are accepted, as a single address or a CIDR range:

An empty list means no restriction. Once there is one active entry, calls from anywhere else are rejected with 401, so add every address your servers call from — including any NAT gateway or egress proxy they sit behind — before you rely on it. Your customers' checkout pages are unaffected either way; this applies to the API only.

1. Create a checkout

Call this from your backend when a customer is ready to pay.

{
  "reference": "order_12345",
  "slug": "order-12345",
  "checkout_url": "https://checkout.payfet.org/order-12345",
  "amount": "2500.00",
  "currency": "NGN",
  "status": "pending"
}

Amounts are in major units, not kobo. "2500.00" means ₦2,500 — not ₦25.

Retries are safe. Creating a checkout twice with the same reference returns the original one rather than a second charge, so a timeout you retry cannot bill your customer twice.

Send customer_phone if you have it. The bank requires a phone number to issue the account. If you omit it, the checkout page asks your customer for one before it can show them the transfer details — one extra step you can remove.

2. Show the checkout

Redirecting is the simplest option and works everywhere:

// after creating the checkout on your server
window.location.href = checkout.checkout_url

Inline: keep them on your page

Drop in our script and the checkout opens in a modal over your site.

<script src="https://cdn.payfet.org/pay.js"></script>

With a button, no JavaScript of your own:

<!-- checkout_url comes from your server -->
<button
  data-payfet-checkout="https://checkout.payfet.org/order-12345"
  data-payfet-success="/thank-you"
>
  Pay ₦2,500
</button>

Or call it yourself:

const res = await fetch('/api/create-checkout', { method: 'POST' })
const { checkout_url } = await res.json()

Payfet.checkout({
  url: checkout_url,
  onSuccess: () => {
    // The modal closes itself. Confirm with your own server before
    // showing a receipt — your server knows because Payfet called your webhook.
    location.assign('/thank-you')
  },
  onClose: () => console.log('customer dismissed the modal'),
})

onSuccess is a UI signal, not a receipt. Fulfil the order from the webhook, which arrives whether or not the customer kept your tab open.

3. Confirm the payment

Payfet calls the webhook URL configured in Settings → Webhook when a transfer clears. This is the event to act on — fulfil the order here, not when the customer is redirected back.

{
  "event": "checkout.paid",
  "id": "6f1c9d2e-...",
  "created_at": "2026-08-10T10:04:11+00:00",
  "data": {
    "reference": "order_12345",
    "status": "paid",
    "amount": "2500.00",
    "settled_amount": "2480.00",
    "currency": "NGN",
    "customer_email": "customer@example.com",
    "customer_name": "Jane Doe",
    "paid_at": "2026-08-10T10:04:09+00:00",
    "metadata": { "order_id": 12345 }
  }
}

Verify the signature

Every call carries X-Payfet-Signature: an HMAC-SHA256 of the raw request body, keyed with your webhook secret. Verify it before trusting anything in the payload — your endpoint is public, and anyone who finds it can post to it.

import crypto from 'node:crypto'

// Use the raw body, not a re-serialised object. JSON.stringify(req.body) can
// reorder keys or change spacing, and the digest will never match.
app.post('/payfet', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = crypto
    .createHmac('sha256', process.env.PAYFET_WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex')

  const signature = req.get('X-Payfet-Signature') ?? ''
  const valid =
    expected.length === signature.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))

  if (!valid) return res.sendStatus(401)

  const { event, id, data } = JSON.parse(req.body)
  if (event === 'checkout.paid') fulfil(data.reference, id)

  res.sendStatus(200)  // acknowledge fast; do the work after
})

Retries, and why your handler must be idempotent

Return 2xx and we consider it delivered. On a timeout, a connection failure or a 5xx we retry on the schedule set in Settings → Webhook. A 4xx is treated as a deliberate rejection and is not retried.

That means the same payment can reach you more than once — a retry after your server accepted the call but timed out on the way back looks identical to a first delivery. Key on id (or on reference, which is your own) and ignore what you have already processed. Shipping goods twice is the failure mode here.

If you would rather poll — for example on your own order page:

curl https://api.payfet.org/v1/checkout/sessions/order_12345/ \
  -H "X-Tenant-Token: $PAYFET_TOKEN" \
  -H "X-Tenant-Secret: $PAYFET_SECRET" \
  -H "X-Tenant-BID: $PAYFET_BID"

You are credited the settled amount, which is net of the transfer fee — reconcile against settled_amount rather than the amount you asked for.

Request fields

Making it look like you

Set "theme": "branded" and the checkout uses your logo, colour, corner radius, button wording and support address, configured once in Settings → Checkout branding. Everything else about the page stays the same, so payers still recognise a Payfet checkout.

Branding is configuration, not code — there is no custom HTML or CSS to upload. That keeps a compromised or careless template on one merchant's account from affecting anyone else's payers.

No code at all?

Create a payment link in Payfet for Business under Payments → Links. You get a shareable checkout.payfet.org URL for WhatsApp, email or a bio — the same checkout page, no server required.

Need help?

Email support@payfet.org with your business ID and the reference you used, and we can trace a specific checkout.