Billecta Docs

Differences between Production and Testing environments

• We use weaker machines and databases compared to the production environment. Performance is not the same. If you want to do performance test in production like environment, please contact us
• We release to test without any warning. The environment can sometimes be unresponsive for a few seconds. Releases are made on a average every second day
• We might release not fully tested code. We do try to test it as much as possible before releasing it to test. If you encounter unexplained error that you are sure are not caused by any change on your side, please contact us
• No charging is made for using test. It is completely free
• No mails is sent to the postal offices at all
• E-mails and SMS are only sent to whitelisted receivers. Please contact us to add emails/phone numbers to the whitelist
• The test environment is restored from production and cleaned from sensitive data from time to time.

TLS/SSL

All connections to the API must be in the HTTPS protocol with TLS 1.2 or above.

Domains

All users are part of a 'domain'. Within a domain you can have multiple users and most important multiple companies (called creditors in the API). A company is the legal entity that for instance sends the invoices and receive payments from their customers (called debtors in the API). Users with the same domain can have read/write/attest/etc rights on each creditor.

Companies/Creditors

In the Billecta services, a company is referred to as a 'creditor'. A company/creditor is the legal entity (not private person) that you as an API integrator perform operations on. Almost all requests of the API require that you specify which creditor the request is made for. That is because one user can handle multiple creditors, and data can't be shared between creditors. Each creditor has their own set of debtors, products, cost centers etc that may not be shared between creditors. For instance, creating a product, we need to know which of the creditors in the domain this should be added to. Another example is when making BankID authentications, since the BankID certificate is a contract between the Bank and the company/creditor.

Customers/Debtors

The customers of a creditor are referred to as 'debtors'. Debtors are the entities that receive the invoices and the one paying to the creditor. A debtor can be an individual or a company. In the API the property OrgNo is used regardless wether it is a personal number (social security number) or an organizational number.

Invoices

Billecta has four different invoice types. This table lists the differences between the types.

A reconciliation invoice is a subset of an invoice. It requires much less data to be sent to the API and is a faster and slimmer invoice. If a invoice PDF is attached to the invoice distribution (through for instance email, mail, e-invoice, etc) is possible. If no PDF is attached, only reconciliation on incoming payment are made. The loss when using reconciliation invoice is that no bookkeeping can be made since the data sent to the API is not complete. The advantage however is a faster and easier integration and features like swish, credit card payments and autogiro withdrawals are supported just like an ordinary invoice.

A verification invoice is a pure bookkeeping event. You create the verification to write to the bookkeeping and have a 'receipt' on the invoice for tracking.

Invoice stages

• Created - Created as draft. The only stage an invoice is removeable
• Attested - Attested/Approved and bookkept. Invoice is from now on not removeable.
• InvoiceSent - Invoice has been sent using the preferred delivery method.
• ReminderInvoiceSent - Invoice has due and a reminder invoice has been sent.
• SentToDebtCollection - Invoice has due and has been sent to debt collection.
• SalesRequested - The invoice is sent to financier for sales (no response received yet)
• SalesRequestedDenied - The invoice sale request was denied
• Sold - The invoice sale request was approved and invoice is sold
• SalesRequestedCancelled - The invoice sale request was approved and then the purchase was cancelled by financier
• Completed - Invoice has been paid/credited and closed. No more actions can be taken on invoice.

Verification invoice stages

• Created - Created as draft. The only stage an invoice is removeable.
• Attested - Attested/Approved and bookkept. Invoice is from now on not removeable.
• Completed - Invoice has been paid/credited and closed. No more actions can be taken on invoice.

Reconciliation invoice stages

• InvoiceSent - Invoice has been created and marked as sent.
• SentToDebtCollection - Invoice has due and has been sent to debt collection.
• Completed - Invoice has been paid/credited and closed. No more actions can be taken on invoice.

Self invoices

Self invoices are supplier invoices that you create for your supplier to yourself. That is, you are invoicing yourself on behalf of your supplier. Self invoices are widely used when invoice for your customer on their behalf (where payment is made to your account) to their customer. To automatize the payment flow you need to further promote the payment from your account to your customer. In a sense a supplier invoice to you that you create yourself.

Self invoice stages

• Created - Created as draft. The only stage a self invoice is removeable.
• Attested - Attested/Approved and bookkept. Invoice is from now on not removeable.
• InvoiceSent - Invoice has been sent using the preferred delivery method.
• PaymentSent - Payment has been sent. Successful payment status from payment system (Bank) has not yet been received.
• PaymentCancelled - Payment was cancelled either by user or bank.
• Completed - Payment was successfully made. No more actions can be taken on self invoice.
• Cancelled - Self invoice has been cancelled and fully credited. No more actions can be taken on self invoice.

Amounts

Amounts in the Billecta API are handled by the Amount/AmountView models. The class contains a Value and a CurrencyCode property. The Value is specified in cents within that currency and is of data type long. For instance, a value of 500.34 SEK should be specified as 50034 in the Value property since SEK currency has 2 cent digits. The first two numbers (from the right are the decimals/cents. The number of decimals can differ from currency to currency. A call to the Currency API will return a list of all currencies and for each currency information on how many numbers in the value that should be decimals.

Files

Getting PDFs, ZIPs or other files from Billecta API always returns a FileView object. The FileView object is a reference to a file with meta data. For performance reasons, the file contents are never returned in the property FileView.Data. To download the actual contents a separate call must be made. Please view GET FILE CONTENT/STREAM in the File API for more information.

Basic invoicing

This section will describe the most basic operation of sending an invoice using the Billecta API, and it's associated bare necessities.

In order to send and invoice, you need to create products which will go onto the records of the invoice. You also need to create debtors, meaning the recipients of invoices.

1. Create debtor

   Call POST /v1/debtors/debtor with a DebtorView body.

   Take note of the id in the CreatedView response.

   Debtors are the recipients of invoices, meaning they are the end customers. There is also a plural POST to create several at a time, and a PUT which would update a preexisting entry. Alternatively, you could create the debtors in the portal if you are always invoicing the same small set of customers.

2. Create product

   Call POST /v1/products/product with a ProductView body.

   Take note of the id in the CreatedView response.

   Product go onto the invoice records. If you are selling furniture, a sofa may be a product. As with debtors, there's also a plural POST to create several at a time, and a PUT (create/update). Alternatively, you could also create products in the portal using your web browser - in case you're going to keep re-using the same small set of already defined products.

3. Create invoice

   Call POST /v1/invoice/action with an InvoiceActionEntryView body.

   Take note of the id in the CreatedView response.

4. Attest the invoice

   Call PUT /v1/invoice/attest/{id} with the id returned in the previous step.

   This will deliver the invoice, provided a means of distibution has been set.

That's it — as the most basic invoicing use case. Certainly creating and attesting an invoice could also be done in the portal, but if you're an API user you should get familiar with these fundamenal steps through the API. If you are on a Microsoft .NET platform, we recommend you to try our SDK, which encapsulates the actual requests described here into methods of our .NET NuGet library.

Get bank accounts

The Billecta API has the feature to retrieve bank account numbers for private persons (no support for companies yet and not available in the Billecta portal). Supported banks are defined in the API reference. By specifying a Swedish person number (12 digits) and a bank code the Billecta system may extract the IBAN, clearing code and account numbers from the person's bank. This is mostly useful in the autogiro approval flow but also for other cases.

The flow for getting bank accounts

This means that you first initiate a 'retrieval job' that will get the process going in the background. Then we wait for the users (can take some time). Meanwhile you continuously check the status if the customer has authenticated themselves and if the 'retrieval job' is completed. Once the 'retrieval job' you will get all data collected.

Note that the information is only stored at most 24 hours before the collected data is removed in accordance to GDPR.

BankID authentication/sign

Authentication and sign with mobile BankID are supported as a standalone feature in Billecta API. Detailed information about each call can be found at API reference. By specifying a Swedish person number (12 digits) you can trigger an authentication or sign in your users mobile phones. This can be used for various purposes in your application.

Prerequisites to use the mobile BankID features are

• A creditor exists in Billecta Portal
• A mobile BankID certificate has been issued by your bank and uploaded in the Billecta Portal (see instructions)

A mobile BankID certificate must be issued by your bank. Please contact your bank if you don't have one already.

Once you have the mobile BankID certificate, convert it to .pfx certificate with a password (required for security reason) and upload it in Billecta. Sign in to Billecta Portal, open settings and press on Addons. Press on Add Addon and select Mobile BankID. Upload your certificate with your password and press save.

The flow for mobile authentication

The sign process is similiar, but to a different endpoint.

This means that you first initiate a 'authenticate job' that will get the process going in the background. Then we wait for the users (can take some time). Meanwhile you continuously check the status if the customer has authenticated themselves and if the 'authenticate job' is completed. Once the 'authenticate job' you will get all data collected (IP-number, etc).

Note that the information is only stored at most 24 hours before the collected data is removed in accordance to GDPR.

Kivra

Kivra Setup

To get started, go to Addons under Settings in the app and enable the Kivra addon. Once Kivra has been enabled, the only remaining task is to update the delivery method for your debtor or select Kivra as the delivery method when creating an invoice through our API. After completing these steps, you're good to go.

Please note that, to send content through Kivra, the following requirements must be fulfilled:

• The debtor must have an active account with Kivra.
• The debtor must have a Swedish SSN.
• The debtor must not have opted out of receiving content from your company.

To check which of your debtors can receive content through Kivra, you can use our endpoint: Check if debtor has enabled Kivra.

Kivra in Test

In our test environment, you can test your Kivra connection. The setup is identical to production. However, to add a user to Kivra in test, you can do any of the following:

• If you have access to Test BankId, follow these steps: Test Kivra's app with BankID.
• Send an email to avsandare.support@kivra.com with the following information:
  • Company name
  • Company registration number
• Contact us, and we will provide you with an SSN that is active in Kivra's Sandbox environment.

Payments with Swish

To get started with allowing payments with Swish within your application the following configuration must be made and flow implemented. By integrating Swish in Billecta API invoices will be automatically processed as paid and bookkept once payment is completed. Swish requires that a Swish certificated is issued by Swish (https://www.getswish.se/). Instructions on how to retrieve a Swish certificate can be read at https://developer.getswish.se/. Please note that you are applying for 'Swish for Merchants'. Also contact your Bank to activate required bank services and more information on how to get started.

Prerequisites to use the Swish features are

• A creditor exists in Billecta Portal
• A Swish certificate has been issued and uploaded in the Billecta Portal (see instructions)

The flow for Swish payments

This means that you first initiate a 'payment job' that will get the process going in the background. Then we wait for the user to approve the payment in their app (can take some time). Meanwhile you continuously check the status if the payment and if the 'payment job' is completed. Once the 'payment job' is completed then show the user the result.

Payments with Credit Cards

This documentation explains two scenarios for credit card payments using the Billecta API: Scenario 1, where the card is saved for future use, and Scenario 2, where the card is used for a one-time payment without saving.

Prerequisites to use the credit card payment features are:

• A debtor exists in the Billecta system with an associated public ID
• The credit card addon has been activated on the creditor in the Billecta portal

Scenario 1: Payments with Saved Credit Cards

This flow involves saving a credit card securely for future payments. The process includes adding the card, confirming the action, and then initiating a payment against the saved card.

Scenario 2: Payments Without Saving Credit Cards

This flow is designed for one-time payments without saving the credit card.

E-invoice intermediators

The intermediator is the wan carrier that your customers use to receive e-invoices. Intermediator is used for B2B.

These are the intermediators that exists in the system

E-invoice banks

The bank type is the receiving bank for e-invoices. Bank type is used for B2C and B2B.

These are the banks that exists in the system

Donor organizations with Autogiro

This is an implementation guide for donor a organization (sv: givarorganisation) basic setup with Autogiro.

In order to send and invoice, you need to create products which will go onto the records of the invoice. You also need to create debtors, meaning the recipients of invoices.

1. Create a product

   One single product needs to be created in Billecta, to be used further on in all billing. Manually create the product in the portal. It is also possible to create products using the API if needed.

2. Collect donor information

   Use a web form or equivalent to get the donor’s personal number, period (monthly, quarterly, yearly) and the recurring amount.

3. Collect an Autogiro approval

   If there is no preexisting Autogiro approval for the donor, present the donor with information that they are asked to confirm a bank account for Autogiro withdrawals from your organization. Please see our guide for bank account lookups.

   Documentation: Bank accounts

   As this involves a BankId signing, this is regarded as a proper approval, provided you are giving clear information to the donor. Save the bank account and use it later when creating a contract invoice.

4. Create a debtor

   Create a debtor. The debtor represents the donor.

   Endpoint: POST /v1/debtors/debtor

   Documentation: Create a debtor

   Intro to lingo and concepts: Concepts

   When creating a debtor, the DebtorView model is populated with Autogiro approval information along with all the other information on the person.

5. Create a contract invoice

   A contract invoice is a container for recurring billing. In this API call, set AutogiroWithdrawalEnabled in the ContractInvoiceActionView, reference the debtor by DebtorPublicId, among other things.

   Endpoint: POST /v1/contractinvoice/action

   Documentation: Create a contract invoice