Your token

What your token is

Sometimes one counter takes the money for several businesses. A food hall with one till for every stand. A shop that sells a neighbour's bread. A market organizer with a single card reader for the whole day. The customer pays once, by card, on your device — and the money belongs to someone else.

Your token is what makes that work. It is a unit your business issues on Citizen Pay, and it does one job: when you take a card payment on your terminal for another business, that business's place is credited in your token, so the sale shows up on their side and they can be paid out for it. You keep the card payment; they hold your token for it until the payout settles it.

A few ground rules:

• Issuing a token is a paid option. Citizen Pay enables it for your organization; after that, Token appears in the sidebar for owners and admins. A business that only accepts another organization's token needs nothing enabled.
• One token on Citizen Pay per business. Once you have issued it, there is no second one. Your organization may also have tokens it issued on Gnosis; see Tokens on Gnosis.
• Only an owner can issue it. Owners and admins can then manage it — invite businesses, look after the connections, follow their sales and pay them out — from the Token entry in the sidebar.
• It only does something once others accept it. Your token is offered to the businesses you invite; nobody can use it until they have said yes.

If you only use your token for badges

Your token is also what your badges pay with. If your organization has Badges but not the option for other businesses to accept your token, Token still appears in the sidebar for owners and admins, and the page keeps only what badges need:

• issuing your badge token — the same card and fields as under Issuing it;
• changing how it looks — its name, logo and colour, with Edit on the header, as under Changing it later.

That is all you see. The header has no Your fee, and there are no Businesses or Invitations tabs, no sales of connected businesses and no payouts: those only matter when other businesses accept your token. If you want other businesses to accept it as well, ask your Citizen Pay contact.

Tokens on Gnosis

Some organizations issued their token on the Gnosis blockchain rather than on Citizen Pay, usually together with a treasury application such as La Caisse. If yours did, the Token page works for that token too:

• the token appears on the page with the businesses connected to it, on the Businesses tab, and its invitations, on the Invitations tab;
• Sales shows the payments made in your token at connected businesses' places;
• Payouts shows the same payouts your treasury application works with — see Who does the burn.

If your organization issues more than one token, a switcher at the top of the page selects the one you are looking at, and everything below it is for that token.

Such a token already exists, so it is not issued from this page.

Issuing it

Open Token in the sidebar. Without a token yet, the page shows a single card, Issue your token, with a short explanation of what it is for and four fields:

1. Name — what the token is called. This is the name the businesses you invite read in their invitation email and on their Payment methods page, so make it obviously yours: "Halle Sud token" says more than "Token".
2. Symbol — a short code of 2 to 8 capital letters or digits, for example HSUD. It appears next to amounts and on chips, the way € does.
3. Logo (optional) — a PNG, JPEG or SVG image of up to 1 MB; a square one looks best. It is uploaded as soon as you pick it, and previewed next to the button.
4. Colour — Citizen Pay blue (#1A73E8) unless you choose another, with the picker or by typing a hex code. Without a logo, your token is shown as a circle in this colour with the first character of its symbol.

The logo and colour are how people recognise your token: they appear on the Payment methods page of the businesses you invite and on the chips next to amounts in your token. The invitation email shows the logo too when it is a PNG or JPEG — most email clients do not display SVG images, so an SVG logo is left out of the email.

Press the button to issue it. Choose the symbol carefully: it is fixed for good.

Once it exists, the top of the page shows the token's logo, name, symbol, its short identifier (the slug) and Your fee — the fee percentage you keep on what you sell for others, explained under How the money flows. Under that header sit two tabs, Businesses and Invitations.

Changing it later

An owner or admin can change the token's name, logo and colour at any time: press Edit on the header, make the change and save. The new look is what everyone sees from then on, including businesses that have already accepted it. The symbol and the identifier cannot be changed; the edit panel shows them for reference only.

Inviting businesses

Businesses come in by invitation. On the Invitations tab, type the email address of someone at the other business — ideally an owner of it — and send the invitation.

What they receive is an email headed with your token's name and symbol, saying you would like their business to accept it at its places. It has a Review invite button, the date the invitation expires, and the address they must sign in with to accept it. The email is in English. An invitation is valid for 7 days.

The table under the form lists every invitation, newest first: the email address, a status chip, when the email was Sent and when the invitation Expires.

If the invitation was created but its email could not go out, an amber notice says so right after you invite — "The invitation to … was created, but its email could not be sent. Use Resend in the table below." — and the Sent column shows "—" for that row.

Two actions are offered while an invitation is pending:

• Resend emails the same invitation again — useful when it went to spam, or when the Sent column shows "—" because the email could not go out the first time. It does not move the expiry date. Once an invitation has expired, send a new one instead.
• Cancel withdraws it, and the link in the email stops working.

What the invited business sees

The person you invited presses Review invite, signs in with the invited address (or creates an account with it), and lands on the acceptance page. It shows your token's name, symbol and logo. They pick which of their businesses accepts it — if they own exactly one, it is picked for them — and press Accept or Decline. The steps, and what each screen says, are on Payment methods.

When they accept, your token is switched on for their business, all of its places, and any item of theirs that limits which tokens it takes. On their own Payment methods page it is listed among their enabled methods with your business's name, as a token issued by you. From then on:

• their places become available to your terminals (see Selling for other places);
• a place where they switch your token off drops out of what your terminals can sell for;
• they can leave your token at any time from their Payment methods page. They disappear from your Businesses tab and your terminals stop offering their places at once. See Tokens issued by other businesses.

Disconnecting a business

The Businesses tab lists every business that has accepted your token, with the places of theirs that currently take it. Disconnect removes one, after a confirmation.

Disconnecting takes your token off their business, their places and their items, and every terminal of yours that was set to sell for one of their places stops offering it — the change reaches the terminal straight away. Nothing is sent to them: the token simply disappears from their payment methods.

Sales already taken for them stay where they are, on their place, and what you still owe them does not go away: their place stays on your Sales page for as long as it has sales in your token, and you can still pay it out. Tell them before you disconnect. To work together again later, invite them again; your terminals will need their places ticked again too.

Selling for other places

Which places a terminal may sell for is set per terminal: open the terminal's page and find Sell for other places on its Terminal tab. The terminal's own place is always there, ticked, and cannot be unticked; you tick only the places of businesses that accepted your token. From then on, a banner on the terminal shows which place it is Selling for. The operator picks the place once from a grid of tiles, and it stays selected for the next sales until they change it; the card button names it, Card · <place name>, and charges that place directly.

How to set it up, and exactly what the operator sees, are on Terminals.

On the other business's side, a sale you took for them looks like any sale of theirs: it is on their place's Payments tab with the amount and the note your operator typed, and underneath it says via your terminal's name and your business's name, so they know it came from your counter. Their Analytics export names your terminal and your business in the same way; the Reports export has no terminal column.

Those sales are theirs, not yours: they do not appear on the Payments tab of your own place. On the terminal itself, the list of recent orders shows them with a For line naming the place they were sold for.

How the money flows

Follow one card payment of a customer at your counter, sold for a stand that belongs to another business:

1. The customer pays by card on your terminal. The payment goes through your Viva account, as any card payment on your terminals does. Viva takes its usual commission.
2. Their place is credited in your token. The sale is booked on their place, and the place receives the amount in your token minus Viva's commission — the card fee is charged on their sale, the same way it would be had they taken the payment themselves.
3. The money reaches your bank with your normal Viva settlement.
4. You pay them out from your bank. On the Sales page you create a payout for their place, and the euros go from your bank account to theirs — either as a transfer you sign through your connected bank, or as one you make yourself. See Paying out connected businesses.
5. Your cut is the fee percentage. The token's fee percentage, shown as Your fee at the top of the Token page, is kept back from their payout for every sale you took for them, and stays with you. It is set with Citizen Pay — the page has no field for it — so ask support if it needs to change.

A sale you take for your own place does none of this: it is booked on your place in €, exactly like any other card sale on that terminal.

Refunds

A card sale can be refunded from the terminal that took it — open the sale in the terminal's list of recent orders, press Refund and confirm — or from the dashboard. The money goes back to the customer's card from your Viva account, the same account that received it. For a sale you made for another business, that business's place sees the refund on its order, and the tokens its place was credited for the sale are taken back.

Sales of connected businesses

The sales you take for other businesses are theirs, but paying them out is up to you. To see what you owe whom, open the Sales of connected businesses card on the Token page; it leads to the Sales page. Like the rest of the token pages, it is for owners and admins of your business. For a token your organization issued on Gnosis, the page shows the payments made in your token at connected businesses' places.

The table has one row per place: every place of a connected business that takes your token, plus any place that still has sales in your token after its business was disconnected — it is marked Disconnected, because money owed does not disappear with the connection. A place whose business has no IBAN on file is marked No IBAN. The places owed the most come first.

The dates only change Sales in period. Unpaid always counts every sale not yet paid out. Both amounts are net: what the customers paid, minus the processor fees (Viva's commission) and minus your fee (see How the money flows). Refunds bring them down.

Unpaid and Ledger balance normally tell the same story. When they do not, the sales are what counts: a payout pays for the sales, whatever the balance says. If a balance cannot be read at the moment, it is simply not shown; the rest of the page still works.

Press a place to see its orders in your token, newest first, with the Date, the Order, its Status, the Total, the Processor fees, Your fee, the Net and the Payout it belongs to, if any. Switch between Period and Unpaid to see the orders of the chosen dates or every order not yet paid out, and page through the rest.

When your bank is not connected, or bank payments are not enabled, a notice at the top of the page says so, with an Open Banking button. You can still pay out by a transfer from your own bank; it only decides how you will pay, as described below.

Paying out connected businesses

You pay out the businesses you sell for yourself, from your dashboard. Every payout goes through the same steps — create it, Burn the place's tokens, Pay the business, Complete — and the payout's own page shows them in its Steps panel, with where it stands and what comes next. All payouts are listed on the Payouts page, reached from the Payouts card on the Token page, under two tabs: Pending and Completed.

For a token on Gnosis, this is the same list your treasury application works with, whichever tool created the payout: a payout you create in the dashboard appears in your treasury application too, and the other way round.

Before you start:

• Only owners and admins of your business can create, burn, pay or delete payouts.
• The other business needs an IBAN on file — the one shown on its Organization page. You can create a payout without it, but the burn and the payment wait until the IBAN is there. If it is missing, ask them to add it: an owner of that business can enter it themselves on their own Organization page.
• Paying from your bank through the dashboard needs payment initiation — your bank connected under Banking, with payment initiation active. Paying by a transfer you make yourself and marking the payout as paid by hand needs no bank connection.

Create the payout

On the Sales page, press Create payout on the place's row. A confirmation shows how many orders the payout takes in and their net amount: every unpaid order of the place up to now. Press Create payout again to confirm. From then on those orders belong to this payout and no longer count as unpaid. If there is nothing to pay — no unpaid orders, or refunds that cancel them out — the row's Create payout button is greyed out.

The payout shows its Orders in this payout and its totals: Sales (what the customers paid), Processor fees (Viva's commission on the card payments), Your fee (the token's fee percentage, which stays with you) and To pay — the amount the business receives.

Burn the place's tokens

For those sales, the place holds your token. Burning destroys those tokens, taking the amount out of its balance, so the same sales can never be paid twice. The amount burned is what the place was credited: the sales minus the processor fees. Your fee is burned with it — the euros for it are already in your bank, where they stay.

Who does the burn

Who burns depends on where your token was issued:

• A token on Citizen Pay. Citizen Pay does the burn when you press Burn and confirm.
• A token on Gnosis. Your treasury application does the burn, because it holds the token's burn key. In the dashboard, the payout shows that the burn is pending or in progress; once the burn is recorded, you pay the business — through your connected bank, or by transfer and Mark as paid — exactly as for any other token.

For a token on Citizen Pay, Burn only becomes available once the business has an IBAN on file. If the place holds less than the payout owes, what it holds is burned and a note right after the burn says how much was missing (the note is not kept after a reload); the amount to pay does not change, because the sales decide what is owed, not the balance. While the burn is in progress, the payout shows a reference. If it is still in progress after a few minutes, do not try again: contact Citizen Pay and quote that reference.

Pay the business

Once the tokens are burned, pay the To pay amount in one of two ways:

• Pay from your bank. If your bank is connected under Banking with payments enabled, press Create bank payment: the transfer to the business's IBAN is prepared in your bank. Then press Open signing page, or scan the QR code with your phone, and sign the payment in your bank. The payout page updates by itself once the payment is signed and accepted, and the payout is complete. If the link no longer works, New signing link makes a fresh one.
• Pay by transfer. The payout shows the Beneficiary, the IBAN, the Amount and the Reference (cp- followed by the payout's ID). Send the transfer from your bank with exactly that reference, then press Mark as paid and confirm with Yes, it is paid. This cannot be undone.

Complete

When the payout is complete, the business gets the usual payout confirmation email with its receipt, at the address it chose for payout emails. The payout appears on its own Payouts page, and the receipt names your business as the one that paid it. On your side, the payout moves to the Completed tab.

Related pages