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.

Checkout redireccionado

Utiliza el checkout de conekta a través de una redirección.

📘

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: Crear un customer

curl -H "Accept: application/vnd.conekta-v2.0.0+json" \
     -H "Content-type: application/json" \
     -u key_XXXXXXXXXXXX: \
     -X POST -d '{
    "name": "Juan Perez",
    "email": "[email protected]"
}' https://api.conekta.io/customers

<?php

$validCustomer = [
  'name' => "Payment Link Name",
  'email' => "[email protected]"
];
$customer = Customer::create($validCustomer);

# Inicialización del cliente Conekta a través de la adición de la llave privada y versión del API
require "conekta"
Conekta.api_key = "key_eYvWV7gSDkNYXsmr" # <-- Mock private key, please use YOUR personal private key
Conekta.api_version = "2.0.0"

valid_customer = {
  name: "Payment Link Name",
  email: "[email protected]"
}
customer = Conekta::Customer.create(valid_customer)

let customer = conekta.Customer.create({
    name: "Payment Link Name",
    email: "[email protected]"
  }, function(err, res) {
      if(err){
        console.log(err);
        return;
      }
      console.log(res.toObject());
  });

using Newtonsoft.Json;

var validCustomer = new 
  {
    name = "Payment Link Name",
    email = "[email protected]"
  };

var customer = new Customer().create(validCustomer);

import (
    "fmt"
    conekta "github.com/conekta/conekta-go"
    "github.com/conekta/conekta-go/customer"
)

conekta.APIKey = "key_pMcnDF4zFyWKyLG15LuqwA"

customerParams := &conekta.CustomerParams{
    Name: "Payment Link Name",
    Email: "[email protected]",
}

customerResponse, err := customer.Create(customerParams)

//Inicialización del cliente Conekta a través de la adición de la llave privada y versión del API.
Conekta.setApiKey("key_eYvWV7gSDkNYXsmr"); //  <-- Mock private key, please use YOUR personal private key
com.conekta.Conekta.apiVersion = "2.0.0"
  
  Customer customer = Customer.create(
    new JSONObject("{"
      + "'name': 'Fulanito Pérez', "
      + "'email': '[email protected]'"
      + "}"
    )
  );

Esto regresa una respuesta como la siguiente:

{
    "livemode": false,
    "name": "Vicente Mendoza",
    "email": "[email protected]",
    "id": "cus_2neG7CYFDERras9GGU",
    "object": "customer",
    "created_at": 1588684774,
    "corporate": false,
    "custom_reference": ""
}

<?php 

echo $customer->livemode;
echo $customer->name;
echo $customer->email;
echo $customer->id;
echo $customer->object;

puts customer.livemode
puts customer.name
puts customer.email
puts customer.id
puts customer.object

console.log(customer.livemode);
console.log(customer.name);
console.log(customer.email);
console.log(customer.id);

Console.WriteLine(customer.livemode);
Console.WriteLine(customer.name);
Console.WriteLine(customer.email);
Console.WriteLine(customer.id);
Console.WriteLine(customer._object);

fmt.Println("Livemode: %v\n", customerResponse.Livemode)
fmt.Println("Name: %v\n", customerResponse.Name)
fmt.Println("Email: %v\n", customerResponse.Email)
fmt.Println("ID: %v\n", customerResponse.ID)

System.out.println(customer.livemode);
System.out.println(customer.name);
System.out.println(customer.email);
System.out.println(customer.id);

Paso 2: Crear una orden vacía con opciones de checkout.

El siguiente snippet incorpora todas las partes del paso 1. Copia y pega el siguiente fragmento de código en tu sandbox y corre el código para crear una orden y un checkout object al mismo tiempo. Aquí se definen las urls de redirección una vez que se haya completado ya sea exitoso o fallido el pago.

curl -H "Accept: application/vnd.conekta-v2.0.0+json" \
     -H "Content-type: application/json" \
     -u key_XXXXXXXXXXX: \
     -X POST -d '{
        "currency": "MXN",
        "customer_info": {
           "customer_id": "cus_2nHprwaWFn7QJ21Lj"
        },
       "line_items": [{
           "name": "Box of Cohiba S1s",
           "unit_price": 35000,
           "quantity": 1
       }],
       "shipping_lines": [{
           "amount": 0
       }],
       "checkout": {
           "allowed_payment_methods": ["cash", "card", "bank_transfer"],
           "type": "HostedPayment",
           "success_url": "https://www.mysite.com/payment/confirmation",
           "failure_url": "https://www.mysite.com/payment/failure",
           "monthly_installments_enabled": true,
           "monthly_installments_options": [3, 6, 9, 12],
           "redirection_time": 4 //Tiempo de Redirección al Success/Failure URL, umbrales de 4 a 20 seg.
        },
       "shipping_contact": {
          "phone": "+5215555555555",
          "receiver": "Marvin Fuller",
          "address": {
            "street1": "Nuevo Leon 4",
            "country": "MX",
            "postal_code": "06100"
          }
       }
}' https://api.conekta.io/orders

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: {
       allowed_payment_methods: ["cash", "card", "bank_transfer"],
       expires_at: Time.now.to_i + 259200,
       failure_url: "testredirect.com",
       force_2fa_flow: true,
       success_url: "testredirect.com",
       monthly_installments_enabled: true,
       monthly_installments_options: [3, 6, 9, 12],
       type: "HostedPayment",
       redirection_time: 4 # Tiempo de Redirección al Success/Failure URL, umbrales de 4 a 20 seg.
   },
   customer_info: {
       customer_id: customer.id
   },
   currency: 'mxn',
   metadata: {test: 'extra info'}
}
order = Conekta::Order.create(valid_order_with_checkout)
puts order.inspect

<?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(
    'allowed_payment_methods' => array("cash", "card", "bank_transfer"),
    'type' => 'HostedPayment',
    'success_url' => 'https://www.mysite.com/payment/confirmation',
    'failure_url' => 'https://www.mysite.com/payment/failure',
    'monthly_installments_enabled' => true,
    'monthly_installments_options' => array(3, 6, 9, 12),
    "redirection_time": 4 //Tiempo de Redirección al Success/Failure URL, umbrales de 4 a 20 seg.
  ),
  'customer_info' => array(
    'customer_id'   =>  'cus_2nHprwaWFn7QJ21Lj'
  ),
  'currency'    => 'mxn',
  'metadata'    => array('test' => 'extra info')
);
$order = Order::create($validOrderWithCheckout);

order = self.client.Order.create(order)
checkout = order.createCheckout({
       "currency": "MXN",
       "customer_info": {
          "customer_id": "cus_2o3FvMEBiKitVK1vQ"
       },
      "line_items": [{
          "name": "Box of Cohiba S1s",
          "unit_price": 300000,
          "quantity": 1
      }],
      "shipping_lines": [{
          "amount": 0
      }],
      "checkout": {
          "type":"HostedPayment",
          "success_url": "testredirect.com",
          "failure_url": "testredirect.com",
          "allowed_payment_methods": ["cash", "card", "bank_transfer"],
          "multifactor_authentication": False,
          "monthly_installments_enabled": True,
          "monthly_installments_options": [3,6,9,12,18],
          "expires_at": 1609891200,
          "redirection_time": 4 //Tiempo de Redirección al Success/Failure URL, umbrales de 4 a 20 seg.
      
       },
      "shipping_contact": {
         "phone": "+5215555555555",
         "receiver": "Marvin Fuller",
         "address": {
           "street1": "Nuevo Leon 4",
           "country": "MX",
           "postal_code": "06100"
         }
      }
   })

conekta.Order.create({
       "currency": "MXN",
       "customer_info": {
          "customer_id": customer.id
       },
      "line_items": [{
          "name": "Box of Cohiba S1s",
          "unit_price": 300000,
          "quantity": 1
      }],
      "shipping_lines": [{
          "amount": 0
      }],
      "checkout": {
          "type":"HostedPayment",
          "success_url": "testredirect.com",
          "failure_url": "testredirect.com",
          "allowed_payment_methods": ["cash", "card", "bank_transfer"],
          "multifactor_authentication": False,
          "monthly_installments_enabled": True,
          "monthly_installments_options": [3,6,9,12,18],
          "expires_at": 1609891200,
          "redirection_time": 4 //Tiempo de Redirección al Success/Failure URL, umbrales de 4 a 20 seg.
       },
      "shipping_contact": {
         "phone": "+5215555555555",
         "receiver": "Marvin Fuller",
         "address": {
           "street1": "Nuevo Leon 4",
           "country": "MX",
           "postal_code": "06100"
         }
      }
   }, function(err, res) {
      if(err){
        console.log(err);
        return;
      }
      console.log(res.toObject());
  });

using Newtonsoft.Json;

var validOrderWithCheckout = new
  {
    currency: "MXN",
    customer_info = new 
      {
        customer_id = "cus_2o3FvMEBiKitVK1vQ"
      },
    line_items = new 
      [
        new
        {
          name = "Box of Cohiba S1s",
          unit_price = 300000,
          quantity = 1
        }
      ],
    shipping_lines = new 
      [
        new
          {
            "amount" = 0
          }
      ],
    checkout = new
      {
        type = "HostedPayment",
        success_url = "testredirect.com",
        failure_url = "testredirect.com",
        allowed_payment_methods = new string[] 
          {
            "cash", 
            "card", 
            "bank_transfer"
          },
        multifactor_authentication = false,
        monthly_installments_enabled = true,
        monthly_installments_options = new int[]
          {
            3, 
            6, 
            9, 
            12
          },
        expires_at = 1609891200,
        redirection_time= 4 //Tiempo de Redirección al Success/Failure URL, umbrales de 4 a 20 seg.
      },
     shipping_contact = new
       {
         phone = "+5215555555555",
         receiver = "Marvin Fuller",
         address = new 
           {
             street1 = "Nuevo Leon 4",
             country = "MX",
             postal_code = "06100"
           }
      }
  };

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

orderParams := &conekta.OrderParams{
    Currency: "MXN",
    CustomerInfo: &CustomerParams{
        ID: customerResponse.ID,
    },
    LineItems: []*LineItemsParams{
        {
            Name:      "Box of Cohiba S1s",
            UnitPrice: 120000,
            Quantity:  1,
        },
    },
    Checkout: &OrderCheckoutParams{
    Type: "HostedPayment",
    SuccessUrl: "testredirect.com",
    FailureUrl: "testredirect.com",
    OnDemandEnabled: false,
    MonthlyInstallmentsEnabled: trye,
    MonthlyInstallmentsOptions: []int64{3, 6, 9, 12},
        ExpiresAt:             time.Now().Unix() + int64(259200) + int64(rand.Float64()*3600),
        AllowedPaymentMethods: []string{"cash", "card", "bank_transfer"},
    Redirection_time: 4 //Tiempo de Redirección al Success/Failure URL, umbrales de 4 a 20 seg.
    }
}

orderResponse, err := order.Create(orderParams)

try {
  Order order = Order.create(
      new JSONObject("{ 'currency': 'mxn'," +
                        " 'customer_info': {" +
                        "   'customer_id': 'cus_2o3FvMEBiKitVK1vQ'" +
                        "  }," +
                        "  'line_items': [{" +
                        "    'name': 'Box of Cohiba S1s'," +
                        "    'unit_price': 300000," +
                        "    'quantity': 1," +
                        "  }]," +
                        "  'checkout': {" +
                        "    'allowed_payment_methods': ['cash','card','bank_transfer']," +
                        "    'expired_at': " + (System.currentTimeMillis() / 1000L) + 259200 + "," +
                        "    'failure_url': 'testredirect.com'," +
                        "    'force_3ds_flow': false," +
                        "    'monthly_installments_enabled': true," +
                        "    'monthly_installments_options': [3,6,9,12,18]," +
                        "    'success_url': 'testredirect.com'," +
                        "    'type': 'HostedPayment'" +
                        "    'redirection_time': 4," +
                        "  }," +
                        "  'shipping_contact': {" +
                        "    'phone': '5555555555'," +
                        "    'receiver': 'Marvin Fuller'" +
                        "  }" +
                        "}")
    );
} catch (Conekta::Error e) {
   System.out.println(e.details.get(0).message);
}

Esto regresa una respuesta como la siguiente, donde es importante obtener la url para el checkout.

{
    "livemode": false,
    "amount": 35000,
    "currency": "MXN",
    "payment_status": "paid",
    "amount_refunded": 0,
    "checkout": {
        "id": "42a4c95e-0db2-4ae8-9bb3-ea681acc8281",
        "object": "checkout",
        "type": "HostedPayment",
        "status": "Issued",
        "url": "https://pay.conektame.io/link/964b5bdfe557467d9e02469e89b48e19",
        "allowed_payment_methods": ["cash", "card", "bank_transfer"],
        "needs_shipping_contact": true,
        "livemode": true
    },
    "customer_info": {
        "email": "[email protected]",
        "name": "Mario Perez",
        "corporate": false,
        "customer_id": "cus_2nHprwaWFn7QJ21Lj",
        "object": "customer_info"
    },
    "shipping_contact": {
        "receiver": "Marvin Fuller",
        "phone": "+5215555555555",
        "address": {
            "street1": "Nuevo Leon 4",
            "country": "mx",
            "residential": true,
            "object": "shipping_address",
            "postal_code": "06100"
        },
        "id": "ship_cont_2nYNo3xT815RRppom",
        "object": "shipping_contact",
        "created_at": 0
    },
    "object": "order",
    "id": "ord_2nYNo3xT815RRppon",
    "metadata": {},
    "created_at": 1587129536,
    "updated_at": 1587129537,
    "line_items": {
        "object": "list",
        "has_more": false,
        "total": 1,
        "data": [{
            "name": "Box of Cohiba S1s",
            "unit_price": 35000,
            "quantity": 1,
            "object": "line_item",
            "id": "line_item_2nYNo3xT815RRppoi",
            "parent_id": "ord_2nYNo3xT815RRppon",
            "metadata": {},
            "antifraud_info": {}
        }]
    },
    "shipping_lines": {
        "object": "list",
        "has_more": false,
        "total": 1,
        "data": [{
            "amount": 0,
            "object": "shipping_line",
            "id": "ship_lin_2nYNo3xT815RRppoj",
            "parent_id": "ord_2nYNo3xT815RRppon"
        }]
    }
}

<?php

print_r((array) $order->checkout->allowed_payment_methods); // array("cash", "card", "bank_transfer")
print_r($order->checkout->monthly_installments_enabled); // true
print_r((array) $order->checkout->monthly_installments_options); // array(3, 6, 9, 12)
print_r($order->checkout->object); // 'checkout'
print_r($order->checkout->url); // 'https://pay.conektame.io/link/964b5bdfe557467d9e02469e89b48e19
print_r($order->checkout->type); // 'HostedPayment'

puts order.checkout.allowed_payment_methods.inspect
puts order.checkout.monthly_installments_enabled
puts order.checkout.monthly_installments_options.inspect
puts order.checkout.object
puts order.checkout.url
puts order.checkout.type

Console.WriteLine("[{0}]", string.Join(", ", order.checkout.allowed_payment_methods)); // [cash, card, bank_transfer]
Console.WriteLine(order.checkout.monthly_installments_enabled); // true
Console.WriteLine("[{0}]", string.Join(", ", order.checkout.monthly_installments_options)); // [3, 6, 9, 12]
Console.WriteLine(order.checkout._object); // 'checkout'
Console.WriteLine(order.checkout.url); // 'https://pay.conektame.io/link/964b5bdfe557467d9e02469e89b48e19
Console.WriteLine(order.checkout.type); // 'HostedPayment'

console.log(stringify(order.checkout.allowed_payment_methods)); // [cash, card, bank_transfer]
console.log(stringify(order.checkout.monthly_installments_enabled)); // true
console.log(stringify(order.checkout.monthly_installments_options)); // [3, 6, 9, 12]
console.log(stringify(order.checkout.url)); // 'https://pay.conektame.io/link/964b5bdfe557467d9e02469e89b48e19
console.log(strinfiy(order.checkout.type)); // 'HostedPayment'

fmt.Println("AllowedPaymentMethod: %v\n", orderResponse.Checkout.AllowedPaymentMethods)
fmt.Println("MonthlyInstallmentsEnabled: %v\n", orderResponse.Checkout.MonthlyInstallmentsEnabled)
fmt.Println("MonthlyInstallmentOptions: %v\n", orderResponse.Checkout.MonthlyInstallmentsOptions)
fmt.Println("Url: %v\n", orderResponse.Checkout.Url)
fmt.Println("Type: %v\n", orderResponse.Checkout.Type)

System.out.println(order.checkout.allowed_payment_methods);
System.out.println(order.checkout.monthly_installments_enabled);
System.out.println(order.checkout.monthly_installments_options);
System.out.println(order.checkout.object);
System.out.println(order.checkout.type);

Paso 3: Redireccionar al checkout de conekta

En tu sitio tienes que hacer redirección a la url regresada en el paso anterior, donde el usuario podra efectuar su pago en el checkout de conekta.

Open a web browser and goto checkout url.

redirect_to order.checkout.url

<?php

header("Location: {$order->checkout->url}");

res.redirect(order.checkout.url);

header($"Location: {order.checkout.url}");

http.HandleFunc("/", http.RedirectHandler(order.checkout.url, 301))

response.sendRedirect(order.checkout.url);

Hosted Payment

Paso 4: Recibir de vuelta al customer a tu sitio

Una vez que tu Cliente procese el pago, ya sea que haya sido Exitoso o Fallido se realizará el redirect a las urls success_url y failure_url definidas en el paso 2, dada la configuración expresada en segundos del redirection_time, definidas en el paso 2.

Se agregaran los siguientes parámetros a la url de redirección devuelta al sitio.

Parámetro

Descripción

Ejemplos

checkout_id

Identificador de la petición del checkout

7e531c1e-7ac7-4c46-8ee1-44d45913449c

order_id

Identificador de la orden.

ord_2oCQQtCxJ5UnQyXSq

payment_status

Status del pago

paid, pending_payment, error

Re dirección a tu sitio, dadas las URLs de Success o Failure, considera configurar una Thank you page para presentar los datos mencionados arriba, datos adicionales de tu negocio así como la identidad de tu marca.

Una vez recibas estos parámetros tienes que validar el status de la órden haciendo una petición a la API de conekta.

curl --request GET \
  --url https://api.conekta.io/orders/ord_2oEhsRCcpaxW66Y2x \
  --header 'accept: application/vnd.conekta-v2.0.0+json' \
  -u key_eYvWV7gSDkNYXsmr: \
  --header 'content-type: application/json'

order = Conekta::Order.find("ord_2oEhsRCcpaxW66Y2x")

var order = new Order().find("ord_2oEhsRCcpaxW66Y2x");

Console.WriteLine(order.payment_status);

<?php

$order = Order::find('ord_2oEhsRCcpaxW66Y2x');
print_r($order->payment_status);

conekta.Order.find("ord_2oEhsRCcpaxW66Y2x", (err, ord) => {
  console.log(stringify(ord.payment_status));
});

orderResponse, err = order.Find("ord_2oEhsRCcpaxW66Y2x")

fmt.Println("Payment Status: %v", orderResponse.PaymentStatus)

Order order = Order.find("ord_2oEhsRCcpaxW66Y2x");

Paso 5 : Meses sin intereses

Puedes configurar el checkout para que pueden funcionar con meses sin intereses si en las peticiones agregas estas dos variables: monthly_installments_enabled para activarlo y monthly_installments_options con los meses habilitados, dentro del objeto de "Checkout"


Ejemplo:

"monthly_installments_enabled": true,
"monthly_installments_options": [3, 6, 9, 12, 18]

Consideraciones para MSI.

* Monto mínimo para meses sin intereses es $300 MXN

Siguiendo la siguiente tabla para el resto de MSI:

Umbral de Monto (MXN)

MSI

$300-$599

Permite 3 MSI (todos los bancos)

$600-$899

Permite hasta 6 MSI (todos los bancos)

$900-$1199

Permite hasta 9 MSI (todos los bancos)

$1200-$1790

Permite hasta 12 MSI (todos los bancos)

$1800-En adelante

Permite hasta 18 MSI (Solo Citibanamex)

Paso 6: Recibir la notificación de pago

Una vez configurado un webhook el Panel Conekta, tu puedes recibir el evento charge.paid y order.paid cada que se reciba un pago exitoso.

👍

¡Listo!

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

Personalización de tu marca

Podrás configurar tu marca y tu imagen empresarial en el Checkout, para que tus clientes identifiquen de forma inmediata que están pagando un producto o servicio de tu empresa, brindando seguridad y confianza en todo momento a la hora del pago.

📘

Consideraciones

A continuación se muestra la forma de realizar la configuración del Checkout, dentro del cuerpo del request se encuentra en forma de "Comentarios" el significado de cada atributo y sus posibles valores:

curl -H "Accept: application/vnd.conekta-v2.0.0+json" \
     -H "Content-type: application/json" \
     -u key_XXXXXXXXXXX: \
     -X PUT -d '{
    "sidebar": {
        "color": "#FFFFFF", //Color de Letra de Resumen de Venta
        "background_color": "#0699a5" //Color del Fondo de Resumen de Venta
    },
    "styles": {
        "background": {
            "body": "#"   //Color del contenedor de las formas de pago
  
        },
        "button_type": "basic",  // basic | rounded | sharp
        "colors": {
            "primary": "#7db300" //Color de Fondo del Botón de Pago
        },
        "font_size": "baseline",   // baseline | compact   -Tamaño de la fuente general
        "input_type": "basic", // basic | rounded | line   -Tipo de Input
        "letters": {
            "payment_methods": {
                "color": "#0079c1" //Color de fuente de las instrucciones e inputs de las formas de pago
            }
        },
        "logo": {
            "size": "large", // small | medium | large
            "source": "https://s3-conektacdn-staging.s3.amazonaws.com/cpanel/statics/assets/brands/logos/logo petsy.svg",
            "type_image": "url"  // Solo es posible un recurso por HTTPS
        },
        "states": {
            "empty": {
                "border_color": "#AAAAAA" //Color de contorno de Input para expresión regular vacía
            },
            "invalid": {
                "border_color": "#FF0000" //Color de contorno de Input para expresión regular inválida
            },
            "valid": {
                "border_color": "#0000FF" //Color de contorno de Input para expresión regular válida
            }
        }
    }
}' https://api.conekta.io/checkout_configuration

A continuación algunos ejemplos de como luce la configuración personalizada:

Logotipo y Color en Títulos de Formas de Pago

Color de Fondo y Fuente en Resumen de Venta

Color de Botones e Instrucciones de Formas de Pago

Expresiones Regulares de Inputs Vacíos, Inválidos y Válidos