Paying authors and sellers

Panel → Pay authors. How much you owe each of them, how much is still on hold and how much can be sent now. And how that money goes out: by hand, or through a payments provider.

Before moving other people's money, check it with an adviser. This guide explains what the system does; not what the law requires of you.

Where what they are owed comes from

Every sale records the seller's share in their wallet, which is a ledger of movements: sale, your commission, refunds. It is explained in Selling with others. What is paid here is the balance of that ledger.

The hold: 30 days

Money from a sale cannot be paid out until 30 days later. PCC_DIAS_ESPERA_PAGO changes it.

A refund or a chargeback arrives days after the sale. If the money has already gone, you are chasing someone who no longer has it. That is why there are three figures:

• Earned: the ledger balance.
• On hold: what came in over the last 30 days.
• Available: the difference. It is the only thing that can be paid.

The minimum: 50 €

Nothing is paid below 50 € available. PCC_UMBRAL_PAGO changes it, in cents (5000 out of the box). Each seller can set their own, but not below 10 €: every transfer costs money, and sending three euros costs more than not sending them.

The payout profile

To get paid, the seller fills in their profile in their panel, under Payouts. While anything is missing they are not paid, and the screen tells them exactly what:

• the name they invoice under and whether they are an individual or a company;
• the country where they are tax resident and their full address;
• their tax identification number;
• their date of birth, if an individual, or the registration number, if a company;
• how they want to be paid — PayPal, bank or Wise —, whose name the account is in, and the account or the email;
• accepting that you issue the invoice on their behalf (explained in the next section).

Asking for it up front is cheap; asking someone who has already been paid and disappeared is impossible.

Some checks happen when it is typed in, not on payment day:

• The IBAN is validated with its check digits, the same way the bank does. A mistyped digit is caught when saving.
• PayPal needs a valid email.
• The account is stored encrypted. Only the last four characters are shown on screen. It is encrypted with PCC_CLAVE_CIFRADO (or JWT_SECRET if that is not set): if you change that key, accounts already stored can no longer be read and have to be asked for again.

Countries that are not paid

There is a fixed list of countries the system will not pay to: Russia, Belarus, Iran, North Korea, Syria, Cuba, Afghanistan, Sudan and Myanmar. With one of them the profile is not saved.

That list does not replace checking who you send money to. Which controls apply to you is another question for your adviser.

Self-billing

The profile asks the seller to accept that you issue the invoice on their behalf. Without that acceptance they are not paid. The date they gave it is stored, and once given it cannot be unticked from their panel.

The system stores the consent; it does not produce that invoice. How you issue it, and whether doing it this way suits you, you decide with your adviser.

Stopping someone's payouts

You can block a seller's payouts. The reason has to be written, and the seller gets an email with it. The same when a payout fails. The money stays in their wallet; the email tells them so.

This is on purpose: there is no way to stop someone's money silently. On unblocking, their profile is checked again: if anything is missing, they still cannot be paid.

Today it has no button in the panel: it is done with POST /gestion/cobros/vendedores/<id>/bloquear and the motivo, and undone with the same route and accion: "desbloquear".

How the money goes out

There are two modes, chosen with PCC_CARRIL_PAGO.

No rail (out of the box): a person pays

Without PCC_CARRIL_PAGO, the system does not move bank money. It keeps the books, schedules the payout and waits for you to make it.

1. Panel → Pay authors lists every seller with a balance: earned, on hold, available and, if they cannot be paid, why.
2. Pay schedules a payout for everything available. It is scheduled, not done.
3. You make the transfer yourself, by the method in their profile.
4. You confirm the payout with its reference (the bank's, PayPal's). Only then, and not before, does it leave the wallet.

Today that confirmation has no button in the panel: it is done with POST /gestion/cobros/pagos/<id> and the referencia. Do not also record it as a settlement on the seller's page: it would be deducted twice.

The payout leaves the ledger when it is confirmed, not when it is scheduled. If it were deducted on scheduling and the transfer failed, the seller would be left with a zero balance and no money.

The seller can also request a withdrawal from their panel. It goes through the same checks: complete profile, hold served and minimum reached. Each seller can have only one payout in progress at a time, and from your panel, one per month. The database decides, not the browser: a double click does not pay twice.

If a payout that had gone out comes back — account rejected, PayPal left unclaimed, the bank returns it weeks later —, it is not deleted: the money coming back is recorded in the wallet, which is how books are kept.

And the seller can download their movements as CSV, with date, concept and amount, for their accounts.

With a rail: the provider pays

With PCC_CARRIL_PAGO=stripe or PCC_CARRIL_PAGO=mangopay, the seller's money is held by the provider, in an account in their name, and the provider pays them. Three things change:

• The seller signs up with the provider from their panel, under Payouts. They get a link to verify their identity; that verification is done by the provider, not you. Until it is finished, the provider pays them nothing.
• When each order is paid, their share is transferred to their wallet at the provider. The money does not sit waiting in your account. If they are not verified yet, their share stays recorded in the ledger, not transferred, and it is transferred as soon as they are verified (and every night, just in case). The same with a transfer that failed. Anything with a refund is not retried automatically: with a partial one the whole share would be transferred, so a person looks at it.
• Pay sends the payout for real. The button in Panel → Pay authors is the same, but now the provider sends it to their bank. If the connection drops halfway, the payout is not marked as failed — it may have gone out —: it is kept alive, and retrying it carries the same reference, which is what prevents paying twice.

With a rail, your ledger becomes the mirror of the provider's balance: it records what the provider confirms.

Stripe

The notice secret is the one for the rail's endpoint, not the one for the gateway you take payments with: in Stripe each endpoint signs with its own. If you only have the rail, STRIPE_WEBHOOK_SECRET also works.

The seller has an Express connected account. Each order is split as one transfer per seller, because an order can contain items from several.

According to the terms the rail itself records, a European platform can only pay to accounts in the European Economic Area, the United Kingdom, the United States, Canada and Switzerland. For everyone else there is Mangopay.

Mangopay

Before signing up a seller, Mangopay is asked whether their country allows sign-ups and payouts. If not, you find out at that moment, not on the day of the first payout. And it pays nobody until the seller completes their verification.

The provider's notice

The provider reports how each payout ended at:

<PCC_BACKEND_URL>/carriles/stripe/avisos
<PCC_BACKEND_URL>/carriles/mangopay/avisos

It is a public address, because the provider calls it. That is why nothing is taken as good without checking it:

• Stripe signs its notices. The signature is checked against the secret, any signature other than v1 is ignored and a notice older than 5 minutes is rejected. One that does not match gets an error back and changes nothing.
• Mangopay does not sign, and notifies by GET, with the id in the address (the route accepts GET and POST). Anyone who knows the address could make one up, so the notice is only used to know which payout to look at: Mangopay is asked about that payout again, and what it answers is what counts.

The daily task: cuadrar-pagos

Every day at 5:00, only if there is a rail, the cuadrar-pagos task distributes what was left undistributed (see above) and does two things nobody else does:

1. It asks about payouts left halfway. Scheduled ones the provider already received that have had no news for more than 2 hours. A notice may never arrive — the network went down, the address was wrong —, and without this the seller's money is left hanging.
2. It compares your ledger with the provider's balance, seller by seller, and writes every one that does not match to the server log.

It does not fix mismatches: it shows them to you. Two sets of books that contradict each other with nobody looking is the expensive failure of this setup, and it is found when someone complains, months later. Watch that log.

What you need

• Email configured (SMTP_*), for the block and failed-payout notices.
• PCC_BACKEND_URL set to the backend's public address, if you use a rail: it is where the notices arrive.
• And, before any of this, talk to your adviser.