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.

Webhooks (Eventos)

Un Webhook es un callback HTTP POST. Nuestra API envia diferentes eventos relacionados con tu negocio en formato JSON con el cuál podrás notificar a tu usuario, crear reportes, notificar a tu equipo operativo sobre contracargos, etc.

Configurar un webhook

Al crear tu cuenta, puedes configurar los webhooks en la sección de Webhooks en el admin.

El evento será enviado a todos los URLs que asignaste la cual permitirá que tus aplicaciones respondan.

Para confirmar de que ya has recibido una notificación de un webhook correctamente, tu servidor debe regresar un código 200 de HTTP.

<?php

$body = @file_get_contents('php://input');
$data = json_decode($body);
http_response_code(200); // Return 200 OK 

if ($data->type == 'charge.paid'){
  $msg = "Tu pago ha sido comprobado.";
  mail("[email protected]","Pago confirmado",$msg);
}
class WebhooksController < ApplicationController
  skip_before_filter :verify_authenticity_token 

  def receive
    data = JSON.parse(request.body.read)
    if data['type'] == 'charge.paid'
        msg = 'Tu pago ha sido comprobado'
        ExampleMailer.paid_email(data, msg)
      end
    end 

    render status: 200
  end
end
import json 

data = json.loads(HttpRequest.body) 

if data.type == 'charge.paid':
  msg['Subject'] = 'Pago confirmado'
  msg['From'] = me
  msg['To'] = you 

  s = smtplib.SMTP('localhost')
  s.sendmail(me, [you], msg.as_string())
  s.quit()
end
//Using nodemailer
var data = typeof req.body == 'string' ? JSON.parse(req.body) : req.body; 

if (data.type == 'order.paid') {
  var mail = {
      from: me,
      to: you,
      subject: 'Pago comprobado',
      text: 'Tu pago ha sido confirmado.'
  };
  transporter.sendMail(mail, function(error, info){
      if(error){ return console.log(error); }
    });
}
import org.json.JSONObject;
  protected void doPost(HttpServletRequest request, HttpServletResponse response)
    throws ServletException, IOException {
      BufferedReader get_body = request.getReader(); 

      //Parse JSON
    }
using System.Net.Mail; 

public class ConektaWebhookController : Controller
    {
      MailMessage mail = new MailMessage(you, me); 

      [HttpPost]
      public ActionResult Index()
      {
          Stream req = Request.InputStream;
          req.Seek(0, System.IO.SeekOrigin.Begin); 

          string json = new StreamReader(req).ReadToEnd();
          var obj = JObject.Parse(json);
          var data = obj.SelectToken("data"); 

          if(data.Type == 'charge.paid'){
            mail.Subject = "Pago comprobado";
            mail.Body = "Tu pago ha sido confirmado.";
            client.Send(mail);
          } 

          return new HttpStatusCodeResult(HttpStatusCode.OK);
      }
  }
# N/A

Si tu servidor cuenta con alguna restricción mediante Firewall debes añadir la IP de nuestros servidores de eventos 52.200.151.182 y 52.72.53.105. Además, puedes seleccionar un puerto específico para tus webhooks. Los puertos que soportamos son el 80, 443 y el rango del 1025 al 10001.

Códigos de Error HTTP

Cuando falla la notificación de un evento, vamos a regresar un código de error HTTP, pero en ciertos casos puedes encontrar los siguientes códigos de error especiales:

HTTP -1
En este caso, no hemos mandado todavía la notificación y sigue pendiente.

HTTP 1
Un caso de falla aleatorio que típicamente indica una falla de SSL, demasiadas redirects (más que una) o una respuesta mal-formada.

HTTP 200
Tu servidor contestó correctamente.

HTTP 201..5XX
Tu servidor respondió con este código HTTP, lo cuál es válido pero no lo esperado para confirmar la recepción de la notificación.

HTTP 598
Un error de connectividad, o timeout al momento de esperar una respuesta.

Events de Conekta

Los eventos que puedes recibir por parte de Conekta son:

  • Order created
  • Order paid - Card
  • Order paid - OXXO
  • Order paid - SPEI
  • Order expired
  • Charge created - Card
  • Charge created - OXXO
  • Charge created - SPEI
  • Charge paid - Card
  • Charge paid - OXXO
  • Charge paid - SPEI
  • Charge refunded
  • Chargeback created
  • Plan created
  • Subscription created
  • Subscription paid
  • Subscription canceled
  • Subscription payment failed

Order Events

Order Created

// order.created
{
  "data": {
      "object": {
        "livemode": false,
        "amount": 1766900,
        "currency": "MXN",
        "amount_refunded": 0,
        "customer_info": {
            "email": "[email protected]",
            "phone": "5555555555",
            "name": "Soporte Conekta",
            "object": "customer_info"
        },
        "shipping_contact": {
            "receiver": "Conekta",
            "phone": "5555555555",
            "address": {
                "street1": "Street 1",
                "city": "Ciudad de México",
                "state": "Distrito Federal",
                "residential": true,
                "object": "shipping_address",
                "postal_code": "06100"
            },
            "id": "ship_cont_2iUNX1yCXRKCVnEor",
            "object": "shipping_contact",
            "created_at": 1599496065
        },
        "object": "order",
        "id": "ord_2iUN",
        "metadata": {
            "checkout_id": "100068588",
            "soft_validations": true
        },
        "created_at": 1599496065,
        "updated_at": 1599496065,
        "line_items": {
            "object": "list",
            "has_more": false,
            "total": 1,
            "data": [{
                "name": "Soporte Conekta",
                "description": "Payment from order",
                "unit_price": 1766900,
                "quantity": 1,
                "sku": "6248_1",
                "tags": [
                    "tag"
                ],
                "object": "line_item",
                "id": "line_item_2iUNX1yCXRKCVnEon",
                "parent_id": "ord_2iCXRKCVnUNX1yEos",
                "metadata": {},
                "antifraud_info": {}
            }]
        },
        "shipping_lines": {
            "object": "list",
            "has_more": false,
            "total": 1,
            "data": [{
                "amount": 0,
                "carrier": "reev_carrier_reev_carrier",
                "method": "reev_carrier_reev_carrier",
                "object": "shipping_line",
                "id": "ship_lin_2iUNX1yCXRKCVnEoo",
                "parent_id": "ord_2iUNX1yCXRKCVnEos"
            }]
        },
        "tax_lines": {
            "object": "list",
            "has_more": false,
            "total": 1,
            "data": [{
                "description": "Payment from order",
                "amount": 0,
                "object": "tax_line",
                "id": "tax_lin_2iUNX1yCXRKCVnEop",
                "parent_id": "ord_2iCXRKCVnUNX1yEos"
            }]
        }
    },
    "previous_attributes": {}
  },
  "livemode": false,
  "webhook_status": "pending",
  "id": "58740be5dba34d123c027a70",
  "object": "event",
  "type": "order.created",
  "created_at": 1599496065,
  "webhook_logs": [{
      "id": "webhl_xtwgFC2EhrSTNKQ",
      "url": "http://requestb.in/1467d141",
      "failed_attempts": 0,
      "last_http_response_status": -1,
      "object": "webhook_log",
      "last_attempted_at": 0
  }]
}

Order Paid - Tarjetas

// order.paid (tarjetas)
{
  "data": {
      "object": {
        "livemode": false,
        "amount": 2944525,
        "currency": "MXN",
        "payment_status": "paid",
        "amount_refunded": 0,
        "customer_info": {
            "email": "[email protected]",
            "phone": "5555555555",
            "name": "Soporte Conekta",
            "object": "customer_info"
        },
        "shipping_contact": {
            "receiver": "Soporte Conekta",
            "phone": "5555555555",
            "address": {
                "street1": "Street 1",
                "city": "Cuidad de mexico ",
                "state": "Distrito Federal",
                "residential": true,
                "object": "shipping_address",
                "postal_code": "06100"
            },
            "id": "ship_cont_2iUhePPDGgdmsptBE",
            "object": "shipping_contact",
            "created_at": 1599496065
        },
        "object": "order",
        "id": "ord_2iUh",
        "metadata": {
            "checkout_id": "1100002080",
            "soft_validations": true
        },
        "created_at": 1599496065,
        "updated_at": 1599496065,
        "line_items": {
            "object": "list",
            "has_more": false,
            "total": 1,
            "data": [{
                "name": "Soporte Conekta",
                "description": "Escritorio Telik - Encino",
                "unit_price": 619900,
                "quantity": 5,
                "sku": "6139_1",
                "tags": [
                    "simple"
                ],
                "object": "line_item",
                "id": "line_item_2iUhyU3NmXSCaSV7p",
                "parent_id": "ord_2iUhePPDGgdmsptBF",
                "metadata": {},
                "antifraud_info": {}
            }]
        },
        "shipping_lines": {
            "object": "list",
            "has_more": false,
            "total": 1,
            "data": [{
                "amount": 0,
                "carrier": "reev_carrier_reev_carrier",
                "method": "reev_carrier_reev_carrier",
                "object": "shipping_line",
                "id": "ship_lin_2iUhyU3NmXSCaSV7q",
                "parent_id": "ord_2iUhePPDGgdmsptBF"
            }]
        },
        "tax_lines": {
            "object": "list",
            "has_more": false,
            "total": 1,
            "data": [{
                "description": "Payment from order",
                "amount": 0,
                "object": "tax_line",
                "id": "tax_lin_2iUhyU3NmXSCaSV7r",
                "parent_id": "ord_2iUhePPDGgdmsptBF"
            }]
        },
        "discount_lines": {
            "object": "list",
            "has_more": false,
            "total": 1,
            "data": [{
                "code": "Conekta",
                "amount": 154975,
                "type": "coupon",
                "object": "discount_line",
                "id": "dis_lin_2iUhyU3NmXSCaSV7s",
                "parent_id": "ord_2iUhePPDGgdmsptBF"
            }]
        },
        "charges": {
            "object": "list",
            "has_more": false,
            "total": 2,
            "data": [{
                    "id": "5ae34c95b795b071223e21a2",
                    "livemode": true,
                    "created_at": 1599496065,
                    "currency": "MXN",
                    "monthly_installments": 3,
                    "device_fingerprint": "11fenw1m2oq7waynewa1o1gg10k787v5",
                    "payment_method": {
                        "name": "Soporte Conekta",
                        "exp_month": "02",
                        "exp_year": "22",
                        "auth_code": "571003",
                        "object": "card_payment",
                        "type": "credit",
                        "last4": "5589",
                        "brand": "mc",
                        "issuer": "BANAMEX",
                        "account_type": "CLASICA",
                        "country": "MX",
                        "fraud_score": 33,
                        "fraud_indicators": []
                    },
                    "object": "charge",
                    "description": "Payment from order",
                    "status": "paid",
                    "amount": 2944525,
                    "paid_at": 1524845720,
                    "fee": 75145,
                    "customer_id": "",
                    "order_id": "ord_2iUh"
                },
                {
                    "id": "5ae346bbedbb6e2ed843c422",
                    "livemode": true,
                    "created_at": 1599496065,
                    "currency": "MXN",
                    "failure_code": null,
                    "failure_message": null,
                    "monthly_installments": 3,
                    "device_fingerprint": "3799848y56yvdw4dj2u4zxeaoenh6vyb",
                    "payment_method": {
                        "name": "Soporte Conekta",
                        "exp_month": "01",
                        "exp_year": "22",
                        "auth_code": "",
                        "object": "card_payment",
                        "type": "credit",
                        "last4": "4094",
                        "brand": "mc",
                        "issuer": "BANAMEX",
                        "account_type": "PLATINUM",
                        "country": "MX",
                        "fraud_score": 24,
                        "fraud_indicators": []
                    },
                    "object": "charge",
                    "description": "Payment from order",
                    "status": "declined",
                    "amount": 2944525,
                    "fee": 75145,
                    "customer_id": "",
                    "order_id": "ord_2iU"
                }
            ]
        }
    },
    "previous_attributes": {}
  },
  "livemode": false,
  "webhook_status": "pending",
  "id": "58740be5dba34d123c027a70",
  "object": "event",
  "type": "order.paid",
  "created_at": 1599496065,
  "webhook_logs": [{
      "id": "webhl_xtwgFC2EhrSTNKQ",
      "url": "http://requestb.in/1467d141",
      "failed_attempts": 0,
      "last_http_response_status": -1,
      "object": "webhook_log",
      "last_attempted_at": 0
  }]
}

Order Paid - OXXO

// order.paid (oxxo)
{
  "data": {
      "object": {
        "livemode": false,
        "amount": 2944525,
        "currency": "MXN",
        "payment_status": "paid",
        "amount_refunded": 0,
        "customer_info": {
            "email": "[email protected]",
            "phone": "5555555555",
            "name": "Soporte Conekta",
            "object": "customer_info"
        },
        "shipping_contact": {
            "receiver": "Soporte Conekta",
            "phone": "5555555555",
            "address": {
                "street1": "Street 1",
                "city": "Cuidad de mexico ",
                "state": "Distrito Federal",
                "residential": true,
                "object": "shipping_address",
                "postal_code": "06100"
            },
            "id": "ship_cont_2iUhePPDGgdmsptBE",
            "object": "shipping_contact",
            "created_at": 1599496065
        },
        "object": "order",
        "id": "ord_2iUh",
        "metadata": {
            "checkout_id": "1100002080",
            "soft_validations": true
        },
        "created_at": 1599496065,
        "updated_at": 1599496065,
        "line_items": {
            "object": "list",
            "has_more": false,
            "total": 1,
            "data": [{
                "name": "Soporte Conekta",
                "description": "Escritorio Telik - Encino",
                "unit_price": 619900,
                "quantity": 5,
                "sku": "6139_1",
                "tags": [
                    "simple"
                ],
                "object": "line_item",
                "id": "line_item_2iUhyU3NmXSCaSV7p",
                "parent_id": "ord_2iUhePPDGgdmsptBF",
                "metadata": {},
                "antifraud_info": {}
            }]
        },
        "shipping_lines": {
            "object": "list",
            "has_more": false,
            "total": 1,
            "data": [{
                "amount": 0,
                "carrier": "reev_carrier_reev_carrier",
                "method": "reev_carrier_reev_carrier",
                "object": "shipping_line",
                "id": "ship_lin_2iUhyU3NmXSCaSV7q",
                "parent_id": "ord_2iUhePPDGgdmsptBF"
            }]
        },
        "tax_lines": {
            "object": "list",
            "has_more": false,
            "total": 1,
            "data": [{
                "description": "Payment from order",
                "amount": 0,
                "object": "tax_line",
                "id": "tax_lin_2iUhyU3NmXSCaSV7r",
                "parent_id": "ord_2iUhePPDGgdmsptBF"
            }]
        },
        "discount_lines": {
            "object": "list",
            "has_more": false,
            "total": 1,
            "data": [{
                "code": "Conekta",
                "amount": 154975,
                "type": "coupon",
                "object": "discount_line",
                "id": "dis_lin_2iUhyU3NmXSCaSV7s",
                "parent_id": "ord_2iUhePPDGgdmsptBF"
            }]
        },
        "charges": {
            "object": "list",
            "has_more": false,
            "total": 2,
            "data": [{
                    "id": "5ae34c95b795b071223e21a2",
                    "livemode": true,
                    "created_at": 1599496065,
                    "currency": "MXN",
                    "monthly_installments": null,
                    "device_fingerprint": "11fenw1m2oq7waynewa1o1gg10k787v5",
                    "payment_method": {
                        "service_name": "OxxoPay",
                        "barcode_url": "https://s3.amazonaws.com/cash_payment_barcodes/93000024137521.png",
                        "object": "cash_payment",
                        "type": "oxxo",
                        "expires_at": 1602088065,
                        "store_name": "OXXO",
                        "reference": "93000024137521"
                    },
                    "object": "charge",
                    "description": "Payment from order",
                    "status": "paid",
                    "amount": 2944525,
                    "paid_at": 1524845720,
                    "fee": 75145,
                    "customer_id": "",
                    "order_id": "ord_2iUh"
                },
                {
                    "id": "5ae346bbedbb6e2ed843c422",
                    "livemode": true,
                    "created_at": 1599496065,
                    "currency": "MXN",
                    "failure_code": null,
                    "failure_message": null,
                    "monthly_installments": 3,
                    "device_fingerprint": "3799848y56yvdw4dj2u4zxeaoenh6vyb",
                    "payment_method": {
                        "name": "Soporte Conekta",
                        "exp_month": "01",
                        "exp_year": "22",
                        "auth_code": "",
                        "object": "card_payment",
                        "type": "credit",
                        "last4": "4094",
                        "brand": "mc",
                        "issuer": "BANAMEX",
                        "account_type": "PLATINUM",
                        "country": "MX",
                        "fraud_score": 24,
                        "fraud_indicators": []
                    },
                    "object": "charge",
                    "description": "Payment from order",
                    "status": "declined",
                    "amount": 2944525,
                    "fee": 75145,
                    "customer_id": "",
                    "order_id": "ord_2iU"
                }
            ]
        }
    },
    "previous_attributes": {}
  },
  "livemode": false,
  "webhook_status": "pending",
  "id": "58740be5dba34d123c027a70",
  "object": "event",
  "type": "order.paid",
  "created_at": 1599496065,
  "webhook_logs": [{
      "id": "webhl_xtwgFC2EhrSTNKQ",
      "url": "http://requestb.in/1467d141",
      "failed_attempts": 0,
      "last_http_response_status": -1,
      "object": "webhook_log",
      "last_attempted_at": 0
  }]
}