DocumentaciónAPIDevToolsRecipesForoTarjetas de PruebasEstado del ServicioChangelog
Documentación
Iniciar Sesión

Cargo bajo demanda

Suggest Edits

❗️

IMPORTANTE

Esta modalidad de Pago con Tarjeta te permitirá almacenar una o varias tarjetas (métodos de pago) y relacionarlas a un único cliente. Con ello podrás crear órdenes de pago cada que lo requiera tu negocio, sin necesidad de solicitar los datos del método de pago de nuevo.

Si tu negocio no cuenta con una Certificación Nivel I de PCI DSS, con permisos para gestionar y procesar datos, deberás utilizar el “Component” de Conekta para integrar esta modalidad. Ve al siguiente enlace para continuar con tu implementación.

Características

  • Es necesario registrar/almacenar un cliente en Conekta
  • Es necesario registrar/almacenar al menos un método de pago en Conekta (tarjeta)
  • El token que se genera al cifrar la tarjeta, no vence. Además no se envía de manera directa sobre la orden de pago

Flujo

Pasos para integrar

Generar autenticación de API

Para configurar los headers de tus peticiones, sigue las instrucciones de la sección “Primeros Pasos”.

Crear Cliente

Se solicita registrar la información mínima indispensable para una transacción, “nombre”, “email” y “teléfono” (para más detalle ver Referencia API). En el siguiente request se incluye un atributo extra tipo llave-valor llamado “Metadata” en el que puedes agregar información específica de tu negocio que requieras.

Request

-H "Accept: application/vnd.conekta-v2.1.0+json" \
-H "Content-type: application/json" \
-u key_YOUR_PRIVATE_API_KEY: \
-X POST -d '{
 "name": "Jorge Martínez",
 "email": "[email protected]",
 "phone": "+52181818181",
 "metadata": {
   "business_ID": "1298-AZS",
   "random_key": "random value"
 }
}’https://api.conekta.io/customers

{
   "livemode": false,
   "name": "Jorge Martínez",
   "email": "[email protected]",
   "phone": "+52181818181",
   "id": "cus_2tTSkfScREpvaRJsE",
   "object": "customer",
   "created_at": 1677797262,
   "corporate": false,
   "metadata": {
       "business_ID": "1298-AZS",
       "random_key": "random value"
   },
   "custom_reference": ""
}

Crear Método de Pago y asociarlo a un cliente

Request

-H "Accept: application/vnd.conekta-v2.1.0+json" \
-H "Content-type: application/json" \
-u key_YOUR_PRIVATE_API_KEY: \
-X POST -d '{
  "type": "card",
  "number": "4242424242424242",
  "name": "Jorge Martinez",
  "exp_month": "12",
  "exp_year": "2029",
  "cvc": "198",
}’https://api.conekta.io/customers/cus_2tTSkfScREpvaRJsE/payment_sources/

{
   "address": {
       "street1": "1295 Charleston Road",
       "city": "Mountain View",
       "state": "CA",
       "country": "US",
       "object": "address",
       "postal_code": "94043"
   },
   "id": "src_2tTTgLhh7wcYanoMZ",
   "object": "payment_source",
   "type": "card",
   "created_at": 1677801479,
   "last4": "8301",
   "bin": "283081",
   "card_type": "credit",
   "exp_month": "12",
   "exp_year": "2024",
   "brand": "visa",
   "name": "Jorge Martínez",
   "parent_id": "cus_2tTSkfScREpvaRJsE",
   "default": false,
   "payment_source_status": "active",
   "visible_on_checkout": false
}

Al consultar la información de los métodos de pago del customer, el recién creado se muestra como “default”: true. Eso significa que ya puedes utilizarlo como predeterminado para tus órdenes posteriores de pago.

Request

-H "Accept: application/vnd.conekta-v2.1.0+json" \
-H "Content-type: application/json" \
-u key_YOUR_PRIVATE_API_KEY: \
-X GET -d '{
}’https://api.conekta.io/customers/cus_2tTSkfScREpvaRJsE/payment_sources/

{
    "has_more": false,
    "object": "list",
    "data": [
        {
            "address": {
                "street1": "1295 Charleston Road",
                "city": "Mountain View",
                "state": "CA",
                "country": "US",
                "object": "address",
                "postal_code": "94043"
            },
            "id": "src_2tTTgLhh7wcYanoMZ",
            "object": "payment_source",
            "type": "card",
            "created_at": 1677801479,
            "last4": "4242",
            "bin": "424242",
            "card_type": "credit",
            "exp_month": "11",
            "exp_year": "36",
            "brand": "visa",
            "name": "Jorge Lopez",
            "parent_id": "cus_2tTSkfScREpvaRJsE",
            "default": true,**
            "payment_source_status": "active",
            "visible_on_checkout": false
        }
    ]
}

Si quieres cambiar de método de pago default, almacena otra tarjeta asociada al customer creando un método de pago nuevo. Después, utiliza el siguiente request para volverlo predeterminado con el src_ID devuelto.

Request

-H "Accept: application/vnd.conekta-v2.1.0+json" \
-H "Content-type: application/json" \
-u key_YOUR_PRIVATE_API_KEY: \
-X PUT -d '{

   "default_payment_source_id": "src_2qUCPsc8vpAVBWHiV"

}’https://api.conekta.io/customers/cus_2tTSkfScREpvaRJsE

{
    "has_more": false,
    "object": "list",
    "data": [
        {
            "address": {
                "street1": "1295 Charleston Road",
                "city": "Mountain View",
                "state": "CA",
                "country": "US",
                "object": "address",
                "postal_code": "94043"
            },
            "id": "src_2qUCPsc8vpAVBWHiV",
            "object": "payment_source",
            "type": "card",
            "created_at": 1677801479,
            "last4": "4242",
            "bin": "424242",
            "card_type": "credit",
            "exp_month": "11",
            "exp_year": "36",
            "brand": "visa",
            "name": "Jorge Lopez",
            "parent_id": "cus_2tTSkfScREpvaRJsE",
            "default": true,
            "payment_source_status": "active",
            "visible_on_checkout": false
        }
    ]
}

👍

TIP

Puedes crear directamente el cliente con su método de pago en 1 solo paso.

Request

-H "Accept: application/vnd.conekta-v2.1.0+json" \
-H "Content-type: application/json" \
-u key_YOUR_PRIVATE_API_KEY: \
-X POST -d '{
 "name": "Jorge Martínez",
 "email": "[email protected]",
 "phone": "+52181818181",
 "metadata": {
   "business_ID": "1298-AZS",
   "random_key": "random value"
 }
"payment_sources":[{
  "type": "card",
  "number": "4242424242424242",
  "name": "Jorge Martinez",
  "exp_month": "12",
  "exp_year": "2024",
  "cvc": "198",
 }]
}’https://api.conekta.io/customers

{
   "livemode": false,
   "name": "Jorge Martínez",
   "email": "[email protected]",
   "phone": "+52181818181",
   "id": "cus_2tTU5GdkwZvBmS3fN",
   "object": "customer",
   "created_at": 1677803280,
   "corporate": false,
   "metadata": {
       "business_ID": "1298-AZS",
       "random_key": "random value"
   },
   "custom_reference": "",
   "default_payment_source_id": "src_2tTU5GdkwZvBmS3fT",
   "payment_sources": {
       "object": "list",
       "has_more": false,
       "data": [
           {
               "address": {
                   "street1": "1295 Charleston Road",
                   "city": "Mountain View",
                   "state": "CA",
                   "country": "US",
                   "object": "address",
                   "postal_code": "94043"
               },
               "id": "src_2tTU5GdkwZvBmS3fT",
               "object": "payment_source",
               "type": "card",
               "created_at": 1677803280,
               "last4": "4242",
               "bin": "424242",
               "card_type": "credit",
               "exp_month": "08",
               "exp_year": "29",
               "brand": "visa",
               "name": "Jorge Lopez",
               "parent_id": "cus_2tTU5GdkwZvBmS3fN",
               "default": true,
               "payment_source_status": "active",
               "visible_on_checkout": false
           }
       ]
   }
}

Crear orden de pago

La orden requiere de cierta información que obtiene ya sea de algún servicio interno del negocio, o directamente del FrontEnd al solicitarla al usuario/cliente final. Los datos principales traducidos a atributos del request son:

  • ¿Quién está pagando? -> Customer
  • ¿Qué está pagando? -> Line_items
  • ¿Cuánto está pagando? -> Unit_pice multiplicado por Quantity
  • ¿Cuál es el método de pago? -> Payment_method
  • ¿Información extra requerida por el negocio? -> Metadata

Request

-H "Accept: application/vnd.conekta-v2.0.0+json" \
-H "Content-type: application/json" \
-u key_YOUR_PRIVATE_API_KEY: \
-X POST -d '{
    "currency": "MXN",
    "customer_info": {
        "customer_id": "cus_2tTU5GdkwZvBmS3fN"
     },
    "line_items": [
      {
        "name": "Vasija de Cerámica",
        "unit_price": 20015,
        "quantity": 1,
        "description": "Description",
        "sku": "SKU",
        "charges":[{
            "payment_method": {
                "type": "default"
            }
      }]
   }]
}’https://api.conekta.io/orders

{
   "livemode": false,
   "amount": 20015,
   "currency": "MXN",
   "amount_refunded": 0,
   "customer_info": {
       "email": "[email protected]",**
       "phone": "+52181818181",**
       "name": "Jorge Martínez",**
       "corporate": false,
       "customer_id": "cus_2tTU5GdkwZvBmS3fN",**
       "object": "customer_info"
   },
   "object": "order",
   "id": "ord_2tTUAiM5p5JbLGbDw",**
   "metadata": {},
   "is_refundable": false,
   "created_at": 1677803708,
   "updated_at": 1677803708,
   "line_items": {
       "object": "list",
       "has_more": false,
       "total": 1,
       "data": [
           {
               "name": "Vasija de Cerámica",**
               "description": "Description",**
               "unit_price": 20015,**
               "quantity": 1,**
               "object": "line_item",
               "id": "line_item_2tTUAiM5p5JbLGbDu",
               "parent_id": "ord_2tTUAiM5p5JbLGbDw",
               "metadata": {},
               "antifraud_info": {}
           }
       ]
   },
    "charges": {
        "object": "list",
        "has_more": false,
        "total": 1,
        "data": [
            {
                "id": "63f3ea0d88dc6c0019a3fe39",
                "livemode": false,
                "created_at": 1676929549,
                "currency": "MXN",
                "device_fingerprint": "e6edc7bb5ca296c0c61acb60ad20d083",
                "payment_method": {
                    "name": "ESTEFANIA ALBARRAN",
                    "exp_month": "12",
                    "exp_year": "23",
                    "auth_code": "731650",
                    "object": "card_payment",
                    "type": "credit",
                    "last4": "4242",
                    "brand": "visa",
                    "issuer": "banamex",
                    "account_type": "BANAMEX",
                    "country": "MX",
                    "fraud_indicators": []
                },
                "object": "charge",
                "description": "Payment from order",
                "status": "paid",**
                "amount": 23000,**
                "paid_at": 1676929550,**
                "fee": 1255,**
                "customer_id": "",
                "order_id": "ord_2tQAKpPrfkdyzZvfM"
            }
        ]
    }
}

🚧

Nota

El mapeo de la respuesta es importante para que puedas realizar la conciliación automática de tu negocio, es decir, cuando recibas un pago puedas registrarlo en tu sistema y ejecutar los procesos requeridos como: actualización de balances, activación de servicio o entrega de producto.

Puedes utilizar el response del request para creación de orden tomando en cuenta los datos principales (marcados con **) y demás información que consideres necesaria para los procesos mencionados anteriormente.


👍

Tip:

Al momento de crear la orden, es importante saber que puedes utilizar directamente el payment_source_id devuelto al asociar la tarjeta al customer, o puedes utilizar directo el método de pago default del cliente.

Utilizando el payment_source_id:

"charges":[{
    "payment_method": {
        "type": "card", 
        "payment_source_id": "src_2qUCNd5AyQqfPMBuV"
      }
  }],

Utilizando el método de pago "default":

  • El método de pago default de un customer siempre será la primer tarjeta asociada, sin embargo puedes cambiar el método de pago predeterminado en con el paso Cambiar método de pago default:
"charges":[{
    "payment_method": {
        "type": "default"
      }
  }],

Además, si tu comercio es PCI, podrás enviar un nuevo CVC/CVV en el cargo:

"charges":[{
"payment_method": {
        "type": "card",  
        "payment_source_id": "src_2qUCNd5AyQqfPMBuV",  
        "cvc": "123"  
      }  
  }],

o también de esta forma:

"charges":[{  
    "payment_method": {  
        "type": "default",  
        "cvc": "123"  
      }  
  }],

Notificaciones vía webhook

Esta modalidad de pago a través de tarjeta tiene comunicación directa vía API para cada uno de los momentos de la transacción. Lo que significa que a cada request hay un response exitoso o fallido inmediato con el que puedes conciliar automáticamente.

Sin embargo, todos los eventos que ocurran antes, durante y después de una transacción pueden ser notificados a través de webhooks, justo en el momento en que ocurren. Te enlistamos todos los eventos que intervienen en esta modalidad, accediendo al siguiente enlace para revisar el detalle del payload correspondiente a cada uno de ellos, y mapearlos para llevar a cabo los procesos internos de tu negocio requeridos.

Te recomendamos capturar los siguientes eventos:

EventoDescripción
order.paidEnviado cuando el cliente completa un pago de forma exitosa
order.pending_paymentEnviado cuando una orden es creada pero está pendiente de pago
order.declinedEnviado cuando el pago de una orden es declinado.

Updated 3 months ago