Introducción

Bienvenido a la referencia completa de nuestro REST API. Aquí podrás encontrar la información de todas las llamadas, respuestas y errores que podrás utilizar con nuestro API. Todas las respuestas de nuestro API son en JSON pero puedes configurar tu sesión para recibir respuestas en XML.

Recuerda que podrás trabajar en modo prueba o producción utilizando tus llaves de API. En modo de prueba, no se generará ningún cargo pero podrás realizar todas las pruebas necesarias antes de salir a producción.

Te invitamos a revisar nuestros tutoriales con ejemplos básicos sobre nuestros distintos métodos de pago.

Autenticación

Las llaves de autenticación son usadas para autenticar todas tus llamadas al servidor de Conekta por medio de autenticación básica HTTP. Las llaves o keys pueden ser recuperadas y configuradas dentro de tu admin. Cada key es configurada para ser utilizada ya sea en modo sandbox o producción y para cada uno de estos modos obtendrás una key privada para llamadas entre servidores y una key pública para utilizar con ConektaJS o en su defecto algún SDK como Android y iOS. Asegúrate de nunca compartir tus keys privadas ya que estas tienen acceso y todos los privilegios de tu cuenta.

Hemos utilizado una llave de API de prueba en todos los ejemplos de la documentación para que puedas probar todos los ejemplos de inmediato y sin tener qué crear una cuenta.

require "conekta"
Conekta.api_key = "{global_api_key}"

Versiones

Todos los cambios que hacemos al API y que son incompatibles con versiones anteriores son liberados en una versión nueva. La versión actual es 1.0.0. En caso de hacer un cambio entre versiones, recomendamos probar la aplicación con la nueva versión antes de hacer el cambio completo en tu aplicación.

Cuando se soluciona algún error en el sistema, la versión sigue siendo la misma, así que no tendrás qué hacer un cambio de versión salvo sean agregadas funcionalidades nuevas.

require "conekta"
Conekta.api_version = "{global_api_version}"

Idioma

Configurando el locale en la librería puedes especificar el idioma (inglés o español) en el cual quieres recibir los mensajes enviados por Conekta al comprador en el parámetro de message_to_purchaser.

require "conekta"
Conekta.api_key = "{global_api_key}"
Conekta.locale = :es

Cargos

Para poder crear un cargo con tarjeta, OXXO o bancos, necesitas crear un objeto de cargo. Los cargos son identificados con un identificador único (id) asignado al azar.

El Objeto Cargo

Atributos

  • id string Identificador único del cargo asignado al azar.
  • object string Clase del objeto. En este caso, “charge”.
  • livemode boolean false: Modo de prueba. true: Modo de producción.
  • created_at integer Fecha de creación del cargo.
  • status string Estatus actual del cargo. Posibles estatus del cargo son:
    • pending_payment El cargo nunca ha sido pagado o los intentos de pago nunca han sido exitosos.
    • paid El cargo ha sido pagado exitosamente.
    • charged_back Un contracargo ha sido creado para este cargo. Para más información, ve la sección de contracargos.
    • refunded El cargo ha sido reembolsado al comprador en su totalidad.
  • description string Descripción o concepto del cargo.
  • amount integer Cantidad del cargo. Cantidad cobrada en centavos (sin decimales y los 2 últimos dígitos de la cantidad son los centavos).
  • currency string Divisa con la cual se realizará el cobro. Utiliza el código de 3 letras del Estándar Internacional ISO 4217.
  • payment_method hash Un hash polimórfico con información acerca de la forma de pago.
  • details hash Hash que contiene información adicional y opcional relacionada a la compra. Este hash es utilizado en gran medida para detectar pagos con tarjetas fraudulentas pero también puede ser utilizada para almacenar información de compra.
    • name string Nombre del usuario
    • phone string El número de teléfono del usuario.
    • email string El correo electrónico del usuario.
    • customer hash Información extra sobre el cliente para reducir el riesgo de transacciones fraudulentas
      • logged_in boolean true/false: identifica si el usuario ha creado una cuenta en el sitio y ha iniciado sesión
      • successful_purchases integer integer de las compras totales en el sitio a través de todos los métodos de pago como Conekta, PayPal, etc. (incluye pagos en efectivo, en caso de que existan)
      • created_at integer timestamp en segundos que indica cuando el usuario creó su cuenta
      • updated_at integer timestamp en segundos que indica cuando el usuario ha modificado alguna información de su cuenta: tarjeta crédito/débito, direcciones, etc.
      • offline_payments integer integer que indica el número de compras a través de métodos de pago en efectivo como OXXO, SPEI, etc.
      • score integer integer que puede tomar un valor de 0 ó 10 en el cual 0 indica que no se conoce al cliente y 10 significa que es un cliente 100% confiable conocido por la empresa
    • line_items array Array de artículos o lineitems asociados con este cargo. Es recomendado que todas las compras, ya sean de productos físicos, digitales o servicios utilicen un lineitem.
      • name string Nombre del producto
      • description string Descripción utilizada por la empresa para identificar el producto
      • sku string Indica el Storage Keeping Unit designado por la empresa
      • unit_price integer integer que indica el precio del producto en centavos
      • type string Indica la categoría del producto designada por la empresa
      • quantity integer La cantidad de artículos de este line_item.
    • billing_address hash Hash de la dirección de facturación asociada con la compra.
      • tax_id string El RFC o tax_id de la compañía.
      • company_name string Nombre legal de la compañía.
      • phone string El teléfono de la compañía.
      • email string El correo de la compañía
      • street1 string Primera línea de la dirección de la compañía. Usualmente es usada para calle, número exterior.
      • street2 string Segunda línea de la dirección de la compañía. Usualmente es utilizado para número interior, suite, fraccionamiento o delegación.
      • street3 string La tercera línea para dirección de la compañía. Para clientes mexicanos, usualmente es utilizado para la colonia.
      • city string La ciudad de la compañía.
      • state string El estado de la compañía.
      • country string El país de la compañía. Utiliza el formato ISO 3166-1 de 2 dígitos.
      • zip string Código postal de la compañía.
  • reference_id string Identificador único que puede ser utilizado para encontrar registros asociados con este cargo.
  • failure_code string Código de error en caso de que haya una falla y el cargo no se haya realizado, para más detalles ve la lista de errores.
  • failure_message string Mensaje legible (human-readable) explicando la razón por la cual el cargo no pudo ser realizado.
{
  "id":"523dd8f6aef8784386000001",
  "livemode": false,
  "created_at": 1379784950,
  "status":"paid",
  "currency":"MXN",
  "description":"Stogies",
  "reference_id":"9839-wolf_pack",
  "failure_code": null,
  "failure_message": null,
  "object":"charge",
  "amount": 20000,
  "payment_method": {
    "object":"card_payment",
    "name":"Thomas Logan",
    "exp_month":"12",
    "exp_year":"15",
    "auth_code": "813038",
    "last4":"1111",
    "brand":"visa",
    "address": {
      "street1":"250 Alexis St",
      "street2": null,
      "street3": null,
      "city":"Red Deer",
      "state":"Alberta",
      "zip":"T4N 0B8",
      "country":"Canada"
    }
  },
  "details": {
    "name":"Arnulfo Quimare",
    "phone":"403-342-0642",
    "email":"logan@x-men.org",
    "customer": {
      "logged_in": true,
      "successful_purchases": 14,
      "created_at": 1379784950,
      "updated_at": 1379784950,
      "offline_payments": 4,
      "score": 9
    },
    "line_items": [{
      "name": "Box of Cohiba S1s",
      "description": "Imported From Mex.",
      "unit_price": 20000,
      "quantity": 1,
      "sku": "7500244909",
      "type": "food"
     }],
    "billing_address": {
      "street1":"77 Mystery Lane",
      "street2":"Suite 124",
      "city":"Darlington",
      "state":"NJ",
      "zip":"10192",
      "country": "Mexico",
      "tax_id":"xmn671212drx",
      "company_name":"X-Men Inc.",
      "phone":"77-777-7777",
      "email":"purshasing@x-men.org"
    }
  }
}

Cargos con Tarjetas de Crédito y Débito

Para realizar el cobro con tarjeta de crédito o débito, debes crear un objeto de cargo para tarjeta. En caso de utilizar la llave en modo de prueba, la tarjeta no será cargada pero todo lo demás será simulado como si fuera un cargo real para que puedas realizar las pruebas necesarias. Al utilizar la llave en modo de producción (solamente si tu cuenta está activada), podrás realizar cargos reales a la tarjeta.

Para realizar un cargo con tarjeta, primero debes tokenizar los datos de la misma.

Puedes revisar nuestros tutoriales para cargos con tarjeta o cargos on-demand

Atributos

  • description string Descripción o concepto del cargo.
  • amount integer Cantidad del cargo. Cantidad cobrada en centavos (sin decimales y los 2 últimos dígitos de la cantidad son los centavos).
  • currency string Divisa con la cual se realizará el cobro. Utiliza el código de 3 letras del Estándar Internacional ISO 4217.
  • reference_id string (opcional) Identificador único que puede ser utilizado para encontrar registros asociados con este cargo.
  • card string String con la tarjeta a la cual se realiza el cargo. Card puede ser un ID de tarjeta, un ID de cliente o un token de tarjeta que obtienes utilizando conekta.js. Para aprender más sobre cómo obtener un ID de tarjeta, ID de cliente o un token, puedes ver el tutorial de suscripciones.
  • details hash Hash que contiene información adicional y opcional relacionada a la compra. Este hash es utilizado en gran medida para detectar pagos con tarjetas fraudulentas pero también puede ser utilizada para almacenar información de compra.
    • name string Nombre del usuario
    • phone string El número de teléfono del usuario. Longitud de 8 a 15 caracteres.
    • email string El correo electrónico del usuario.
    • customer hash (opcional) Información extra sobre el cliente para reducir el riesgo de transacciones fraudulentas
      • logged_in boolean (opcional) true/false: identifica si el usuario ha creado una cuenta en el sitio y ha iniciado sesión
      • successful_purchases integer (opcional) integer de las compras totales en el sitio a través de todos los métodos de pago como Conekta, PayPal, etc. (incluye pagos en efectivo, en caso de que existan)
      • created_at integer (opcional) timestamp en segundos que indica cuando el usuario creó su cuenta
      • updated_at integer (opcional) timestamp en segundos que indica cuando el usuario ha modificado alguna información de su cuenta: tarjeta crédito/débito, direcciones, etc.
      • offline_payments integer (opcional) integer que indica el número de compras a través de métodos de pago en efectivo como OXXO, SPEI, etc.
      • score integer (opcional) integer que puede tomar un valor de 0 ó 10 en el cual 0 indica que no se conoce al cliente y 10 significa que es un cliente 100% confiable conocido por la empresa
    • line_items array Array de artículos o lineitems asociados con este cargo. Es recomendado que todas las compras, ya sean de productos físicos, digitales o servicios utilicen un lineitem.
      • name string Nombre del producto
      • description string Descripción utilizada por la empresa para identificar el producto
      • unit_price integer integer que indica el precio del producto en centavos
      • quantity integer La cantidad de artículos de este line_item.
      • sku string (opcional) Indica el Storage Keeping Unit designado por la empresa
      • type string (opcional) Indica la categoría del producto designada por la empresa
    • billing_address hash (opcional) Hash de la dirección de facturación asociada con la compra.
      • tax_id string (opcional) El RFC o tax_id de la compañía.
      • company_name string (opcional) Nombre legal de la compañía.
      • phone string (opcional) El teléfono de la compañía.
      • email string (opcional) El correo de la compañía
      • street1 string (opcional) Primera línea de la dirección de la compañía. Usualmente es usada para calle, número exterior.
      • street2 string (opcional) Segunda línea de la dirección de la compañía. Usualmente es utilizado para número interior, suite, fraccionamiento o delegación.
      • street3 string (opcional) La tercera línea para dirección de la compañía. Para clientes mexicanos, usualmente es utilizado para la colonia.
      • city string (opcional) La ciudad de la compañía.
      • state string (opcional) El estado de la compañía.
      • country string (opcional) El país de la compañía. Utiliza el formato ISO 3166-1 de 2 dígitos.
      • zip string (opcional) Código postal de la compañía.
Conekta.api_key = "{global_api_key}"

charge = Conekta::Charge.create({
  "description"=> "Stogies",
  "amount"=> 20000,
  "currency"=> "MXN",
  "reference_id"=> "9839-wolf_pack",
  "card"=> "tok_test_visa_4242",
  "details"=> {
    "name"=> "Arnulfo Quimare",
    "phone"=> "403-342-0642",
    "email"=> "logan@x-men.org",
    "customer"=> {
      "logged_in"=> true,
      "successful_purchases"=> 14,
      "created_at"=> 1379784950,
      "updated_at"=> 1379784950,
      "offline_payments"=> 4,
      "score"=> 9
    },
    "line_items"=> [{
      "name"=> "Box of Cohiba S1s",
      "description"=> "Imported From Mex.",
      "unit_price"=> 20000,
      "quantity"=> 1,
      "sku"=> "cohb_s1",
      "category"=> "food"
    }],
    "billing_address"=> {
      "street1"=>"77 Mystery Lane",
      "street2"=> "Suite 124",
      "city"=> "Darlington",
      "state"=>"NJ",
      "zip"=> "10192",
      "country"=> "Mexico",
      "tax_id"=> "xmn671212drx",
      "company_name"=>"X-Men Inc.",
      "phone"=> "77-777-7777",
      "email"=> "purshasing@x-men.org"
    }
  }
})


# Respuesta de Llamada

puts charge.inspect
{
  "id":"523dd8f6aef8784386000001",
  "livemode": false,
  "created_at": 1379784950,
  "status":"paid",
  "currency":"MXN",
  "description":"Stogies",
  "reference_id":"9839-wolf_pack",
  "failure_code": null,
  "failure_message": null,
  "object":"charge",
  "amount": 20000,
  "payment_method": {
    "object":"card_payment",
    "name":"Thomas Logan",
    "exp_month":"12",
    "exp_year":"15",
    "auth_code": "813038",
    "last4":"1111",
    "brand":"visa",
    "address": {
      "street1":"250 Alexis St",
      "street2": null,
      "street3": null,
      "city":"Red Deer",
      "state":"Alberta",
      "zip":"T4N 0B8",
      "country":"Canada"
    }
  },
  "details": {
    "name":"Arnulfo Quimare",
    "phone":"403-342-0642",
    "email":"logan@x-men.org",
    "customer": {
      "logged_in": true,
      "successful_purchases": 14,
      "created_at": 1379784950,
      "updated_at": 1379784950,
      "offline_payments": 4,
      "score": 9
    },
    "line_items": [{
      "name": "Box of Cohiba S1s",
      "description": "Imported From Mex.",
      "unit_price": 20000,
      "quantity": 1,
      "sku": "7500244909",
      "category": "food"
     }],
    "billing_address": {
      "street1":"77 Mystery Lane",
      "street2":"Suite 124",
      "street3": null,
      "city":"Darlington",
      "state":"NJ",
      "zip":"10192",
      "country": "Mexico",
      "tax_id":"xmn671212drx",
      "company_name":"X-Men Inc.",
      "phone":"77-777-7777",
      "email":"purshasing@x-men.org"
    }
  }
}

Meses sin Intereses

Puedes utilizar cargo a meses sin intereses cuando quieras generar una promoción y diferir el cargo en meses sin intereses para el tarjetahabiente. Consulta la guía de meses sin intereses.

Atributos

  • description string Descripción o concepto del cargo.
  • amount integer Cantidad del cargo. Cantidad cobrada en centavos (sin decimales y los 2 últimos dígitos de la cantidad son los centavos).
  • currency string Divisa con la cual se realizará el cobro. Utiliza el código de 3 letras del Estándar Internacional ISO 4217.
  • reference_id string (opcional) Identificador único que puede ser utilizado para encontrar registros asociados con este cargo.
  • monthly_installments integer (opcional) Cantidad de meses a los que se va aplicar la promoción de meses sin intereses, puede ser 3, 6, 9 o 12 meses y es recomendable leer la guía de meses sin intereses.
  • card string String con la tarjeta a la cual se realiza el cargo. Card puede ser un ID de tarjeta, un ID de cliente o un token de tarjeta que obtienes utilizando conekta.js. Para aprender más sobre cómo obtener un ID de tarjeta, ID de cliente o un token, puedes ver el tutorial de suscripciones.
  • details hash Hash que contiene información adicional y opcional relacionada a la compra. Este hash es utilizado en gran medida para detectar pagos con tarjetas fraudulentas pero también puede ser utilizada para almacenar información de compra.
    • name string Nombre del usuario
    • phone string El número de teléfono del usuario. Longitud de 8 a 15 caracteres.
    • email string El correo electrónico del usuario.
    • customer hash (opcional) Información extra sobre el cliente para reducir el riesgo de transacciones fraudulentas
      • logged_in boolean (opcional) true/false: identifica si el usuario ha creado una cuenta en el sitio y ha iniciado sesión
      • successful_purchases integer (opcional) integer de las compras totales en el sitio a través de todos los métodos de pago como Conekta, PayPal, etc. (incluye pagos en efectivo, en caso de que existan)
      • created_at integer (opcional) timestamp en segundos que indica cuando el usuario creó su cuenta
      • updated_at integer (opcional) timestamp en segundos que indica cuando el usuario ha modificado alguna información de su cuenta: tarjeta crédito/débito, direcciones, etc.
      • offline_payments integer (opcional) integer que indica el número de compras a través de métodos de pago en efectivo como OXXO, SPEI, etc.
      • score integer (opcional) integer que puede tomar un valor de 0 ó 10 en el cual 0 indica que no se conoce al cliente y 10 significa que es un cliente 100% confiable conocido por la empresa
    • line_items array Array de artículos o lineitems asociados con este cargo. Es recomendado que todas las compras, ya sean de productos físicos, digitales o servicios utilicen un lineitem.
      • name string Nombre del producto
      • description string Descripción utilizada por la empresa para identificar el producto
      • unit_price integer integer que indica el precio del producto en centavos
      • quantity integer La cantidad de artículos de este line_item.
      • sku string (opcional) Indica el Storage Keeping Unit designado por la empresa
      • type string (opcional) Indica la categoría del producto designada por la empresa
    • billing_address hash (opcional) Hash de la dirección de facturación asociada con la compra.
      • tax_id string (opcional) El RFC o tax_id de la compañía.
      • company_name string (opcional) Nombre legal de la compañía.
      • phone string (opcional) El teléfono de la compañía.
      • email string (opcional) El correo de la compañía
      • street1 string (opcional) Primera línea de la dirección de la compañía. Usualmente es usada para calle, número exterior.
      • street2 string (opcional) Segunda línea de la dirección de la compañía. Usualmente es utilizado para número interior, suite, fraccionamiento o delegación.
      • street3 string (opcional) La tercera línea para dirección de la compañía. Para clientes mexicanos, usualmente es utilizado para la colonia.
      • city string (opcional) La ciudad de la compañía.
      • state string (opcional) El estado de la compañía.
      • country string (opcional) El país de la compañía. Utiliza el formato ISO 3166-1 de 2 dígitos.
      • zip string (opcional) Código postal de la compañía.
Conekta.api_key = "{global_api_key}"

charge = Conekta::Charge.create({
  "description"=> "Stogies",
  "amount"=> 20000,
  "currency"=> "MXN",
  "reference_id"=> "9839-wolf_pack",
  "monthly_installments" => 3,
  "card"=> "tok_test_visa_4242",
  "details"=> {
    "name"=> "Arnulfo Quimare",
    "phone"=> "403-342-0642",
    "email"=> "logan@x-men.org",
    "customer"=> {
      "logged_in"=> true,
      "successful_purchases"=> 14,
      "created_at"=> 1379784950,
      "updated_at"=> 1379784950,
      "offline_payments"=> 4,
      "score"=> 9
    },
    "line_items"=> [{
      "name"=> "Box of Cohiba S1s",
      "description"=> "Imported From Mex.",
      "unit_price"=> 20000,
      "quantity"=> 1,
      "sku"=> "cohb_s1",
      "category"=> "food"
    }],
    "billing_address"=> {
      "street1"=>"77 Mystery Lane",
      "street2"=> "Suite 124",
      "city"=> "Darlington",
      "state"=>"NJ",
      "zip"=> "10192",
      "country"=> "Mexico",
      "tax_id"=> "xmn671212drx",
      "company_name"=>"X-Men Inc.",
      "phone"=> "77-777-7777",
      "email"=> "purshasing@x-men.org"
    }
  }
})

# Ejemplo respuesta

puts charge.inspect
{
  "id":"523dd8f6aef8784386000001",
  "livemode": false,
  "created_at": 1379784950,
  "status":"paid",
  "currency":"MXN",
  "description":"Stogies",
  "reference_id":"9839-wolf_pack",
  "failure_code": null,
  "failure_message": null,
  "object":"charge",
  "amount": 20000,
  "monthly_installments": 3,
  "payment_method": {
    "object":"card_payment",
    "name":"Thomas Logan",
    "exp_month":"12",
    "exp_year":"15",
    "auth_code": "813038",
    "last4":"1111",
    "brand":"visa",
    "address": {
      "street1":"250 Alexis St",
      "street2": null,
      "street3": null,
      "city":"Red Deer",
      "state":"Alberta",
      "zip":"T4N 0B8",
      "country":"Canada"
    }
  },
  "details": {
    "name":"Arnulfo Quimare",
    "phone":"403-342-0642",
    "email":"logan@x-men.org",
    "customer": {
      "logged_in": true,
      "successful_purchases": 14,
      "created_at": 1379784950,
      "updated_at": 1379784950,
      "offline_payments": 4,
      "score": 9
    },
    "line_items": [{
      "name": "Box of Cohiba S1s",
      "description": "Imported From Mex.",
      "unit_price": 20000,
      "quantity": 1,
      "sku": "7500244909",
      "category": "food"
     }],
    "billing_address": {
      "street1":"77 Mystery Lane",
      "street2":"Suite 124",
      "street3": null,
      "city":"Darlington",
      "state":"NJ",
      "zip":"10192",
      "country": "Mexico",
      "tax_id":"xmn671212drx",
      "company_name":"X-Men Inc.",
      "phone":"77-777-7777",
      "email":"purshasing@x-men.org"
    }
  }
}

Cargos con OXXO

Debes crear un objeto de cargo para OXXO con el cual recibirás una respuesta con el número de código de barras, el URL del código de barras en formato PNG y la fecha de expiración para que el comprador pueda realizar el pago en la caja de cualquier tienda OXXO.

En caso de utilizar la llave en modo de prueba, se generará un código de barras de prueba (no podrás utilizarlo en OXXO). Además de esto, recibirás una notificación de pago de prueba después de 30 segundos por medio de webhooks para que puedas realizar todas las pruebas necesarias. Al utilizar la llave en modo de producción (solamente si tu cuenta está activada), recibirás un código de barras real con el cual podrás ir al OXXO a pagar y recibirás la notificación de pago real por medio de webhooks el día siguiente al que se realizó el pago.

Contamos con un tutorial para cargos con OXXO para ayudarte a integrarlo a tu sistema.

Atributos

  • description string Descripción o concepto del cargo.
  • amount integer Cantidad del cargo. Cantidad cobrada en centavos (sin decimales y los 2 últimos dígitos de la cantidad son los centavos).
  • currency string Divisa con la cual se realizará el cobro. Utiliza el código de 3 letras del Estándar Internacional ISO 4217.
  • reference_id string (opcional) Identificador único que puede ser utilizado para encontrar registros asociados con este cargo.
  • cash hash Hash con toda la información para hacer el pago en efectivo (requerido solo para pagos en efectivo, por ejemplo, OXXO).
    • type string El tipo o método de pago con el cual se puede completar el pago en efectivo. Hasta este momento, el único valor aceptado es: OXXO.
    • expires_at integer (opcional) La fecha de expiración para la referencia. Después de esta fecha el comprador no podrá realizar el pago (el día de expiración sí podrá realizar el pago. A partir del siguiente día, no). Este valor es un UNIX timestamp, truncado al principio del día.
  • details hash Hash que contiene información adicional y opcional relacionada a la compra. Este hash es utilizado en gran medida para detectar pagos con tarjetas fraudulentas pero también puede ser utilizada para almacenar información de compra.
    • name string Nombre del usuario
    • phone string El número de teléfono del usuario. Longitud de 8 a 15 caracteres.
    • email string El correo electrónico del usuario.
    • customer hash (opcional) Información extra sobre el cliente para reducir el riesgo de transacciones fraudulentas
      • logged_in boolean (opcional) true/false: identifica si el usuario ha creado una cuenta en el sitio y ha iniciado sesión
      • successful_purchases integer (opcional) integer de las compras totales en el sitio a través de todos los métodos de pago como Conekta, PayPal, etc. (incluye pagos en efectivo, en caso de que existan)
      • created_at integer (opcional) timestamp en segundos que indica cuando el usuario creó su cuenta
      • updated_at integer (opcional) timestamp en segundos que indica cuando el usuario ha modificado alguna información de su cuenta: tarjeta crédito/débito, direcciones, etc.
      • offline_payments integer (opcional) integer que indica el número de compras a través de métodos de pago en efectivo como OXXO, SPEI, etc.
      • score integer (opcional) integer que puede tomar un valor de 0 ó 10 en el cual 0 indica que no se conoce al cliente y 10 significa que es un cliente 100% confiable conocido por la empresa
    • line_items array Array de artículos o lineitems asociados con este cargo. Es recomendado que todas las compras, ya sean de productos físicos, digitales o servicios utilicen un lineitem.
      • name string Nombre del producto
      • description string Descripción utilizada por la empresa para identificar el producto
      • unit_price integer integer que indica el precio del producto en centavos
      • quantity integer La cantidad de artículos de este line_item.
      • sku string (opcional) Indica el Storage Keeping Unit designado por la empresa
      • type string (opcional) Indica la categoría del producto designada por la empresa
    • billing_address hash (opcional) Hash de la dirección de facturación asociada con la compra.
      • tax_id string (opcional) El RFC o tax_id de la compañía.
      • company_name string (opcional) Nombre legal de la compañía.
      • phone string (opcional) El teléfono de la compañía.
      • email string (opcional) El correo de la compañía
      • street1 string (opcional) Primera línea de la dirección de la compañía. Usualmente es usada para calle, número exterior.
      • street2 string (opcional) Segunda línea de la dirección de la compañía. Usualmente es utilizado para número interior, suite, fraccionamiento o delegación.
      • street3 string (opcional) La tercera línea para dirección de la compañía. Para clientes mexicanos, usualmente es utilizado para la colonia.
      • city string (opcional) La ciudad de la compañía.
      • state string (opcional) El estado de la compañía.
      • country string (opcional) El país de la compañía. Utiliza el formato ISO 3166-1 de 2 dígitos.
      • zip string (opcional) Código postal de la compañía.
Conekta.api_key = "{global_api_key}"

charge = Conekta::Charge.create({
  "description"=> "Stogies",
  "amount"=> 20000,
  "currency"=> "MXN",
  "reference_id"=> "9839-wolf_pack",
  "cash"=> {
    "type"=> "oxxo",
    "expires_at"=> {global_expiration_date_timestamp}
  },
  "details"=> {
    "name"=> "Arnulfo Quimare",
    "phone"=> "403-342-0642",
    "email"=> "logan@x-men.org",
    "customer"=> {
      "logged_in"=> true,
      "successful_purchases"=> 14,
      "created_at"=> 1379784950,
      "updated_at"=> 1379784950,
      "offline_payments"=> 4,
      "score"=> 9
    },
    "line_items"=> [{
      "name"=> "Box of Cohiba S1s",
      "description"=> "Imported From Mex.",
      "unit_price"=> 20000,
      "quantity"=> 1,
      "sku"=> "cohb_s1",
      "category"=> "food"
    }],
    "billing_address"=> {
      "street1"=>"77 Mystery Lane",
      "street2"=> "Suite 124",
      "city"=> "Darlington",
      "state"=>"NJ",
      "zip"=> "10192",
      "country"=> "Mexico",
      "tax_id"=> "xmn671212drx",
      "company_name"=>"X-Men Inc.",
      "phone"=> "77-777-7777",
      "email"=> "purshasing@x-men.org"
    }
  }
})

# Ejemplo de respuesta
puts charge.inspect
{
  "id":"523dd8f6aef8784386000001",
  "livemode": false,
  "created_at": 1379784950,
  "status":"paid",
  "currency":"MXN",
  "description":"Stogies",
  "reference_id":"9839-wolf_pack",
  "failure_code": null,
  "failure_message": null,
  "object":"charge",
  "amount": 20000,
  "payment_method": {
    "expires_at": {global_expiration_date_timestamp},
    "barcode":"38100000000042290121213001160013",
    "barcode_url":"https://www2.oxxo.com:8443/HTP/barcode/genbc?data=38100000000042290121213001160013&height=50&width=1&type=Code128",
    "object":"cash_payment",
    "type":"oxxo"
  },
  "details": {
    "name":"Arnulfo Quimare",
    "phone":"403-342-0642",
    "email":"logan@x-men.org",
    "customer": {
      "logged_in": true,
      "successful_purchases": 14,
      "created_at": 1379784950,
      "updated_at": 1379784950,
      "offline_payments": 4,
      "score": 9
    },
    "line_items": [{
      "name": "Box of Cohiba S1s",
      "description": "Imported From Mex.",
      "unit_price": 20000,
      "quantity": 1,
      "sku": "7500244909",
      "category": "food"
     }],
    "billing_address": {
      "street1":"77 Mystery Lane",
      "street2":"Suite 124",
      "street3": null,
      "city":"Darlington",
      "state":"NJ",
      "zip":"10192",
      "country": "Mexico",
      "tax_id":"xmn671212drx",
      "company_name":"X-Men Inc.",
      "phone":"77-777-7777",
      "email":"purshasing@x-men.org"
    }
  }
}

Cargos vía SPEI

Para recibir un pago vía SPEI, debes crear un objeto de cargo para banco de tipo SPEI, con el que recibirás una respuesta con la CLABE única y el banco hacia donde se debe dirigir el pago. Debes proporcionar estos datos a tu comprador para que pueda realizar el pago vía SPEI. Es importante tener en cuenta que una CLABE sólo puede ser utilizada una vez y sólo puede recibir el monto exacto con el cual fue creado. Al momento de recibir el pago te llegará una notificación por medio de webhook.

En nuestro tutorial para cargos con SPEI podrás ver una integración completa de esta forma de pago.

Atributos

  • description string Descripción o concepto del cargo.
  • amount integer Cantidad del cargo. Cantidad cobrada en centavos (sin decimales y los 2 últimos dígitos de la cantidad son los centavos).
  • currency string Divisa con la cual se realizará el cobro. Utiliza el código de 3 letras del Estándar Internacional ISO 4217.
  • reference_id string (opcional) Identificador único que puede ser utilizado para encontrar registros asociados con este cargo.
  • bank hash Hash con toda la información para realizar pago en efectivo.
    • type string El valor para generar un cargo de tipo transferencia bancaria es spei.
    • expires_at integer (opcional) La fecha de expiración para la referencia. Después de esta fecha el comprador no podrá realizar el pago (el día de expiración sí podrá realizar el pago. A partir del siguiente día, no). Este valor es un UNIX timestamp, truncado al principio del día.
  • details hash Hash que contiene información adicional y opcional relacionada a la compra. Este hash es utilizado en gran medida para detectar pagos con tarjetas fraudulentas pero también puede ser utilizada para almacenar información de compra.
    • name string Nombre del usuario
    • phone string El número de teléfono del usuario. Longitud de 8 a 15 caracteres.
    • email string El correo electrónico del usuario.
    • customer hash (opcional) Información extra sobre el cliente para reducir el riesgo de transacciones fraudulentas
      • logged_in boolean (opcional) true/false: identifica si el usuario ha creado una cuenta en el sitio y ha iniciado sesión
      • successful_purchases integer (opcional) integer de las compras totales en el sitio a través de todos los métodos de pago como Conekta, PayPal, etc. (incluye pagos en efectivo, en caso de que existan)
      • created_at integer (opcional) timestamp en segundos que indica cuando el usuario creó su cuenta
      • updated_at integer (opcional) timestamp en segundos que indica cuando el usuario ha modificado alguna información de su cuenta: tarjeta crédito/débito, direcciones, etc.
      • offline_payments integer (opcional) integer que indica el número de compras a través de métodos de pago en efectivo como OXXO, SPEI, etc.
      • score integer (opcional) integer que puede tomar un valor de 0 ó 10 en el cual 0 indica que no se conoce al cliente y 10 significa que es un cliente 100% confiable conocido por la empresa
    • line_items array Array de artículos o lineitems asociados con este cargo. Es recomendado que todas las compras, ya sean de productos físicos, digitales o servicios utilicen un lineitem.
      • name string Nombre del producto
      • description string Descripción utilizada por la empresa para identificar el producto
      • unit_price integer integer que indica el precio del producto en centavos
      • quantity integer La cantidad de artículos de este line_item.
      • sku string (opcional) Indica el Storage Keeping Unit designado por la empresa
      • type string (opcional) Indica la categoría del producto designada por la empresa
    • billing_address hash (opcional) Hash de la dirección de facturación asociada con la compra.
      • tax_id string (opcional) El RFC o tax_id de la compañía.
      • company_name string (opcional) Nombre legal de la compañía.
      • phone string (opcional) El teléfono de la compañía.
      • email string (opcional) El correo de la compañía
      • street1 string (opcional) Primera línea de la dirección de la compañía. Usualmente es usada para calle, número exterior.
      • street2 string (opcional) Segunda línea de la dirección de la compañía. Usualmente es utilizado para número interior, suite, fraccionamiento o delegación.
      • street3 string (opcional) La tercera línea para dirección de la compañía. Para clientes mexicanos, usualmente es utilizado para la colonia.
      • city string (opcional) La ciudad de la compañía.
      • state string (opcional) El estado de la compañía.
      • country string (opcional) El país de la compañía. Utiliza el formato ISO 3166-1 de 2 dígitos.
      • zip string (opcional) Código postal de la compañía.
Conekta.api_key = "{global_api_key}"

charge = Conekta::Charge.create({
  "description"=> "Stogies",
  "amount"=> 20000,
  "currency"=> "MXN",
  "reference_id"=> "9839-wolf_pack",
  "bank"=> {
    "type"=> "spei"
  },
  "details"=> {
    "name"=> "Arnulfo Quimare",
    "phone"=> "403-342-0642",
    "email"=> "logan@x-men.org",
    "customer"=> {
      "logged_in"=> true,
      "successful_purchases"=> 14,
      "created_at"=> 1379784950,
      "updated_at"=> 1379784950,
      "offline_payments"=> 4,
      "score"=> 9
    },
    "line_items"=> [{
      "name"=> "Box of Cohiba S1s",
      "description"=> "Imported From Mex.",
      "unit_price"=> 20000,
      "quantity"=> 1,
      "sku"=> "cohb_s1",
      "category"=> "food"
    }],
    "billing_address"=> {
      "street1"=>"77 Mystery Lane",
      "street2"=> "Suite 124",
      "city"=> "Darlington",
      "state"=>"NJ",
      "zip"=> "10192",
      "country"=> "Mexico",
      "tax_id"=> "xmn671212drx",
      "company_name"=>"X-Men Inc.",
      "phone"=> "77-777-7777",
      "email"=> "purshasing@x-men.org"
    }
  }
})

# Ejemplo respuesta

puts charge.inspect
{
  "id":"523dd8f6aef8784386000001",
  "livemode": false,
  "created_at": 1379784950,
  "status":"paid",
  "currency":"MXN",
  "description":"Stogies",
  "reference_id":"9839-wolf_pack",
  "failure_code": null,
  "failure_message": null,
  "object":"charge",
  "amount": 20000,
  "payment_method": {
    "clabe": "646180111800009801",
    "bank": "STP",
    "receiving_account_number": "646180111800009801",
    "receiving_account_bank": "STP",
    "object": "bank_transfer_payment",
    "type": "spei",
    "expires_at": 1433187502
  },
  "details": {
    "name":"Arnulfo Quimare",
    "phone":"403-342-0642",
    "email":"logan@x-men.org",
    "customer": {
      "logged_in": true,
      "successful_purchases": 14,
      "created_at": 1379784950,
      "updated_at": 1379784950,
      "offline_payments": 4,
      "score": 9
    },
    "line_items": [{
      "name": "Box of Cohiba S1s",
      "description": "Imported From Mex.",
      "unit_price": 20000,
      "quantity": 1,
      "sku": "7500244909",
      "category": "food"
     }],
    "billing_address": {
      "street1":"77 Mystery Lane",
      "street2":"Suite 124",
      "street3": null,
      "city":"Darlington",
      "state":"NJ",
      "zip":"10192",
      "country": "Mexico",
      "tax_id":"xmn671212drx",
      "company_name":"X-Men Inc.",
      "phone":"77-777-7777",
      "email":"purshasing@x-men.org"
    }
  }
}

Cargos con Banorte

Debes crear un objeto de cargo para Banorte con el cual recibirás una respuesta con el número, nombre de servicio y referencia única para que el comprador pueda realizar el pago en la caja de cualquier banco Banorte o por medio de su banca en línea.

Tenemos un tutorial para pagos Banorte en el cual puedes tomar de referencia para tu integración.

Atributos

  • description string Descripción o concepto del cargo.
  • amount integer Cantidad del cargo. Cantidad cobrada en centavos (sin decimales y los 2 últimos dígitos de la cantidad son los centavos).
  • currency string Divisa con la cual se realizará el cobro. Utiliza el código de 3 letras del Estándar Internacional ISO 4217.
  • reference_id string (opcional) Identificador único que puede ser utilizado para encontrar registros asociados con este cargo.
  • bank hash Hash con toda la información para hacer el pago en banorte.
    • type string El tipo o método de pago con el cual se puede completar el pago. En este caso, sería “banorte”.
    • expires_at integer (opcional) La fecha de expiración para la referencia. Después de esta fecha el comprador no podrá realizar el pago (el día de expiración sí podrá realizar el pago. A partir del siguiente día, no). Este valor es un UNIX timestamp, truncado al principio del día.
  • details hash Hash que contiene información adicional y opcional relacionada a la compra. Este hash es utilizado en gran medida para detectar pagos con tarjetas fraudulentas pero también puede ser utilizada para almacenar información de compra.
    • name string Nombre del usuario
    • phone string El número de teléfono del usuario. Longitud de 8 a 15 caracteres.
    • email string El correo electrónico del usuario.
    • customer hash (opcional) Información extra sobre el cliente para reducir el riesgo de transacciones fraudulentas
      • logged_in boolean (opcional) true/false: identifica si el usuario ha creado una cuenta en el sitio y ha iniciado sesión
      • successful_purchases integer (opcional) integer de las compras totales en el sitio a través de todos los métodos de pago como Conekta, PayPal, etc. (incluye pagos en efectivo, en caso de que existan)
      • created_at integer (opcional) timestamp en segundos que indica cuando el usuario creó su cuenta
      • updated_at integer (opcional) timestamp en segundos que indica cuando el usuario ha modificado alguna información de su cuenta: tarjeta crédito/débito, direcciones, etc.
      • offline_payments integer (opcional) integer que indica el número de compras a través de métodos de pago en efectivo como OXXO, SPEI, etc.
      • score integer (opcional) integer que puede tomar un valor de 0 ó 10 en el cual 0 indica que no se conoce al cliente y 10 significa que es un cliente 100% confiable conocido por la empresa
    • line_items array Array de artículos o lineitems asociados con este cargo. Es recomendado que todas las compras, ya sean de productos físicos, digitales o servicios utilicen un lineitem.
      • name string Nombre del producto
      • description string Descripción utilizada por la empresa para identificar el producto
      • quantity integer La cantidad de artículos de este line_item.
      • unit_price integer integer que indica el precio del producto en centavos
      • sku string (opcional) Indica el Storage Keeping Unit designado por la empresa
      • type string (opcional) Indica la categoría del producto designada por la empresa
    • billing_address hash (opcional) Hash de la dirección de facturación asociada con la compra.
      • tax_id string (opcional) El RFC o tax_id de la compañía.
      • company_name string (opcional) Nombre legal de la compañía.
      • street1 string (opcional) Primera línea de la dirección de la compañía. Usualmente es usada para calle, número exterior.
      • street2 string (opcional) Segunda línea de la dirección de la compañía. Usualmente es utilizado para número interior, suite, fraccionamiento o delegación.
      • street3 string (opcional) La tercera línea para dirección de la compañía. Para clientes mexicanos, usualmente es utilizado para la colonia.
      • city string (opcional) La ciudad de la compañía.
      • state string (opcional) El estado de la compañía.
      • country string (opcional) El país de la compañía. Utiliza el formato ISO 3166-1 de 2 dígitos.
      • zip string (opcional) Código postal de la compañía.
      • phone string (opcional) El teléfono de la compañía.
      • email string (opcional) El correo de la compañía
begin
  charge = Conekta::Charge.create({
    "description"=> "Stogies",
    "amount"=> 20000,
    "currency"=> "MXN",
    "reference_id"=> "9839-wolf_pack",
    "bank"=> {
      "type"=> "banorte",
      "expires_at"=> {global_expiration_date_timestamp}
    },
    "details"=> {
      "name"=> "Arnulfo Quimare",
      "phone"=> "403-342-0642",
      "email"=> "logan@x-men.org",
      "customer"=> {
        "logged_in"=> true,
        "successful_purchases"=> 14,
        "created_at"=> 1379784950,
        "updated_at"=> 1379784950,
        "offline_payments"=> 4,
        "score"=> 9
      },
      "line_items"=> [{
        "name"=> "Box of Cohiba S1s",
        "description"=> "Imported From Mex.",
        "unit_price"=> 20000,
        "quantity"=> 1,
        "sku"=> "cohb_s1",
        "category"=> "food"
      }],
      "billing_address"=> {
        "street1"=>"77 Mystery Lane",
        "street2"=> "Suite 124",
        "city"=> "Darlington",
        "state"=>"NJ",
        "zip"=> "10192",
        "country"=> "Mexico",
        "tax_id"=> "xmn671212drx",
        "company_name"=>"X-Men Inc.",
        "phone"=> "77-777-7777",
        "email"=> "purshasing@x-men.org"
      }
    }
  })
rescue Conekta::ParameterValidationError => e
  puts e.message_to_purchaser 
  #alguno de los parámetros fueron inválidos

rescue Conekta::ProcessingError => e
  puts e.message_to_purchaser 
  #la tarjeta no pudo ser procesada

rescue Conekta::Error => e
  puts e.message_to_purchaser 
  #un error ocurrió que no sucede en el flujo normal de cobros como por ejemplo un auth_key incorrecto

end

Recuperar Cargos

Recupera la información de un cargo creado anteriormente utilizando el charge_id del cargo. El objeto de cargo que recibes es exactamente igual al que recibirás después de crear o hacer devolución de un cargo. Solamente puedes utilizar la llave privada para poder recuperar información de un cargo.

Argumentos

  • id: string Identificador único del cargo.
# Ejemplo Llamada
Conekta.api_key = "{global_api_key}"

charge = Conekta::Charge.find('523dd8f6aef8784386000001')

# Ejemplo Respuesta
puts charge.inspect

{
  "id":"523dd8f6aef8784386000001",
  "livemode": false,
  "created_at": 1379784950,
  "status":"paid",
  "currency":"MXN",
  "description":"Stogies",
  "reference_id":"9839-wolf_pack",
  "failure_code": null,
  "failure_message": null,
  "object":"charge",
  "amount": 20000,
  "payment_method": {
    "object":"card_payment",
    "name":"Thomas Logan",
    "exp_month":"12",
    "exp_year":"15",
    "auth_code": "813038",
    "last4":"1111",
    "brand":"visa",
    "address": {
      "street1":"250 Alexis St",
      "street2": null,
      "street3": null,
      "city":"Red Deer",
      "state":"Alberta",
      "zip":"T4N 0B8",
      "country":"Canada"
    }
  },
  "details": {
    "name":"Arnulfo Quimare",
    "phone":"403-342-0642",
    "email":"logan@x-men.org",
    "customer": {
      "logged_in": true,
      "successful_purchases": 14,
      "created_at": 1379784950,
      "updated_at": 1379784950,
      "offline_payments": 4,
      "score": 9
    },
    "line_items": [{
      "name": "Box of Cohiba S1s",
      "description": "Imported From Mex.",
      "unit_price": 20000,
      "quantity": 1,
      "sku": "7500244909",
      "category": "food"
     }],
    "billing_address": {
      "street1":"77 Mystery Lane",
      "street2":"Suite 124",
      "street3": null,
      "city":"Darlington",
      "state":"NJ",
      "zip":"10192",
      "country": "Mexico",
      "tax_id":"xmn671212drx",
      "company_name":"X-Men Inc.",
      "phone":"77-777-7777",
      "email":"purshasing@x-men.org"
    }
  }
}

Devoluciones

Crea una devolución de un cargo ‘card_payment’ creado anteriormente. Puedes crear una devolución total o una devolución parcial si especificas una cantidad menor al total del cargo original. Necesitas utilizar las llaves privadas de API para poder realizar una devolución.

Argumentos

  • id: string Identificador único del cargo.
  • amount: integer Cantidad de la devolución. Cantidad cobrada en centavos (sin decimales y los 2 últimos dígitos de la cantidad son los centavos). Si se deja en blanco, se realizará una devolución total sobre el cargo.
# Ejemplo Llamada

Conekta.api_key = "{global_api_key}"

charge = Conekta::Charge.find('523dd8f6aef8784386000001')
charge.refund()

# Ejemplo Respuesta

puts charge.inspect

{
  "id":"523dd8f6aef8784386000001",
  "livemode": false,
  "created_at": 1379784950,
  "status":"refunded",
  "currency":"MXN",
  "description":"Stogies",
  "reference_id":"9839-wolf_pack",
  "failure_code": null,
  "failure_message": null,
  "object":"charge",
  "amount": 20000,
  "amount_refunded":20000,
  "refunds":[{
    "created_at": 1379792934,
    "amount":20000,
    "currency": "MXN",
    "transaction": "5254d0f026c605054b0015ea"
  }],
  "payment_method": {
    "object":"card_payment",
    "name":"Thomas Logan",
    "exp_month":"12",
    "exp_year":"15",
    "auth_code": "813038",
    "last4":"1111",
    "brand":"visa",
    "address": {
      "street1":"250 Alexis St",
      "street2": null,
      "street3": null,
      "city":"Red Deer",
      "state":"Alberta",
      "zip":"T4N 0B8",
      "country":"Canada"
    }
  },
  "details": {
    "name":"Arnulfo Quimare",
    "phone":"403-342-0642",
    "email":"logan@x-men.org",
    "customer": {
      "logged_in": true,
      "successful_purchases": 14,
      "created_at": 1379784950,
      "updated_at": 1379784950,
      "offline_payments": 4,
      "score": 9
    },
    "line_items": [{
      "name": "Box of Cohiba S1s",
      "description": "Imported From Mex.",
      "unit_price": 20000,
      "quantity": 1,
      "sku": "cohb_s1",
      "category": "food"
     }],
    "billing_address": {
      "street1":"77 Mystery Lane",
      "street2":"Suite 124",
      "street3": null,
      "city":"Darlington",
      "state":"NJ",
      "zip":"10192",
      "country": "Mexico",
      "tax_id":"xmn671212drx",
      "company_name":"X-Men Inc.",
      "phone":"77-777-7777",
      "email":"purshasing@x-men.org"
    }
  }
}

Capturar un Cargo

Procesa un cargo que ha sido previamente autorizado. El tipo de objeto es el mismo al crear o realizar una devolución del cargo. Toma en cuenta que solo con llaves privadas se puede hacer una petición de lista de cargos.

Conekta.api_key = "{global_api_key}"

charge = Conekta::Charge.find('523dd8f6aef8784386000001')
charge.capture()

# Ejemplo de respuesta
{
  "id":"523dd8f6aef8784386000001",
  "livemode": false,
  "created_at": 1379784950,
  "status":"paid",
  "currency":"MXN",
  "description":"Stogies",
  "reference_id":"9839-wolf_pack",
  "failure_code": null,
  "failure_message": null,
  "object":"charge",
  "amount": 20000,
  "payment_method": {
    "object":"card_payment",
    "name":"Thomas Logan",
    "exp_month":"12",
    "exp_year":"15",
    "auth_code": "813038",
    "last4":"1111",
    "brand":"visa",
    "address": {
      "street1":"250 Alexis St",
      "street2": null,
      "street3": null,
      "city":"Red Deer",
      "state":"Alberta",
      "zip":"T4N 0B8",
      "country":"Canada"
    }
  },
  "details": {
    "name":"Arnulfo Quimare",
    "phone":"403-342-0642",
    "email":"logan@x-men.org",
    "customer": {
      "logged_in": true,
      "successful_purchases": 14,
      "created_at": 1379784950,
      "updated_at": 1379784950,
      "offline_payments": 4,
      "score": 9
    },
    "line_items": [{
      "name": "Box of Cohiba S1s",
      "description": "Imported From Mex.",
      "unit_price": 20000,
      "quantity": 1,
      "sku": "7500244909",
      "category": "food"
     }],
    "billing_address": {
      "street1":"77 Mystery Lane",
      "street2":"Suite 124",
      "street3": null,
      "city":"Darlington",
      "state":"NJ",
      "zip":"10192",
      "country": "Mexico",
      "tax_id":"xmn671212drx",
      "company_name":"X-Men Inc.",
      "phone":"77-777-7777",
      "email":"purshasing@x-men.org"
    }
  }
}

Consulta de Cargos

Crea una consulta de cargos. Esta función acepta condiciones básicas de búsqueda que te permitirá filtrar, ordenar y paginar resultados. Información adicional sobre las consultas y operadores pueden ser encontrados en la sección de consultas. Solo puedes utilizar las llaves privadas de API para poder crear una consulta de cargos.

Argumentos

  • options: hash Un hash con los argumentos de la consulta.
Conekta.api_key = "{global_api_key}"

Conekta::Charge.where({
  'status.ne'=>'paid',
  'sort'=>'created_at.desc'
})

# Ejemplo Respuesta

puts charges.inspect
[{
  "id":"523dd8f6aef8784386000001",
  "livemode": false,
  "created_at": 1379784950,
  "status":"paid",
  "currency":"MXN",
  "description":"Stogies",
  "reference_id":"9839-wolf_pack",
  "failure_code": null,
  "failure_message": null,
  "object":"charge",
  "amount": 20000,
  "payment_method": {
    "object":"card_payment",
    "name":"Thomas Logan",
    "exp_month":"12",
    "exp_year":"15",
    "auth_code": "813038",
    "last4":"1111",
    "brand":"visa",
    "address": {
      "street1":"250 Alexis St",
      "street2": null,
      "street3": null,
      "city":"Red Deer",
      "state":"Alberta",
      "zip":"T4N 0B8",
      "country":"Canada"
    }
  },
  "details": {
    "name":"Arnulfo Quimare",
    "phone":"403-342-0642",
    "email":"logan@x-men.org",
    "customer": {
      "logged_in": true,
      "successful_purchases": 14,
      "created_at": 1379784950,
      "updated_at": 1379784950,
      "offline_payments": 4,
      "score": 9
    },
    "line_items": [{
      "name": "Box of Cohiba S1s",
      "description": "Imported From Mex.",
      "unit_price": 20000,
      "quantity": 1,
      "sku": "7500244909",
      "category": "food"
     }],
    "billing_address": {
      "street1":"77 Mystery Lane",
      "street2":"Suite 124",
      "street3": null,
      "city":"Darlington",
      "state":"NJ",
      "zip":"10192",
      "country": "Mexico",
      "tax_id":"xmn671212drx",
      "company_name":"X-Men Inc.",
      "phone":"77-777-7777",
      "email":"purshasing@x-men.org"
    }
  }
}]

Clientes

Clientes te permite crear suscripciones y guardar tarjetas para clientes que requieren pagos automáticos.

El Objeto Cliente

Atributos

  • id: string Identificador único asignado al azar.
  • object: string Clase del objeto. En este caso, "customer".
  • livemode: boolean false: Modo de prueba. true: Modo de producción.
  • created_at: timestamp Fecha de creación del cliente.
  • name: string El nombre del cliente.
  • email: string El correo electrónico del cliente.
  • phone: string El teléfono del cliente.
  • defaultcardid: string El id de la tarjeta primaria del cliente.
  • subscription: hash Hash de la suscripción asociada con el cliente. Ve la sección de suscripciones para más detalles.
    • id: string ID de la sucripción.
    • object: string Clase del objeto. En este caso, "subscription".
    • created_at: integer Timestamp de cuando la suscripción fue creada.
    • plan_id: string ID del plan de la suscripción.
    • subscription_start: integer Timestamp of the subscription's start date.
    • canceled_at: integer Timestamp when the subscription was canceled.
    • paused_at: integer Timestamp when the subscription was paused.
    • billingcyclestart: integer Timestamp when the current billing cycle started.
    • billingcycleend: integer Timestamp when the current billing cycle ends.
    • trial_start: integer Timestamp when the subscription's trial starts.
    • trial_end: integer Timestamp when the subscription's trial ends.
    • status: string El estatus de la suscripción, valores pueden ser: intrial, active, pastdue, paused, canceled.
  • cards: array Array de las tarjetas asociadas con el cliente. Ve la sección de suscripciones para más detalles.
    • id: string The card's id.
    • object: string Object class. In this case, "card".
    • active: boolean false: La tarjeta está desactivada y no puede usarse.
    • last4: integer Últimos 4 números de la tarjeta.
    • exp_month: integer Expiration Month of the Card.
    • exp_year: integer Expiration Year of the Card.
    • name: string Name of the card holder.
    • cvc: integer Card's Security Code (CVC)
    • address: hash (optional) Hash of the address associated with this card.
      • street1: string (optional) The first line of the address. It is usually used for street and number.
      • street2: string (optional) The second line of the address. Usually it is used for internal number, suite, or delegation.
      • street3: string (optional) The third line of the address. For Mexican customers, it is usually used for the 'colonia'.
      • city: string (optional) The city of the user.
      • state: string (optional) The user state.
      • country: string (optional) The country of the user. Use the ISO 3166-1 standard with 2 digits.
      • zip: string (optional) User's zip/postal code code.
  • billing_address: hash Hash con la dirección fiscal asociada con el cliente.
    • tax_id: string El tax_id del cliente. RFC para México.
    • company_name: string Razón Social del cliente.
    • phone: string Teléfono del cliente.
    • email: string Correo electrónico del cliente.
    • street1: string La primera línea para la dirección de facturación. Usualmente es utilizado para calle y número.
    • street2: string La segunda línea para la dirección de facturación. Usualmente es utilizado para número interior, suite, fraccionamiento o delegación.
    • street3: string La tercera línea para la dirección de facturación. Para clientes mexicanos, usualmente es utilizado para la colonia.
    • city: string La ciudad de la dirección de facturación.
    • state: string El estado de la dirección de facturación.
    • country: string El país de la dirección de facturación. Utiliza el formato ISO 3166-1 de 2 dígitos.
    • zip: string El código postal de la dirección de facturación.
  • shipping_address: hash Hash con la dirección de envío asociada al cliente.
    • street1: string La primera línea para la dirección de envío. Usualmente es utilizado para calle y número.
    • street2: string La segunda línea para la dirección de envío. Usualmente es utilizado para número interior, suite, fraccionamiento o delegación.
    • street3: string La tercera línea para la dirección de envío. Para clientes mexicanos, usualmente es utilizado para la colonia.
    • city: string La ciudad de la dirección de envío.
    • state: string El estado de la dirección de envío.
    • country: string TEl país de la dirección de envío. Utiliza el formato ISO 3166-1 de 2 dígitos.
    • zip: string El código postal de la dirección de envío.
puts customer.inspect

{
  "id":"cus_k2D9DxlqdVTagmEd400001",
  "object":"customer",
  "livemode": false,
  "created_at": 1379784950,
  "name":"Thomas Logan",
  "email":"thomas.logan@xmen.org",
  "phone":"55-5555-5555",
  "default_card_id":"card_9kWcdlL7xbvQu5jd3",
  "billing_address": {
    "street1":"77 Mystery Lane",
    "street2":"Suite 124",
    "street3": null,
    "city":"Darlington",
    "state":"NJ",
    "zip":"10192",
    "country": null,
    "tax_id":"xmn671212drx",
    "company_name":"X-Men Inc.",
    "phone":"77-777-7777",
    "email":"purshasing@x-men.org"
  },
  "shipping_address": {
    "street1":"250 Alexis St",
    "street2": null,
    "street3": null,
    "city":"Red Deer",
    "state":"Alberta",
    "zip":"T4N 0B8",
    "country":"Canada"
  },
  "cards":[{
  	"id":"card_9kWcdlL7xbvQu5jd3",
  	"name":"Thomas Logan",
  	"last4":"4242",
  	"exp_month":"12",
  	"exp_year":"17",
  	"active":true
  }],
  "subscription":{
  	"id":"sub_ls9dklD9sAxW29dSmF",
  	"card":"card_9kWcdlL7xbvQu5jd3",
  	"plan_id":"gold-plan",
  	"status":"active",
  	"start":1379784950,
  	"billing_cycle_start":1379784950,
  	"billing_cycle_end":1379384950
  }
}

Crear Cliente

Crea un cliente nuevo. Puedes opcionalmente usar parámetros para inicializar una suscripción o añadir tarjetas.

Argumentos

  • name: string El nombre del cliente.
  • email: string El correo electrónico del cliente.
  • phone: string El número de teléfono del cliente.
  • cards: array Array de ids de tokens que se utilizarán para crear tarjetas para este cliente. Ve el tutorial de suscripciones para más información de cómo tokenizar tarjetas.
  • plan: string (opcional) El id del plan que utilizarás para la suscripción. Ve la sección de planes para más detalles.
  • billing_address: hash (opcional) Hash de la dirección fiscal asociada al cliente.
    • tax_id: string (opcional) El tax_id del cliente. RFC para México.
    • company_name: string (opcional) Razón Social de la Compañía.
    • phone: string (opcional) Teléfono de la compañía.
    • email: string (opcional) Correo electrónico de la compañía.
    • street1: string (opcional) The first line of the company`s address. It is usually used for street and number.
    • street2: string (opcional) The second line of the company`s address. Usually it is used for internal number, suite, or delegation.
    • street3: string (opcional) The third line of the company`s address. For Mexican customers, it is usually used for the 'colonia'.
    • city: string (opcional) The city of the company.
    • state: string (opcional) The state of the company.
    • country: string (opcional) The country of the company. Use the ISO 3166-1 standard with 2 digits.
    • zip: string (opcional) User's zip/postal code.
  • shipping_address: hash (opcional) Hash of the address associated with this shipment.
    • street1: string (opcional) The first line of the customer's shipping address. It is usually used for street and number.
    • street2: string (opcional) The second line of the customer's shipping address. Usually it is used for internal number, suite, or delegation.
    • street3: string (opcional) The third line of the customer's shipping address. For Mexican customers, it is usually used for the 'colonia'.
    • city: string (opcional) The city of the customer's shipping address.
    • state: string (opcional) The customer's shipping state.
    • country: string (opcional) The country of the customer's shipping address. Use ISO 3166-1 standard with 2 digits.
    • zip: string (opcional) Zip/postal code of the customer's shipping address.
Conekta.api_key="{global_api_key}"

customer = Conekta::Customer.create({
    :name => "James Howlett",
    :email => "james.howlett@forces.gov",
    :phone => "55-5555-5555",
    :cards => ["tok_8kZwafM8IcN23Nd9"],
    :plan => "gold-plan"
})

# Ejemplo de respuesta

puts customer.inspect

{
  "id":"cus_Z9cVem5W3Rus2TAs7",
  "name":"James Howlett",
  "email":"james.howlett@forces.gov",
  "phone":"55-5555-5555",
  "livemode":false,
  "default_card_id":"card_TCuBjUEcy9r41Fk2",
  "object":"customer",
  "created_at":1385608474,
  "cards":[{
    "brand":"VISA",
    "last4":"4242",
    "name":"James Howlett",
    "exp_month":"12",
    "exp_year":"2013",
    "id":"card_TCuBjUEcy9r41Fk2",
    "last4":"4242",
    "object":"card"
  }],
  "subscription":{
    "id":"sub_GG1Hk9oRm1DsoCvXW",
    "status":"in_trial",
    "object":"subscription",
    "start":1385608474,
    "billing_cycle_start":1385608474,
    "plan":"gold-plan",
    "card":"card_TCuBjUEcy9r41Fk2"
  }
}

Actualizar Cliente

Actualiza la información de un cliente existente. Ten en cuenta que Tarjetas y Suscripciones tienen sus propios métodos para ser modificados.

Argumentos

  • name: string (opcional) El nombre del cliente.
  • email: string (opcional) El correo electrónico del cliente.
  • phone: string (opcional) El número de teléfono del cliente.
  • defaultcardid: string (opcional) El id de la tarjeta primaria del cliente.
  • billing_address: hash (opcional) Hash con la dirección fiscal asociada con el cliente.
    • tax_id: string (opcional) The customer's company tax_id
    • company_name: string (opcional) The company's legal name.
    • phone: string (opcional) The company's phone number.
    • email: string (opcional) The company's email.
    • street1: string (opcional) The first line of the company`s address. It is usually used for street and number.
    • street2: string (opcional) The second line of the company`s address. Usually it is used for internal number, suite, or delegation.
    • street3: string (opcional) The third line of the company`s address. For Mexican customers, it is usually used for the 'colonia'.
    • city: string (opcional) The city of the company.
    • state: string (opcional) The state of the company.
    • country: string (opcional) The country of the company. Use the ISO 3166-1 standard with 2 digits.
    • zip: string (opcional) User's zip/postal code.
  • shipping_address: hash (opcional) Hash con la dirección de envío asociada al cliente.
    • street1: string (opcional) The first line of the customer's shipping address. It is usually used for street and number.
    • street2: string (opcional) The second line of the customer's shipping address. Usually it is used for internal number, suite, or delegation.
    • street3: string (opcional) The third line of the customer's shipping address. For Mexican customers, it is usually used for the 'colonia'.
    • city: string (opcional) The city of the customer's shipping address.
    • state: string (opcional) The customer's shipping state.
    • country: string (opcional) The country of the customer's shipping address. Use ISO 3166-1 standard with 2 digits.
    • zip: string (opcional) Zip/postal code of the customer's shipping address.
Conekta.api_key="{global_api_key}"

customer = Conekta::Customer.find("cus_k2D9DxlqdVTagmEd400001")
customer = customer.update({
  :name  => "Logan",
  :email => "logan@x-men.org",
})

# Ejemplo de respuesta

puts customer.inspect

{
  "id":"cus_k2D9DxlqdVTagmEd400001",
  "name":"Logan",
  "email":"logan@x-men.org",
  "phone":"55-5555-5555",
  "livemode":false,
  "default_card_id":"card_TCuBjUEcy9r41Fk2",
  "object":"customer",
  "created_at":1385608474,
  "cards":[{
    "brand":"VISA",
    "last4":"4242",
    "name":"James Howlett",
    "exp_month":"12",
    "exp_year":"2013",
    "id":"card_TCuBjUEcy9r41Fk2",
    "last4":"4242",
    "object":"card"
  }],
  "subscription":{
    "id":"sub_GG1Hk9oRm1DsoCvXW",
    "status":"in_trial",
    "object":"subscription",
    "start":1385608474,
    "billing_cycle_start":1385608474,
    "plan":"gold-plan",
    "card":"card_TCuBjUEcy9r41Fk2"
  }
}

Eliminar Cliente

Elimina un cliente existente. También eliminará todas las tarjetas y suscripciones asociadas con el cliente.

Argumentos

  • id: string El id del cliente.
Conekta.api_key = "{global_api_key}"

customer = Conekta::Customer.find("cus_k2D9DxlqdVTagmEd400001")
customer.delete

# Ejemplo de respuesta

puts customer.inspect

{
  "id":"cus_k2D9DxlqdVTagmEd400001",
  "deleted":true,
  "name":"Logan",
  "email":"logan@x-men.org",
  "phone":"55-5555-5555",
  "livemode":false,
  "default_card_id":"card_TCuBjUEcy9r41Fk2",
  "object":"customer",
  "created_at":1385608474,
  "cards":[{
    "brand":"VISA",
    "last4":"4242",
    "name":"James Howlett",
    "exp_month":"12",
    "exp_year":"2013",
    "id":"card_TCuBjUEcy9r41Fk2",
    "last4":"4242",
    "object":"card"
  }],
  "subscription":{
    "id":"sub_GG1Hk9oRm1DsoCvXW",
    "status":"in_trial",
    "object":"subscription",
    "start":1385608474,
    "billing_cycle_start":1385608474,
    "plan":"gold-plan",
    "card":"card_TCuBjUEcy9r41Fk2"
  }
}

Tarjetas

Tarjetas te permite guardar y procesar tarjetas de clientes sin tener qué tocar la información de la tarjeta. A diferencia de los tokens, las tarjetas pueden ser utilizadas si son incrustadas en un cliente.

El Objeto Tarjeta

Atributos

  • id: string Identificador único asignado al azar.
  • object: string Clase del objeto. En este caso, “card”.
  • active: boolean false: La tarjeta está desactivada y no puede usarse. true: La tarjeta está activada.
  • created_at: timestamp Fecha de creación del cargo.
  • last4: string Últimos 4 números de la tarjeta.
  • exp_month: string Mes de expiración de la tarjeta.
  • exp_year: string Año de expiración de la tarjeta.
  • name: string Nombre del titular de la tarjeta.
  • address: hash (optional) Hash de la dirección asociada con la tarjeta.
    • street1: string (opcional) La primera línea para dirección de la tarjeta. Usualmente es utilizado para calle y número.
    • street2: string (opcional) La segunda línea para dirección de la tarjeta. Usualmente es utilizado para número interior, suite, fraccionamiento o delegación.
    • street3: string (opcional) La tercera línea para dirección de la tarjeta. Para clientes mexicanos, usualmente es utilizado para la colonia.
    • city: string (opcional) La ciudad de la tarjeta.
    • state: string (opcional) El estado de la tarjeta.
    • country: string (opcional) El país de la tarjeta. Utiliza el formato ISO 3166-1 de 2 dígitos.
    • zip: string (opcional) Código postal de la tarjeta.
{
  "id":"card_9kWcdlL7xbvQu5jd3"
  "object": "card",
  "created_at": 1386015496,
  "name":"Thomas Logan",
  "last4":"4242",
  "exp_month":"12",
  "exp_year":"17",
  "active":true,
  "address":{
    "street1":"250 Alexis St",
    "street2": null,
    "street3": null,
    "city":"Red Deer",
    "state":"Alberta",
    "zip":"T4N 0B8",
    "country":"Canada"
  }
}

Crear Tarjeta

Crea una nueva tarjeta utilizando un token.

Argumentos

  • token: string Id de token que será utilizado para crear la tarjeta. Ve el tutorial de suscripciones para más información sobre cómo tokenizar tarjetas.
Conekta.api_key="{global_api_key}"

customer = Conekta::Customer.find("cus_k2D9DxlqdVTagmEd400001")
card = customer.create_card(:token => "tok_8kZwafM8IcN23Nd9")

# Ejemplo de respuesta

puts card.inspect

{
  "id":"card_TCuBjUEcy9r41Fk2",
  "object":"card",
  "active":"true",
  "brand":"VISA",
  "last4":"4242",
  "name":"James Howlett",
  "exp_month":"12",
  "exp_year":"2013",
  "address":{
    "street1":"250 Alexis St",
    "street2": null,
    "street3": null,
    "city":"Red Deer",
    "state":"Alberta",
    "zip":"T4N 0B8",
    "country":"Canada"
  }
}

Actualizar Tarjeta

Actualiza la información de la tarjeta.

Argumentos

  • id: string El id de la tarjeta.
  • token: string Id de token que será utilizado para actualizar la tarjeta. Ve el tutorial de suscripciones para más información sobre cómo tokenizar tarjetas.
  • active: boolean Boolean flag indicando si la tarjeta está activa y puede ser utilizada o no.
Conekta.api_key="{global_api_key}"

customer = Conekta::Customer.find("cus_k2D9DxlqdVTagmEd400001")
card = customer.cards[0].update(:token => "tok_8kZwafM8IcN23Nd9", :active => false)

# Ejemplo de respuesta

puts card.inspect

{
	"id": "card_8KnNtNhurSxqsF4T",
	"object": "card",
	"created_at": 1386015496,
	"name": "Thomas Logan",
	"brand": "VISA",
	"last4": "4242",
	"active": false,
	"exp_year": "2013",
	"exp_month": "12"
}

Eliminar Tarjeta

Elimina la información de la tarjeta.

Argumentos

  • id: string El id de la tarjeta.
Conekta.api_key="{global_api_key}"

customer = Conekta::Customer.find("cus_k2D9DxlqdVTagmEd400001")
card = customer.cards[0].delete

# Ejemplo de respuesta

puts card.inspect

{
	"id": "card_8KnNtNhurSxqsF4T",
	"deleted": true,
	"object": "card",
	"created_at": 1386015496,
	"name": "Thomas Logan",
	"brand": "VISA",
	"last4": "4242",
	"active": false,
	"exp_year": "2013",
	"exp_month": "12"
}

Planes

Planes son plantillas que te permiten crear suscripciones. Dentro del plan definirás la cantidad y frecuencia con el cual generarás cobros recurrentes a tus clientes.

El Objeto Plan

Atributos

  • id: string Identificador único asignado al plan.
  • object: string Clase del objeto. En este caso, “plan”.
  • livemode: boolean false: Modo de prueba. true: Modo de producción.
  • created_at: timestamp Timestamp de creación del plan.
  • name: string Nombre del plan.
  • amount: integer Cantidad del cargo al cliente en centavos.
  • currency: string Divisa con el cual se procesará la suscripción.
  • interval: string El intervalo con el cual se genera un cargo al cliente. El valor puede ser ‘week’, ‘half_month’, ‘month’ o ‘year’. Por ejemplo, para crear un cargo a tu cliente cada 2 meses, establece el intervalo a ‘month’ y la frecuencia a 2.
  • frequency: integer La frecuencia con el cual se genera el cargo al cliente. Por ejemplo, para crear un cargo a tu cliente cada 2 meses, establece el intervalo a ‘month’ y la frecuencia a 2.
  • trialperioddays: integer La duración del periodo de prueba en días.
  • expiry_count: integer El número de veces que se realizará el cargo antes de que la suscripción expire.
puts plan.inspect

{
  "id":"gold-plan",
  "object":"plan",
  "livemode":false,
  "created_at":1385481591,
  "name":"Gold Plan",
  "amount":10000,
  "currency":"MXN",
  "interval":"month",
  "frequency":1,
  "interval_total_count":12,
  "trial_period_days":15
}

Crear Plan

Crea un nuevo plan utilizando información tokenizada.

Argumentos

  • id: string (optional) Identificador único que puedes asignar a este plan.
  • name: string Nombre del plan.
  • amount: integer Cantidad del cargo al cliente en centavos.
  • currency: string Divisa utilizada para procesar la suscripción.
  • interval: string (optional) El intervalo con el cual se genera un cargo al cliente. El valor puede ser ‘week’, ‘half_month’, ‘month’ o ‘year’. Por ejemplo, para crear un cargo a tu cliente cada 2 meses, establece el intervalo a ‘month’ y la frecuencia a 2. En caso de no mandar este argumento, el valor por defecto es ‘month’.
  • frequency: integer (optional) La frecuencia con el cual se genera el cargo al cliente. Por ejemplo, para crear un cargo a tu cliente cada 2 meses, establece el intervalo a ‘month’ y la frecuencia a 2. En caso de no mandar este argumento, el valor por defecto es 1.
  • trialperioddays: integer (optional) La duración del periodo de prueba en días.
  • expiry_count: integer (optional) El número de veces que se realizará el cargo antes de que la suscripción expire.
Conekta.api_key="{global_api_key}"

plan = Conekta::Plan.create({
  :id => "gold-plan",
  :name => "Gold Plan",
  :amount => 10000,
  :currency => "MXN",
  :interval => "month",
  :frequency => 1,
  :trial_period_days => 15,
  :expiry_count => 12})

# Ejemplo de respuesta

puts plan.inspect

{
  "id":"gold-plan",
  "object":"plan",
  "livemode":false,
  "created_at":1385481591,
  "name":"Gold Plan",
  "amount":10000,
  "currency":"MXN",
  "interval":"month",
  "frequency":1,
  "interval_total_count":12,
  "trial_period_days":15
}

Actualizar Plan

Actualiza la información del plan.

Argumentos

  • id: string Identificador único del plan. Ten en cuenta que no puedes cambiar el id del plan. Unique identifier for this plan.
  • name: string Nombre del plan.
  • amount: integer Cantidad del cargo al cliente en centavos.
Conekta.api_key="{global_api_key}"

plan = Conekta::Plan.find("cus_k2D9DxlqdVTagmEd400001")
plan.update({
  :id => "gold-plan",
  :name => "Gold Plan",
  :amount => 10000
})

# Ejemplo de respuesta

puts plan.inspect

{
  "id":"gold-plan",
  "object":"plan",
  "livemode":false,
  "created_at":1385481591,
  "name":"Gold Plan",
  "amount":10000,
  "currency":"MXN",
  "interval":"month",
  "frequency":1,
  "interval_total_count":12,
  "trial_period_days":15
}

Eliminar Plan

Elimina la información del plan.

Argumentos

  • id: string El id del plan.
Conekta.api_key="{global_api_key}"

plan = Conekta::Plan.find("cus_k2D9DxlqdVTagmEd400001")
plan.delete

# Ejemplo de respuesta

puts plan.inspect

{
  "id":"gold-plan",
  "object":"plan",
  "deleted":true,
  "livemode":false,
  "created_at":1385481591,
  "name":"Gold Plan",
  "amount":10000,
  "currency":"MXN",
  "interval":"month",
  "frequency":1,
  "interval_total_count":12,
  "trial_period_days":15
}

Suscripciones

Suscripciones son una manera de realizar cargos a un cliente con una cantidad fija de manera recurrente. Puedes cambiar el plan, pausar, cancelar y reanudar una suscripción a tu gusto.

Puedes ver como se realiza una suscripción en nuestro tutorial.

El Objeto Suscripción

Atributos

  • id: string Identificador único asignado al azar.
  • object: string Clase de objeto. En este caso, “subscription”.
  • created_at: timestamp Timestamp de cuando la suscripción fue creada.
  • canceled_at: timestamp Timestamp cuando la suscripción fue cancelada.
  • paused_at: timestamp Timestamp cuando la suscripción fue pausada.
  • billingcyclestart: timestamp Timestamp de inicio del periodo de cargo.
  • billingcycleend: timestamp Timestamp de la finalización del periodo de cargo.
  • trial_start: timestamp Timestamp del inicio del periodo de prueba.
  • trial_end: timestamp Timestamp de la finalización del periodo de prueba.
  • plan_id: string El id del plan asignado a la suscripción.
  • status: string El estatus de la suscripción, valores pueden ser: intrial, active, pastdue, paused, canceled.
puts subscription.inspect

{
  "id":"sub_EfhFCp5SKvp5XzXQk",
  "status":"in_trial",
  "object":"subscription",
  "created_at":1385696776,
  "billing_cycle_start":1385696776,
  "billing_cycle_end":1386301576,
  "plan_id":"gold-plan",
  "card_id":"card_vow1u83899Rkj5LM"
}

Crear Suscripción

Crea una suscripción usando información tokenizada.

Argumentos

  • customer_id: string El id del cliente al cual se generará la suscripción.
  • plan: string El id del plan que utilizarás para crear la suscripción.
  • card: string (optional) El id de la tarjeta que utilizarás para procesar la suscripción en caso de que sea diferente a la tarjeta primaria. La tarjeta ya debe ser parte de este cliente.
Conekta.api_key="{global_api_key}"

customer = Conekta::Customer.find("cus_k2D9DxlqdVTagmEd400001")
subscription = customer.create_subscription({
  :plan => "gold-plan"
})

# Ejemplo de respuesta

puts subscription.inspect

{
  "id":"sub_EfhFCp5SKvp5XzXQk",
  "status":"in_trial",
  "object":"subscription",
  "created_at":1385696776,
  "billing_cycle_start":1385696776,
  "billing_cycle_end":1386301576,
  "plan_id":"gold-plan",
  "card_id":"card_vow1u83899Rkj5LM"
}

Cambiar la Tarjeta o Plan

Actualiza la suscripción con una tarjeta o plan diferente.

Argumentos

  • customer_id: string El id del cliente de la suscripción.
  • plan: string (optional) Id del nuevo plan a utilizar.
  • card: string (optional) Id de la nueva tarjeta a utilizar.
Conekta.api_key="{global_api_key}"

customer = Conekta::Customer.find("cus_k2D9DxlqdVTagmEd400001")
subscription = customer.subscription.update({
  :plan => "opal-plan"
})

# Ejemplo de respuesta

puts subscription.inspect

{
  "id":"sub_EfhFCp5SKvp5XzXQk",
  "status":"in_trial",
  "object":"subscription",
  "created_at":1385696776,
  "billing_cycle_start":1385696776,
  "billing_cycle_end":1386301576,
  "plan_id":"opal-plan",
  "card_id":"card_vow1u83899Rkj5LM"
}

Pausar Suscripción

Pausa una suscripción.

Argumentos

  • customer_id: string El id del cliente de la suscripción.
Conekta.api_key="{global_api_key}"

customer = Conekta::Customer.find("cus_k2D9DxlqdVTagmEd400001")
subscription = customer.subscription.pause

# Ejemplo de respuesta

puts subscription.inspect

{
  "id":"sub_EfhFCp5SKvp5XzXQk",
  "status":"paused",
  "object":"subscription",
  "created_at":1385696776,
  "billing_cycle_start":1385696776,
  "billing_cycle_end":1386301576,
  "plan_id":"opal-plan",
  "card_id":"card_vow1u83899Rkj5LM"
}

Reanudar Suscripción

Reanuda una suscripción.

Argumentos

  • customer_id: string El id del cliente de la suscripción.
Conekta.api_key="{global_api_key}"

customer = Conekta::Customer.find("cus_k2D9DxlqdVTagmEd400001")
subscription = customer.subscription.resume

# Ejemplo de respuesta

puts subscription.inspect

{
  "id":"sub_EfhFCp5SKvp5XzXQk",
  "status":"active",
  "object":"subscription",
  "created_at":1385696776,
  "billing_cycle_start":1385696776,
  "billing_cycle_end":1386301576,
  "plan_id":"opal-plan",
  "card_id":"card_vow1u83899Rkj5LM"
}

Cancelar Suscripción

Cancela una suscripción.

Argumentos

  • customer_id: string El id del cliente de la suscripción.
Conekta.api_key="{global_api_key}"

customer = Conekta::Customer.find("cus_k2D9DxlqdVTagmEd400001")
subscription = customer.subscription.cancel

# Ejemplo de respuesta

puts subscription.inspect

{
  "id":"sub_EfhFCp5SKvp5XzXQk",
  "status":"canceled",
  "object":"subscription",
  "created_at":1385696776,
  "billing_cycle_start":1385696776,
  "billing_cycle_end":1386301576,
  "plan_id":"opal-plan",
  "card_id":"card_vow1u83899Rkj5LM"
}

Eventos

Eventos son la manera en que te podemos comunicar cualquier cosa que ha pasado en tu cuenta. Para poderte notificar, creamos un objeto de evento, el cual contiene toda la información que necesitas saber sobre el evento. Un ejemplo de eventos es cuando el pago de un cargo es exitoso creamos el evento charge.paid.

Por medio de nuestro API podrás realizar llamadas para poder obtener información sobre un evento en específico.

Otra manera de poder recibir estos eventos es por medio de webhooks, donde mandaremos cada uno de los eventos directamente a tu servidor. Para saber un poco más sobre webhooks, puedes ver la sección de webhooks.

Contamos con un video explicativo sobre el funcionamiento de webhooks al igual que nuestra documentación

.

NOTA: Si tu servidor cuenta con alguna restricción mediante Firewall debes añadir la IP de nuestro servidor de eventos 52.200.151.182. 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.

El Objeto Evento

Atributos

  • id: string Identificador único del cargo asignado al azar.
  • object: string Clase del objeto. En este caso, "event"
  • livemode: boolean false: Modo de prueba. true: Modo de producción.
  • created_at: timestamp Fecha de creación del cargo.
  • type: string Tipo de evento. Ejemplo: charge.paid, charge. refunded, etc.
  • data: hash Hash que contiene toda la información asociada al evento.

Tipos de Evento

  • charge.created: Evento relacionado a un cargo Este evento ocurre cuando un cargo ha sido creado pero todavía no ha sido pagado.
  • charge.paid: Evento relacionado a un cargo Este evento ocurre cuando un cargo ha sido pagado.
  • charge.refunded: Evento relacionado a un cargo Este evento ocurre cuando un cargo ha sido reembolsado en su totalidad al comprador.
  • charge.chargeback.created: Evento relacionado a un contracargo Este evento ocurre cuando el tarjetahabiente no reconoce el cargo y contacta a su banco para generar un contracargo. Para más información sobre contracargos, visita la sección de contracargos.
  • charge.chargeback.updated: Evento relacionado a un contracargo Este evento ocurre cuando alguien dentro de tu cuenta actualiza el contracargo con evidencia que apoya el caso de contracargo. Para más información sobre contracargos, visita la sección de contracargos.
  • charge.chargeback.under_review: Evento relacionado a un contracargo Este evento ocurre cuando el contracargo ha sido bloqueado y la evidencia que has proporcionado ha sido enviada al banco adquiriente para revisar el caso. Para más información sobre contracargos, visita la sección de contracargos.
  • charge.chargeback.won: Evento relacionado a un contracargo Este evento ocurre cuando el contracargo ha sido resuelto a tu favor. En este momento, el monto del contracargo que había sido retenido será devuelto a tu saldo y será disponible para el siguiente depósito a tu cuenta. Para más información sobre contracargos, visita la sección de contracargos.
  • charge.chargeback.lost: Evento relacionado a un contracargo Este evento ocurre cuando el contracargo ha sido resuelto a favor del tarjetahabiente. El monto del contracargo que había sido retenido será enviado al tarjetahabiente. Para más información sobre contracargos, visita la sección de contracargos.
  • subscription.created: Evento relacionado a una suscripción Este evento ocurre cuando una nueva suscripción ha sido creada.
  • subscription.paused: Evento relacionado a una suscripción Este evento ocurre cuando una suscripción ha sido pausada.
  • subscription.resumed: Evento relacionado a una suscripción Este evento ocurre cuando una suscripción pausada ha sido reanudada.
  • subscription.canceled: Evento relacionado a una suscripción Este evento ocurre cuando una suscripción ha sido cancelada. Aparte de que tú o el cliente haya cancelado la suscripción, también se cancelará después de varios intentos de realizar el cobro al cliente.
  • subscription.updated: Evento relacionado a una suscripción Este evento ocurre cuando una suscripción ha sido actualizada ya sea con un nuevo plan o tarjeta.
  • subscription.paid: Evento relacionado a una suscripción Este evento ocurre cuando una suscripción ha sido pagada.
  • subscription.payment_failed: Evento relacionado a una suscripción Este evento ocurre cuando el pago de una suscripción no ha podido ser procesado. En caso de que la suscripción no pueda ser procesada después de 3 intentos consecutivos, la suscripción será cancelada.
# Ejemplo de objeto de Evento

Conekta.api_key = "{global_api_key}"

events = Conekta::Event.where
puts events.inspect

[{
  "livemode": false,
  "id":"523e04f2aef878a53c000001",
  "object":"event",
  "type":"charge.paid",
  "created_at": 1379796210,
  "data": {
    "object": {
      "id":"523e04d4aef8781eaa000001",
      "livemode": false,
      "created_at": 1379796180,
      "status":"paid",
      "currency":"MXN",
      "description":"Stogies",
      "reference_id":"9839-wolf_pack",
      "failure_code": null,
      "failure_message": null,
      "object":"charge",
      "amount": 20000,
      "payment_method": {
        "service_name":"Conekta",
        "service_number":"127589",
        "object":"bank_transfer_payment",
        "type":"spei",
        "reference":"0011587"
      },
      "details": {
        "name":"Wolverine",
        "phone":"403-342-0642",
        "email":"logan@x-men.org"
      }
    },
    "previous_attributes": {
      "status":"pending_payment"
    }
  },
}]

Errores

Por medio de nuestro API, podrás ser notificado con toda la información en caso de cualquier error al momento de crear cualquier llamada a nuestro servicio.

Atributos

  • type: string El tipo de error devuelto.
  • message: string Mensaje legible para humanos el cual provee más detalles sobre el error. Este mensaje debe ser usado internamente para depuración y solo está disponible en inglés. Para cargos de tarjeta, el mensaje puede ser mostrado al usuario.
  • messagetopurchaser: string Mensaje legible para humanos el cual provee más detalles sobre el error. Este mensaje debe ser desplegado al usuario y está disponible en inglés y español. Para cargos de tarjeta, el mensaje puede ser mostrado al usuario.
  • code: string (optional) Un código corto y específico detallando processing_error.
  • param: string (optional) El parámetro al cual este error está relacionado. Puedes usar este error para subrayar campos de texto erróneos.
TIPOS
malformed_request_error
HTTP 400 - Error cuando la llamada tiene una sintaxis inválida.
authentication_error
HTTP 401 Error - La llamada no pudo ser procesada debido a problemas con la llave de API o con los permisos.
processing_error
HTTP 402 - Error más común que sucede al utilizar el cobro con tarjeta y la tarjeta no puede ser cobrada por cualquier motivo.
resource_not_found_error
HTTP 404 Error - El recurso solicitado en la llamada no existe.
parameter_validation_error
HTTP 422 - Este error ocurre cuando algún parámetro de cualquier llamada es inválido.
api_error
HTTP 500 and 503 Errors - Engloba cualquier otro tipo de error (ejemplo: problema temporal con los servidores de Conekta) y debería de ocurrir muy pocas veces.
Códigos
invalid_amount
La cantidad a cobrar no está presente o es inválida. La cantidad debe ser un integer con valor en centavos (ejemplo: $50.00 -> 5000).
invalid_payment_type
El tipo de pago no está presente o es inválido. Los tipos de pago aceptados son card, bank, and cash.
missing_description
La descripción del cargo no está presente. La descripción del cargo es obligatoria.
unsupported_currency
La divisa proporcionada no puede ser reconocida o no es soportada hasta ahora.
invalid_number
El número de la tarjeta es inválido.
invalid_expiry_month
El mes de expiración de la tarjeta es inválido.
invalid_expiry_year
El año de expiración de la tarjeta es inválido.
invalid_cvc
El código de seguridad de la tarjeta es inválido.
expired_card
La tarjeta ha expirado.
card_declined
La tarjeta ha sido declinada.
processing_error
Ha habido un error al momento de procesar la tarjeta. Ningún cargo ha sido realizado.
insufficient_funds
El cargo no ha sido procesado porque la tarjeta no tiene fondos suficientes.
suspected_fraud
Se ha detectado un comportamiento sospechoso en la transacción.

Códigos de Status HTTP

200 - OK
Todo ha salido a la perfección.
400 - Bad Request
La llamada no pudo ser entendida por el servidor debido a una sintaxis incorrecta.
401 - Unauthorized
La llave de API utilizada es inválida.
402 - Payment Required
El pago no pudo ser procesado.
404 - Not Found
El recurso solicitado en la llamada no existe.
422 - Unprocessable Entity
La sintaxis de la llamada es válida pero la información dentro de los Argumentos es inválida.
500, 503 - Server Errors
Algo estuvo mal del lado de Conekta y la llamada no pudo ser procesada.

Manejar Errores

Nuestras librerías pueden regresar excepciones por diferentes razones, como cargos fallidos, parámetros inválidos, errores de autenticación, etc. Te recomendamos siempre tratar de manejar excepciones en tu implementación.

begin
  # Llamada a Conekta...
rescue Conekta::ParameterValidationError => e
  puts e.message_to_purchaser 
  #alguno de los parámetros fueron inválidos

rescue Conekta::ProcessingError => e
  puts e.message_to_purchaser 
  #la tarjeta no pudo ser procesada

rescue Conekta::Error => e
  puts e.message_to_purchaser 
  #un error ocurrió que no sucede en el flujo normal de cobros como por ejemplo un auth_key incorrecto

rescue => e
  # algo distinto sucedió totalmente ajeno a Conekta

end