An accepted transfer is not a transfer that arrived

"Accepted" does not mean "arrived"

You send a payout batch. The API answers in two seconds, every line carries an id, and the status reads PENDING or SUCCESS depending on the provider. Your dashboard says "sent", the affiliate gets an email announcing their payment, and everyone moves on.

Except that the answer you just received does not say the funds arrived. It says the request was accepted for processing. Those are two very different claims, and the gap between them can last thirty days.

The PayPal case, in detail

A PayPal payout to an email address follows this path:

1. You send the batch. PayPal accepts and returns a batch id.
2. If the address matches a confirmed PayPal account, the funds arrive within minutes. That is the common case, and it is the one that builds confidence in the rest.
3. If the address matches no confirmed account, PayPal holds the payment and emails that address: "somebody sent you a payment, create an account to receive it".
4. The person has thirty days. After that the payment is UNCLAIMED, then RETURNED, and the funds go back to your balance.

There are other paths back: a closed account, an unsupported country, an address with a typo, a compliance hold. What they have in common is that none of it was known at the moment the API answered you.

What happens if nobody is watching

A platform that stops at the first answer produces a specific and unpleasant situation:

• Your books say €128 was paid, and the funds are sitting in your PayPal balance.
• The affiliate's balance is zero, while you still owe them €128.
• An invoice was issued for a payment that never happened.
• The affiliate got an email announcing a payment they never received.

And above all: they are the one who tells you, often weeks later, often annoyed. You open PayPal, you cannot find the line, you have to go looking for it, and meanwhile the person bringing you sales is wondering whether they will be paid.

The worst thing about a returned transfer is not the amount. It is that the only person who knows is the one waiting for the funds.

What to do instead

Poll until an answer that can no longer change

Every line that has left must stay in an "in flight" state and be re-polled periodically — hourly, in our case — until the provider gives a terminal state: arrived, failed, or returned. As long as the answer can still change, the line is not settled.

One hour is not a magic number. It is a trade-off: frequent enough that you hear about it the same day, spaced enough not to trip an API rate limit on a two-hundred-line batch.

Undo cleanly, not partly

When the answer is "returned", there are five things to do, and doing four of the five leaves the database inconsistent:

1. Mark the line as returned, with its date and the reason the provider gave.
2. Restore the affiliate's balance, with an opposite entry — not by editing the original entry, which has to stay readable.
3. Put the sales concerned back to "payable", so they naturally return in the next batch.
4. Issue a numbered credit note naming the invoice that was issued. You do not delete an invoice; you cancel it.
5. Tell both sides. The affiliate received a message saying they had been paid: they have to receive one that corrects it, and that says what to do next.

How to have fewer of them

A return stays a rare case, but it can be made rarer.

• Ask for payout details at signup, not at the first payment. The affiliate checks them while they are paying attention, not while they are waiting.
• Refuse an incomplete batch rather than skipping lines. An affiliate with no payout address should appear in an "impossible to pay" list with the reason, and get an email — once, at the moment you decide to pay.
• Check the destination before sending, where the provider allows it. Wise, for instance, does not accept an email address alone for every destination: some require the affiliate's bank details. Better to know before sending.
• A minimum threshold. Sending tiny amounts mostly produces fees and returns.

The question to ask

Of an affiliate platform, or of whoever is writing yours:

What happens, precisely, thirty days after a PayPal payout has gone to an address with no confirmed account?

If the answer starts with "you check in PayPal", the work has not been done. It should start with "you get an email, the affiliate's balance is restored, and a credit note has cancelled the invoice".

Read next