Get started with the API

Our API

The Billecta API was created to enable partners to integrate their systems directly into Billecta.

To integrate with Billecta you need to start with a test account. A test account is free. Within the test environment you can perform all operations without the concern of your customers getting any test invoice. Please note that the credentials for the test environment logon will not work in the production environment and vice versa.

If you have any questions regarding our API or the integration itself you are welcome to contact us by either sending an email or calling our support. Logs of all requests and possible errors are stored and we're happy to assist with reviewing and troubleshooting.

Once the integration is built and the testing is done you are ready to move to the production environment. Contact Billecta support for planning and creating an account in the production environment.

Create test account

Environments

The following environments are available for integrations.

Environment API Portal
Production https://api.billecta.com* https://app.billecta.com
Testing https://apitest.billecta.com https://apptest.billecta.com

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

Restore of test database

The test environment is never restored and data from production will never be restored to test

XSD

You can automatically create model in your applications from and XSD. You will always find an updated XSD with all our models here. For .NET applications we have an SDK for faster implementation.

Concepts

There is some concept in the API that are good to know before starting to identify how to map models in your application with models in Billecta API.

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 received 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

A company that uses Billecta services also called creditor in the API. A company/creditor is the legal company (not private person) that you as a 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 can't 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. Same is also for instance for making BankID authentications, since the BankID certificate is a contract between the Bank and the company/creditor.

Customers/Debtors

A debtor is a creditors customer. Debtors are the entities that receive the invoices are the one paying to the creditor. A debtor can be an individual or a company. In the API the same property OrgNo is used regardless if it is person number/social security number or an organizational number.

Invoices

Billecta has 4 different invoice types. The following map show what the difference is between each type

Type API ActionTypes (See ActionTypeView) Features
Invoice InvoiceAction, DebentureAction, CreditInvoiceAction
  • Distribution (all methods)
  • Reconciliation (bankgiro, autogiro, swish, credit card)
  • Bookkeeping
  • Creditation
  • Billecta invoice template
  • Custom invoice template
Verification invoice VerificationInvoiceAction
  • Bookkeeping
  • Billecta invoice template
Reconciliation invoice ReconciliationInvoiceAction
  • Distribution (all methods)
  • Reconciliation (bankgiro, autogiro, swish, credit card)
  • Custom invoice template

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

An invoice can be in on one of the following stages (ActionStageType)
  • 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
  • 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

An invoice can be in on one of the following stages (ActionStageType)
  • 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

An invoice can be in on one of the following stages (ActionStageType)
  • 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 you 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 you account) to their customer. To automatize the payment flow you need to further promote the payment from your account to you customer. In a sense a supplier invoice to you that you create yourself.

Self invoice stages

A self invoice can be in on one of the following stages (ActionStageType)
  • 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 Billecta API are handled by the Amount/AmountView class. The class contains a Value and a CurrencyCode property. The Value is specified in cents within that currency and has 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.



Ignore ValueForView

ValueForView in the Amount/AmountView structure shall be omitted when calling the API. It is a read only value.

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. The actual file content is never returned in the property FileView.Data to increase performance. To download the actual content a separate call must be made. Please view GET FILE CONTENT/STREAM in the File API for more information.

Basics

Requests/responses

The Billecta API supports both XML and JSON data formation for both request and response calls.

  • By sending application/xml in the Accept header the Billecta API will return XML formatted text.
  • By sending application/xml in the Content-Type header the Billecta API interpret request data as XML.

Same applies for JSON. Sending application/json will interpret requests as JSON and write responses in JSON.

The API responses with the following HTTP codes

  • 200 - Everything has passed OK.
  • 400 - Something when wrong. Please refer to the error message in the Header or Response content stream
  • 401 - You are unauthorized to the requested data or the API. Verify that you have specified the correct CreditorPublicId, DebtorPublicId, etc, or contact support@billecta.com if everything looks fine in the data.
  • 500 - Some other internal error. Please contact support@billecta.com.


Default value

The default value is always XML if no header is specified

Transactional calls

Internet connections are not always stable. Occasions might occur that a successful HTTP 200 response from Billecta API to your system might be interrupted somewhere in the line between Billecta API and your system. In that case your application will assume that the call was never processed and redo the request. In those scenarios duplicate data will be inserted into Billecta API. To handle this, we have a method of handling unique calls.

To ensure unique API requests without duplicate calls, requests to Billecta API can include a request header named 'UniqueApiCallId'. The header value should be of type string and contain between one and fifty characters. The UniqueApiCallId value will be kept in the Billecta for three months before new calls can be made with old UniqueApiCallId values. Requests made to Billecta API with UniqueApiCallId containing duplicate or invalid value will not be processed and a response with status code 403 (Forbidden) including a status description will be returned.

The UniqueApiCallId can be hash or similar that is calculated in your application and passed in request to Billecta API.

UniqueApiCallId is optional

Note that the UniqueApiCallId is optional. It can also be used in only a subset of calls. For instance payment reqistrations that you might want higher transactional security on

Errors

All data passed to Billecta API is validated and upon errors the following codes will be returned

  • 400 - Data is wrong
  • 401 - You are unauthorized to the requested data or the API. Verify that you have specified the correct CreditorPublicId, DebtorPublicId, etc, or contact support@billecta.com if everything looks fine in the data.
  • 500 - Some other internal error. Verify that Json/XML is parsable and that Enums are correctly spelled. Please contact support@billecta.com in other cases.

401

When requesting data without specifying the correct id:s the API will regardless of if the referenced data exists or not respond with access denied. For instance, when creating a debtor and no creditor is specified (it will be interpreted as the empty guid in that case) the api will respond access denied even though the id reference was empty.

400

Data sent to Billecta api is always validated against rules and regulations for that data that is saved. For instance, when saving a debtor and setting EInvoiceBank to a non-empty value the organization/person number must be specified. A validation is made in that case and if no organization/person number is specified the api will respond with a 400. To view the error message, you can either see the error message in the header "ErrorMessage" or by reading the content stream in the response (either Json or XML depending on the "Accept" header value. The error message in the header is encoded in ISO-8859-1 while the content stream is encoded in UTF-8.


Localized errors

Note that errors in the test environment can be localized to English instead of standard language Swedish. To change to English, sign in to the portal in test environment and change the language on the api user.

Authentication

All communication between your system and Billecta is secured and encrypted with SSL. Authentication towards Billecta API can be done i two ways:

  • Basic Authentication with a username and password
  • SecureToken - equal to so called API-key
The methods are described below

Basic Authentication

In order to authenticate a call with Basic Authentication you use the Authorization header. The header should be created accordingly:

  1. Username and password is combined into a string "username:password"
  2. The string should be coded in Base64
  3. The authentication method Basic a space should be preceding the coded string

For example, if the user has "Alladin" as a username and "Sesame, open" as a password, the header should have the following structure:

Authorization: Basic QWxsYWRpbjpTZXNhbSwgw7ZwcG5hIGRpZw==

You can use Basic authentication in all calls to Billecta API.

An example using CURL

curl -X "POST" https://api.billecta.com/v1/authentication/apiauthenticate -H "Content-Length:0" -H "Authorization: Basic QWxsYWRpbjpTZXNhbSwgw7ZwcG5hIGRpZw==" -H "Accept: application/json"

SecureToken authentication

An alternative way where you don't need to use your username and password, is to generate a SecureToken and use it in communication to the Billecta API. To create a SecureToken you need to logon a first time using your username and password, and create a SecureToken. A SecureToken is valid until a new one is generated. When a new SecureToken is created, the old one is revoked and can not be used when authenticating towards the Billecta API. To generate a new SecureToken you make a Basic authentication request with username and password to:

/v1/authentication/apiauthenticate

You find more information about this call in the API reference, see the Authentication section

To authenticate with SecureToken you use the Authorization header. The header should be created accordingly:

  1. Encode the SecureToken in Base64
  2. The authentication method, SecureToken and a space is preceded by the encoded SecureToken

For example if the request to generate a SecureToken returned: 5Uis54EmQ/9jJtGhQoS8K9xHRsMXQhZg== the requests to the Billecta API should contain the following header

Authorization: SecureToken NVVpczU0RW1RLzlqSnRHaFFvUzhLOXhIUnNNWFFoWmc9PQ==

An example using CURL

curl -X "POST" https://api.billecta.com/v1/authentication/apiauthenticate -H "Content-Length:0" -H "Authorization: SecureToken NVVpczU0RW1RLzlqSnRHaFFvUzhLOXhIUnNNWFFoWmc9PQ==" -H "Accept: application/json"

Creating a new SecureToken

Note that if the SecureToken is changed, the user will receive an email regarding the updated SecureToken as a security measurement.

SSL certificates

API features like BankID and Swish require a real certificate in production environment before they are available for usage. Please contact you bank to request such certificates. Once the certificates are received, password encrypt them to pfx format and upload them to Billecta in the Portal. We require encrypted certificates to ensure higher certificate and customer security.

The test environment requires certificates as well. However, those certificates are not used and are merely there for simulating production like requirements. Test certificate can be download from this link unless you want to generate one yourself. The password is '12345'.

Webhooks

Webhooks can be used for subscribing on a range of events in the Billecta system. When an event is triggered in the Billecta system a POST request to your predefined URL is made. POST data is located in the request content stream. Creating event webhooks is made in the Billecta Portal and requires that you are an administrator when setting up. It is located under settings, then click on the integration tab. Note that the event webhook settings are applied on all your creditors. If the post request from Billecta fails, Billecta will retry 4 times with the interval of:

  • 5 minutes for the first retry
  • 60 minutes for second
  • 3 hours for third
  • 24 hours for the last retry

If the request still fails after 5 tries, an email is sent to the administrator users with the post data included as a json-file.

Data posted in the Web hook request

The property 'Data' will contain different types of data depending on the event type. Here is an example.

{
    "EventDate":"2017-01-23T11:33:43.332895",
    "CreditorPublicId":"ff18cb9d-f9ae-4128-xxxx-xxxxxxxxxxxx",
    "Event":"InvoicePaymentReceived",
    "Data":
    {
        "Amount":
        {
        "CurrencyCode":"SEK",
        "Value":10000,
        "ValueForView":100.0
        },
        "CreatedDate":"2017-01-23 11:32:10+01:00",
        "PaymentDate":"2017-01-23 00:00:00+01:00",
        "ActionType":"InvoiceAction", 
        "ActionPublicId":"9141xxxxxx",
        "PaymentReferenceId":"704b7222-c765-48db-xxxx-xxxxxxxxxxxx",
        "InvoiceNumber":"1",
        "DebtorName":"John Doe",
        "DebtorPublicId":"80d0ca84-5535-48b0-xxxx-xxxxxxxxxxxx",
        "OCR":"00000000000",
        "File":null,
        "PaymentMeanCode":"BG"
    }
}

Events

Event descriptionEvent typeData type
Invoice created InvoiceActionCreatedInvoiceActionView
Invoice fully paid InvoiceActionPaidInvoiceActionView
Invoice sale acceptedInvoiceSaleWasAcceptedInvoiceActionView
Invoice sale denied InvoiceSaleWasDeniedInvoiceActionView
Invoice state has changed InvoiceActionStateChangedInvoiceActionView
Invoice has been viewed on 'minasidor'InvoiceActionViewedInvoiceActionView
Invoice has been commentedInvoiceCommentedInvoiceActionCommentedView
Invoice email has been openedInvoiceActionOpenedInvoiceActionView
Invoice email or SMS has been receivedInvoiceActionReceivedInvoiceActionView
Invoice attested InvoiceActionAttested InvoiceActionView
Received payment for invoice/reconciliation invoiceInvoicePaymentReceivedIncomingPaymentView
Amount credited on invoice/reconciliation invoiceAmountCreditedOnInvoiceIncomingPaymentView
Amount written off on invoice/reconciliation invoiceAmountWrittenOffOnInvoiceIncomingPaymentView
Reconciliation invoice created ReconciliationInvoiceActionCreatedReconciliationInvoiceActionView
Invoice/Self invoice/Reconciliation invoice email or SMS could not be deliveredUndeliveredInvoiceInvoiceDeliveryStatusView
Successful self invoice payment SelfInvoiceOutgoingPaymentSucceededOutgoingPaymentStatusView
Successful supplier invoice payment SupplierInvoiceOutgoingPaymentSucceededOutgoingPaymentStatusView
Successful payment through the api OutgoingPaymentSucceededOutgoingPaymentStatusView
Failed self invoice payment SelfInvoiceOutgoingPaymentFailedOutgoingPaymentStatusView
Failed supplier invoice payment SupplierInvoiceOutgoingPaymentFailedOutgoingPaymentStatusView
Failed payment through the api OutgoingPaymentFailedOutgoingPaymentStatusView
Unmatched payment UnmatchedPaymentUnhandledPaymentView
Overpayment OverpaymentUnhandledPaymentView
Creditor shared CreditorSharedWebhookCreditorShareView
Creditor shared removedCreditorUnshared[Nothing]
Debtor createdDebtorCreatedDebtorView
Debtor updatedDebtorUpdatedDebtorView
Debtor deletedDebtorDeletedstring
Debtor has requested change of stored customer information DebtorInformationCorrectionRequestedDebtorInformationCorrectionRequestView
Unknown e-invoice registration (B2C)UnknownEInvoiceRegistrationEInvoiceRegistrationView
Creditor created CreditorCreatedCreditorView
Creditor updated CreditorUpdatedCreditorView
Creditor deleted CreditorDeletedstring
Autogiro approval failed to register AutogiroApprovalFailedDebtorView
Autogiro approval has changed (added, changed or deleted)AutogiroApprovalChangedDebtorView
Autogiro withdrawal failed on invoice AutogiroWithdrawalFailedOnInvoiceInvoiceActionView
Autogiro withdrawal failed on reconciliation invoice AutogiroWithdrawalFailedOnReconciliationInvoiceReconciliationInvoiceActionView
Autogiro withdrawal failed but new retry will be made tomorrow on invoice AutogiroWithdrawalRenewedOnInvoiceInvoiceActionView
Autogiro withdrawal failed but new retry will be made tomorrow on reconciliation invoice AutogiroWithdrawalRenewedOnReconciliationInvoiceReconciliationInvoiceActionView
Product createdProductCreatedProductView
Product updatedProductUpdatedProductView
Contract invoice createdContractInvoiceActionCreatedContractInvoiceActionView
Contract invoice updatedContractInvoiceActionUpdatedContractInvoiceActionView

Missing a web hook?

If you are missing a webhook, please send a request to us and we'll add it to the API

Dates and time zones

The Billecta API server run on Stockholm time zone, ie +01:00 from GMT. All dates passed to Billecta without time zone information are considered as in Stockholm time. Likewise, all dates returned from Billecta API without any time zone information are in Stockholm time. The API should however always return dates with time zone information. When using the SDKs this is managed automatically by the SDK library.

Dates must always be specified in ISO 8601. The standard defines dates in the following format

  • 2017-03-15T06:35:06+00:00
  • 2017-03-15T06:35:06+01:00
  • 2017-03-15T06:35:06Z
  • 20170315T063506Z
  • 2017-03-15

Dates in invoice rows

All invoice rows, products and contract invoice rows that has a description property where the description of the sold entity supports programming of dates in each row. If you want to have, for instance, contract invoices that foreach time a new invoice is created from a certain row should have the current, future or past date certain codes can be put in the invoice rows. The following codes can be inserted in product descriptions and contract invoice row descriptions (if the current date is 2017-03-07):

{YY} or {ÅÅ} 19 Prints out the current year in short
{YYYY} or {ÅÅÅÅ} 2019 Prints out the current year
{MM}, {MMM} resp. {MMMM} 09, Sep resp. September Prints out the current month as number, short and long formats
{DD} 17 Prints out the current day in the month

All the formats above can have the suffix +/- followed by an integer number. For instance

  • {YYYY+1Y} prints YYYY
  • {MMM-2M} prints jul

The codes above only print parts of a day (year, month or day). When calculating on complete dates the following formats must be used

{YYMMDD} or {ÅÅMMDD} 190917
{YY-MM-DD} or {ÅÅ-MM-DD} 19-09-17
{YYYYMMDD} or {ÅÅÅÅMMDD} 20190917
{YYYY-MM-DD} or {ÅÅÅÅ-MM-DD} 2019-09-17
{MMM YYYY} or {MMM ÅÅÅÅ} Sep 2019
{MMMM YYYY} or {MMMM ÅÅÅÅ} September 2019

Also, complete dates have support for suffixes using +/- and an integer number. However complete number must also specify which part of the date is added/decreased. You can select amount

  • Y for year. For example {YY-MM-DD+1Y} prints 20-09-17
  • M for month. For example {YY-MM-DD+18M} prints 21-03-17
  • D for day. For example {YY-MM-DD+30D} prints 19-10-17
  • D for day, M for month. For example {YY-MM-DD-30D+2M} prints 19-10-18

Specifics

This page and the subsections below describe specific flows and usages of Billecta API/features.

Get bank accounts

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 Billecta through mobile BankID extract the IBAN, clearing and account numbers from the persons banks. This is mostly useful in the autogiro approval flow and for other cases. You do not need to any own BankID certificate for this service since each bank own BankID will be used.

The flow for getting bank accounts

User mobile/browser Your system Billecta API
1. Your customer in your system wants to extract their account number.

2. Your application makes a request to Initiate retrieval of bank account numbers in Billecta API (see API reference).

3. Billecta API initiates a mobile BankID authentication to selected bank and returns a PublicId to the initiated request.
5.1 User open app and authenticates him/her self. 4. Your system receives the PublicId to the initiated requests and inform the customer to open their mobile BankID app (or automatically open their mobile BankID app). Information on how to open BankID app on cell phone is covered in the following link.
5.2 While user authenticates them self your application polls Billecta API (each second is sufficient) by making a request to Get bank account numbers in Billecta API. Use the PublicId received when initiating the account number retrieval. 5.3 Billecta API checks status of authentication and if accounts have been retrieved.
  • If authenticated and accounts retreived: The response will be a BankAccountRequestView with status Success.
  • If not authenticated yet (might take some time): The response will be a BankAccountRequestView with status Waiting. Poll again according to 5.2 after 1 second.
  • If aborted or other error: The response will be a BankAccountRequestView with status Failed.
7. User selected one of the accounts.
6. When receiving BankAccountRequestView a response with status Success, present the found accounts to the user.

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

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 (similar for sign but different endpoint in the api)

User mobile/browser Your system Billecta API

1. Start by making a request to Create Mobile BankID authentication request in Billecta API (see API reference).

2. Billecta API initiates a mobile BankID authentication with the bank and returns a BankIdAuthenticationStatusView containing a ReferenceToken.
4.1 User open app and authenticates him/her self. 3. Your system receives the BankIdAuthenticationStatusView to the initiated requests and inform the customer to open their mobile BankID app (or automatically open their mobile BankID app). Information on how to open BankID app on cell phone is covered in the following link.
4.2 While user authenticates them self your application polls Billecta API (each second is sufficient) by making a request to Get Mobile BankID authentication status in Billecta API. Use the ReferenceToken received when initiating the mobile BankID authentication. 4.3 Billecta API checks status of user authentication.
  • If authenticated: The response will be a BankIdAuthenticationStatusView with status Complete.
  • If not authenticated yet (might take som time): The response will be a BankIdAuthenticationStatusView with status Started or OutstandingTransaction. Poll again according to 4.2 after 1 second.
  • If aborted or other error: The response will be a BankIdAuthenticationStatusView with status NoClient or Error.
7. User is authenticated.
6. When receiving BankIdAuthenticationStatusView a response with status Complete, present to the user that they are authenticated.

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.

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 on how to setup the creditor)

The flow for swish payments

User mobile/browser Your system Billecta API
2. Present the Swish payment form for the user where they should have the possibility to specify their registered phone number for Swish payments.
1. Start by creating an invoice or retrieve the action public id of an existing invoice.
3. User enters phone number and presses 'Pay' (or other button to initiate the payment flow)
4. Your system makes a request to Create Swish payment request in Billecta API (see API reference) with the ActionPublicId and the users phone number.
5. Billecta API initiates a swish payment at Swish and returns a token/public id that identifies the initiated payment.
7.1. User opens the Swish app. The app is prepopulated with you company name and amount to pay.
6.1. Your system receives the token/public to the initiated request and inform the customer to open their Swish app (or automatically open it if user is on a cell phone).
7.2. User approves the payment. If user is on cell phone he/she switches app back to your website and waits for updated status. 6.2. While user approves the payment your application polls Billecta API (each second is sufficient) by making a request to Get Swish payment status in Billecta API. Use the token/public id received when initiating the swish payment. Your system receives the SwishPaymentStatusView to the payment request. If status is 'Created' then keep polling. All other states move down to step 8.
6.3. Billecta contacts Swish and checks status on payment request and returns a SwishPaymentStatusView.
9. Information about the payment status is shown
8. Payment has at this stage either been paid or cancelled depending on the status. If paid, the invoice is marked as paid and payment is registered automatically in Billecta API. If cancelled then no payment has been made. User is informed about the payment status.

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.

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

Enum name Description
ITELLA OpusCapita
TIETOSE Tieto
LOGICA CGI
PROCEEDO Visma Proceedo AB
HUSERA Palette
BASWARE Basware
EDB Evry
STRALFORS1 Strålfors Svenska AB
LIAISON_FI Liaison Technologies
EXPERT Readsoft/Lexmark
ESSESESS SEB
HANDSESS Handelsbanken
DABASESS Danske bank
SWEDSESS Swedbank
NDEASESS Nordea
INEXCHANGE InExchange
SCANCLOUD Scancloud
PAGERO Pagero
CREDIFLOW Crediflow
PEPPOL PEPPOL
COMPELLO Compello
LOGIQ Logiq AS
APIX Apix Messaging AB
AKSESSPUNKT Aksesspunkt Norge AS