Pagos únicos en efectivo

Antes de comenzar

Al finalizar este tutorial podrás recibir pagos en efectivo desde tu tienda en línea y recibir las notificaciones de los pagos en tiempo real.

📘

¿Qué necesito para comenzar?

Recomendamos tener conocimientos de APIs.
Es preferible ser desarrollador fullstack (frontend + backend).
Debes instalar o incluir una de las librerías disponibles de Conekta.
Tener tus API Keys (llave personal) de pruebas.

Paso 1 - Agrega tu llave privada y versión del API

Copia tus llaves privadas de pruebas. Si aún no las tienes, puedes obtenerlas en el siguiente enlace:
Quiero obtener mis API keys .

require "conekta"
Conekta.api_key = "key_eYvWV7gSDkNYXsmr"
Conekta.api_version = "2.0.0"
# N/A
require_once("/path/to/lib/Conekta.php");
\Conekta\Conekta::setApiKey("key_eYvWV7gSDkNYXsmr");
\Conekta\Conekta::setApiVersion("2.0.0");
import conekta
conekta.api_key = "key_eYvWV7gSDkNYXsmr"
conekta.api_version = "2.0.0"
var conekta = require('conekta');
conekta.api_key = 'key_eYvWV7gSDkNYXsmr';
conekta.api_version = '2.0.0';
import com.conekta;
Conekta.setApiKey("key_eYvWV7gSDkNYXsmr");
com.conekta.Conekta.apiVersion = "2.0.0";
using conekta;
conekta.Api.apiKey = "key_eYvWV7gSDkNYXsmr";
conekta.Api.version = "2.0.0";
import (
    conekta "github.com/conekta/conekta-go"
)
conekta.APIKey = "key_pMcnDF4zFyWKyLG15LuqwA"

Paso 2 - Crea una orden

Al crear una orden se generará el cargo de tu cliente. Si no deseas crear el cargo de inmediato, puedes preparar la orden y después generar el cargo mandando la información del arreglo charges.

Los campos mostrados en el siguiente ejemplo son los mínimos que se requieren para continuar, si deseas saber más sobre el objeto llamado order, puedes revisar nuestra REST API para más información.

Si deseas que tu ficha de compra tenga un periodo de expiración, puedes agregar expires_at dentro de payment_method, es un campo tipo unix timestamp que te permite generar una ficha que expire ¡incluso segundos!

begin
  thirty_days_from_now = Time.now.advance(days: 30).to_i 

  order = Conekta::Order.create({
    line_items: [{
        name: "Tacos",
        unit_price: 1000,
        quantity: 12
    }],
    shipping_lines: [{
        amount: 1500,
        carrier: "FEDEX"
    }], #shipping_lines - physical goods only
    currency: "MXN",
    customer_info: {
        name: "Fulanito Pérez",
        email: "[email protected]",
        phone: "+5218181818181"
    },
    shipping_contact: {
        address: {
            street1: "Calle 123, int 2",
            postal_code: "06100",
            country: "MX"
        }
    }, #shipping_contact - required only for physical goods
    charges: [{
        payment_method: {
            type: "cash",
            expires_at: thirty_days_from_now
        }
    }]
  })
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/orders \
  --header 'accept: application/vnd.conekta-v2.0.0+json' \
  -u key_eYvWV7gSDkNYXsmr: \
  --header 'content-type: application/json' \
  --data '{
    "line_items": [{
      "name": "Tacos",
      "unit_price": 1000,
      "quantity": 12
    }],
    "shipping_lines": [{
      "amount": 1500,
      "carrier": "FEDEX"
    }],
    "currency": "MXN",
    "customer_info": {
      "name": "Fulanito Pérez",
      "email": "[email protected]",
      "phone": "+5218181818181"
    },
    "shipping_contact":{
    "address": {
      "street1": "Calle 123, int 2",
      "postal_code": "06100",
      "country": "MX"
     }
    },
    "charges":[{
      "payment_method": {
        "type": "oxxo_cash",
        "expires_at": 1600871926
      }
    }]
  }'
try{
  $thirty_days_from_now = (new DateTime())->add(new DateInterval('P30D'))->getTimestamp(); 

  $order = \Conekta\Order::create(
    [
      "line_items" => [
        [
          "name" => "Tacos",
          "unit_price" => 1000,
          "quantity" => 12
        ]
      ],
      "shipping_lines" => [
        [
          "amount" => 1500,
          "carrier" => "FEDEX"
        ]
      ], //shipping_lines - physical goods only
      "currency" => "MXN",
      "customer_info" => [
        "name" => "Fulanito Pérez",
        "email" => "[email protected]",
        "phone" => "+5218181818181"
      ],
      "shipping_contact" => [
        "address" => [
          "street1" => "Calle 123, int 2",
          "postal_code" => "06100",
          "country" => "MX"
        ]
      ], //shipping_contact - required only for physical goods
      "charges" => [
        [
          "payment_method" => [
            "type" => "oxxo_cash",
            "expires_at" => $thirty_days_from_now
          ]
        ]
      ]
    ]
  );
} catch (\Conekta\ParameterValidationError $error){
  echo $error->getMessage();
} catch (\Conekta\Handler $error){
  echo $error->getMessage();
}
try:
  from datetime import datetime
  from datetime import timedelta 

  thirty_days_from_now = int((datetime.now() + timedelta(days=1)).timestamp()) 

  order = conekta.Order.create({
    "line_items": [{
        "name": "Tacos",
        "unit_price": 1000,
        "quantity": 12
    }],
    "shipping_lines": [{
        "amount": 1500,
        "carrier": "FEDEX"
    }], #shipping_lines - physical goods only
    "currency": "MXN",
    "customer_info": {
      "name": "Fulanito Pérez",
      "email": "[email protected]",
      "phone": "+5218181818181"
    },
    "shipping_contact":{
       "address": {
         "street1": "Calle 123, int 2",
         "postal_code": "06100",
         "country": "MX"
       }
    }, #shipping_contact - required only for physical goods
    "charges":[{
      "payment_method": {
        "type": "oxxo_cash",
        "expires_at": thirty_days_from_now
      }
    }]
  })
except conekta.ConektaError as e:
  print e.message
thirty_days_from_now = (Math.round(Date.now()/1000 + 60 \* 60 \* 24 \* 30)).toString() 

order = conekta.Order.create({
  "line_items": [{
      "name": "Tacos",
      "unit_price": 1000,
      "quantity": 12
  }],
  "shipping_lines": [{
      "amount": 1500,
      "carrier": "FEDEX"
  }], //shipping_lines - phyiscal goods only
  "currency": "MXN",
  "customer_info": {
    "name": "Fulanito Pérez",
    "email": "[email protected]",
    "phone": "+5218181818181"
  },
  "shipping_contact":{
     "address": {
       "street1": "Calle 123, int 2",
       "postal_code": "06100",
       "country": "MX"
     }
  }, //shipping_contact - required only for physical goods
  "charges":[{
    "payment_method": {
      "type": "oxxo_cash",
      "expires_at": thirty_days_from_now
    }
  }]
}, function(err, res) {
    console.log(res.toObject());
});
Long nowUnixTimestamp = System.currentTimeMillis();
Long thirtyDaysFromNowUnixTimestamp =  (nowUnixTimestamp + 30L \* 24 \* 60 \* 60 \* 1000) / 1000L;
String thirtyDaysFromNow = thirtyDaysFromNowUnixTimestamp.toString(); 

try{
  Order order = Order.create(
    new JSONObject("{"
      + "'line_items': [{"
          + "'name': 'Tacos',"
          + "'unit_price': 1000,"
          + "'quantity': 12"
      + "}],"
      + "'shipping_lines': [{"
          + "'amount': 1500,"
          + "'carrier': 'FEDEX',"
      + "}]," //shipping_lines - physical goods only
      + "'currency': 'MXN',"
      + "'customer_info': {"
        + "'name': 'Fulanito Pérez',"
        + "'email': '[email protected]',"
        + "'phone': '+5218181818181'"
      + "},"
      + "'shipping_contact':{"
         + "'address': {"
           + "'street1': 'Calle 123, int 2',"
           + "'postal_code': '06100',"
           + "'country': 'MX'"
         + "}"
       + "}," //shipping_contact - required only for physical goods
      + "'charges':[{"
        + "'payment_method': {"
          + "'type': 'oxxo_cash',"
          + "'expires_at': " + thirtyDaysFromNow
        + "}"
      + "}]"
    + "}"
    )
  );
}catch (Conekta::Error e) {
   System.out.println(e.details.get(0).message);
}
//Calculate an expiration time
DateTime thirtyDaysFromNowDateTime = DateTime.Now.AddDays(30);
long thirtyDaysFromNowUnixTimestamp = (Int64)(thirtyDaysFromNowDateTime.Subtract(new DateTime(1970, 1, 1)).TotalSeconds);
String thirtyDaysFromNow = thirtyDaysFromNowUnixTimestamp.ToString(); 

try{
  conekta.Order order = new conekta.Order ().create(@"{
    ""line_items"": [{
        ""name"": ""Tacos"",
        ""unit_price"": 1000,
        ""quantity"": 12
    }],
    ""shipping_lines"": [{
        ""amount"": 1500,
        ""carrier"": ""FEDEX""
    }]," + //shipping_lines - physical goods only
    @"""currency"": ""MXN"",
    ""customer_info"": {
      ""name"": ""Fulanito Pérez"",
      ""email"": ""[email protected]"",
      ""phone"": ""+5218181818181""
    },
    ""shipping_contact"":{
       ""address"": {
         ""street1"": ""Calle 123, int 2"",
         ""postal_code"": ""06100"",
         ""country"": ""MX""
       }
    }," + //shipping_contact - required only for physical goods only
    @"""charges"":[{
      ""payment_method"": {
        ""type"": ""oxxo_cash"",
        ""expires_at"": " + thirtyDaysFromNow + @"
      }
    }]
  }");
} 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"));
  }
}
Address := &conekta.Address{
    Street1: "Street1",
    Street2: "Street2",
    City: "City",
    State: "State",
    Country: "Country",
    PostalCode: "PostalCode",
}

customerParams := &conekta.CustomerParams{
    Name: "Fulanito Perez",
    Phone: "5512345678",
    Email: "[email protected]",
}

lineItemParams := &conekta.LineItemsParams{
    Name: "Naranjas Robadas",
    UnitPrice: 10000,
    Quantity: 2,
}

shippingParams := &conekta.ShippingLinesParams{
    Amount: 200,
    TrackingNumber: "123",
    Carrier: "Test Carrier",
    Method: "method",
}

shippingContactParams := &conekta.ShippingContactParams{
    Phone: "55-5555-5555",
    Receiver: "Miguel",
    BetweenStreets: "BetweenStreets",
    Address: Address,
}

chargeParams := &conekta.ChargeParams{
    PaymentMethod: &conekta.PaymentMethodParams{
        Type: "oxxo_cash",
        ExpiresAt: time.Now().AddDate(0, 0, 90).Unix(),
    },
}

orderParams := &conekta.OrderParams{}
orderParams.Currency = "MXN"
orderParams.CustomerInfo = customerParams
orderParams.LineItems = append(orderParams.LineItems, lineItemParams)
orderParams.ShippingLines = append(orderParams.ShippingLines, shippingParams)
orderParams.ShippingContact = shippingContactParams
orderParams.Charges = append(orderParams.Charges, chargeParams)

ord, err := order.Create(orderParams)
if err != nil {
    code := err.(conekta.Error).Details[0].Code
    fmt.Printf(code)
} else {
    fmt.Println(ord)
}

Paso 3 - Procesa una respuesta

Una vez que creaste la orden y el cargo, debes procesar la respuesta y compartir la ficha de pago.
Recuerda que la respuesta de una orden es formato “JSON”

puts "ID: #{order.id}"
puts "Payment Method puede ser Cash o Oxxo"
puts "Payment Method: #{order.charges.first.payment_method.service_name}"
puts "Reference: #{order.charges.first.payment_method.reference}"
puts "$ #{(order.amount/100).to_f} #{order.currency}"
puts "Order"
puts "#{order.line_items.first.quantity}
      - #{order.line_items.first.name}
      - $ #{(order.line_items.unit_price/100).to_f}"


# Response
# ID: ord_2fsQdMUmsFNP2WjqS
# Payment Method puede ser Cash o Oxxo
# Payment Method: Cash
# Reference: 123456789012
# $ 135.0 MXN
# Order
# 12 - Tacos - $10.0
# N/A
echo "ID: ". $order->id;
echo "Payment Method:". $order->charges[0]->payment_method->service_name;
echo "Reference: ". $order->charges[0]->payment_method->reference;
echo "$". $order->amount/100 . $order->currency;
echo "Order";
echo $order->line_items[0]->quantity .
      "-". $order->line_items[0]->name .
      "- $". $order->line_items[0]->unit_price/100;


// Response
// ID: ord_2fsQdMUmsFNP2WjqS
// Payment Method: Cash
// Reference: 123456789012
// $ 135.0 MXN
// Order
// 12 - Tacos - $10.0
print("ID: " + order.id)
print("Payment Method: " + order.charges[0].payment_method.service_name)
print("Reference: " + order.charges[0].payment_method.reference)
print("$" + str(order.amount/100) + order.currency)
print("Order")
print(order.line_items[0].quantity + " - "
            + order.line_items[0].name + " - "
            + (order.line_items.unit_price/100))


# Response
# ID: ord_2fsQdMUmsFNP2WjqS
# Payment Method: Cash
# Reference: 123456789012
# $ 135.0 MXN
# Order
# 12 - Tacos - $10.0
console.log("ID: " + order.id);
console.log("Payment Method: " + order.charges[0].payment_method.service_name);
console.log("Reference: " + order.charges[0].payment_method.reference);
console.log("$" + (order.amount/100) + order.currency);
console.log("Order");
console.log(order.line_items[0].quantity + " - "
            + order.line_items[0].name + " - "
            + (order.line_items.unit_price/100));


// Response
// ID: ord_2fsQdMUmsFNP2WjqS
// Payment Method: Cash
// Reference: 123456789012
// $ 135.0 MXN
// Order
// 12 - Tacos - $10.0
OxxoPayment oxxoPayment = (OxxoPayment) charge.payment_method;


System.out.println("ID: " + order.id);
System.out.println("Payment Method: " + oxxoPayment.service_name);
System.out.println("Reference: " + oxxoPayment.reference);
System.out.println("$" + (order.amount/100) + order.currency);
System.out.println("Order");
System.out.println(order.line_items.get(0).quantity + " - "
            + order.line_items.get(0).name + " - "
            + (order.line_items.get(0).unit_price/100));


// Response
// ID: ord_2fsQdMUmsFNP2WjqS
// Payment Method: Cash
// Reference: 123456789012
// $ 135.0 MXN
// Order
// 12 - Tacos - $10.0
Console.WriteLine("ID: " + order.id);
Console.WriteLine("Payment Method: " + order.charges[0].payment_method.service_name);
Console.WriteLine("Reference: " + order.charges[0].payment_method.reference);
Console.WriteLine("$" + (order.amount/100) + order.currency);
Console.WriteLine("Order");
Console.WriteLine(order.line_items[0].quantity + " - "
            + order.line_items[0].name + " - "
            + (order.line_items.unit_price/100));


// Response
// ID: ord_2fsQdMUmsFNP2WjqS
// Payment Method: Cash
// Reference: 123456789012
// $ 135.0 MXN
// Order
// 12 - Tacos - $10.0
fmt.Println("ID: ", o.ID)
fmt.Println("Payment Method: ", o.Charges.Data[0].PaymentMethod.ServiceName)
fmt.Println("Reference: ", o.Charges.Data[0].PaymentMethod.Reference)
fmt.Println("$", o.Amount/100, o.Currency)
fmt.Println("------Order------")
fmt.Println(" - ", o.LineItems.Data[0].Quantity)
fmt.Println(" - ", o.LineItems.Data[0].Name)
fmt.Println(" - ", o.LineItems.Data[0].UnitPrice/100)

//Response
//ID:  ord_2nCsbdLXvdAgDVcKr
//Payment Method:  Cash
//Reference:  98000004875830
//$ 152 MXN
//------Order------
// -  1
// -  Producto 7
// -  152

Paso 4 - Presenta la ficha de pago

Utiliza la siguiente ficha para darle a tu cliente la referencia de pago junto con los pasos necesarios para completar su compra.

399399

Ficha de pago en efectivo con Conekta

Te recomendamos incluirla en tu Checkout de compra o enviarla por correo para ofrecer una mejor experiencia.
Puedes obtenerla en repo en Github.

Paso 5 - Recibe notificaciones

Para poder confirmar los pagos que se realicen en efectivo deberás añadir un Webhook en tu Admin Conekta para recibir las notificaciones POST (HTTP JSON) correctamente.

Utiliza URLs públicos: Si no tienes un IP público o un domino a tu disposición, te recomendamos utilizar servicios como ultrahook o localtunnel. También puedes consultar la referencia sobre webhooks. Recomendamos escuchar eventos de order.paid así

{
    "object": {
        "livemode": false,
        "amount": 18500,
        "currency": "MXN",
        "payment_status": "paid",
        "amount_refunded": 0,
        "customer_info": {
            "name": "Fulanito Pérez",
            "email": "[email protected]",
            "phone": "+5218181818181",
            "object": "customer_info"
        },
        "shipping_contact": {
            "receiver": "JOSE  MORALES",
            "phone": "6691208528",
            "address": {
                "street1": "Calle 123, int 2",
                "postal_code": "06100",
                "country": "MX"
            },
            "id": "ship_cont_2s53K99C8GXVmCfPk",
            "object": "shipping_contact",
            "created_at": 0
        },
        "object": "order",
        "id": "ord_2s53K99C8GXVmCfPm",
        "created_at": 1656547670,
        "updated_at": 1656547702,
        "line_items": {
            "object": "list",
            "has_more": false,
            "total": 1,
            "data": [{
                "name": "Tacos",
                "unit_price": 1000,
                "quantity": 12,
                "object": "line_item",
                "id": "line_item_2s53K99C8GXVmCfPg",
                "parent_id": "ord_2s53K99C8GXVmCfPm",
                "metadata": {}
            }]
        },
        "shipping_lines": {
            "object": "list",
            "has_more": false,
            "total": 1,
            "data": [{
                "name": "Tacos",
                "amount": 1500,
                "carrier": "FEDEX",
                "object": "line_item",
                "id": "line_item_2s53K99C8GXVmCfPg",
                "parent_id": "ord_2s53K99C8GXVmCfPm",
                "metadata": {}
            }]
        },
        "tax_lines": {
            "object": "list",
            "has_more": false,
            "total": 0,
            "data": []
        },
        "charges": {
            "object": "list",
            "has_more": false,
            "total": 1,
            "data": [{
                "id": "62bce95741de276186407e41",
                "livemode": false,
                "created_at": 1656547671,
                "currency": "MXN",
                "payment_method": {
                    "service_name": "OxxoPay",
                    "barcode_url": "https://s3.amazonaws.com/cash_payment_barcodes/sandbox_reference.png",
                    "object": "cash_payment",
                    "type": "oxxo",
                    "expires_at": 1656634070,
                    "store_name": "OXXO",
                    "reference": "98000013217610"
                },
                "object": "charge",
                "description": "Payment from order",
                "status": "paid",
                "amount": 13500,
                "paid_at": 1656547702,
                "fee": 537,
                "customer_id": "",
                "order_id": "ord_2s53K99C8GXVmCfPm"
            }]
        }
    },
    "previous_attributes": {}
}

Paso 6 - Notifica a tu cliente

Te recomendamos notificar a tu cliente vía mail el estatus de su compra.

Paso 7 - Prueba tu Webhook

Dentro de tu perfil de Administrador en Conekta, puedes probar la funcionalidad de tu Webhook

¿Qué necesito para probar mi Webhook? Solo agrega la URL de tu Webhook y los datos de acceso al Perfil de Administrador Conekta.

👍

¡Listo!

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