Documentación

MCI

Suggest Edits

Meses con intereses es una opción de pago que permite a los consumidores dividir el costo de una compra en varias cuotas mensuales, pero a diferencia de "MSI" (Mensualidades Sin Intereses), en este caso se aplican intereses sobre el saldo pendiente. En otras palabras, el consumidor paga una tasa de interés adicional por dividir el costo de la compra en cuotas mensuales.

Cuando un consumidor elige pagar a través de Meses con intereses, el costo total de la compra se divide en cuotas mensuales y se le aplican tasas de interés sobre el saldo que queda pendiente en cada período. Estas tasas de interés suelen ser determinadas por el emisor de la tarjeta de crédito utilizada para la transacción o por el acuerdo con el comerciante.

Como funciona MCI?

  1. El merchant configura en el admin de DEUNA las diferentes mensualidades por PSP (según disponibilidad), teniendo en cuenta la franquicia de la tarjeta de credito en las que aplica, asi como el monto minimo respectivo para cada exhibicion configurada, al igual que los interes que aplican para cada una de estas.
  2. El checkout del merchant muestra la disponibilidad de los meses, al momento en que el comprador ingresa el bin de la tarjeta.
  3. Tras seleccionar la mensualidad en la lista desplegable mostrada en el checkout, segun disponibilidad, la transacción es enviada al PSP para ser procesada.

Como Implementar MCI

  1. En primer lugar debemos configurar al menos una campaña de installments, la cual se consumirá al momento de generar el plan de installments. En el momento que se realice eso, se requiere que la/s campañas estén vigentes. . Para ofrecer opciones de financiación con MSI, es fundamental que las opciones de la campaña tengan el installments_type correspondiente (”MCI”)
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.
    ]
}'

  1. Posteriormente tenemos que asegurarnos que los merchant payment processors encendidos (enabled) tengan permitido realizar transacciones con installments con el flag allow_installments: true. Se requiere al menos uno con esa opción activa. El flag se puede activar al crear el merchant payment processor o actualizar posterior a su creación.
    Además, se utiliza un flag para especificar cómo se va a procesar la transacción del lado del procesador, el cual es mci_to_psp_as, cuyos valores permitidos son “MCI” (mismo comportamiento que null) y “MSI”.
    Su comportamiento de acuerdo a esos valores es el siguiente:

    • “MCI” o null: implica que el amount que va hacia el procesador no tiene aplicados los intereses, por ende la transacción debe actualizarse posterior a ser procesada con los intereses aplicados por el procesador. Éstos campos que se actualizan en base a la respuesta del procesador son: amount, installments_amount e installments_rate.

    • “MSI”: implique que, más allá de que la transacción es de tipo “MCI”, contra el procesador se va a realizar la transacción sin intereses, por ende el amount ya llega al mismo con los intereses calculados. A diferencia del punto anterior, el amount (ya con intereses calculados) se actualiza antes de ir al procesador a llevar a cabo la transacción.
      Creando merchant payment 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"
}'

      Actualizando merchant payment 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"
}'

  2. Luego debemos tener en cuenta que el merchant puede ofrecer cuotas ya configuradas en Vtex o no. Para el primer caso, vamos a necesitar activar un flag para el mismo. Ésto significa que los installments obtenidos de Vtex tienen que hacer “match” con las opciones ofrecidas en la campaña, pero los mismos ya se obtienen con interés aplicado desde esa plataforma. El flag a configurar para directamente obtener es el feature flag “ALLOW_MCI”.

    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"
}'

    Dado que tenemos que ir a buscar los installments a Vtex, necesitaremos configurar en base a credenciales el endpoint de Deuna que va a buscar ésta información. Para ello, debemos crear un external endpoint, especificando que el mismo es para MCI:

    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"
  }'

    Si ésto último no es configurado, los installments se intentarán recuperar de un endpoint default que se utiliza para ésto, por favor consulte en caso de que se complique la implementación.

    En caso de no configurar el feature flag ALLOW_MCI, o dejarlo deshabilitado (se hace con un delete en el mismo endpoint sumando en el path el id de la config), el plan de installments de MCI se arma en base a la configuración de la campaña, y el amount depende de:

    • installments_rate: se aplica al amount directamente en caso de no tener definida una installments_interest_formula.
    • installments_interest_formula: si se especifica define la forma en que se debe realizar el cálculo del interés, en base a variables como "amount", "rate" and "installments". Por ejemplo: amount+((amount*rate*installments)/100).

  3. Posterior a la creación de la orden, antes de proceder con su pago, podemos consultar las opciones de financiación (installments).

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}'
  1. Posterior a la selección de la opción, realizar el purchase con la opción de installments seleccionada.
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}
        }
    }
}'

Como probar MCI

  1. Para crear la campaña es necesario autenticarse como merchant y para la misma configurar los “processors” para los cuales se vayan a ofrecer installments. Éstos últimos tienen que tener el id y name del ecosistema Deuna, por ejemplo:

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

    La misma campaña debiese tener sus opciones con “installments_type”: “MCI”.

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

    Dentro de “card_branch”, el “name” de las mismas puede ser “visa”, “mastercard” o “amex”. Lógicamente es requerido especificar los “installments_rate” de cada opción (equivalentes al porcentaje de interés) para el caso que se desee directamente calcular sin configuraciones externas el amount con intereses.
    Http status codes esperados:

    • 201: creación exitosa de la campaña
    • 401: no autorizado para crear la campaña
    • 400: request inválida

  2. Para crear los merchant payment processors es necesario autenticarse como merchant y tener las credenciales necesarias para luego poder realizar las transacciones con MSI. [debería haber una guía acá de como configurar cada processor].

    Http status codes esperados:

    • 201: creación exitosa del merchant payment processor
    • 401: no autorizado para crear el merchant payment processor
    • 400: request inválida

  3. Si se desean obtener installments de Vtex, configurar el feature flag “ALLOW_MCI”. Si no se desea ésto último, ir directamente al step 5.

    Http status codes esperados:

    • 200: creación exitosa del merchant store config
    • 401: no autorizado para crear el merchant store config
    • 400: request inválida

  4. Si en base a lo último se requiere alguna configuración adicional y se necesita configurar un endpoint con credenciales específicas para Vtex, enconces hay que crear un external endpoint, cómo se especifica en el punto 3 de la sección anterior. En caso de no realizar éste paso, se utilizará el endpoint default para obtener los MCI.
    Http status codes esperados:

    • 200: creación exitosa del external endpoint
    • 401: no autorizado para crear el external endpoint
    • 400: request inválida

  5. Posterior a crear la orden [debería de haber algún tutorial de eso] consultar con el bin de la tarjeta (primeros 6 dígitos de la misma) el plan de installments

    Http status codes esperados:

    • 200: obtención exitosa del plan de installments
    • 401: no autorizado para crear el merchant payment processor
    • 400: request inválida
    • 404: no hay merchant payment processors configurados correctamente

  6. Al realizar el purchase con la opción de installments seleccionada, tener en cuenta que todos los datos de prueba de las tarjetas deben proveerse por el procesador (consultar su documentación). En general esos datos son “card_number”, “card_cvv”, “expiry_year” y “expiry_month” (en algunos casos también “card_holder”).

    Http status codes esperados:

    • 200: purchase exitoso
    • 401: usuario no autorizado para realizar el purchase
    • 400: request inválida, como por ejemplo que el merchant no tenga merchant payment processors habilitados
    • 422: el purchase no pudo realizarse debido a que el procesador la declinó

Updated 12 days ago