Webhook

Overview

Gracias a nuestro webhook podras recibir en tu sistema el status de una suscripción en diferentes casos, como renovación automática, reintento de pago, finalización, renovación por invitación y cambio de plan por invitación.

Para poder recibir actualizaciones de tus suscripciones es importante que cuando estes creando la suscripción agregues el endpoint del webhook que habilites para recibir la data de nuestro lado.

{info} 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.

La data enviada sera enviada en formato JSON.

Si la aplicacion no responde con un estado 2xx se reintentara el llamado 10s despues, si tambien falla se reitentara despues de 100s, despues de este ultimo no habran mas intentos.

Detalle data

Plan

Campo Descripcion
name Contiene la descripcion del plan
descripcion Contiene el nombre del plan
price Define el precio del plan
currency_type Define el tipo de moneda

Suscriptor

Campo Descripción
identification_type Define el tipo de identificación
id_number Contiene el numero de identificación
name Contiene el nombre del suscriptor
last_name Contiene el apellido del suscriptor
email Contiene el correo electrónico del suscriptor
phone_code Contiene el código del país al que pertenece el número celular
cellphone_number Contiene el número celular del cliente
billing_address Contiene la dirección de facturación del suscriptor
billing_city Contiene la ciudad del suscriptor
Billing Country Contiene el país del suscriptor

Siguiente Cargo

Campo Descripcion
amount Contiene el costo del siguiente cargo
currency_type Define el tipo de moneda
next_renew_at Define la fecha de la siguiente renovación

Sucursal

Campo Descripcion
name Contiene el nombre de la oficina
descripcion Contiene más detalles sobre la oficina

Transacción

Campo Descripción
transaction_id Contiene el ID de la transacción
amount Contiene el monto de la transacción
currency_type Define el tipo de moneda
value_cop Muestra el valor en pesos
payment_method Muestra el método de pago usado
payment_method_source Muestra el origen del método de pago, ejemplo: Mastercard
trazability_id Muestra el ID de trazabilidad

Status

Campo Descripcion
key Puede ser uno de los siguientes casos: renew, retry, finished, finished time, renewed, plan_changed.
value Valor de visualización asociado al estado (por ejemplo: Renovado, Reintento de Pago, Suscripción Finalizada, Plan Cambiado).
descripcion Mensaje descriptivo del estado.

Eventos de estado que puedes recibir:

  • renew: El pago fue exitoso y la suscripción se renovó.
  • retry: El pago falló y se intentará nuevamente.
  • finished: La suscripción finalizó por no lograr renovación.
  • finished time: La suscripción finalizó por límites de recurrencia o fecha límite del plan.
  • renewed: Renovación/reactivación aceptada por invitación.
  • plan_changed: Cambio de plan aceptado por invitación.

Ejemplo

El objeto retornado del webhook suscripción es el siguiente:

{
    "subscription": {
        "id": "9ad70d0e-61e1-4c17-99c3-355b50d79954",
        "webhook_url": "http://efipay:80/api/v1/webhook",
        "trial_ends_at": "2023-12-22T16:28:48.000000Z",
        "discount_ends_at": null,
        "starts_at": "2023-12-24T16:28:48.000000Z",
        "ends_at": "2023-12-25T16:28:48.000000Z",
        "grace_ends_at": "2023-12-25T16:28:48.000000Z",
        "canceled_at": null,
        "is_active": false,
        "is_inactive": true,
        "on_trial": false,
        "on_discount": false,
        "canceled": false,
        "is_ended": true,
        "is_expired": true,
        "on_grace_period": false,
        "production": 0,
        "plan": {
            "id": "9ae4dc2d-8b2e-4920-ac1f-80f2d648a2e6",
            "name": "Prueba 1 dia",
            "description": "Prueba a 1 dia, sin periodo de prueba, sin periodo de gracia,",
            "price": 150,
            "currency_type": "COP",
            "trial_period": 0,
            "trial_interval": "day",
            "invoice_period": 1,
            "invoice_interval": "day",
            "grace_period": 0,
            "grace_interval": "day",
            "discount_period": 0,
            "discount_interval": "day",
            "discount_subscribers_limit": null,
            "discount_type_amount": null,
            "discount_amount": null,
            "sort_order": 0,
            "active_subscribers_limit": null,
            "active": true,
            "subscription_group_id": "9ad70293-cec8-4e07-8ddf-1272252a0014",
            "user_id": 2,
            "office_id": 1,
            "commerce_id": 1,
        },
        "subscriber": {
            "id": "9ae92bbb-2cab-4569-85b1-6173d0fb9d4b",
            "identification_type": "CC",
            "id_number": "561215132",
            "name": "Prueba",
            "last_name": "suscripciones",
            "email": "prueba@emi.com",
            "phone_code": 57,
            "cellphone_number": "20053442",
            "billing_address": "calle 32 32",
            "billing_city": "Bogota",
            "billing_country": "Colombia",
            "user_id": 2,
            "office_id": 1,
            "commerce_id": 1,
        },
        "next_charge": {
            "id": "9af32ada-ce51-4e43-bf63-2372d2d0b968",
            "amount": 150,
            "currency_type": "COP",
            "next_renew_at": "2023-12-25",
            "charge_at": null,
            "approved": null,
            "transaction_id": null,
            "subscription_id": "9ae92bcc-2026-48ff-830e-76bff3a43c9d",
        },
        "office": {
            "id": 1,
            "name": "Principal (default)",
            "description": "Sucursal Principal del comercio",
            "active": 1,
            "main": 1,
            "commerce_id": 1,
            "user_id": 2,
            "created_at": "2023-10-27 13:05:48",
            "updated_at": "2023-10-27 13:05:48",
        }
    },
    "transaction": {
        "transaction_id": 108,
        "amount": 150,
        "currency_type": "COP",
        "value_cop": 150,
        "payment_method": "credit",
        "payment_method_source": "Mastercard",
        "trazability_id": "108",
        "transaction_details": {
            "name": "Santiago Otalora",
            "identification_type": "CC",
            "identification_number": "561215132",
            "email": "prueba@emi.com",
            "country": "57",
            "phone": "20053442",
            "number_card": "52**********0339",
            "installments": 1,
            "franchise": "Mastercard",
            "status_message": "Runing Mock",
        },
        "status": "Aprobada",
        "url_response": "http://localhost/Checkout/Transaction/9af32ad7-e36f-4b6d-b801-00a2b078ee85/Response",
        "approved_at": "2023-12-27 10:44:25",
        "production": false,
        "created_at": "2023-12-27T15:44:25.000000Z",
        "customer_payer": {
            "id": "9ae92bcc-2967-452b-b162-f4786bb35367",
            "name": "Prueba suscripciones",
            "email": "prueba@emi.com",
            "created_at": "2023-12-22 16:28:48",
            "updated_at": "2023-12-22 16:28:48",
        },
        "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,
        }
    },
    "status": {
        "key": "renew",
        "value": "Renovado",
        "description": "El pago ha sido exitoso, la suscripción fue renovada y seguira activa",
    }
}