Webhook

---

• Webhook
  • Overview
  • Webhook
  • Rechazos y metadata

Overview

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.

Nota

Recuerda que esta ruta debe ser de tipo post.

Ademas te enviaremos un header Signature que contendrá una firma que podras usar para verificar que la carga útil no haya sido manipulada. Para realizar la firma usamos el token para webhooks que generamos en tu comercio, lo puedes encontrar aquí, adicional generamos el hash “HMAC” con el algoritmo sha256

La data enviada sera enviada en formato JSON.

Si la aplicación no responde con un estado 2xx reintentamos hasta 7 veces, repartidas en unas 17 horas (ver Reintentos). Cada envío queda en el historial de webhooks por 30 días, con sus intentos: desde ahí puedes consultarlo y reenviarlo con el mismo meta.event_id.

Webhook

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
    }
}

Rechazos y metadata

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.

Consejo

Si generaste el pago con payment.metadata, la recibes de vuelta en checkout.payment_referenceable.metadata. Úsala para enlazar el webhook con tu pedido sin guardar nuestro id.