Conekta Dev Center

Conekta Developer's Hub

Bienvenido al Conekta Developer's Hub. Aquí encontrarás la más robusta documentación del API Conekta y todos los tutoriales que te ayudarán a comenzar a recibir pagos de la manera más rápida, sencilla y segura.

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.0.0");

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

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

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

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

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

import (
    conekta "github.com/conekta/conekta-go"
)
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.0.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.0.0+json" \
     -H "Content-type: application/json" \
     -u YOUR_ACCESS_TOKEN \
     -X POST -d '{
       "id": "gold-plan",
       "name": "Gold Plan",
       "amount": 10000,
       "currency": "MXN",  //Solo se aceptan MXN
       "interval": "month",  // "week", "half_month", "month", "year"
       "frequency": 1,  //Frecuencia según intervalo seleccionado
       "trial_period_days": 15, // Días de prueba
       "expiry_count":12   //Cantidad de Pagos a recibir
     }' https://api.conekta.io/plans

\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 el plan por medio del campo “planId” 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:

curl -H "Accept: application/vnd.conekta-v2.0.0+json" \
     -H "Content-type: application/json" \
     -u YOUR_ACCESS_TOKEN \
     -X POST -d '{
        "currency": "MXN",  //Solo acepta MXN
        "customer_info": {
           "customer_id": "cus_2oAokFrKM7CyVxGJm"  //Id de cliente previamente creado
        },
       "line_items": [{         //La suma de tus productos debe ser igual al costo del Plan
           "name": "Box of Cohiba S1s",
           "unit_price": 300000,
           "quantity": 1
       }],
       "shipping_lines": [{
           "amount": 0
       }],
       "checkout": {
           "allowed_payment_methods": ["card"],
           "type": "Integration", // "Integration" para Checkout Embebido, "HostedPayment" para Checkout Redireccionado
           “planId: “gold-plan”   //Id de plan previamente creado
       },
       "shipping_contact": {
          "phone": "+5215555555555",
          "receiver": "Marvin Fuller",
          "address": {
            "street1": "Nuevo Leon 4",
            "country": "MX",
            "postal_code": "06100"
          }
       }
}' https://api.conekta.io/orders

<?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),
    'planId' => '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_id: '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_id": "gold-plan",
       "recurrent": False,
       "expired_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_id = "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