Crear cobros va SPEI
En este tutorial aprenders a generar y recibir pagos seguros por medio de transferencias bancarias a travs de SPEI o por depsitos en firme en sucursales bancarias.
1 Entendiendo el Flujo
Para recibir pagos a travs de SPEI, es necesario crear un cargo en Conekta con los siguientes datos: importe, tipo de moneda y descripcin. Como respuesta recibirs una CLABE como referencia nica de pago que debers enviar a tu cliente para efecte su pago y pueda completar la compra.
Tus clientes podrn pagar por medio de transferencia electrnica o directamente en sucursales bancarias con efectivo o cheque.
Como el proceso de este mtodo de pago es asncrono y el estatus del cargo no cambiar a Pagado de manera automtica, es necesario implementar webhooks para recibir las notifaciones que se generen.
2 Realizando un Cargo
El primer paso es incluir una de nuestras libreras en tu proyecto. Una vez instalada la librera de tu preferencia necesitars utilizar tu llave privada, de esta manera podrs autenticar todas las llamadas que realices.
Recuerda que solamente las llaves de produccin pueden procesar pagos reales. Las llaves sandbox estn diseadas para realizar pruebas solamente. Tambin, toma en cuenta que las llamadas del lado del servidor debern utilizar las llaves privadas ya que, por cuestiones de seguridad, las llaves pblicas tienen permisos limitados.
require_once("/path/to/lib/Conekta.php");
Conekta::setApiKey("key_eYvWV7gSDkNYXsmr");
Ahora realizaremos una peticin a Conekta con el importe, tipo de moneda y la descripcin de la compra. Tambin necesitamos especificar el tipo de cargo que estamos realizando (en este caso spei).
try { $charge = Conekta_Charge::create(array( "amount"=> 51000, "currency"=> "MXN", "description"=> "Pizza Delivery", "bank"=> array( "type"=>"spei", "expires_at"=>"2015-03-04" ) ));} catch (Conekta_Error $e) { echo $e->getMessage(); // Ocurri un error al procesar el pago}
Adicionalmente, y de manera opcional, podemos enviar una referencia para relacionar el cargo con tus propias rdenes, al igual que una fecha de expiracin dentro del objeto bancario para establecer una fecha lmite de pago.
3 Procesando una Respuesta
Una vez creado el cargo, debemos de procesar la respuesta y enviar la CLABE de pago a tu cliente. Esta referencia aparecer en la respuesta, dentro del atributo payment_method.clabe.
print($charge->payment_method->clabe);print($charge->payment_method->bank);
El atributo payment_method.bank siempre ser STP.
4 Recibiendo notificaciones
Al momento de procesar pagos de manera asncrona, necesitars recibir notificaciones para confirmar que los cargos realizados han sido pagados. Conekta enviar webhooks de todas las notificaciones de pagos asncronas a tu servidor. Estas notificaciones son mensajes POST de tipo HTTP jSON. Cada notificacin contiene un objeto jSON con informacin particular del evento y suscripcin asociada.
Al configurar notificaciones de pago, necesitars configurar los webhooks dentro de la seccin de webhooks del admin. La configuracin es simple. Todo lo que necesitas hacer es especificar el URL (o los URL) a donde te gustara recibir notificaciones y Conekta enviar todas las notificaciones al (los) URL especificado(s).
Para operar las notificaciones en tu servidor, debers configurar una ruta para el webhook que creaste, escribir cdigo para analizar el mensaje POST y operar sobre l. Para ms informacin sobre webhooks, ve a la seccin de webhooks.
Ten en cuenta que el URL usado en la configuracin de webhook debe poder ser accedido de manera pblica. Si no tienes un IP pblico o un domino a tu disposicin, sugerimos usar un servicio local->pblico como ultrahook o localtunnel. Abajo te compartimos un ejemplo de cmo usar ultrahook. Antes de utilizar ultrahook debers registrarte en ultrahook para obtener una llave de API.
$ gem install ultrahook$ echo "api_key: my-ultrahook-api-hey" > ~/.ultrahook$ ultrahook webhook-test 5000 Authenticated as conekta Forwarding activated... http://webhook-test.conekta.ultrahook.com -> http://localhost:5000
Para recibir notificaciones de webhooks, puedes usar el siguiente cdigo:
// Analizar la informacin del evento en forma de json$body = @file_get_contents('php://input');$event_json = json_decode($body);if ($event_json->type == 'charge.paid'){ //Hacer algo con la informacin como actualizar los atributos de la orden en tu base de datos //charge = $this->Charge->find('first', array( // 'conditions' => array('Charge.id' => $event_json->object->id) //))}
Recibiendo notificaciones de pagos por medio de Webhooks
Esta es una referencia sobre notificaciones en Conekta y de cmo manejarlas.
Qu son Webhooks?
Un Webhook es una notificacin de eventos por medio de HTTP POST, podras pensarlo como un HTTP callback. Cuando algo sucede en Conekta, por ejemplo, un cargo fue pagado, el mecanismo notifica a tu servidor por medio de un HTTP POST (Webhook). Mientras tu puedes recibir notificaciones por correo, tu servidor tpicamente procesa eventos por medio de esta forma de comunicacin entre servidores.
Qu hacen los Webhooks?
Puedes usar los Webhooks para recibir notificaciones de cualquier evento en tu cuenta. La configuracin de webhooks es flexible, y puedes recibir estas notificaciones en tantos servidores quieras. Si tu servidor no puede ser localizado cuando el webhook es enviado, el servidor volver a intentar.
Con webhooks puedes:
1. Recibir notificaciones de compras exitosas de cualquier mtodo de pago.
2. Actualizar aplicaciones o servicios no conectados al API.
3. Recibir notificaciones de actualizaciones de negocios como contracargos y eventos de cargos recurrentes, que no son generados por llamadas al API.
Cmo configurar Webhooks?
Al crear tu cuenta, puedes configurar los webhooks en la seccin de Desarrolladores / Webhooks en el admin. En esta seccin puedes agregar, borrar modificar urls para recibir notificaciones. Puedes limitar los webhooks a que sean de produccin o de pruebas y enviar notificaciones de prueba para probar que puedan responder tus listeners.
La notificacin ser enviada a todos los URLs que asignaste en la seccin de Webhooks la cual permitir que tus aplicaciones respondan a eventos de pago. Las notificaciones sern hechas con peticiones post a tu listener, aqu hay algunos ejemplos que puedes usar para recibir notificaciones.
// Analiza el cuerpo de la notifiacin como JSON$body = @file_get_contents('php://input');$event_json = json_decode($body);//Hacer algo con los datos como actualizar los atributos de una orden en tu base de datos
Cmo responder a un Webhook?
Para confirmar de que ya has recibido una notificacin de un webhook correctamente, tu servidor debe regresar un cdigo 200 de HTTP.
Ejemplo de Webhooks
A continuacin se muestra una lista de algunas de las notificaciones que puedes recibir por medio de los Webhooks a la URL previamente configurada.
Cargo creado con tarjeta
Cargo pagado con tarjeta
Cargo de OXXO creado
Cargo de OXXO pagado
Cargo de SPEI creado
Cargo de SPEI pagado
Plan creado
Crear un customer sin tarjeta y sin plan
Customer creado con una tarjeta y sin plan
Customer creado con tarjeta y con plan (suscripcin)
Suscripcin creada
Suscripcin pagada
Suscripcin activa
Contracargo perdido
Cargo creado con tarjeta
Regresar a la lista de ejemplos
{ "data": { "object": { "id": "5511d4ce2412294cf6000081", "livemode": false, "created_at": 1427231950, "status": "pending_payment", "currency": "MXN", "description": "Stogies", "reference_id": "9839-wolf_pack", "failure_code": null, "failure_message": null, "monthly_installments": null, "object": "charge", "amount": 20000, "paid_at": null, "fee": 963, "customer_id": "", "refunds": [], "payment_method": { "name": "Jorge Lopez", "exp_month": "12", "exp_year": "19", "auth_code": null, "object": "card_payment", "last4": "4242", "brand": "visa" }, "details": { "name": null, "phone": null, "email": null, "line_items": [] } }, "previous_attributes": {} }, "livemode": false, "webhook_status": "pending", "id": "5511d4ce2412294cf6000084", "object": "event", "type": "charge.created", "created_at": 1427231950, "webhook_logs": [ { "id": "webhl_nPzGMBeQmMUu7aQ", "url": "http://requestb.in/1em0jsx1", "failed_attempts": 0, "last_http_response_status": -1, "object": "webhook_log", "last_attempted_at": 0 } ]}
Cargo pagado con tarjeta
Regresar a la lista de ejemplos
{ "data": { "object": { "id": "5511d4ce2412294cf6000081", "livemode": false, "created_at": 1427231950, "status": "paid", "currency": "MXN", "description": "Stogies", "reference_id": "9839-wolf_pack", "failure_code": null, "failure_message": null, "monthly_installments": null, "object": "charge", "amount": 20000, "paid_at": 1427231952, "fee": 963, "customer_id": "", "refunds": [], "payment_method": { "name": "Jorge Lopez", "exp_month": "12", "exp_year": "19", "auth_code": "000000", "object": "card_payment", "last4": "4242", "brand": "visa" }, "details": { "name": null, "phone": null, "email": null, "line_items": [] } }, "previous_attributes": { "payment_method": {} } }, "livemode": false, "webhook_status": "pending", "id": "5511d4d02412294cf6000088", "object": "event", "type": "charge.paid", "created_at": 1427231952, "webhook_logs": [ { "id": "webhl_m5kgkhmgETe6Y4s", "url": "http://requestb.in/1em0jsx1", "failed_attempts": 0, "last_http_response_status": -1, "object": "webhook_log", "last_attempted_at": 0 } ]}
Cargo de OXXO creado
Regresar a la lista de ejemplos
{ "data": { "object": { "id": "5514803f241229981e0022e6", "livemode": false, "created_at": 1427406911, "status": "pending_payment", "currency": "MXN", "description": "Stogies", "reference_id": "9839-wolf_pack", "failure_code": null, "failure_message": null, "monthly_installments": null, "object": "charge", "amount": 20000, "paid_at": null, "fee": 812, "customer_id": "", "refunds": [], "payment_method": { "barcode": "38100000000042290121213001160013", "barcode_url": "http://s3.amazonaws.com/cash_payment_barcodes/38100000000042290121213001160013.png", "object": "cash_payment", "type": "oxxo", "expires_at": 1430006400, "store_name": "OXXO" }, "details": { "name": "Wolverine", "phone": "403-342-0642", "email": "[email protected]", "line_items": [] } }, "previous_attributes": {} }, "livemode": false, "webhook_status": "pending", "id": "5514803f241229981e0022e9", "object": "event", "type": "charge.created", "created_at": 1427406911, "webhook_logs": [ { "id": "webhl_PBmYvkfdNDYKezJ", "url": "http://requestb.in/u3n4ywu3", "failed_attempts": 0, "last_http_response_status": -1, "object": "webhook_log", "last_attempted_at": 0 } ]}
Cargo de OXXO pagado
Regresar a la lista de ejemplos
{ "data": { "object": { "id": "5514803f241229981e0022e6", "livemode": false, "created_at": 1427406911, "status": "paid", "currency": "MXN", "description": "Stogies", "reference_id": "9839-wolf_pack", "failure_code": null, "failure_message": null, "monthly_installments": null, "object": "charge", "amount": 20000, "paid_at": 1427406913, "fee": 812, "customer_id": "", "refunds": [], "payment_method": { "barcode": "38100000000042290121213001160013", "barcode_url": "http://s3.amazonaws.com/cash_payment_barcodes/38100000000042290121213001160013.png", "object": "cash_payment", "type": "oxxo", "expires_at": 1430006400, "store_name": "OXXO" }, "details": { "name": "Wolverine", "phone": "403-342-0642", "email": "[email protected]", "line_items": [] } }, "previous_attributes": { "status": "pending_payment" } }, "livemode": false, "webhook_status": "pending", "id": "55148042241229d4fb00b58a", "object": "event", "type": "charge.paid", "created_at": 1427406914, "webhook_logs": [ { "id": "webhl_yYes9gx41vAj6ag", "url": "http://requestb.in/151xj4r1", "failed_attempts": 0, "last_http_response_status": -1, "object": "webhook_log", "last_attempted_at": 1427406984 } ]}
Cargo de SPEI creado
Regresar a la lista de ejemplos
{ "data": { "object": { "id": "551499322412292eec002159", "livemode": false, "created_at": 1427413298, "status": "pending_payment", "currency": "MXN", "description": "Stogies", "reference_id": "9839-wolf_pack", "failure_code": null, "failure_message": null, "monthly_installments": null, "object": "charge", "amount": 20000, "paid_at": null, "fee": 928, "customer_id": "", "refunds": [], "payment_method": { "clabe": "646180111800012432", "bank": "STP", "issuing_account_holder": null, "issuing_account_tax_id": null, "issuing_account_bank": null, "issuing_account_number": null, "receiving_account_holder": null, "receiving_account_tax_id": null, "receiving_account_number": "646180111800012432", "receiving_account_bank": "STP", "reference_number": null, "description": null, "tracking_code": null, "executed_at": null, "object": "bank_transfer_payment", "type": "spei", "expires_at": 1435189298 }, "details": { "name": "Wolverine", "phone": "403-342-0642", "email": "[email protected]", "line_items": [] } }, "previous_attributes": {} }, "livemode": false, "webhook_status": "pending", "id": "551499322412292eec00215c", "object": "event", "type": "charge.created", "created_at": 1427413298, "webhook_logs": [ { "id": "webhl_ENPXoFkKWyDqTAt", "url": "http://requestb.in/151xj4r1", "failed_attempts": 0, "last_http_response_status": -1, "object": "webhook_log", "last_attempted_at": 1427413285 } ]}
Cargo de SPEI pagado
Regresar a la lista de ejemplos
{ "data": { "object": { "id": "551499322412292eec002159", "livemode": false, "created_at": 1427413298, "status": "paid", "currency": "MXN", "description": "Stogies", "reference_id": "9839-wolf_pack", "failure_code": null, "failure_message": null, "monthly_installments": null, "object": "charge", "amount": 20000, "paid_at": 1427413301, "fee": 928, "customer_id": "", "refunds": [], "payment_method": { "clabe": "646180111800012432", "bank": "STP", "issuing_account_holder": null, "issuing_account_tax_id": null, "issuing_account_bank": null, "issuing_account_number": null, "receiving_account_holder": null, "receiving_account_tax_id": null, "receiving_account_number": "646180111800012432", "receiving_account_bank": "STP", "reference_number": null, "description": null, "tracking_code": null, "executed_at": null, "object": "bank_transfer_payment", "type": "spei", "expires_at": 1435189298 }, "details": { "name": "Wolverine", "phone": "403-342-0642", "email": "[email protected]", "line_items": [] } }, "previous_attributes": { "status": "pending_payment" } }, "livemode": false, "webhook_status": "pending", "id": "551499352412299fd600b5ce", "object": "event", "type": "charge.paid", "created_at": 1427413301, "webhook_logs": [ { "id": "webhl_zNFL9UGDd4dY9Hb", "url": "http://requestb.in/151xj4r1", "failed_attempts": 0, "last_http_response_status": -1, "object": "webhook_log", "last_attempted_at": 1427413289 } ]}
Plan creado
Regresar a la lista de ejemplos
{ "data": { "object": { "id": "mutant_course", "livemode": false, "created_at": 1428338382, "name": "six month of x-men school", "amount": 10000, "currency": "MXN", "interval": "month", "frequency": 1, "expiry_count": 6, "trial_period_days": 15, "object": "plan" }, "previous_attributes": {} }, "livemode": false, "webhook_status": "pending", "id": "5522b6ce19ce8800d9000003", "object": "event", "type": "plan.create", "created_at": 1428338382, "webhook_logs": [ { "id": "webhl_zYZxstg2XH9oStU", "url": "http://requestb.in/1467d141", "failed_attempts": 0, "last_http_response_status": -1, "object": "webhook_log", "last_attempted_at": 0 } ]}
Customer creado sin tarjeta y sin plan
Regresar a la lista de ejemplos
{ "data": { "object": { "id": "cus_rRk8xpuSHW4AUEsm3", "email": "Charles [email protected]", "name": "Charles Xavier", "phone": "55-5555-5555", "livemode": false, "default_card_id": null, "object": "customer", "created_at": 1428337640, "cards": [], "subscription": null } }, "livemode": false, "webhook_status": "pending", "id": "5522b3e8241229f132002baa", "object": "event", "type": "customer.created", "created_at": 1428337640, "webhook_logs": [ { "id": "webhl_SvY3zpiSVw1cpMh", "url": "http://requestb.in/1467d141", "failed_attempts": 0, "last_http_response_status": -1, "object": "webhook_log", "last_attempted_at": 0 } ]}
Customer creado con una tarjeta y sin plan
Regresar a la lista de ejemplos
{ "data": { "object": { "id": "cus_n1ZcDf7BWB5Hj89cd", "email": "Charles [email protected]", "name": "Charles Xavier", "phone": "55-5555-5555", "livemode": false, "default_card_id": "card_kkY5nFnto37FNN5D", "object": "customer", "created_at": 1428336972, "cards": [ { "id": "card_kkY5nFnto37FNN5D", "created_at": 1428336972, "active": true, "last4": "4242", "object": "card", "exp_month": "12", "exp_year": "19", "brand": "VISA", "name": "Jorge Lopez", "customer_id": "cus_n1ZcDf7BWB5Hj89cd" } ], "subscription": null } }, "livemode": false, "webhook_status": "pending", "id": "5522b14c241229168e002a87", "object": "event", "type": "customer.created", "created_at": 1428336972, "webhook_logs": [ { "id": "webhl_dqynaXPCTzG6u3o", "url": "http://requestb.in/1467d141", "failed_attempts": 0, "last_http_response_status": -1, "object": "webhook_log", "last_attempted_at": 0 } ]}
Customer creado con tarjeta y con plan (suscripcin)
Regresar a la lista de ejemplos
{ "data": { "object": { "id": "cus_yyDRajnSHe61Ebd7b", "email": "Charles [email protected]", "name": "Charles Xavier", "phone": "55-5555-5555", "livemode": false, "default_card_id": "card_2s1BpzjePT2nxipt", "object": "customer", "created_at": 1428338839, "cards": [ { "id": "card_2s1BpzjePT2nxipt", "created_at": 1428338839, "active": true, "last4": "4242", "object": "card", "exp_month": "12", "exp_year": "19", "brand": "VISA", "name": "Jorge Lopez", "customer_id": "cus_yyDRajnSHe61Ebd7b" } ], "subscription": { "id": "sub_7hcSiRWUpukffri8W", "status": "in_trial", "object": "subscription", "created_at": 1428338839, "trial_end": 1429634839, "plan_id": "mutant_course", "customer_id": "cus_yyDRajnSHe61Ebd7b", "card_id": "card_2s1BpzjePT2nxipt" } } }, "livemode": false, "webhook_status": "pending", "id": "5522b897241229e16c000019", "object": "event", "type": "customer.created", "created_at": 1428338839, "webhook_logs": [ { "id": "webhl_YWuBR2yATA47mX6", "url": "http://requestb.in/1467d141", "failed_attempts": 0, "last_http_response_status": -1, "object": "webhook_log", "last_attempted_at": 0 } ]}
Suscripcin creada
Regresar a la lista de ejemplos
{ "data": { "object": { "id": "sub_7hcSiRWUpukffri8W", "status": "in_trial", "object": "subscription", "created_at": 1428338839, "trial_end": 1429634839, "plan_id": "mutant_course", "customer_id": "cus_yyDRajnSHe61Ebd7b", "card_id": "card_2s1BpzjePT2nxipt" }, "previous_attributes": {} }, "livemode": false, "webhook_status": "pending", "id": "5522b897241229e16c000018", "object": "event", "type": "subscription.created", "created_at": 1428338839, "webhook_logs": [ { "id": "webhl_wZrZRyWvpMtMbGp", "url": "http://requestb.in/1467d141", "failed_attempts": 0, "last_http_response_status": -1, "object": "webhook_log", "last_attempted_at": 0 } ]}
Suscripcin pagada
Regresar a la lista de ejemplos
{ "data": { "object": { "id": "5522c1e919ce883fbf00002a", "livemode": false, "created_at": 1428341225, "status": "paid", "currency": "MXN", "description": "a few weeks of x-men school", "reference_id": null, "failure_code": null, "failure_message": null, "monthly_installments": null, "object": "charge", "amount": 10000, "paid_at": 1428341230, "fee": 626, "customer_id": "cus_9m3aK5RU9mW8Syo26", "refunds": [], "payment_method": { "name": "Jorge Lopez", "exp_month": "12", "exp_year": "19", "auth_code": "000000", "object": "card_payment", "last4": "4242", "brand": "visa" }, "details": { "name": "Charles Xavier", "phone": "55-5555-5555", "email": "Charles [email protected]", "line_items": [] } }, "previous_attributes": { "payment_method": {} } }, "livemode": false, "webhook_status": "pending", "id": "5522c1ee19ce883fbf000030", "object": "event", "type": "charge.paid", "created_at": 1428341230, "webhook_logs": [ { "id": "webhl_xtwgFC2EhrSTNKQ", "url": "http://requestb.in/1467d141", "failed_attempts": 0, "last_http_response_status": -1, "object": "webhook_log", "last_attempted_at": 0 } ]}
Suscripcin activa
Regresar a la lista de ejemplos
{ "data": { "object": { "id": "sub_PinCKLnjRuHuyVBEC", "status": "active", "object": "subscription", "created_at": 1428341221, "billing_cycle_start": 1428341230, "billing_cycle_end": 1428946035, "plan_id": "mutant_course_min", "customer_id": "cus_9m3aK5RU9mW8Syo26", "card_id": "card_H6TiyZTLF6Wxiyo6" }, "previous_attributes": {} }, "livemode": false, "webhook_status": "pending", "id": "5522c1f319ce883fbf000033", "object": "event", "type": "subscription.paid", "created_at": 1428341235, "webhook_logs": [ { "id": "webhl_Ue4E8BdereQJyrp", "url": "http://requestb.in/1467d141", "failed_attempts": 0, "last_http_response_status": -1, "object": "webhook_log", "last_attempted_at": 0 } ]}
Contracargo perdido
Regresar a la lista de ejemplos
{ "data": { "object": { "id": "chbk_iobELtnpKWkisC69", "status": "lost", "reason": "general", "note": "El envo se realiz a nombre de Darth Vader en la estrella de la muerte de una galaxia muy lejana. Telfono: 001 001 0001", "followup_status": "customer_unreachable", "response_from_client": "", "object": "chargeback", "charge_id": "54f776db2412293584333a5c", "created_at": 1427318899, "evidence_due_by": 1427923666, "files": [ { "id": "chbkf_4Jivno3aTg77Xz3", "file_name": "evidence_file1.pdf", "url": null, "created_at": 1427318688 }, { "id": "chbkf_f3bH9AYKmhYghd8", "file_name": "evidence_file2.jpg", "url": null, "created_at": 1427488727 }, { "id": "chbkf_hRhiPuoAnkDbCCp", "file_name": "evidence_file3.jpg", "url": null, "created_at": 1427488777 } ] }, "previous_attributes": { "status": null, "created_at": 0, "evidence_due_by": 0 } }}Fuentes:https://www.conekta.io/es/docs/tutoriales/pago-con-transferencia-via-spei/?backend-language=php&frontend-language=web&javascript-interpreter-language=javascript#2-realizando-un-cargohttps://www.conekta.io/es/docs/referencias/webhooks/?backend-language=php&frontend-language=web&javascript-interpreter-language=javascript