Skip to main content

billing-flow

Entities​

To have a detailed description of entities involved in billing flow, check Billing

BillingProcess​

A BillingProcess is a series of steps that, for each country, is responsible for the invoice generation for TW PRO venues. (https://admin.uala.com/backend/billing_processes).

For each country, finance team create the approriate record around the first day of the month and follow its execution until completed.

State machine implementation​

  • pending: Is the initial state of any BillingProcess after its creation
  • invoice_generated: All the invoices for the given time range are created
  • invoice_synched: All the invoices are synched with the provider, different countries have different providers.
  • transfer_generated: All transfer for the given time are generated
  • transfer_disposed: All transfer for the given time are disposed.
  • payment_summaries: all Payment Summaries for the current period are generated
  • payment_notified: all Payment Summaries for the current period are notified
  • invoice_payment_slip_generated: all invoice payment slip are generated
  • transfer_payment_slip_generated: all transfer payment slip are generated
  • completed: All steps completed.
  • failed: Something went wrong during the billing_process.

Not all countries needs all the steps, here's a list off all the countries with all the final steps:

  • INVOICE SYNCHED: countries using Treatwell Ledger system without Marketplace (SWITZERLAND, BELGIUM, IRELAND, UNITED KINGDOM, NETHERLANDS, LITHUANIA, AUSTRIA, GERMANY)

  • TRANSFER DISPOSED: countries using Treatwell Ledger system with Marketplace (GREECE, PORTUGAL, ITALY)

  • INVOICE PAYMENT SLIP GENERATED: FRANCE

  • TRANSFER PAYMENT SLIP GENERATED: SPAIN

The main job of responsible for this steps is Billing::ExecuteBillingProcessStepJob witch is called at every change of state of BillingProcesses::StateMachine.

Troubleshooting​

Misconfiguration​

The process may fail due to misconfiguration of BillingCompany and data need to be updated by finance team. To easily identify those cases, this Metabase card is available. This case can be identified by a dangling BillingProcess's state (statuses ending in -ing) and the relative failed job can be found in Sidekiq failed jobs page. In the majority of cases, this can happen during PaymentSlip generation due to missing IBANs. In that case, the finance team will receive an automatic email listing missing data.

Once finance team fixed the data, the job can be retried.

FattureInCloud server errors​

It can happens that FattureInCloud servers fail to process our requests. This case can be identified by a dangling BillingProcess's state (statuses ending in -ing) and the relative failed job can be found in Sidekiq failed jobs page. This can happens when sending data to FattureInCloud (syncing_invoices, notifying_payment_summaries).

Once finance team fixed the data, the job can be retried.

Invoice external systems​

Invoices are fiscal documents and there are countries that requires a certified fiscal representation of them (XML e-invoice in Italy for example), so we leverage on external systems to handle them. Also, it's convenient to have all financial transactions unified into a single system, and this is also achieved with external systems.

TW Pro billing is, at least, responsible of the management of billing plans and computation of money due to the client or owed from the client.

Treatwell Ledger​

The Ledger system is the standard de-facto for billing activities here in Treatwell. For each supplier, it keeps track of incoming and outcoming transactions. To accomplish the task of synchronizing data from TW Pro and TW Ledger, the uala-main application calls tw-integration application through the synch_supplier_fee endpoint.

In tw-integration application, and asynchronous job will call the invoice-summary API and data will be properly sent to TW Ledger system.

NOTE: when using the TW Ledger system, once the invoice has been sent to it, no further action is possible, since TW Ledger will take care of it (in BillingProcess's flow, countries that use_treatwell_ledger? will stop after finish_invoices_sync).

:::code source="../../uala-main/app/services/payments/invoice_payment/treatwell_ledger_provider.rb" title="uala-main/app/services/payments/invoice_payment/treatwell_ledger_provider.rb" :::

for more information about Treatwell Ledger and Unified Invoicing check doc/team-cash/Unified-Invoicing page

FattureInCloud​

This system was the first introduced and finance team heavily used it to keep track of company financials. All the possible actions of an invoice is synchable through FIC API and the uala-main/app/services/payments/invoice_payment/fattureincloud_provider.rb will take care of it.

The system doesn't allow legal_entities (BillingCompany) duplicates, thus is needed to search for them before adding a new one to avoid conflicts.

NOTE: any change made on FIC system won't be reflected in TW Pro system, the communication is mono-directional.

Elorus​

Invoice provider for Greece, dismissed after switching to TW Ledger.

Dummy provider​

A dummy provider implementation is available for countries that don't need external sync of data. In this way, it's possible to simulate a full BillingProcess flow without sending data anywhere.