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 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 – 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" = Bankgiro

"2" = Plusgiro

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"

Flexible Option

The flexible option enables the user to enter the amount to pay within a range that you define. The attributes of the flexible option that share names with attributes for normal options work the same also for the flexible option. These are title, description, reference, type, due date and icon. In addition the flexible option may have these optional attributes:

min_limit 

The hard minimum allowed to be paid. The user may not specify an amount lower than this. In case min_limit is not provided the minimum allowed amount is 1 SEK.

min_suggested

The suggested minimum to pay. The app will notify the user if they enter an amount lower than this, but if the user insists the payment is allowed to go through. The suggested minimum must be larger than the hard minimum, if both are provided.

max_limit

The hard maximum allowed to be paid. The user may not specify an amount greater than this. In all cases the maximum allowed amount is 150 000 SEK due to payment provider restrictions.

max_suggested

The suggested maximum to pay. The app will notify the user if they enter an amount greater than this, but if the user insists the payment is allowed to go through. The suggested maximum must be less than the hard maximum, if both are provided.

The amounts must be in this order from smallest to largest: min_limit, min_suggested, max_suggested, max_limit.

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!