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

Al crear un customer con la información de tu cliente en conjunto con el token que ConektaJS te proporcionó anteriormente tendrás la capacidad de hacer cargos recurrentes y on-demand siempre y cuando el usuario final esté consciente de ello.

Un customer puede tener muchos payment_sources pero sólo uno puede ser el default al cual se carga la suscripción.

Los campos mostrados en el ejemplo son los mínimos requeridos, si deseas saber más sobre el objeto customer revisa nuestra <a href="https://conekta-dev-center.readme.io/reference#clientes" REST API.

curl --request POST \
  --url https://api.conekta.io/customers \
  --header 'accept: application/vnd.conekta-v2.0.0+json' \
  -u key_eYvWV7gSDkNYXsmr: \
  --header 'content-type: application/json' \
  --data '{
  "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" => ["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 key_eYvWV7gSDkNYXsmr: \
     -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

\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.

curl -H "Accept: application/vnd.conekta-v2.0.0+json" \
     -H "Content-type: application/json" \
     -u key_eYvWV7gSDkNYXsmr: \
     -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": ["cash", "card", "bank_transfer"],
           "monthly_installments_enabled": true,
           "monthly_installments_options": [3,6,9,12,18],
           "expires_at": 1597276799,
           "type": "Integration",
           “planId: “gold-plan”
       },
       "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.

* Elige el método de pago, en esta ocasión solo está disponible 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.

Reanudar

Una suscripción se puede reanudar cuando ha sido pausada con anterioridad.

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.

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.