Invoices

Note! For documentation on specific payment options, please visit:

• Multiple payment options (let your recipients choose between two or more fixed amounts)
• Flexible option (let your recipients pay an amount of their choice, within a range defined by you)
• Swish (let your recipients pay with Swish)

Open API reference/send content in new tab.

Note! These instructions apply only for sending invoices in Sweden.

Defining content as an invoice requires correct metadata:

Step 1 – add the recipients's SSN, Email or VAT number

SSN, Email or VAT numbers are required for all content in Kivra.

Step 2 – add subject/title

This subject/title will be visible in the Recipient’s Inbox.

Note! Don’t include any personal information here, such as the recipient's name or SSN in the subject/title.

Step 3 – set type

By setting the type, you determine what type of content you're sending.

Note! It’s important to set the correct type. If not, the notification and content interaction might not be correct.

These are the available types for invoices:

invoice A “standard” invoice

Notifications and emails for invoice:

• Alert: immediately. Push notification and email.
• First reminder: 2 bankdays + 2 days before due_date. Push notification.
• Second reminder: 1 bankday + 2 days before due_date. Email.

invoice.reminder

A reminder for an unpaid invoice

Notifications and emails for invoice.reminder:

• Alert: immediately. Push notification and email.
• First reminder: 2 bankdays + 2 days before due_date. Push notification.
• Second reminder: 1 bankday + 2 days before due_date. Email.

invoice.debtcollection

A special type of content that is used by debt collection agencies to send debt collection claims (sv: inkassokrav).

Notifications and emails for invoice.debtcollection:

• Alert: immediately. Push notification and email.
• First reminder: 2 bankdays + 2 days before due_date. Push notification.
• Second reminder: 1 bankday + 2 days before due_date. Email.

invoice.debtcampaign

A special type of invoice that is used in long-term monitoring of debt collection. This type supports long due dates, and can be used when the debtor doesn’t have sufficient creditworthiness to meet the claims.

Notifications and emails for invoice.debtcampaign:

• Alert: immediately. Push notification and email.
• First reminder: After 7 days. Push notification.
• Second reminder: After 7 + 35 days. Push notification and email.

invoice.renewal

This is not an actual invoice, but an offer. As such, it’s voluntary to pay for the recipient. We recommend using this type for prolonging an insurance, a subscription, or similar.

Notifications and emails for invoice.renewal:

• Alert: immediately. Push notification and email.
• First reminder: 2 bankdays + 2 days before due_date. Push notification.
• Second reminder: 1 bankday + 2 days before due_date. Email.

Step 4 – add file and details

Content in Kivra always contains a PDF file. If you’re sending responsive content, you will also need to provide a HTML document. In that case, the PDF will serve as backup if the user wants to access the original content.

The following details are required for your file:

– name the filename that is shown alongside the File in the Kivra GUI.

– data base64-encoded data. This is the data for the actual PDF file.

– content_type the IANA media type corresponding to the file. In the case of invoices, this will most likely be "application/pdf".

Step 5 – choose between "PaymentMultipleOptions" and "Payment"

"Context" sets the payment details for your invoice. There are 2 alternatives for invoices:

1. "PaymentMultipleOptions" (recommended) – gives you the possibility to set one or more payment options. The options can differ in descriptions, amounts, due dates, etc. See documentation for Multiple payment options.
2. "Payment" (legacy) – gives your invoice a maximum of one payable amount. Use this alternative for Variable amount. See documentation for Variable amount.

Note! “Payment” is a legacy product. Thus, we recommend “PaymentMultipleOptions”, regardless of how many options your invoice has. It’s perfectly alright to set just 1 option on “PaymentMultipleOptions” invoices.

We only recommend using "Payment" for maintenance of existing codebases, and in order to use the "Variable amount" functionality.

After this step, you will proceed with either step 5.1 or 5.2.

Step 5.1 – add details for "PaymentMultipleOptions" invoices

If you chose "PaymentMultipleOptions" in the above step, the following details are required (or, where stated, optional) for your invoice:

– Payable

Toggles whether this content should be payable through Kivra’s payment platform.

Note! If 'Payable' is set to 'false' the content will not be payable through Kivra.

– Method

"1" = Bankgiro

"2" = Plusgiro

– Account

The receiving account number.

– Currency

– Options

A list of payment options, where each option should differ in either amount or reference.

Note! We strongly recommend setting the “default” option first in the list. In some cases, only the first option will be visible to users.

– Due date

– Amount

The payment amount for this option.

– Type

Type of format for the reference. Must be consistent with “Reference” (below). There are 2 alternatives:

"SE_OCR" – must fulfill the requirements for OCR.

"TENANT_REF" – a reference of your choice.

– Reference

The reference used for paying. Must be consistent with “Type” (above).

– Title

Optional. Set the title for this payment option. If your invoice has only one option, this will be overridden by the subject/title that you set in step 2.

– Description

Optional. Set the description for this payment option. If your invoice has only one option, this will be overridden by the subject/title that you set in step 2.

– Icon

Optional, but has required details if used. If these are incorrect, your invoice will be rejected.

Details for Icon:

– Name

Optional.

– Data

Max size is 134 kB when encoded, which is roughly equivalent to 100 kB before encoding. The image format must be PNG. The image must be quadratic (that is, width and height must be the same). The sides must be at least 256 pixels long, and at most 512 pixels long. The image must have an alpha channel.

– Content_type

Value: "image/png"

Step 5.2 – add details for "Payment" invoices

If you chose "Payment" in the above step, the following details are required (or, where stated, optional) for your invoice:

– Payable

Toggles whether this content should be payable through Kivra’s payment platform.

Note! If this is set to 'false' the content will not be payable through Kivra.

– Currency

– Due date

– total_owed

The total amount, and the maximum amount that can be paid.

– Type

Type of format for the reference. Must be consistent with “Reference” (below).

There are 2 alternatives:

"SE_OCR" – must fulfill the requirements for OCR.

"TENANT_REF" – a reference of your choice.

– Account

The receiving account number.

– Reference

The reference used for paying. Must be consistent with “Type” (above).

– Variable amount

Default: "false". Change to "true" if you want to use a variable amount.

– min_amount

If you use a variable amount, this is where you set the minimum amount that can be paid.

An open rate of 97-99%, easy user experience, and many payment options. These are characteristics of invoices in Kivra. Also, recipients generally pay their Kivra invoices quicker than paper invoices. Here's what the invoice experience is like.

1 – notifications and email

As soon as the invoice is registered in Kivra, the recipient receives a push notification and an email, alerting them of the invoice. If the recipient doesn’t pay the invoice in Kivra, or doesn’t mark it as “paid” in Kivra, they will eventually be reminded with more push notifications and emails. This significantly reduces the risk of overdue invoices.

Note! Notifications and emails are tailored to fit the specific type that you chose in step 3 above.

2 – opening the invoice

The recipient opens the invoice in their Kivra app. From there, they are only a few clicks away from completing the payment. All required fields are pre-filled with the data that you have provided.

• If you've created an invoice with multiple payment options, the recipient chooses one of the options you've provided.

• If you've created an invoice with a variable amount, the recipient chooses an amount within the range that you have set.

3 – paying the invoice

The recipient chooses which payment method to use when paying:

• From their bank account. This option is always available. The user selects which bank account to pay from and approves the payment with BankID.
• Swish. This option is available if Swish is enabled for your company. See documentation on setting up Swish payments.
• The recipient can also pay the invoice outside of Kivra, through their usual bank app or similar.

And that's it!