DEV Community

Dalia Rumbaitė
Dalia Rumbaitė

Posted on

Why most 'payout' APIs weren't built for paying people

#api #fintech #webdev #integrations

The problem you're about to hit

You're building a survey tool. Or a referral program. Or a creator marketplace. Or an HR rewards module.
At some point, you need to send money to people — small amounts, lots of recipients, across borders.
So you check the obvious options:

  • Stripe Connect → great for paying businesses, painful for paying individuals at scale (KYC, regional restrictions)

  • PayPal Mass Pay → unavailable in roughly half the countries you actually need

  • Wire transfer API → $25–50 per transaction, 3–5 business days, banking details required for every recipient

  • Physical gift cards → shipping costs and lead times kill the entire model

The tools built for B2B AP were never designed for B2C disbursement at scale. So you end up either bolting together three providers or punting on global coverage entirely.

What "good" looks like

A payout API for paying people — not businesses — should:

  • Work in 90+ countries out of the box, with multi-currency support
  • Let the recipient choose their preferred brand (not force them to use yours)
  • Cost face value, not face-value-plus-markup-plus-platform-fee
  • Settle instantly, not in 3–5 business days
  • Have a sandbox you can hit in 5 minutes

That's the spec we built GIFQ Payouts against.

How the integration looks

bashcurl -X POST https://api.gifq.com/v1/payouts \
  -H "Authorization: Bearer $GIFQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": {
      "email": "alice@example.com",
      "country": "DE"
    },
    "amount": 25.00,
    "currency": "EUR",
    "brand": "open_choice"
  }'
Enter fullscreen mode Exit fullscreen mode

(Schema simplified for illustration — see the full API reference for production-ready payloads.)

That single call:

  1. Triggers a branded email to the recipient
  2. Lands them on a redemption page where they pick from 5,000+ brands
  3. Issues the gift card in their local currency
  4. Sends you a webhook on delivery + on redemption

SDKs are available in Python, Node.js, and PHP. Sandbox accounts come with seeded test balances so you can hit the full flow without burning real money.

Webhook handling pattern

javascriptapp.post('/webhooks/gifq', (req, res) => {
  const { event, payout_id, recipient_email, status } = req.body;

  switch (event) {
    case 'payout.delivered':
      // Update your internal record — recipient got the email
      break;
    case 'payout.redeemed':
      // Recipient picked a brand and redeemed
      // Trigger your own analytics / loyalty logic here
      break;
    case 'payout.failed':
      // Surface to ops / retry logic
      break;
  }

  res.sendStatus(200);
});
Enter fullscreen mode Exit fullscreen mode

When not to use a gift card payout API

Be honest with yourself. If your recipients need cash to pay rent, a gift card is the wrong instrument. If you're paying contractors > $600/year in the US, you need W-9 collection and 1099 reporting, which is a different stack.

Gift card payouts shine for:

  • Survey & research incentives
  • Employee spot bonuses / anniversary rewards
  • Creator / affiliate payouts (small to mid-value, recurring)
  • Customer loyalty, NPS follow-ups, referral fulfillment

Try it

Free sandbox, no credit card required. Full docs at docs.gifq.com.

Top comments (0)