What a payout API has to do when you send mass payouts

If you only read vendor pages, a payout API looks simple: you send a list of people and amounts, you get a success response, and the money (or the reward) goes out. That version of the story holds up in a demo. It starts to fall apart the first time you actually need to pay a few hundred people across more than one country on a short deadline, because a survey closed, a campaign ended, or sellers in your marketplace hit their payout threshold at the same time.

This article is about what a payout API has to handle when mass payouts are a normal part of the product, not a one-off finance task. It is written for the people who have to integrate it and keep it running, not for a feature checklist.

Mass payouts are a different problem from payroll

A mass payout is a single operation (or a short series of them) that sends money or rewards from one sender to many recipients. The individual amounts are often small, sometimes only five or ten dollars, but the operational load comes from volume and variety: different countries, different currencies, incomplete recipient data, and a finance team that still needs a clear record of what left the account and what was actually claimed.

Payroll systems are built around employment. They assume tax forms, a known cadence, and a fixed population. Mass payouts usually do not. You might be paying affiliates, research participants, creators, marketplace sellers, channel partners, or customers who are owed a make-good. A lot of those people will not complete a bank onboarding flow for a small incentive, and even when they do, international wires remain slow and expensive enough to make the economics silly.

If the only tool you have is a bank-transfer payout API, you have already limited which markets you can serve cleanly. Everyone outside that rail tends to show up later as a support conversation.

People use "payout API" for three different things

In practice the same phrase covers a few products that behave very differently:

1. Pushing funds to a bank account over ACH, SEPA, or another local rail. That is often the cheapest option where it works, and a dead end where the recipient cannot or will not provide banking details.
2. Pushing funds to a card through networks like Visa Direct or Mastercard Send. That can be fast when the issuer accepts the credit, but decline rates in the mid single digits to high teens are common in production and need a real fallback path.
3. Delivering spendable value through gift cards, prepaid products, or crypto, so the recipient can redeem without sharing bank details, usually in a local currency and often with a choice of brand.

GIFQ is built around that third model, with crypto available on the same API surface when a campaign is configured for it. Bank and card rails still matter as comparison points, because most teams evaluating a mass payout stack will put all three in the same spreadsheet. The category is larger than any one method.

What separates a usable payout API from a thin wrapper is usually not the create call. It is everything after that call: foreign exchange, delivery, failure handling, webhooks you can trust enough to automate on, and records that finance can reconcile without reconstructing history from email.

How a mass send works in the API

In GIFQ, a mass send is a payout order tied to a campaign. The campaign holds the recipient-facing setup (branding, messaging, and which reward types people can choose). The order is the batch itself: who gets paid, how much, and in which currency.

A single payout order can include up to 1,000 recipients. Larger lists should be split across multiple orders. That limit is there because very large payloads make retries and partial failures harder to reason about, not because the product wants you to click more often.

A gift-card campaign request hits POST /api/payout-orders with an X-Api-Token header. You send a campaign_id, a wallet_currency, an optional callback_url and expires_in_days, and a recipients array. Each recipient needs at least an email, amount, and currency; name is optional.

Example: one order can pay Priya in INR, Tomasz in PLN, and Ada in EUR while you settle the wallet in EUR. The API accepts the order and returns an identifier, totals, and status (202 Accepted). Later status changes can be pushed to your callback URL.

For anything that touches money, treat GET /api/payout-orders/:id as the source of truth, because webhook delivery is best-effort and at-least-once. Design your side so a missed or duplicated event does not corrupt your ledger.

One practical constraint: hybrid campaigns, where the recipient chooses gift card or crypto at redeem time, are limited to one recipient per order. If you need true batch volume, use a gift-card-only campaign rather than trying to work around that with a thousand single-recipient hybrid creates.

When bank rails are enough, and when they are not

If your recipients are mostly domestic, already verified, and comfortable sharing bank details, a bank-transfer API can be the right answer. If you are paying research participants across many countries, or marketplace sellers who will not share an IBAN for a modest balance, that same API becomes the wrong abstraction no matter how polished the docs look.

The failure mode that matters most in mass payouts is not a missing field in JSON. It is learning that something failed from the recipient (or from finance) before your own systems noticed. An API that cannot tell you delivery and redemption state in a structured way will push that discovery back onto email and support.

Batch jobs and event-driven payouts use the same surface

In a real product, mass payouts show up in two rhythms.

The first is scheduled: monthly affiliate commissions, weekly creator payouts, incentives at the end of a study. A dashboard upload can get you through the first run. By the second or third cycle, that process should be a job that calls the API with a list you already trust.

The second is event-driven: a survey is completed, a seller clears a threshold, a referral converts. You use the same endpoint with one recipient or a small array. You do not need a separate "instant payout product" for that. You need the same create, status, and reconciliation path to work when the batch size is one.

In both cases, it is worth refusing to call the integration done until you have:

• Create behavior you can retry safely (check whether the order exists before posting again blindly)
• Clear per-recipient statuses through the full life cycle
• Webhooks for status changes and terminal states, with signature verification and deduplication
• Per-redemption rows for gift cards, so finance is not reconstructing outcomes from inboxes
• A sandbox that behaves like production before real balance moves

If a vendor only returns a boolean success flag and emails you a spreadsheet a week later, you do not really have an integration you can put inside a product.

Redemption is part of the system, not a nice-to-have

You can have a clean API and still fail the program if recipients ignore the message or cannot use what they received.

Giving everyone the same brand in every country is a common way to create unclaimed value. Letting people choose from a catalog that matches their market usually completes more cleanly. Paying in the recipient's currency matters for the same reason; on GIFQ, wallet_currency can differ from each recipient's currency, and any FX shows up on the order (including as fx_fee_amount), so finance should see that before close rather than after. Expiry should be an intentional product decision as well. When a redeem link expires, unredeemed gift-card value can return to you, and your product needs a defined response to that. The redeem experience should also still feel like your product. If people think they have been sent to an unrelated third party, completion tends to drop and support volume tends to rise.

A build order that surfaces problems early

1. Start in the sandbox with a token and create an order that includes at least two recipients in different currencies.
2. Wire webhooks with signature checks, and deduplicate deliveries using the delivery identifier.
3. Build reconciliation against the GET endpoints before you treat the first live send as a success.
4. Configure a real campaign with the brands, branding, and copy you actually want recipients to see.
5. Keep production batches at 1,000 recipients or fewer, and store order identifiers in your own database.
6. Only then automate the scheduled job or the event trigger that creates orders from your product.

The payout reference is at docs.gifq.com. If you are integrating soon, it is worth sending one deliberately awkward multi-currency sandbox order early. The interesting failure cases show up there, not in the happy-path diagram.

When another rail is enough

If you need payroll, tax withholding, and employment compliance, a payroll product is the right stack. Gift-card payouts are not a substitute for that.

If every recipient already has verified bank details on one domestic rail, and the amounts are large enough that bank transfer is cheaper end to end, stay on bank transfer. There is no reason to add another layer just because it is available.

If you only need to pay US debit cards and you already have a Visa Direct aggregator that returns structured decline reasons you can automate against, that may be enough on its own.

GIFQ fits when the payout still has to complete for people who will not or cannot give you banking data, including in markets where a single ACH-style API does not cover the recipient base you actually have. In those cases, a gift-card and prepaid layer is usually the simpler path to a finished payout.

Related reading

• Mass payouts guide for the finance-facing overview of the same problem
• Visa Direct explained if you are comparing push-to-card rails
• Understanding payouts for the API reference behind the examples above