Subscripciones en Checkout

Añade pagos a un checkout por suscripción con tarjetas de crédito y/o débito.

📘
Primeros Pasos

Instalar e incluir alguna de nuestras SDKs en tu proyecto.

Utilizar tu propia llave privada. Si no la conoces, puedes obtenerla aquí.

Paso 1 - Añade tu llave privada y versión del API

Necesitarás tu llave privada de pruebas. Si aún no cuentas con ella, puedes obtenerla en tu Panel Conekta.

N/A

require_once("/path/to/lib/Conekta.php");
\Conekta\Conekta::setApiKey("key_eYvWV7gSDkNYXsmr");
\Conekta\Conekta::setApiVersion("2.3.0");

require "conekta"
Conekta.api_key = "key_eYvWV7gSDkNYXsmr"
Conekta.api_version = "2.3.0"

import conekta
conekta.api_key = "key_eYvWV7gSDkNYXsmr"
conekta.api_version = "2.3.0"

var conekta = require('conekta');
conekta.api_key = 'key_eYvWV7gSDkNYXsmr';
conekta.api_version = '2.3.0';

import com.conekta;
Conekta.setApiKey("key_eYvWV7gSDkNYXsmr");
com.conekta.Conekta.apiVersion = "2.3.0"

using conekta;
conekta.Api.apiKey = "key_eYvWV7gSDkNYXsmr";
conekta.Api.version = "2.3.0";

import (
    conekta "github.com/conekta/conekta-go/v8"
)
conekta.APIKey = "key_pMcnDF4zFyWKyLG15LuqwA"

Paso 2 - Crear un Customer

Los campos mostrados en el ejemplo son los mínimos requeridos, si deseas saber más sobre el objeto customer revisa nuestro API Reference

curl --request POST \
  --url https://api.conekta.io/customers \
  --header 'accept: application/vnd.conekta-v2.3.0+json' \
  -u YOUR_ACCESS_TOKEN \
  --header 'content-type: application/json' \
  --data '{
  "name": "Fulanito Pérez",
  "email": "[email protected]",
  "phone": "+52181818181"
}'

try {
  $customer = \Conekta\Customer::create(
    [
      "name" => "Fulanito Pérez",
      "email" => "[email protected]",
      "phone" => "+52181818181",
      "metadata" => ["reference" => "12987324097", "random_key" => "random value"],
      "payment_sources" => [
        [
          "type" => "card",
          "token_id" => "tok_test_visa_4242"
        ]
      ]
    ]
  );
} catch (\Conekta\ProccessingError $error){
  echo $error->getMesage();
} catch (\Conekta\ParameterValidationError $error){
  echo $error->getMessage();
} catch (\Conekta\Handler $error){
  echo $error->getMessage();
}

customer = Conekta::Customer.create({
  name: 'Fulanito Pérez',
  email: '[email protected]',
  phone: '+52181818181',
  metadata: {"reference" => "12987324097", "random_key" => "random value"},
  payment_sources: [{
    type: 'card',
    token_id: 'tok_test_visa_4242'
  }]
})

try:
  customer = conekta.Customer.create({
    'name': 'Fulanito Pérez',
    'email': '[email protected]',
    'phone': '+52181818181',
    'metadata': { 'description': 'Compra de creditos: 300(MXN)', 'reference': '1334523452345' },
    'payment_sources': [{
      'type': 'card',
      'token_id': 'tok_test_visa_4242'
    }]
  })
except conekta.ConektaError as e:
  print(e.message)

customer = conekta.Customer.create({
    'name': 'Fulanito Pérez',
    'email': '[email protected]',
    'phone': '+52181818181',
    'metadata': { 'description': 'Compra de creditos: 300(MXN)', 'reference': '1334523452345' },
    'payment_sources': [{
      'type': 'card',
      'token_id': 'tok_test_visa_4242'
    }]
  }, function(err, res) {
      if(err){
        console.log(err);
        return;
      }
      console.log(res.toObject());
  });

try{
  Customer customer = Customer.create(
    new JSONObject("{"
      + "'name': 'Fulanito Pérez', "
      + "'email': '[email protected]',"
      + "'phone': '+52181818181',"
      + "'metadata': {'description': 'Compra de creditos: 300(MXN)' , 'reference' : '1334523452345'},"
      + "'payment_sources':[{"
        + "'type': 'card',"
        + "'token_id: 'tok_test_visa_4242"
        + "}]"
      + "}"
    )
  );
}catch (Conekta::Error e) {
   System.out.println(e.details.get(0).message);
}

try {
  conekta.Customer customer = new conekta.Customer().create(@"{
    ""name"":""Fulanito Pérez"",
    ""email"":""[email protected]"",
    ""phone"":""+52181818181"",
    ""metadata"":{""description"" : ""Compra de creditos: 300(MXN)"", ""reference"" : ""1334523452345""},
    ""payment_sources"":[{
      ""type"": ""card"",
      ""token_id"":""tok_test_visa_4242""
    }]
  }");
} catch (ConektaException e) {
  foreach (JObject obj in e.details) {
    System.Console.WriteLine("\n [ERROR]:\n");
    System.Console.WriteLine("message:\t" + obj.GetValue("message"));
    System.Console.WriteLine("debug:\t" + obj.GetValue("debug_message"));
    System.Console.WriteLine("code:\t" + obj.GetValue("code"));
  }
}

paymentSource := &conekta.PaymentSourceCreateParams{
    PaymentType: "card",
    TokenID: "tok_test_visa_4242",
}


customerParams := &conekta.CustomerParams{}
customerParams.Name = "fulanito Perez"
customerParams.Phone = "+5215555555555"
customerParams.Email = "[email protected]"
customerParams.PaymentSources = append(customerParams.PaymentSources, paymentSource)
customer, err := customer.Create(customerParams)

if err != nil {
    code := err.(conekta.Error).Details[0].Code
    fmt.Printf(code)
} else {
    fmt.Println(customer)
}

Paso 3 - Crear un Plan

Al contar con un plan podrás crear la relación con tu customer y elegir el comportamiento de la suscripción.

curl -H "Accept: application/vnd.conekta-v2.3.0+json" \
     -H "Content-type: application/json" \
     -u YOUR_ACCESS_TOKEN \
     -X POST -d '{
       "id": "gold-plan",
       "name": "Gold Plan",
       "amount": 10000,
       "currency": "MXN",
       "interval": "month",
       "frequency": 1,
       "trial_period_days": 15,
       "expiry_count":12
     }' https://api.conekta.io/plans

Notas de los campos:

currency: código de moneda ISO 4217 (máx. 3 caracteres); MXN o USD.

interval: valores posibles "week", "half_month", "month", "year".

frequency: entero (mínimo 1) que multiplica el interval para definir cada cuánto se cobra (p. ej. interval: month con frequency: 3 = cada 3 meses).

trial_period_days: días de prueba.

expiry_count: cantidad de pagos a recibir.

\Conekta\Plan::create([
    'id' => "gold-plan",
    'name' => "Gold Plan",
    'amount' => 10000,
    'currency' => "MXN",
    'interval' => "month",
    'frequency' => 1,
    'trial_period_days' => 15,
    'expiry_count' => 12
]);

conekta.Plan.create({
    "id": "gold-plan",
    "name": "Gold Plan",
    "amount": 10000,
    "currency": "MXN",
    "interval": "month",
    "frequency": 1,
    "trial_period_days": 15,
    "expiry_count": 12
});

conekta.Plan.create({
  "id": "gold-plan",
  "name": "Gold Plan",
  "amount": 10000,
  "currency": "MXN",
  "interval": "month",
  "frequency": 1,
  "trial_period_days": 15,
  "expiry_count": 12
})

Plan.create(new JSONObject("{"
  + "'id' : 'gold-plan',"
  + "'name' : 'Gold Plan',"
  + "'amount' : 10000,"
  + "'currency' : 'MXN',"
  + "'interval' : 'month',"
  + "'frequency' : 10,"
  + "'trial_period_days' : 15,"
  + "'expiry_count' : 12"
+"}"));

conekta.Plan plan = new conekta.Plan().create(@"{
   ""id"": ""gold-plan999"",
   ""name"": ""Gold Plan 999"",
   ""amount"": 10000,
   ""currency"": ""MXN"",
   ""interval"": ""month"",
   ""frequency"": 1,
   ""trial_period_days"": 15,
   ""expiry_count"": 12
}");

planParams := &conekta.PlanParams{}
    planParams.ID = "gold-plam"
    planParams.Name = "plan"
    planParams.Currency = "MXN"
    planParams.Amount = 10000
    planParams.Interval = "month"
    planParams.Frequency = 1
    planParams.TrialPeriodDays = 15
  planParams.ExpiryCount = 9999999
}

plan.Create(planParams)

Paso 4 - Crea una orden con Checkout y relaciona con el Plan y Customer

Al crear el checkout relaciona los planes por medio del campo plan_ids para posteriormente poder generar la suscripción.

Los campos mostrados en el ejemplo son los mínimos requeridos, si deseas mejorar la veracidad de tus transacciones necesitas saber más sobre el objeto order, para ello, revisa nuestra REST API.

Puedes seleccionar el tipo de Checkout para Suscripciones:

Checkout Embebido (Componente incrustado en tu tienda) Tutorial de Apoyo
Checkout Hosted Payment (Componente redireccionado a un sitio externo) Tutorial de Apoyo

curl -H "Accept: application/vnd.conekta-v2.3.0+json" \
     -H "Content-type: application/json" \
     -u YOUR_ACCESS_TOKEN \
     -X POST -d '{
        "currency": "MXN",
        "customer_info": {
           "customer_id": "cus_2oAokFrKM7CyVxGJm"
        },
       "line_items": [{
           "name": "Box of Cohiba S1s",
           "unit_price": 300000,
           "quantity": 1
       }],
       "shipping_lines": [{
           "amount": 0
       }],
       "checkout": {
           "allowed_payment_methods": ["card"],
           "type": "Integration",
           "plan_ids": ["gold-plan"]
       },
       "shipping_contact": {
          "phone": "+5215555555555",
          "receiver": "Marvin Fuller",
          "address": {
            "street1": "Nuevo Leon 4",
            "country": "MX",
            "postal_code": "06100"
          }
       }
}' https://api.conekta.io/orders

Notas de los campos:

currency: moneda en formato ISO 4217 (máx. 3 caracteres); ej. MXN.

customer_id: id de cliente previamente creado.

line_items: la suma de tus productos debe ser igual al costo del Plan.

type: "Integration" para Checkout Embebido, "HostedPayment" para Checkout Redireccionado.

plan_ids: arreglo con los id de los planes que el cliente podrá suscribir desde este checkout; requerido para pagos de suscripción.

<?php 

$validOrderWithCheckout =
array(
  'line_items'=> array(
    array(
      'name'=> 'Box of Cohiba S1s',
      'description'=> 'Imported From Mex.',
      'unit_price'=> 120000,
      'quantity'=> 1,
      'sku'=> 'cohbs1',
      'category'=> 'food',
      'tags' => array('food', 'mexican food')
    )
  ),
  'checkout'    => array(
    'type' => 'Integration',
    'allowed_payment_methods' => array("cash", "card", "bank_transfer"),
    'monthly_installments_enabled' => true,
    'monthly_installments_options' => array(3, 6, 9, 12),
    'plan_ids' => array('gold-plan')
  ),
  'customer_info' => array(
    'customer_id' =>  'cus_2oAokFrKM7CyVxGJm'
  ),
  'currency'    => 'mxn',
  'metadata'    => array('test' => 'extra info')
);
$order = Order::create($validOrderWithCheckout);
print_r($order->checkout);

valid_order_with_checkout =
  {
    line_items: [
      {
        name: 'Box of Cohiba S1s',
        description: 'Imported From Mex.',
        unit_price: 120000,
        quantity: 1,
        sku: 'cohbs1',
        category: 'food',
        tags: ['food', 'mexican food']
      }
    ],
    checkout: {
      type: 'Integration',
      allowed_payment_methods: ["cash", "card", "bank_transfer"],
      monthly_installments_enabled: true,
      monthly_installments_options: [3, 6, 9, 12],
      plan_ids: ['gold-plan'],
    },
    customer_info: {
      customer_id: 'cus_2oAokFrKM7CyVxGJm'
    },
    currency: 'mxn',
    metadata: {'test' => 'extra info'}
  }
order = Conekta::Order.create(valid_order_with_checkout)

checkout = conekta.Checkout.create({
   {
       "name": "Payment Link Name",
       "type": "PaymentLink",
       "plan_ids": ["gold-plan"],
       "recurrent": False,
       "expires_at": 1590882634,
       "allowed_payment_methods": ["cash", "card", "bank_transfer"],
       "needs_shipping_contact": True,
       "monthly_installments_enabled": False,
       "monthly_installments_options": [3, 6, 9, 12],
       "order_template": {
           "line_items": [{
               "name": "Red Wine",
               "unit_price": 1000,
               "quantity": 10
           }],
       "currency": "MXN",
       "customer_info": {
             "customer_id": "cus_2oAokFrKM7CyVxGJm"
       }
     }
   }
})

using Newtonsoft.Json;

var validOrderWithCheckout = new
  {
    line_items = new 
      [
        new
        {
          name = "Box of Cohiba S1s",
          description = "Imported From Mex.",
          unit_price = 120000,
          quantity = 1,
          sku = "cohbs1",
          category = "food",
          tags = new string[] 
            { 
                "food", 
                "mexican food"
            }
        }
      ],
    checkout = new
      {
        type = "Integration",
        plan_ids = new string[] { "gold-plan" },
        allowed_payment_methods = new string[] 
          {
            "cash", 
            "card", 
            "bank_transfer"
          },
        monthly_installments_enabled = true,
        monthly_installments_options = new int[]
          {
            3, 
            6, 
            9, 
            12
          }
      },
    customer_info = new 
      {
        customer_id = "cus_2oAokFrKM7CyVxGJm"
      },
    currency: "mxn",
    metadata: new 
      {
        test = "extra info"
      }
  };

var order = new Order()
  .create(JsonConvert.SerializeObject(validOrderWithCheckout));

Paso 5 - Paga el Checkout creado en la orden

Por último, realiza el pago del checkout con forma de pago tarjeta y completa el proceso de pago.

* Para Suscripciones en Checkout, solo está disponible pago con tarjeta.

Te mostrará los detalles del plan con el cual se va a generar la suscripción y te mostrará los campos para ingresar los datos de tu tarjeta.

Al ingresar correctamente los datos y dar click en finalizar se crea la suscripción y se mostrarán los detalles de esta misma.

Pausando, reanudando, cancelando y actualizando suscripciones

Una parte importante del ciclo de tu cliente es permitirles cambiar, pausar y cancelar la suscripción.

Pausar

Es posible pausar una suscripción siempre y cuando esta se encuentre activa, para continuar haciendo los cargos es necesario reanudar la suscripción. Puedes consultarlo en la siguiente referencia

Reanudar

Una suscripción se puede reanudar cuando ha sido pausada con anterioridad. Puedes consultarlo en la siguiente referencia

Cancelar

En caso de querer terminar la suscripción antes de cumplir con el número de cobros indicados por el plan, se puede cancelar la suscripción. Puedes consultarlo en la siguiente referencia

Actualizar

En caso de actualizar el plan de una suscripción del Plan A al Plan B, se comenzará a realizar el cobro del Plan B en el momento que se termine el ciclo de cobro del Plan A. Puedes consultarlo en la siguiente referencia