Interest-installments

Monthly payments with interest is a payment option that allows your customers to divide the cost of a purchase into several monthly installments, with interest applied to the outstanding balance.

With MCI, a customer pays an additional interest rate for dividing the purchase cost into monthly installments.

When a customer chooses to pay through Monthly payments with interest, the total cost of the purchase is divided into monthly installments and interest rates are applied to the balance remaining in each period.

📘
Interest rates are determined by the credit card issuer used for the transaction or by the agreement with the store.

How MCI Works

Here's how an MCI flow works:

The store configures the different monthly payment options by PSP in the DEUNA Admin.
The following is taken into account:
- The credit card franchise to which it applies.
- The respective minimum amount for each configured installment.
- The interest that applies to each franchise.
The store checkout shows MCI availability when a customer enters the BIN of a card.
The customer selects the monthly payment from a dropdown list shown in the checkout.
The transaction is sent to the PSP to be processed.

Implement MCI

To use MSI or MCI, configure at least one installments campaign.

📘
Each campaign is consumed when generating the installment plan.

To offer installment options

Generate the campaign options installments_type.

curl --location --request POST 'https://apigw.getduna.com/merchants/{merchant_id}/installments/campaigns' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {merchant_auth_token}' \
--data '{
    "name": "new campaign",
    "description": "testing campaign MCI",
    "status": "active",
    "processors": [
        {
            "id": {processor_id},
            "name": {processor_name}
        }
    ],
		// display_label_template is optional; that configuration allows you to 
		// change the format of the field "display_label_amount" of each available 
    	'// option when you generate an installment plan. If you don`t configurate this'
    	'// field, the template will be the default one.'
    "display_label_template": {
        "language": "es",
        "MSI": "{installments} meses sin intereses de ${amount}",
        "MCI": "{installments} meses de ${amount}"
    },
    "options": [
        {
            "installments": 3,
            "installments_type": "MCI",
            "currency": "MXN",
            "card_branch": [
                {
										// minimum amount for installment amount in the plan, this option
										// will be valid to generate installment plan only in that case;
										// E.g. with a total amount of $2100; in 3 installments the amount 
										// will be of $700, so $700 >= $500, then the option is valid to
										// generate an installment plan of $2100 (you can offer 3 installments
										// to pay $2100). In the case of having intallments_rate greater than 0, 
										// first the interest is applied to the amount and then it is compared with the min_amount.
                    "amount_min": 500,
										// optional, the same example than amount_min but with the maximum value.
                    "amount_max": 2000,
                    "name": "visa",
										// is the percentage applied to the amount in order to generate the options for the plan.
										"installment_rate": 1.5,
										// use the operators "amount", "rate" and "installments" when calculate the new amount;
										// if it's not specified, the calculation is the default for interests: "amount+(amount*(rate/100))"
										"installments_interest_formula": "amount+((amount*rate*installments)/100)"
                }
            ]
        },
        {
            "installments": 6,
            "installments_type": "MCI",
            "currency": "MXN",
            "card_branch": [
                {
                    "amount_min": 250,
                    "amount_max": 1000,
                    "name": "visa",
                }
            ]
        }
				// you can offer more options, the installments quantity must be divisible by 3.
    ]
}'

Enable your store's payment processors to perform transactions with the flag allow_installments: true. The flag behavior is as follows:
- "MCI" or null: The amount that goes to the processor does not have interest applied and the transaction must be updated after being processed with the interest applied by the processor. The fields that are updated based on the processor response are:
  - amount
  - installments_amount
  - installments_rate.
- "MSI": A transaction without interest is performed against the processor that carries out the transaction. The amount reaches the processor with calculated interest. The amount is updated before carrying out the transaction and being sent to the processor.

Example to create the processor

curl --location --request POST 'https://apigw.getduna.com/merchants/{merchant_id}/stores/{store_code}/processors' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {merchant_auth_token}' \
--data '{
    "name": {processor_name},
    "payment_processor_id": {processor_id},
    "enabled": true,
    "currency_iso3": "MXN",
    "external_merchant_id": "your merchant id in payment processor",
    "public_api_key": "your public key in payment processor",
		"private_api_key": "your private key in payment processor",
    "allow_installments": true,
		"mci_to_psp_as": "MCI"|"MSI"
}'

Example to update the processor

curl --location --request PATCH 'https://apigw.getduna.com/merchants/{merchant_id}/stores/{store_code}/processors/{merchant_payment_processor_id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {merchant_auth_token}' \
--data '{
    "allow_installments": true,
		"mci_to_psp_as": "MCI"|"MSI"
}'

Check if your store can offer pre-configured installments in VTEX.
- If you can offer installments in VTEX, configure the ALLOW_MCI flag for your store. The installments obtained in VTEX must match the options offered in the campaign, but with interest already applied.
```
curl --location --request POST 'https://apigw.getduna.com/payments/merchants/{merchant_id}/stores/{store_code}/configurations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {merchant_auth_token}' \
--data '{ 	
  "config_code":"ALLOW_MCI",
  "config_value":"ENABLED"
}'
```
- If the option is disabled, the MCI installments plan is built based on the campaign configuration, and the amount depends on:
  - installments_rate: Applies to the amount directly if no installments_interest_formula is defined.
  - installments_interest_formula: If specified, then defines the interest calculation based on:
    - "amount"
    - "rate"
    - "installments".

📘
For example: amount+((amount*rate*installments)/100).

📘
You can remove the VTEX option with a delete in the same endpoint by adding the config id to the path.

Configure the DEUNA endpoint according to the installments enabled in VTEX.
1. Create an external endpoint, specifying that it is for MCI.
2. If you don't configure the endpoint, then a default endpoint is used for the case.

curl --location 'https://apigw.getduna.com/merchants/{merchant_id}/external-endpoints' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {merchant_auth_token}' \
  --data '{
      "url": "https://middleware.deuna.io/api/v1/merchants/{merchant_id}/transactions/{transaction_id}/installments/mci?bin={bin}&salesChannel=1&paymentProcessors=t1pagos",
      "http_method": "GET",
      "headers": [
          {
              "key": "vtex-key-header",
              "value": "vtex-value-header"
          }
      ],
      "config_type": "MCI"
  }'

Query installment options.

curl --location --request GET 'https://apigw.getduna.com/merchants/transactions/orders/{orden_token}/installments?bin={card_bin}'
	--header 'x-api-key: {x_api_key}'
	--header 'Authorization: Bearer {merchant_auth_token}'

Select an installment option.
Make the purchase with the installment option.

curl --location --request POST 'https://api.dev.deuna.io/merchants/transactions/purchase' \
--header 'x-api-key: {x_api_key}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {user_auth_token}' \
--data-raw '{
    "token": {orden_token},
    "method_type": "credit_card",
    "processor_name": {processor_name},
    "email": "[[email protected]](mailto:[email protected])",
    "credit_card": {
        "expiry_month": "11",
        "expiry_year": "2025",
        "card_holder": "Duna Developers",
        "card_holder_dni": "185396924",
        "card_number": "4111111111111111",
        "card_cvv": "123",
        "address1": "Vergara 548",
        "zip": "001100",
        "city": "santiago",
        "state": "rm",
        "country": "cl",
        "phone": "12345755",
        "installment": {
            "plan_option_id": {plan_option_id}
        }
    }
}'

Test MCI

To create the campaign it is necessary to:

Be authenticated as merchant.
Configure the processors that offer installments.
The processors must have the id and name of the DEUNA ecosystem.

Example

{
	"processors": [
		{
			"id": 39,
			"name": "mercadopago"
		}
	]
}

The same campaign must have its options with "installments_type": "MCI".

Example

{
	"options": [
        	{
            	"installments": 3,
            	"installments_type": "MCI",
            	"currency": "MXN",
            	"card_branch": [
                	...
            	]
        	}
	]
}

Within "card_branch", the "name" can be:

"visa"
"mastercard"
"amex".

📘
Specify the "installments_rate" of each option equivalent to the interest percentage if you calculate interest directly without external configurations.

Expected response codes

201: Successful campaign creation.
401: Not authorized to create the campaign.
400: Invalid request.

To create merchant payment processors it is necessary to authenticate as merchant and have the necessary credentials to later be able to perform transactions with installments.

Installments with VTEX

Configure the ALLOW_MCI flag to get available installments in VTEX.

Expected response codes

200: Successful creation of merchant store config.
401: Not authorized to create merchant store config.
400: Invalid request.

If you require any additional configuration to set up an endpoint with specific credentials for VTEX, you must create an external endpoint.

📘
Talk to your DEUNA TPM to help you with VTEX.

Expected response codes

200: Successful creation of external endpoint.
401: Not authorized to create external endpoint.
400: Invalid request.

Query installments

Query the installment plan with the card BIN after creating an order.

Expected response codes

200: Successful retrieval of installments plan.
401: Not authorized to create merchant payment processor.
400: Invalid request.
404: No merchant payment processors configured correctly.

Test cards

Provide all test card data from the processor.

In general the data is:

"card_number"
"card_cvv"
"expiry_year"
"expiry_month"
"card_holder"

📘
Check the provider's test card documentation.

Expected response codes

200: Successful transaction.
401: User not authorized to make the purchase.
400: Invalid request, such as the merchant not having enabled merchant payment processors.
422: The transaction could not be performed because the processor declined it.

Interest-installments

📘
Interest rates are determined by the credit card issuer used for the transaction or by the agreement with the store.

How MCI Works

Implement MCI

📘
Each campaign is consumed when generating the installment plan.

📘
For example: `amount+((amountrateinstallments)/100)`.

📘
You can remove the VTEX option with a delete in the same endpoint by adding the config id to the path.

Test MCI

📘
Specify the `"installments_rate"` of each option equivalent to the interest percentage if you calculate interest directly without external configurations.

Installments with VTEX

📘
Talk to your DEUNA TPM to help you with VTEX.

Query installments

Test cards

📘
Check the provider's test card documentation.

📘Interest rates are determined by the credit card issuer used for the transaction or by the agreement with the store.

How MCI Works

Implement MCI

📘Each campaign is consumed when generating the installment plan.

📘For example: amount+((amount*rate*installments)/100).

📘You can remove the VTEX option with a delete in the same endpoint by adding the config id to the path.

Test MCI

📘Specify the "installments_rate" of each option equivalent to the interest percentage if you calculate interest directly without external configurations.

Installments with VTEX

📘Talk to your DEUNA TPM to help you with VTEX.

Query installments

Test cards

📘Check the provider's test card documentation.

📘
Interest rates are determined by the credit card issuer used for the transaction or by the agreement with the store.

📘
Each campaign is consumed when generating the installment plan.

📘
For example: `amount+((amountrateinstallments)/100)`.

📘
You can remove the VTEX option with a delete in the same endpoint by adding the config id to the path.

📘
Specify the `"installments_rate"` of each option equivalent to the interest percentage if you calculate interest directly without external configurations.

📘
Talk to your DEUNA TPM to help you with VTEX.

📘
Check the provider's test card documentation.