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.

Pagos con OXXO Pay Recurrente

Pagos con OXXO Pay Recurrente

Creamos OXXO Pay Recurrente para que puedas recibir pagos recurrentes. De esta forma tus clientes podrán pagar la cantidad de veces que necesiten, y que tú autorices. En el caso de OXXO Pay Recurrente cada uno de tus clientes tendrá una referencia única para realizar varios pagos.

A continuación, los pasos para usar OXXO Pay Recurrente.

📘

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 tu OXXO Pay Recurrente

CUSTOM_REFERENCE_RETURNED​ se refiere a su ​referencia personalizada ​y barcode_url es la imagen del código de barras generada.

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",
      "email": "[email protected]",
      "phone": "+5218181818181",
      "payment_method": {
        "type": "oxxo_recurrent"
      }
  }'

#Respuesta json de API
{
"livemode":​false​, 
"name":​"Oxxo recc"​, 
"email":​"[email protected]"​, 
"phone":​"52134659439"​, 
"id":​"cus_2jP5P8huCTWqcTtrn"​, 
"object":​"customer"​,
"created_at":​1538686075​, 
"corporate":​false​, 
"custom_id":​""​, 
"payment_sources":{
    "object":​"list"​, 
    "has_more":​false​, 
    "total":​1​,
"data":[{
"id":​"off_ref_2jP5P8huCTWqcTtro"​, 
"object":​"payment_source"​, 
"type":​"oxxo_recurrent"​,
"provider":​"Oxxo"​, 
"reference":​"CUSTOM_REFERENCE_RETURNED"​, 
"barcode":​"CUSTOM_REFERENCE_RETURNED"​, 
"barcode_url":​"https://sandbox_reference.png"​,
"expires_at":​0​, 
"created_at":​1538686075​, 
"parent_id":​"cus_2jP5P8huCTWqcTtrn" }]
}}try{
    $customer = \Conekta\Customer::create(
      array(
          'name'  => "fulanito",
          'email' => "[email protected]",
          'phone' => "+5218181818181",
          'payment_sources' => array(
                array(
                'type' => "oxxo_recurrent"
                )
            )
      )
    );
    var_dump(json_encode($customer));
  } catch (\Conekta\ProcessingError $error){
    echo $error->getMessage();
  } catch (\Conekta\ParameterValidationError $error){
    echo $error->getMessage();
  } catch (\Conekta\Handler $error){
    echo $error->getMessage();
  }

#Respuesta json de API
{
"livemode":​false​, 
"name":​"Oxxo recc"​, 
"email":​"[email protected]"​, 
"phone":​"52134659439"​, 
"id":​"cus_2jP5P8huCTWqcTtrn"​, 
"object":​"customer"​,
"created_at":​1538686075​, 
"corporate":​false​, 
"custom_id":​""​, 
"payment_sources":{
    "object":​"list"​, 
    "has_more":​false​, 
    "total":​1​,
"data":[{
"id":​"off_ref_2jP5P8huCTWqcTtro"​, 
"object":​"payment_source"​, 
"type":​"oxxo_recurrent"​,
"provider":​"Oxxo"​, 
"reference":​"CUSTOM_REFERENCE_RETURNED"​, 
"barcode":​"CUSTOM_REFERENCE_RETURNED"​, 
"barcode_url":​"https://sandbox_reference.png"​,
"expires_at":​0​, 
"created_at":​1538686075​, 
"parent_id":​"cus_2jP5P8huCTWqcTtrn" }]
}}
try{
    $customer = \Conekta\Customer::create(
      array(
          'name'  => "fulanito",
          'email' => "[email protected]",
          'phone' => "+5218181818181",
          'payment_sources' => array(
                array(
                'type' => "oxxo_recurrent"
                )
            )
      )
    );
    var_dump(json_encode($customer));
  } catch (\Conekta\ProcessingError $error){
    echo $error->getMessage();
  } catch (\Conekta\ParameterValidationError $error){
    echo $error->getMessage();
  } catch (\Conekta\Handler $error){
    echo $error->getMessage();
  }

#Respuesta json de API
{
"livemode":​false​, 
"name":​"Oxxo recc"​, 
"email":​"[email protected]"​, 
"phone":​"52134659439"​, 
"id":​"cus_2jP5P8huCTWqcTtrn"​, 
"object":​"customer"​,
"created_at":​1538686075​, 
"corporate":​false​, 
"custom_id":​""​, 
"payment_sources":{
    "object":​"list"​, 
    "has_more":​false​, 
    "total":​1​,
"data":[{
"id":​"off_ref_2jP5P8huCTWqcTtro"​, 
"object":​"payment_source"​, 
"type":​"oxxo_recurrent"​,
"provider":​"Oxxo"​, 
"reference":​"CUSTOM_REFERENCE_RETURNED"​, 
"barcode":​"CUSTOM_REFERENCE_RETURNED"​, 
"barcode_url":​"https://sandbox_reference.png"​,
"expires_at":​0​, 
"created_at":​1538686075​, 
"parent_id":​"cus_2jP5P8huCTWqcTtrn" }]
}}
begin
  customer = Conekta::Customer.create({
        name: "Fulanito",
        email: "[email protected]",
        phone: "52134659439",
        payment_method: {
            type: "oxxo_recurrent"
        }
  })
rescue Conekta::Error => error
  for error_detail in error.details do
    puts error_detail.message
  end
end
try:
  customer = conekta.Customer.create({
      "name": "Fulanito",
      "email": "[email protected]",
      "phone": "+5218181818181",
      "payment_method": {
        "type": "oxxo_recurrent"
      }
  })
except conekta.ConektaError as e:
  print e.message

#Respuesta json de API
{
"livemode":​false​, 
"name":​"Oxxo recc"​, 
"email":​"[email protected]"​, 
"phone":​"52134659439"​, 
"id":​"cus_2jP5P8huCTWqcTtrn"​, 
"object":​"customer"​,
"created_at":​1538686075​, 
"corporate":​false​, 
"custom_id":​""​, 
"payment_sources":{
    "object":​"list"​, 
    "has_more":​false​, 
    "total":​1​,
"data":[{
"id":​"off_ref_2jP5P8huCTWqcTtro"​, 
"object":​"payment_source"​, 
"type":​"oxxo_recurrent"​,
"provider":​"Oxxo"​, 
"reference":​"CUSTOM_REFERENCE_RETURNED"​, 
"barcode":​"CUSTOM_REFERENCE_RETURNED"​, 
"barcode_url":​"https://sandbox_reference.png"​,
"expires_at":​0​, 
"created_at":​1538686075​, 
"parent_id":​"cus_2jP5P8huCTWqcTtrn" }]
}}
customer = conekta.Customer.create({
    "name": "Fulanito",
    "email": "[email protected]",
    "phone": "+5218181818181",
    "payment_method": {
      "type": "oxxo_recurrent"
    }
}, function(err, res) {
    console.log(res.toObject());
});

//Respuesta json de API
{
"livemode":​false​, 
"name":​"Oxxo recc"​, 
"email":​"[email protected]"​, 
"phone":​"52134659439"​, 
"id":​"cus_2jP5P8huCTWqcTtrn"​, 
"object":​"customer"​,
"created_at":​1538686075​, 
"corporate":​false​, 
"custom_id":​""​, 
"payment_sources":{
    "object":​"list"​, 
    "has_more":​false​, 
    "total":​1​,
"data":[{
"id":​"off_ref_2jP5P8huCTWqcTtro"​, 
"object":​"payment_source"​, 
"type":​"oxxo_recurrent"​,
"provider":​"Oxxo"​, 
"reference":​"CUSTOM_REFERENCE_RETURNED"​, 
"barcode":​"CUSTOM_REFERENCE_RETURNED"​, 
"barcode_url":​"https://sandbox_reference.png"​,
"expires_at":​0​, 
"created_at":​1538686075​, 
"parent_id":​"cus_2jP5P8huCTWqcTtrn" }]
}}
try{
  Customer customer = Customer.create(
    new JSONObject("{"
        + "'name': 'Fulanito',"
        + "'email': '[email protected]',"
        + "'phone': '+5218181818181',"
        + "'payment_method': {"
          + "'type': 'oxxo_recurrent',"
        + "}"
    + "}"
    )
  );
}catch (Conekta::Error e) {
   System.out.println(e.details.get(0).message);
}

//Respuesta json de API
{
"livemode":​false​, 
"name":​"Oxxo recc"​, 
"email":​"[email protected]"​, 
"phone":​"52134659439"​, 
"id":​"cus_2jP5P8huCTWqcTtrn"​, 
"object":​"customer"​,
"created_at":​1538686075​, 
"corporate":​false​, 
"custom_id":​""​, 
"payment_sources":{
    "object":​"list"​, 
    "has_more":​false​, 
    "total":​1​,
"data":[{
"id":​"off_ref_2jP5P8huCTWqcTtro"​, 
"object":​"payment_source"​, 
"type":​"oxxo_recurrent"​,
"provider":​"Oxxo"​, 
"reference":​"CUSTOM_REFERENCE_RETURNED"​, 
"barcode":​"CUSTOM_REFERENCE_RETURNED"​, 
"barcode_url":​"https://sandbox_reference.png"​,
"expires_at":​0​, 
"created_at":​1538686075​, 
"parent_id":​"cus_2jP5P8huCTWqcTtrn" }]
}}
try{
  conekta.Customer customer = new conekta.Customer ().create(@"{
      ""name"": ""Fulanito"",
      ""email"": ""[email protected]"",
      ""phone"": ""+5218181818181"",
      ""payment_method"": {
        ""type"": ""oxxo_recurrent"",
      }
  }");
} 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"));
  }
}

//Respuesta json de API
{
"livemode":​false​, 
"name":​"Oxxo recc"​, 
"email":​"[email protected]"​, 
"phone":​"52134659439"​, 
"id":​"cus_2jP5P8huCTWqcTtrn"​, 
"object":​"customer"​,
"created_at":​1538686075​, 
"corporate":​false​, 
"custom_id":​""​, 
"payment_sources":{
    "object":​"list"​, 
    "has_more":​false​, 
    "total":​1​,
"data":[{
"id":​"off_ref_2jP5P8huCTWqcTtro"​, 
"object":​"payment_source"​, 
"type":​"oxxo_recurrent"​,
"provider":​"Oxxo"​, 
"reference":​"CUSTOM_REFERENCE_RETURNED"​, 
"barcode":​"CUSTOM_REFERENCE_RETURNED"​, 
"barcode_url":​"https://sandbox_reference.png"​,
"expires_at":​0​, 
"created_at":​1538686075​, 
"parent_id":​"cus_2jP5P8huCTWqcTtrn" }]
}}
payment := &conekta.PaymentSourceCreateParams{
    PaymentType: "oxxo_recurrent",
}

cus := &conekta.CustomerParams{}
cus.Name = "fulanito"
cus.Email = "[email protected]"
cus.Phone = "+5215555555555"
cus.PaymentSources = append(cus.PaymentSources, payment)

res, err := customer.Create(cus)

//Respuesta de API
{
"livemode":​false​, 
"name":​"Oxxo recc"​, 
"email":​"[email protected]"​, 
"phone":​"52134659439"​, 
"id":​"cus_2jP5P8huCTWqcTtrn"​, 
"object":​"customer"​,
"created_at":​1538686075​, 
"corporate":​false​, 
"custom_id":​""​, 
"payment_sources":{
    "object":​"list"​, 
    "has_more":​false​, 
    "total":​1​,
"data":[{
"id":​"off_ref_2jP5P8huCTWqcTtro"​, 
"object":​"payment_source"​, 
"type":​"oxxo_recurrent"​,
"provider":​"Oxxo"​, 
"reference":​"CUSTOM_REFERENCE_RETURNED"​, 
"barcode":​"CUSTOM_REFERENCE_RETURNED"​, 
"barcode_url":​"https://sandbox_reference.png"​,
"expires_at":​0​, 
"created_at":​1538686075​, 
"parent_id":​"cus_2jP5P8huCTWqcTtrn" }]
}}

Paso 3 - Presentar ficha de pago

Utiliza una ficha como esta para darle a tu cliente la referencia de pago junto con los pasos necesarios para completar la compra.

Ficha OXXO PAY

Inclúyela en tu checkout o envíala por correo para ofrecer una mejor experiencia.
Consulta el repo en Github.

Paso 4 - Crear un Webhook

Como mencionamos al principio, nuestra plataforma debe estar en constante comunicación contigo a través de Webhooks para:

1)​ Validar que la referencia del usuario sea correcta y pueda hacer pagos.

2)​ Aprobar la cantidad que el usuario quiere abonar.

3)​ Notificar un pago.

Un Webhook es un sistema de notificaciones, donde tu plataforma web debe definir una URL, para que nuestra API mande peticiones HTTP y pueda notificarte de los distintos eventos que posteriormente vamos a especificar. Por ello, deberás crear un Webhook desde tu Admin. De esta forma estarás activando la notificación de eventos. En el Admin. abre el menú principal de tu cuenta, ubicado en la esquina superior derecha, y selecciona la sección ​Webhooks​.

Dentro de esa sección verás un botón llamado ​crear webhook​, al presionarlo se abrirá un modal con un formulario en el que deberás colocar la url del webhook donde deseas recibir los eventos de OXXO Pay Recurrente, de igual manera deberás de seleccionar la opción de "Usar para Oxxo Pay Recurrente".

Después de crear una referencia para tus clientes y añadir un ​Webhook​ a tu ​Admin Conekta, estarás listo para recibir pagos.

Si lo deseas, puedes ver más información de eventos y configuración de webhook.

Con todo esto configurado ahora podrás utilizar OXXO Pay Recurrente para tus clientes.