Accept QR & bank payments with Manual Mode

What Manual Mode is

Manual Mode is for payments where money moves outside a PSP API — bank transfer, QR, or a personal wallet. SkyPay shows your account details at checkout, the customer pays you, then claims “I’ve paid.” You review and mark the payment complete.

Best for freelancers, social sellers, students, and early launches before merchant API keys.

How the flow works

Manual payments are asynchronous. Confirming a transfer can take minutes or longer — design fulfillment around that delay.

Status path

Set up Manual Mode

1. 1 Sign up and open the merchant dashboard
2. 2 Go to Payment Providers and add a Manual provider (bank / QR / eSewa personal, etc.)
3. 3 Enter the account details or QR image customers should pay to
4. 4 Choose After mark paid: wait (default) stays on verifying until Complete; continue auto-redirects to success_url after Mark as Paid
5. 5 Generate a checkout / payment link as usual (same ck token flow)
6. 6 Add a webhook endpoint and enable payment.waiting + payment.completed

Open providers in the dashboard →

Send customers to checkout

Same payment link pattern as the main guide. Generate a signed ck token from the dashboard, include amount, unique code, and return URLs.

<a href="https://app.skypay.dev/checkout?ck=YOUR_CHECKOUT_TOKEN&amount=500&code=ORDER_8821&success_url=https://yourapp.com/orders/ORDER_8821/paid&failure_url=https://yourapp.com/orders/ORDER_8821/failed">
  Pay with SkyPay
</a>

Confirm waiting payments

When a customer marks paid, the payment appears under waiting on your dashboard.

1. 1 Open Waiting payments on your dashboard
2. 2 Match the amount / reference / screenshot against your bank or wallet
3. 3 Mark Complete, Cancelled, or Invalid
4. 4 On Complete, SkyPay sets status to complete and fires payment.completed

Redirects vs webhooks

This is the part that trips people up. success_url is a browser return URL. SkyPay does not server-call it when you click Complete.

Fulfill with webhooks

Configure an HTTPS endpoint in the dashboard (Webhooks). Enable at least payment.waiting and payment.completed.

Example handler

// Express example — POST /webhooks/skypay
app.post('/webhooks/skypay', express.raw({ type: 'application/json' }), (req, res) => {
  const body = req.body.toString('utf8');
  // Verify SkyPay-Signature: t=...,v1=hmac_sha256(secret, `${t}.${body}`)
  const event = JSON.parse(body);

  if (event.type === 'payment.completed') {
    const payment = event.data.object; // { code, status, amount, ... }
    // Prefer: re-verify, then fulfill
    // GET https://app.skypay.dev/api/v1/checkout/payments-verify/${payment.code}
  }

  res.status(200).send('ok'); // respond fast (< ~5s)
});

if (event.type === 'payment.waiting') {
  // Optional: notify ops ("new bank transfer claim")
  // Do NOT fulfill yet
}

Signatures

Each delivery includes SkyPay-Signature: t=timestamp,v1=hmac_sha256(secret, "{t}.{body}"). Respond with 2xx quickly; failed deliveries retry with backoff.

Always verify

After a webhook (or after a redirect), call verify with your API key before fulfillment. Same endpoint for every rail — including Manual.

const res = await fetch(
  'https://app.skypay.dev/api/v1/checkout/payments-verify/ORDER_8821',
  { headers: { Key: 'YOUR_API_KEY' } }
);
const { data } = await res.json();

if (data?.status === 'complete') {
  // Safe to fulfill / unlock access
}

Production checklist

• Manual provider configured with correct account / QR
• Unique code per order
• Webhook endpoint live for payment.completed (and preferably waiting)
• Signature verification on your server
• Fulfill only when verify returns complete
• Ops process to clear waiting payments promptly
• Customer copy: “Stay on this page for instant confirmation, or we’ll email / unlock after we verify your transfer.”

FAQ