Ir al contenido

Webhook

Ver .md

Gracias a nuestro webhook podras recibir en tu sistema el status de una transacción y recibir la información asi como el estado aprobado, rechazado…

Este webhook se envia al endpoint colocado en las opciones avanzadas en los urls de resultados.

El objeto retornado de webhook transacción es el siguiente:

{
"transaction": {
"transaction_id": 107,
"amount": 37323.25,
"currency_type": "COP",
"value_cop": 37323.25,
"payment_method": "credit",
"payment_method_source": "Visa",
"trazability_id": 107,
"transaction_details": {
"name": "PRUEBA TARJETA",
"identification_type": "CC",
"identification_number": "342343243",
"email": "email@gmail.com",
"country": "57",
"phone": "3004564884",
"number_card": "52**********0339",
"installments": "1",
"franchise": "Visa",
"status_message": "Runing Mock"
},
"status": "Aprobada",
"status_key": "approved",
"response_code": "00",
"error": null,
"url_response": "https://sag.efipay.co/Checkout/Transaction/9af329f1-e96a-40ab-b466-94a412f12c4a/Response",
"approved_at": "2023-12-27T15:41:54.553992Z",
"production": false,
"created_at": "2023-12-27T15:41:54.000000Z",
"customer_payer": {
"id": "9a80a7b1-950f-486a-ac84-b36fb852a6c9",
"name": "Santiago Otlaroa",
"email": "santiago@gmail.com",
"created_at": "2023-10-31 17:33:19",
"updated_at": "2023-11-10 15:03:17"
},
"currency_rate_conversion": {
"id": 1,
"usd_to_cop": 0.000244,
"eur_to_cop": 0.000231,
"active": 1,
"created_at": "2023-10-27T13:20:07.000000Z",
"updated_at": "2023-11-24T18:44:18.000000Z",
"deleted_at": null
}
},
"checkout": {
"id": "9af329f1-dc79-49d4-b462-feea272e82ce",
"payment_referenceable_type": "App\\Models\\CollectionTools\\Api\\SimpleApi",
"payment_referenceable_id": "9af329b7-01f3-4acc-88a0-13476cb1d783",
"payment_gateway_id": "9af329b7-3137-4673-86a4-46e4367222b4",
"delivery_address_id": 2,
"commerce_id": 1,
"office_id": 1,
"comments": null,
"total_advance": 37323.25,
"paid_at": "2023-12-27 10:41:54",
"ongoing_transaction": 0,
"customer_payer_id": "9a80a7b1-950f-486a-ac84-b36fb852a6c9",
"created_at": "2023-12-27 15:41:54",
"updated_at": "2023-12-27 15:41:54",
"total_pending": 0,
"payment_referenceable": {
"id": "9af329b7-01f3-4acc-88a0-13476cb1d783",
"description": "Prueba alltruismo 2",
"metadata": { "order_id": "A-1001" }
},
"pivot": {
"transaction_id": "9af329f1-e96a-40ab-b466-94a412f12c4a",
"checkout_gateway_id": "9af329f1-dc79-49d4-b462-feea272e82ce"
},
"payment_gateway": {
"id": "9af329b7-3137-4673-86a4-46e4367222b4",
"gatewayable_type": "App\\Models\\CollectionTools\\Api\\SimpleApi",
"gatewayable_id": "9af329b7-01f3-4acc-88a0-13476cb1d783",
"advanced_option_id": "9af329b7-2b2c-40cd-9d6f-f72bd6fb1205",
"created_user_id": 2,
"updated_user_id": 2,
"office_id": 1,
"commerce_id": 1,
"massive_upload_id": null,
"url": null,
"full_payment_at": "2023-12-27 10:41:54",
"active": 1,
"production": 0,
"created_at": "2023-12-27 15:41:16",
"updated_at": "2023-12-27 15:41:54",
"deleted_at": null,
"sub_total": 35323.25,
"amount_without_tax": 35323.25,
"tax_amount": null,
"total": 37323.25,
"total_cop": 37323.25,
"tool_name": "SimpleApi",
"purchase_detail": {},
"gatewayable": {},
"advanced_option": {
"id": "9af329b7-2b2c-40cd-9d6f-f72bd6fb1205",
"limit_date": "2023-12-30",
"references": [
"123455678",
"1234556789",
"1234556780"
],
"result_urls": {
"pending": "https://yourdoamin.com/pending",
"webhook": "http://yourdoamin.com/api/v1/webhook",
"approved": "https://yourdoamin.com/approved"
},
"delivery_service_type": "Con Valor",
"delivery_service_value": 2000,
"request_address_delivery": true,
"payment_methods": [],
"discount_before_on": "2023-12-30",
"discount_type": "Valor",
"discount_value": 2000,
"has_comments": true,
"comments_label": "Aqui tu comentario",
"limit_payments": null,
"created_at": "2023-12-27 15:41:16",
"updated_at": "2023-12-27 15:41:16",
"deleted_at": null,
"url_picture": "https://mi-tienda.com/img/producto.png",
"has_delivery_service": true,
"has_all_payment_methods": true,
"has_discount_early_payment": true,
"has_limit_payments": false,
"delivery_service": {
"type": "Con Valor",
"value": 2000
},
"discount": {
"before_on": "2023-12-30",
"type": "Valor",
"value": 2000
}
}
},
"paid_advance": {
"id": "9af329f1-f064-437d-9137-05a1530d0dd1",
"description": "Prueba alltruismo 2",
"amount_paid": 37323.25,
"amount_currency": {
"name": "Peso Colombiano",
"symbol": "$",
"abbreviation": "COP"
},
"exchange_paid": 37323.25,
"exchange_currency": "COP",
"tool_paid": true,
"checkout_gateway_id": "9af329f1-dc79-49d4-b462-feea272e82ce",
"transaction_id": "9af329f1-e96a-40ab-b466-94a412f12c4a",
"created_at": "2023-12-27T15:41:54.000000Z",
"updated_at": "2023-12-27T15:41:54.000000Z",
"deleted_at": null
},
"answer_form": null
}
}

transaction trae los mismos campos de decisión que la respuesta del checkout: status_key, response_code y error. En un rechazo, error es {code, message, retryable, action} y description el mensaje para el tarjetahabiente:

{
"status": "Rechazada",
"status_key": "rejected",
"response_code": "51",
"error": {
"code": "51",
"message": "Transacción declinada. Fondos insuficientes",
"retryable": false,
"action": "contact_issuer"
},
"description": "Transacción declinada. Fondos insuficientes"
}

Decide con status_key y error.retryable; el catálogo está en Códigos de error.

Si generaste el cobro por API y configuraste advanced_options.limit_date junto con result_urls.webhook, te avisamos cuando esa fecha se cumple y nadie inició el pago. Un Y-m-d vence al final de ese día. El aviso sale una sola vez, a la misma URL y con la misma firma que el resto de webhooks.

meta.event_type es transaction.expired. El webhook de un pago que sí se intentó sigue siendo transaction.status_changed y trae checkout.

{
"error": "Time expired",
"transaction": {
"transaction_id": null,
"amount": null,
"currency_type": null,
"value_cop": null,
"payment_method": null,
"payment_method_source": null,
"trazability_id": null,
"authorization_code": null,
"transaction_details": null,
"status": "Rechazada",
"status_key": "rejected",
"response_code": null,
"error": null,
"tax": null,
"card": null,
"url_response": null,
"approved_at": null,
"production": null,
"created_at": null,
"customer_payer": null,
"currency_rate_conversion": null,
"description": "Transacción Rechazada: Tiempo de espera excedido o transacción no iniciada o usuario abandono la transacción"
},
"payment_gateway": {
"id": "9dc12b03-5833-496a-83e6-4dfb8eb2570b",
"tool_name": "SimpleApi",
"total": 50000,
"production": false
},
"meta": {
"event_id": "9b1f0e34-6b2a-4a7e-9d0a-3c5f2b7a1d80",
"event_type": "transaction.expired",
"timestamp": "2026-12-24T23:59:12-05:00",
"api_version": "v1"
}
}
Campo Qué mirar
meta.event_type transaction.expired. Deduplica con meta.event_id
error El texto Time expired. Aquí es un string, no el objeto {code, message, retryable, action} de un rechazo de red
transaction.status / status_key Rechazada / rejected
transaction.transaction_id null: no se creó transacción
transaction.description Transacción Rechazada: Tiempo de espera excedido o transacción no iniciada o usuario abandono la transacción
payment_gateway.id El payment_id que guardaste al generar el pago

payment_gateway es el cobro completo: además de id trae montos, url, production, sucursal y comercio. El ejemplo deja solo los campos con los que identificas el pedido.

Sin result_urls.webhook no hay aviso. Puedes confirmar el mismo resultado con estado de transacción: Rechazada, status_key rejected y transaction_id en null.

Última actualización: