Interface Guideline

Request flow

Show terms of use and privacy policy

Koin is regulated by the central bank of Brazil and for this reason we need to follow some rules described in the terms of use. Due to some data protection legislation, the buyer also needs to agree with our privacy policy. Here is an example of how to display and request buyer consent for these two required items:

Links to the terms of use and privacy policy are as follows;

Termos of use: https://termos.koin.com.br/

Privacy policy: https://www.koin.com.br/politica-de-privacidade/

❗️

IMPORTANT

Before calling any koin method, whether availability or order, it is necessary to obtain consent that the buyer has read the terms of use and privacy policy

Show detailed list of installment options

It is mandatory to display all installment data, such as date of the first installment, interest rate, cet and IOF. The total financing amount should also be displayed, as shown in the example below:

📝

DOWN PAYMENT

In a differentiated down payment model, the value of the down payment must be taken from the incoming_value field. The remaining installments should be displayed according to the installment_amount field.

🧩

User Interface Highlights

In some cases, it will be necessary to include certain highlights in the user interface to achieve a better conversion rate. We provide the following highlights:

 "ui": {
        "layout": {
            "tags": [
                "INTEREST_FREE",
                "ENTRY_REQUIRED",
                "FORCED_FIRST_INSTALLMENT"
            ],
            "highlighted": true,
            "sorted": 2
        },
        "hints": {
            "birthdate": {
                "required": true
            }
        }
    }

No Interest – A label should be displayed indicating that the transaction has no interest. In tags, it will be labeled as INTEREST_FREE.

Down Payment Required – Inform the user that a down payment is required to complete the transaction. In tags, it will be labeled as ENTRY_REQUIRED or FORCED_FIRST_INSTALLMENT.

Highlight on Installment Condition – We will indicate when a specific installment option should be emphasized. When the layout contains the attribute highlighted set to true.\

Display Order – We provide a specific order in which installment options should be shown. The sorted attribute will determine the display order of the installment options. The integer value in this attribute must be followed.\

Discont - In some cases, we may offer a discount on a specific payment option. In such cases, we will return the DISCOUNT tag and describe the discount details in the discountInfo attribute.

"discountInfo": {
    "originalInstallmentValue": 31.26,
    "percent": "0.0200",
    "value": 6.99
}

Recommended: It indicates that this payment option is recommended to the user, based on criteria such as more attractive rates, better cost-benefit or greater popularity among customers.

📘

NOTE

Each installment option may contain a different interest rate or other information. Therefore, each installment option must display its respective fees and taxes

Show Status Details

After the request is made to complete the financing, there may be different transaction statuses as described in Guides -> BNPL Transparent checkout. Below are highlighted the main statuses and how to display the information to the buyer:

Type: Waiting ---> Reason: FirstPayment

The financing request has been approved and created and is now awaiting the first payment to be made. At this point, it is necessary to display the PIX QR Code and the copy paste so that the buyer can pay the first installment. Only after payment of the first installment will financing be approved. Below is an example of how pix information can be displayed:

Type: Collected

After payment of the first installment, financing is finally approved. As the management of other payments will be done through our APP, we suggest showing the buyer how they can have access. Below is an example of how this can be communicated to the buyer:

Google Play: https://play.google.com/store/apps/details?id=br.com.koin&pcampaignid=web_share

Apple Store: https://apps.apple.com/br/app/koin-cr%C3%A9dito-e-pix-parcelado/id1618949374

Type: Waiting ---> Reason: EmailValidation

The financing request has been created and is now awaiting email validation. At this point it is necessary to display the message so that the buyer needs to validade their email. Only after validating the email will the buyer be able to proceed to the pix payment flow. Below is an example of how the message might be displayed::

Type: Waiting ---> Reason: ProviderReview

The financing request has been created and is now pending provider review. At this point it is necessary to display the message so that the buyer wait the provider review process. Only after finish provider review will the buyer be able to proceed to the pix payment flow. Below is an example of how the message might be displayed:

Type: Waiting ---> Reason: WhatsAppValidation

The financing request has been created and is now awaiting WhatsApp validation. At this point it is necessary to display the message so that the buyer can validate their WhatsApp. Only after validating the WhatsApp will the buyer be able to proceed to the pix payment flow. Below is an example of how the message might be displayed:

Type: Failed

After the validations that were left waiting or even after the financing was created, the buyer may not be able to purchase with Koin. In these cases, a message must be displayed informing the buyer. An example of how this can be demonstrated is below: