Multiple payment options

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 your company's SSN or VAT number

SSN 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 – add context

"Context" sets the payment details for your invoice. In order to use Multiple payment options, you must choose "PaymentMultipleOptions”.

The following details are required (or, where stated, optional) for "PaymentMultipleOptions" invoices:

Payable 

Set to “true”.

Method 

"1" = Postgiro

"2" = Bankgiro

Account 

The receiving account number.

Swish Alias

The Swish Payee Alias that should be used if the user chooses to pay this invoice with Swish. The alias given must be one that is listed as available for the sender, or it will be ignored. The value can also be the string disable, in order to override a default payee alias and disable Swish payment for this invoice only.

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 1 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 1 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"

Invoices with Multiple payment options let the recipient choose between two or more pre-defined amounts. Suitable for debt campaigns and upselling. Here's what the Multiple payment options invoice experience is like for the recipient.

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 leaves the invoice unpaid, they eventually get reminded with more push notifications and emails. This significantly reduces the risk of unpaid 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. When paying the invoice, they choose one of the amounts that you have defined.

An invoice with Multiple payment options

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 for 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!