by
Automatic invoicing for EuPago payments.
Every payment received through EuPago becomes an invoice in InvoiceXpress, Moloni, Vendus or TOConline, and every refund a credit note. With payment requests, the invoice is issued in your customer's name, with their tax number. This guide shows, step by step, how to connect your EuPago channel to Rioko.
→
Access to the EuPago backoffice and to your invoicing software: InvoiceXpress, Moloni, Vendus or TOConline.
About 10 minutes, from the start to the first document.
€7.50 + VAT a month or €75 + VAT a year, per integration.
How it works
EuPago tells Rioko about each payment the moment it is confirmed, through your channel's Webhooks 2.0. Rioko checks that the notice came from that channel and creates the document in your invoicing software, with the series, VAT and finalization you set.
Payment
Your customer pays by Multibanco, MB WAY, card or another method of your EuPago channel.
by
Rioko
Checks the notice's signature and applies your rules: series, VAT, exemption and finalization.
One invoice per payment. A refund becomes a credit note.
EuPago does not send the payer's name, email or tax number, so a payment collected directly in EuPago is invoiced to "Consumidor final" (final consumer). To invoice in the customer's name, with their tax number, create the payment in Rioko, under Payment requests (step 07).
Do not connect this integration if EuPago collects invoices you already issue in another program (for example, Multibanco references generated by your invoicing software), or if another system already invoices the channel's payments: the same payment would get two invoices.
The images in this guide come from an EuPago demo account and a Rioko test account. In yours you will see your own data: channels, company, series and your connection's address. EuPago's screens are in Portuguese, so where a step names an EuPago button, its English meaning follows in brackets. Click an image to see it full size.
- 1Open Integrations.
- 2Under Payment / E-commerce platform, choose EuPago. Under Invoicing platform, choose InvoiceXpress, Moloni, Vendus or TOConline.
- 3Click Configure now.
- 4In the EuPago step, under 1. Address for EuPago, click Copy. The address is unique to your account: you will paste it into EuPago in step 02.
Turn on Webhooks 2.0 in EuPago
Webhooks 2.0 are set up on each channel, in the EuPago backoffice (clientes.eupago.pt).
- 1Open Canais → Listagem de Canais (Channels → Channel listing) and click Editar (Edit) on the channel that receives the payments.
- 2Scroll down to Webhooks 2.0 and tick the box.
- 3Under Software Integrado (Integrated software), choose Integração Personalizada (Custom integration).
- 4Under Webhook Endpoint, paste the address you copied from Rioko.
- 5Under Tipo de Webhook (Webhook type), choose Pagamento (Payment) and Reembolso (Refund). Leave Encriptar Webhook (Encrypt webhook) on Sim (Yes).
- 6Click Gerar Chave Criptográfica (Generate encryption key) and confirm. Show the key with the eye icon and copy it.
- 7Click Guardar (Save) and confirm with Editar (Edit).
Treat the encryption key like a password: do not share it by email, chat or screenshots.
If you generate a new key in EuPago, paste it into Rioko straight away as well: with the old key, Rioko refuses the notices and those payments are left uninvoiced.
Paste the encryption key into Rioko
Back in Rioko, on the EuPago step.
- 1Paste the key into 2. Encryption key (Chave Criptográfica).
- 2If you will create payment requests (step 07), paste the same channel's Chave API (API key) into 3. Channel API key (optional). It is under Canais → Listagem de Canais (Channels → Channel listing) in EuPago.
- 3Under Environment, choose Production. Test (sandbox) is only for EuPago sandbox accounts (sandbox.eupago.pt), and there documents stay as drafts in InvoiceXpress, Moloni and TOConline, and in test mode in Vendus.
- 4Click Save and continue.
Connect your invoicing software
Step 2 depends on the software you chose. Rioko's Help shows where to find each value.
- InvoiceXpress
- The account name and the API key, under Configurações → API.
- Moloni
- Turn on the API under Configurações, Configuração da API e Plugins, paste Rioko's callback URL into URI de Resposta (Callback), fill in the Developer ID and the Client Secret and click Authorise Moloni.
- Vendus
- The API key, in the menu under your name, API.
- TOConline
- Request the API details under Empresa > Configurações > Dados API, paste Rioko's redirect address on the page TOConline sends you, copy the four values into step 2 and click Authorise TOConline. The TOConline guide shows every step.
Invoice settings
Step 3. EuPago does not state the sale's VAT: Rioko uses the rate you set here.
- Where to issue
- The company and the series in Moloni, the series in InvoiceXpress, the register in Vendus; in TOConline, the company's default series. If you also invoice from another source, use a series of its own: it keeps the books readable and avoids date-order problems.
- Document type
- Invoice-receipt by default, because EuPago only reports payments already received. If you prefer a separate invoice and receipt, choose Invoice + automatic receipt (in Vendus, the Automatic receipt switch): the invoice is issued on payment and the receipt right after; if the invoice stays a draft, the receipt follows once you finalize it.
- VAT rate
- The rate each payment is invoiced at. Empty = 23%. With 0%, also choose the exemption reason: without it, payments are not invoiced.
- VAT included
- On, the amount paid already includes VAT.
- Auto-finalize
- In InvoiceXpress, Moloni and TOConline. On, the document is issued straight away; off, it stays as a draft for you to finalize by hand.
In InvoiceXpress, Moloni and TOConline, leave "Auto-finalize" off for the first payments, to confirm everything is right, and turn it on afterwards.
Activate and test
Check the first document before letting invoicing run on its own.
- 1On the same page, activate the integration's subscription (monthly or yearly).
- 2In step 4, click Mark as active.
- 3Make a small payment on the EuPago channel.
- 4The payment shows under Latest documents, with the EuPago transaction number and the document's status. Open the document in your software and check totals, VAT and series.
If you left "Auto-finalize" off, turn it on in step 3. From then on, every payment is invoiced automatically.
Rioko invoices them when EuPago notifies it. If a notice does not arrive, the payment is left uninvoiced, because Rioko cannot yet read EuPago's list of payments. Now and then, compare the transactions in the EuPago backoffice with Latest documents. Payment requests (step 07) do not carry this risk: Rioko checks them with EuPago every night.
Invoices with a tax number: payment requests
To charge a customer who needs an invoice in their own name, create the payment in Rioko. Rioko creates it in EuPago and, when the customer pays, the invoice is issued in your software with the customer's name and tax number. You need the channel's API key, saved in the EuPago step (step 03).
- 1Open Payment requests and click New request.
- 2Under 1. Customer, search for the customer by name, tax number or email, among the customers in your invoicing software, or click + New customer (in TOConline there is no search: click + New customer and enter the customer's details). With no customer, the invoice goes to "Consumidor final".
- 3Under 2. What you are charging for, write each line: description, quantity, price and VAT rate. Choose Incl. VAT or Excl. VAT to match how you write the prices. Excl. VAT, the invoice carries that price and the customer pays the total with VAT, shown on the Create request button.
- 4Under 3. How the customer pays, choose Multibanco (a reference, between €1 and €99,999, valid for the days you choose), MB WAY (the customer has 5 minutes to accept it in the app: meant for when they are present) or Payment link (an EuPago page with the methods active on your channel).
- 5Click Create request and send the customer the reference or the link (Copy details).
- 6When the customer pays, the request turns Paid and invoiced, with the invoice in your software.
In InvoiceXpress and Moloni, a Multibanco request's invoice is issued when you create the request, and VAT is due from that date, even before payment. The receipt follows when the customer pays.
If the reference expires unpaid, Rioko deletes the invoice while it is a draft. If it is already finalized, the request asks whether there was a delivery: Annul the invoice (no delivery) annuls it in your software, with no credit note; Keep it (there was a delivery) leaves it as the customer's debt.
Every night Rioko checks the unpaid Multibanco and MB WAY references with EuPago: if a notice is lost, the invoice is issued anyway.
Refunds are made in the EuPago backoffice. When EuPago reports one, Rioko issues the credit note on the request's invoice, if it is already finalized.
Frequently asked questions
Which notices does EuPago send Rioko?
The channel's Webhooks 2.0 send a Pagamento (payment) notice when a payment is confirmed and a Reembolso (refund) notice when a refund is made. Rioko answers the first with an invoice and the second with a credit note. The other notice types produce no document.
Do I need the channel's API key or EuPago API credentials?
No. Rioko only needs the Webhooks 2.0 encryption key: the amount, date, payment method and reference arrive in the notice itself, encrypted and signed.
What happens if the encryption key is wrong?
Rioko refuses the notice and records the incident: no document is issued. Paste the key that is on the EuPago channel into Rioko. Payments refused in the meantime may be left uninvoiced: talk to us before invoicing them by hand, so they do not end up with two invoices.
Can I run EuPago and Shopify in parallel, into the same invoicing software?
Yes. Each source is an independent connection with its own settings, and both can issue into the same account. Use a series of its own for each source: it keeps the books readable and avoids date-order problems.
Why are EuPago invoices issued to "Consumidor final"?
Because EuPago does not send the payer's name, email or tax number. For an invoice in the customer's name, with their tax number, create the payment in Rioko, under "Payment requests": the invoice carries the customer's details when they pay.
Need help?
If you would rather set it up with us, book a call. We configure everything with you, live.
Book a call ↗ calendly.com/pedro-kapta/rioko-support
by