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": "logan@x-men.org", "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": "logan@x-men.org", "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": "logan@x-men.org", "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": "logan@x-men.org", "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 Xacier@x-men.org", "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 Xacier@x-men.org", "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 Xacier@x-men.org", "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 Xacier@x-men.org", "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