Pagos recurrentes con efectivo

Hemos creado este tutorial para que puedas recibir pagos recurrentes en efectivo a través de Conekta. Así, tus clientes podrán pagar las veces que quieran tus productos o servicios. En el caso de Oxxo, cada cliente tendrá una referencia única para realizar los pagos.

Copia tus llaves privadas de pruebas. Si aún no las tienes, puedes obtenerlas en el siguiente enlace: panel Conekta](https://admin.conekta.com/settings/keys).

1. Crea tu orden de pago recurrente

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

begin
  customer = Conekta::Customer.create({
        name: "Fulanito",
        email: "[email protected]",
        phone: "52134659439",
        payment_method: {
            type: "cash_recurrent"
        }
  })
rescue Conekta::Error => error
  for error_detail in error.details do
    puts error_detail.message
  end
end
curl --request POST \
  --url https://api.conekta.io/customers \
  --header 'accept: application/vnd.conekta-v2.0.0+json' \
  -u key_eYvWV7gSDkNYXsmr: \
  --header 'content-type: application/json' \
  --data '{
      "name": "Fulanito",
      "email": "[email protected]",
      "phone": "+5218181818181",
      "payment_sources": [{
        "type": "oxxo_recurrent"
        }]
  }'

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

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

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

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

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

//Respuesta json de API
{
"livemode":false, 
"name":"Oxxo recc", 
"email":"[email protected]",
"phone":"52134659439",
"id":"cus_2jP5P8huCTWqcTtrn", 
"object":"customer",
"created_at":1538686075,
"corporate":false, 
"custom_id":"", 
"payment_sources":{
  "object":"list", 
  "has_more":false, 
  "total":1,
  "data":[{
    "id":"off_ref_2jP5P8huCTWqcTtro", 
    "object":"payment_source",
    "type":"oxxo_recurrent",
    "provider":"Oxxo",
    "reference":"CUSTOM_REFERENCE_RETURNED",
    "barcode":"CUSTOM_REFERENCE_RETURNED",
    "barcode_url":"https://sandbox_reference.png",
    "expires_at":0,
    "created_at":1538686075,
    "parent_id":"cus_2jP5P8huCTWqcTtrn"}]
}}
try{
  conekta.Customer customer = new conekta.Customer ().create(@"{
      ""name"": ""Fulanito"",
      ""email"": ""[email protected]"",
      ""phone"": ""+5218181818181"",
      ""payment_method"": {
        ""type"": ""oxxo_recurrent"",
      }
  }");
} catch (ConektaException e) {
  foreach (JObject obj in e.details) {
    System.Console.WriteLine("\n [ERROR]:\n");
    System.Console.WriteLine("message:\t" + obj.GetValue("message"));
    System.Console.WriteLine("debug:\t" + obj.GetValue("debug_message"));
    System.Console.WriteLine("code:\t" + obj.GetValue("code"));
  }
}

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

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

res, err := customer.Create(cus)

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

2. Presenta la ficha de pago

Utiliza la ficha de pago que muestre las cadenas que corresponden al pago en efectivo configurado para tu negocio. Esta ficha permitirá mostrarle a tus clientes la referencia de pago en efectivo junto con los pasos necesarios para completarlo en el punto de venta de su preferencia.

Referencia de pago "Oxxo"

300300

Referencia de pago "Otras cadenas"

Ficha de pago en efectivo con Conekta

Tienes que incluirla en tu Checkout o enviarla por correo para ofrecer una mejor experiencia.
Puedes obtenerla en Ejemplo de pago en efectivo con Conekta

En este link puedes descargar los logos de nuestra red de efectivo.

3. Crea un Webhook

Recuerda que Conekta debe estar en constante comunicación con tu sitio a través de Webhooks para:

1)​ Validar que la referencia del usuario sea correcta y pueda hacer pagos
2)​ Aprobar la cantidad que el usuario quiere pagar
3)​ Notificar un pago
Un “Webhook” es un sistema de notificaciones, donde tu sitio debe definir una dirección o URL, para que nuestra API mande peticiones HTTP y pueda notificarte de los eventos que se van a realizar en tu sitio. Por ello, deberás crear un “Webhook” desde tu perfil de administrador con los siguientes pasos:

Abre el menú principal de tu cuenta, ubicado en la esquina superior derecha, y selecciona la sección “​Webhooks”.

3.1 Crear un Webhook Sincrónico para Aprobar Pagos

En el caso de pagos recurrentes, vas a recibir eventos especiales para poder aprobar o declinar los pagos de forma dinámica. Estas peticiones te van a llegar en tiempo real y tienes un máximo de dos segundos para contestarlas o se va declinar el pago. En el Perfil de Administrador abre el menú principal de tu cuenta, ubicado en la esquina superior derecha, y selecciona Webhooks​

201201

Selecciona la opción “​Crear Webhook” al presionarlo se abrirá una ventana con un formulario en donde deberás colocar la dirección o URL del “Webhook” donde deseas recibir las notificaciones de los pagos recurrentes en efectivo con Conekta, selecciona la casilla de "Usar para Oxxo Pay Recurrente" y da clic en “Crear”.

451451

Ya estás listo para recibir pagos recurrentes desde tu sitio.

3.2 Crea un Webhook asincrónico para recibir notificaciones de pagos

Adicional al primer Webhook, tendrías que armar endpoint para escuchar notificaciones asincrónicas de pago. A diferencia de las notificaciones anteriores, Conekta va reintentar las notificaciones en caso de que fallen y vas a recibir mayor carga de otras notificaciones por eso que es importante ocupar otro endpoint.

Cuando creas este Webhook, no tendrías que indicar que es para pagos recurrentes.

4. Responder a Webhooks

A diferencia de métodos de pago en línea, como tarjetas, los usuarios tienen que realizar acciones offline para hacer pagos en efectivo así que flujo es asincrónico y el procesamiento y seguridad de notificaciones es fundamental para tu flujo.

4.1 Responder a Consultas

El primero notificación a responder, es una notificación sincrónica de consulta y con el tipo de inbound_payment.lookup.

{
  "data":{
    "object": {
      "payment_method": {
        "service_name": "OxxoPay",
        "barcode_url": "https://barcode/url.png",
        "object": "cash_payment",
        "type": "oxxo",
        "expires_at": 1541289600,
        "reference": "8400003726321"
      },
      "charge_id": "5bb675388a268e0ef4a56a42",
      "livemode": true,
      "created_at": 0,
      "object": "inbound_payment",
      "amount": 0,
      "currency": "MXN",
      "customer_id": "cus_2jP5P8huCTWqcTtrn"
    },
    "previous_attributes": {}
  },
  "livemode": true,
  "webhook_status": "not_applicable",
  "webhook_logs": [],
  "id": "5b438f82583eb80d50b4652c",
  "object": "event",
  "type": "inbound_payment.lookup",
  "created_at": 1531154306
}

Para aprobar el pago tendrías que contestar en JSON, indica que payable es true, y el rango de cantidades en centavos.

{
    "payable": true,
    "min_amount": 5000,
    "max_amount": 1000000
}

En caso que quieras declinar un pago, puedes indicar payable: false y un código de rechazo. Puedes consultar la lista completa de códigos de rechazo al final del tutorial.

{
    "payable": false,
    "failure_code": "15"
}

4.2 Responder a confirmaciones de Pago

La primer notificación a responder, es una notificación sincrónica de consulta y con el tipo de inbound_payment.payment_attempt.

{
  "data": {
  "object": {
    "payment_method": {
        "service_name":"OxxoPay",
        "barcode_url": "https://s3.amazonaws.com/cash_payment_barcodes/84000045432316.png",
        "object": "cash_payment",
        "type": "oxxo",
        "expires_at": 1541289600,
        "reference": "84000045432316"
      },
      "charge_id": "5bb6755d8a268e0ed9a56acb", "livemode": true,
      "created_at": 1538684253,
      "object": "inbound_payment",
      "amount": 110700,
      "currency": "MXN",
      "customer_id": "cus_2jHUgfTB4pYmjmHpB"
    },
    "previous_attributes": {}
  },
  "livemode": true,
  "webhook_status": "not_applicable",
  "webhook_logs": [],
  "id": "5b439072583eb80d50b46534",
  "object": "event",
  "type": "inbound_payment.payment_attempt",
  "created_at": 1531154546
}

Para aprobar el pago tendrías que contestar en JSON, indicando que payable es true

{
    "payable": true
}

En caso que quieras declinar un pago, puedes indicar payable: false y un código de rechazo. Puedes consultar la lista completa de códigos de rechazo al fin del tutorial.

{
    "payable": false,
    "failure_code": "15"
}

5. Recibir confirmaciones de pago

La última notificación a recibir es una notificación asincrónica de pago con el tipo de charge.paid. Para seguridad es crítico verificar la firma de notificaciones. El siguiente ejemplo pertenece a una notificación de pago:

{
  "data": {
    "object": {
      "id": "5c0968098a268e02ab8aa3f7",
      "livemode": true,
      "created_at": 1544120329,
      "currency": "MXN",
      "description": null,
      "reference_id": null,
      "failure_code": null,
      "failure_message": null,
      "monthly_installments": null,
      "device_fingerprint": null,
      "refunds": [],
      "payment_method": {
        "barcode": "XXXXXXXXX",
        "reference": "XXXXXXXXX",
        "barcode_url": "https://s3.amazonaws.com/cash_payment_barcodes/XXXXXXXXX.png",
        "object": "cash_payment",
        "type": "oxxo",
        "expires_at": 1546732800,
        "store_name": "OXXO"
      },
      "details": {
        "name": "Juan Perez",
        "phone": null,
        "email": "[email protected]",
        "line_items": [],
        "coupons": [],
        "object": "details"
      },
      "object": "charge",
      "status": "paid",
      "amount": 350000,
      "paid_at": 1544120362,
      "fee": 10150,
      "customer_id": "cus_2j35ehQaF1jZEcWH7",
      "subscription_id": "",
      "amount_refunded": null
      },
    "previous_attributes": {}
  },
  "livemode": true,
  "webhook_status": "not_applicable",
  "webhook_logs": [],
  "id": "5b439072583eb80d50b46534",
  "object": "event",
  "type": "charge.paid",
  "created_at": 1531154546
}

6. Flujos de prueba

Tienes disponibles endpoints para que para que puedas probar el flujo de pagos end-to-end antes de hacer pruebas. Recuerda que todo se puede probar pegando el endpoints de https://api.conekta.io/payment_test

6.1 Pruebas de Consultas

El siguiente payload va lanzar la notificación a tu endpoint de consulta.

{
  "event_type": "inbound_payment.lookup",
  "reference": "99000000001273"
}

Por ejemplo

curl --request POST \
  --url https://api.conekta.io/payment_test \
  --header 'accept: application/vnd.conekta-v2.0.0+json' \
  -u YOUR_PRIVATE_SANDBOX_API_KEY: \
  --header 'content-type: application/json' \
  --data '{ "event_type": "inbound_payment.lookup", "reference": "99000000001273" }'

6.2 Pruebas de confirmaciones de pago

El siguiente payload te enviará una notificación de confirmación de pago a tu Webhook.

{
  "event_type": "inbound_payment.payment_attempt",
  "reference": "99000000001273",
  "amount": "10000"
}

Por ejemplo

curl --request POST \
  --url https://api.conekta.io/payment_test \
  --header 'accept: application/vnd.conekta-v2.0.0+json' \
  -u YOUR_PRIVATE_SANDBOX_API_KEY: \
  --header 'content-type: application/json' \
  --data '{ "event_type": "inbound_payment.payment_attempt", "reference": "99000000001273", "amount": "10000" }'

6.3 Pruebas de reversos de pago

El siguiente payload va lanzar una notificación de reverso de pago a tu Webhook.

{
  "event_type": "inbound_payment.reverse",
  "reference": "99000000001273"
}

Por ejemplo

curl --request POST \
  --url https://api.conekta.io/payment_test \
  --header 'accept: application/vnd.conekta-v2.0.0+json' \
  -u YOUR_PRIVATE_SANDBOX_API_KEY: \
  --header 'content-type: application/json' \
  --data '{ "event_type": "inbound_payment.reverse", "reference": "99000000001273" }'

Códigos de rechazo

Te compartimos los siguientes códigos de rechazo para que puedes comunicar fallas a tus clientes en cajero

failure_codeDescripción
01Referencia no encontrada
02Cantidad inválida
03Referencia expirada
10Referencia sin deuda
13Referencia inactiva
14Referencia cancelada
15Usuario bloqueado
16Cantidad no permitida
18Comercio fuera de horario
19No autorizado
35Monto fuera del rango permitido
36Referencia ya pagada