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.

Suscripciones con tarjeta

Suscripciones con tarjeta

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

📘

Primeros pasos

  • Es necesario contar con conocimiento de APIs.
  • Es preferible ser desarrollador fullstack (frontend + backend).
  • Instalar e incluir una de las librerías disponibles de Conekta.
  • Contar con tus API Keys (llave personal) de pruebas.

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

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.

Paso 4 - Relaciona a tu cliente

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

$subscription = $customer->createSubscription(
  [
    'plan' => 'plan-mensual'
  ]
);

subscription = customer.create_subscription(
  plan: "plan-mensual"
);

subscription = customer.subscription.update({
  "plan": "plan-mensual"
})

customer.createSubscription({
  "plan": "plan-mensual"
}, function(err, res) {
      console.log(res.toObject());
});

customer.createSubscription (@"{
  ""plan"": ""plan-mensual""
}");

Paso 5 - Recibir el evento

Para poder confirmar los pagos que se realicen en el intervalo que indicaste deberás añadir un Webhook en tu Admin Conekta para recibir las notificaciones POST (HTTP JSON) correctamente.

Utiliza URLs públicos: Si no tienes un IP público o un domino a tu disposición, puedes utilizar servicios como ultrahook o localtunnel.

Consultar la referencia sobre Webhooks.

{
  "data": {
    "object": {
      "id": "588258fbedbb6e85e7000f95",
      "livemode": false,
      "created_at": 1598283970,
      "currency": "MXN",
      "payment_method": {
        "service_name": "OxxoPay",
        "object": "cash_payment",
        "type": "oxxo",
        "expires_at": 1600875970,
        "store_name": "OXXO",
        "reference": "93345678901234"
      },
      "details": {
        "name": "Fulanito Pérez",
        "phone": "+5218181818181",
        "email": "[email protected]",
        "line_items": [{
            "name": "Tacos",
            "unit_price": 1000,
            "quantity": 12
        }],
        "shipping_contact": {
           "phone": "5555555555",
           "receiver": "Bruce Wayne",
           "address": {
             "street1": "Calle 123 int 2 Col. Chida",
             "city": "Cuahutemoc",
             "state": "Ciudad de Mexico",
             "country": "MX",
             "postal_code": "06100",
             "residential": true
           }
         },
        "object": "details"
      },
      "object": "charge",
      "status": "paid",
      "amount": 13500,
      "paid_at": 1484937498,
      "fee": 1421,
      "customer_id": "",
      "order_id": "ord_2fshhd1RAEnB5zUfG",
    },
    "previous_attributes": {
      "status": "pending_payment"
    }
  },
  "livemode": false,
  "webhook_status": "successful",
  "webhook_logs": [
    {
      "id": "webhl_2fshi2CmCGqx4p6go",
      "url": "https://www.example.com/my_webhook_listener",
      "failed_attempts": 0,
      "last_http_response_status": 200,
      "object": "webhook_log",
      "last_attempted_at": 1484937503
    }
  ],
  "id": "5882591b5906e7819c0007f1",
  "object": "event",
  "type": "charge.paid",
  "created_at": 1598283970
}

Paso 6 - Notifica a tu cliente

Una buena práctica es notificar a tu usuario.

Paso 7 - Prueba tu webhook

Dentro de tu Admin Conekta puedes probar la funcionalidad de tu webhook

¿Qué necesitarás? La URL de tu webhook y acceso al Admin Conekta.

👍

¡Listo!

Recuerda cambiar tus llaves pública y privada de pruebas por tus llaves de producción después de realizar pruebas.

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