Ir al contenido
Documentación Efipay

Conexión a ERP

Ver .md

Con recauda erp podrás proporcionar un endpoint de tipo get por el cual consultaremos la información de pagos que desees realizar a un cliente a partir de un número de identificación, de tal manera que cada vez que tu cliente ingrese al portal de recaudo e ingrese su número de identificación, nosotros consultaremos el endpoint proporcionado y poder mostrarle los pagos pendientes.

Documentación de la Estructura de Datos

Sección titulada «Documentación de la Estructura de Datos»
Método Uri Query Params
Get https://your.domain.com/… id_number

ejemplo

Sección titulada «ejemplo»
Get https://your.domain.com/get-recaudas?id_number=12345678

Al realizar el consumo del api, se espera el body en formato json y con un array de objetos “payments”.

Nota: Se recomienda llevar seguimiento de los recauda pendientes enviados para no volver a enviarlos y así hacer mas rápida la consulta.

Estructura del body

Sección titulada «Estructura del body»

El body es un objeto con un único campo payments, un array donde cada elemento es un recaudo. Cada recaudo tiene dos objetos: recauda_information (el cobro) y advanced_options (opcional, todo lo demás).

Campo Tipo Descripción
payments array, requerido Array de objetos con los recauda a ser consultados
payments[].recauda_information object, requerido Información del cobro de cada recauda
payments[].advanced_options object, opcional Opciones adicionales del cobro

recauda_information

Sección titulada «recauda_information»
Campo Tipo Descripción
description string, requerido, min:4, max:191 Descripción de la recaudación
amount string, requerido, min:4, max:191 Monto de la recaudación
currency_type string, requerido, enum: COP, USD, EUR Tipo de moneda del monto
id_number string numérico, min_dígitos:5 Número de identificación del cliente
payer_name string, requerido, min:5, max:191 Nombre del pagador
ref_payment string, requerido, único Referencia de pago. Debe ser único: es lo que usamos para no duplicar los recauda
expiration_date fecha yyyy-mm-dd, opcional Fecha de expiración, informativa para el cliente. Se sigue mostrando y se permite pagar aunque ya esté vencida
advance object, opcional Indica si el recaudo permite adelantos
advance.type string, enum: Valor Minimo, Porcentaje Minimo Tipo de adelanto
advance.value número, requerido Monto mínimo permitido para el adelanto
metadata array, opcional Data adicional que el comercio requiera

advanced_options

Sección titulada «advanced_options»
Campo Tipo Descripción
picture string, opcional, max:250 Imagen relacionada
limit_date fecha Y-m-d, opcional, igual o mayor a hoy Fecha límite para pagar. Solo se muestra y se permite el pago si la fecha es mayor a la fecha de consulta del recaudo
references array, opcional, max:3 Contenedor de las referencias
references[] string, requerido, max:50 Referencias a agregar
result_urls object, opcional Contenedor para las url de respuesta
result_urls.webhook string url, requerido Url para recibir actualizaciones vía webhook
delivery_service object, opcional Indica si tiene servicio a domicilio
delivery_service.type enum: Gratis, Con Valor, requerido Tipo de entrega
delivery_service.value decimal:2 Valor de la entrega
request_address_delivery bool, opcional Indica si se solicita la dirección de entrega
discount object, opcional Indica si se aplica algún descuento al pago
discount.before_on fecha Y-m-d, igual o posterior a hoy Fecha máxima para aplicar el descuento
discount.type enum: Porcentaje, Valor Tipo de descuento a aplicar
discount.value decimal:2 Valor del descuento a aplicar
cash_expired_period integer, nullable, min:1, max:60 Customiza el tiempo de expiración de un cupón en efectivo. Requiere cash_expired_interval. Solo aplica al pago de una factura
cash_expired_interval enum: minute, hour, day, week, month, year, nullable Unidad del tiempo de expiración del cupón en efectivo. Requiere cash_expired_period. Solo aplica al pago de una factura
has_comments bool, requerido Indica si permite comentarios
comments_label string, opcional, max:100 Personaliza el campo para adicionar comentarios

Ejemplo de body esperado

Sección titulada «Ejemplo de body esperado»
{
    "payments": [
        {
            "recauda_information": {
                "description": "prueba fill out all",
                "amount": 20000,
                "selected_taxes": null,
                "currency_type": "COP",
                "id_number": "12345678",
                "payer_name": "efipay",
                "ref_payment": "1234567",
                "advance": {
                    "type": "Valor Minimo",
                    "value": 5000
                },
                "metadata": {
                    "data": "Your additional data here"
                }
            },
            "advanced_options": {
                "picture": "https://efipay.co/images/logo.svg",
                "limit_date": "2025-03-15",
                "references": [
                    "123456",
                    "323432",
                    "6546456"
                ],
                "result_urls": {
                    "webhook": "https://webhook-test.com/310b715b9704556033c7fe260915cdfd"
                },
                "delivery_service": {
                    "type": "Con Valor",
                    "value": 5000
                },
                "has_comments": false,
                "comments_label": "Deja tus comentarios"
            }
        },
        {
            "recauda_information": {
                "description": "prueba fill out recauda only",
                "amount": 20000,
                "selected_taxes": null,
                "currency_type": "COP",
                "id_number": "12345678",
                "payer_name": "efipay",
                "ref_payment": "7654321",
                "advance": {
                    "type": "Valor Minimo",
                    "value": 5000
                }
            },
            "advanced_options": null
        },
        {
            "recauda_information": {
                "description": "prueba fill out errors",
                "amount": 20000,
                "selected_taxes": null,
                "currency_type": "COP",
                "id_number": "12345678",
                "payer_name": "efipay",
                "ref_payment": "7654322",
                "advance": {
                    "type": "Valor Minimo",
                    "value": 5000
                }
            },
            "advanced_options": null
        }
    ]
}

Ejemplo webhook

Sección titulada «Ejemplo webhook»

El webhook se usará para notificar la trx creada y el valor abonado.

La respuesta se compone de la transacción, con el monto pagado y el estado de la transacción. Adicionalmente el checkout tiene información importante sobre la información del recauda configurado, y el abono realizado.

Ten en cuenta que el monto de la trx puede no corresponder al del recauda configurado, ya que en una sola transacción se pueden pagar diferentes facturas de recauda.

Para identificar la trx puedes basarte en la referencia de pago que puedes ubicar checkout.payment_referenceable.ref_payment

Si la transacción se encuentra Aprobada puedes agregar el monto abonado en esta transacción el cual lo ubicas en checkout.paid_advance.amount_paid

Ejemplo del body:

{
  "transaction": {
    "transaction_id": 758,
    "amount": 100000,
    "currency_type": "COP",
    "value_cop": 100000,
    "payment_method": "pse",
    "payment_method_source": "BANCO BANK",
    "trazability_id": "UGdRx2g4AH",
    "authorization_code": "UGdRx2g4AH",
    "reference_1": "example@email.com",
    "reference_2": "1772557680767",
    "reference_3": "Recauda : 2referencias a pagar",
    "transaction_details": {
      "name": "dsfasd fas",
      "user_type": "person",
      "identification_type": "CedulaDeCiudadania",
      "identification_number": "424342432",
      "email": "example@email.com",
      "country": "+57",
      "phone": "3001234567",
      "address": "address",
      "bank": "BANCO BANK",
      "status_message": "Test mock"
    },
    "status": "Aprobada",
    "url_response": "https://efipay-sag.test/Checkout/Transaction/019cb4ab-c080-72fa-b029-19841fe1d7c7/Response",
    "approved_at": "2026-03-03T17:08:54.285461Z",
    "production": true,
    "created_at": "2026-03-03 12:08:00",
    "customer_payer": {
      "id": "9d549c89-5633-439c-ba42-f2f275d21636",
      "name": "dsfasd fas",
      "email": "example@email.com",
      "identification_type": "CC",
      "id_number": "123456789",
      "dialling_code": "+57",
      "cellphone": "3001234567",
      "country": "COL",
      "zip_code": "0000",
      "state": "Bogotá",
      "city": "Bogota",
      "address_2": "Apto",
      "address_1": "Calle 32 32",
      "created_at": "2024-10-25 04:41:30",
      "updated_at": "2026-03-03 12:08:54"
    },
    "currency_rate_conversion": {
      "id": 3,
      "usd_to_cop": 4192.65,
      "eur_to_cop": 4692.573296,
      "trm_for_cop": 1,
      "active": 1,
      "created_at": "2025-05-15T09:24:57.000000Z",
      "updated_at": "2025-05-15T09:24:57.000000Z",
      "deleted_at": null
    },
    "description": "Test mock"
  },
  "checkout": {
    "id": "019cb4aa-27ac-7079-bade-b21dcc0fcb72",
    "payment_referenceable_type": "App\\Models\\CollectionTools\\Recauda\\Recauda",
    "payment_referenceable_id": "019cb4a9-a206-7375-a57a-1a2305cf0dd4",
    "payment_gateway_id": "019cb4a9-a224-708a-9c9b-90718973fb3d",
    "delivery_address_id": null,
    "commerce_id": 1,
    "office_id": 1,
    "comments": null,
    "total_advance": 0,
    "paid_at": null,
    "ongoing_transaction": 0,
    "customer_payer_id": "9d549c89-5633-439c-ba42-f2f275d21636",
    "created_at": "2026-03-03 12:06:16",
    "updated_at": "2026-03-03 12:08:54",
    "total_pending": 50000,
    "pivot": {
      "transaction_id": "019cb4ab-c080-72fa-b029-19841fe1d7c7",
      "checkout_gateway_id": "019cb4aa-27ac-7079-bade-b21dcc0fcb72"
    },
    "payment_gateway": {
      "id": "019cb4a9-a224-708a-9c9b-90718973fb3d",
      "gatewayable_type": "App\\Models\\CollectionTools\\Recauda\\Recauda",
      "gatewayable_id": "019cb4a9-a206-7375-a57a-1a2305cf0dd4",
      "advanced_option_id": "019cb4a9-a21d-7241-8684-0c08b1cfcf49",
      "created_user_id": 11,
      "updated_user_id": 11,
      "office_id": 1,
      "commerce_id": 1,
      "massive_upload_id": null,
      "url": "https://efipay-sag.test/Checkout/Recauda/1/c4ca4238a0b923820dcc509a6f75849b",
      "full_payment_at": "2026-03-03 12:08:54",
      "active": 1,
      "production": 1,
      "expired_at": null,
      "checkout_template_id": null,
      "created_at": "2026-03-03 12:05:41",
      "updated_at": "2026-03-03 12:08:54",
      "deleted_at": null,
      "sub_total": 50000,
      "amount_without_tax": 50000,
      "tax_amount": null,
      "total": 50000,
      "total_cop": 50000,
      "tool_name": "Recauda",
      "purchase_detail": {},
      "advanced_option": {},
      "gatewayable": {}
    },
    "payment_referenceable": {
      "id": "019cb4a9-a206-7375-a57a-1a2305cf0dd4",
      "description": "Prueba 1",
      "amount": 50000,
      "tax": null,
      "currency_type": {
        "name": "Peso Colombiano",
        "symbol": "$",
        "abbreviation": "COP"
      },
      "id_number": "12345679",
      "payer_name": "Efipay prueba",
      "advance_type": null,
      "advance_value": null,
      "metadata": null,
      "ref_payment": null,
      "expiration_date": null,
      "email": null,
      "cellphone": null,
      "created_at": "2026-03-03 12:05:41",
      "updated_at": "2026-03-03 12:05:41",
      "deleted_at": null,
      "total": 50000,
      "include_tax": false,
      "has_advance": false,
      "advance": {
        "type": null,
        "value": null
      },
      "url_bill": null,
      "tax_amount": 0
    },
    "paid_advance": {
      "id": "019cb4aa-284c-702e-b311-1c76e7382a61",
      "description": "Prueba 1",
      "amount_paid": 50000,
      "amount_currency": {
        "name": "Peso Colombiano",
        "symbol": "$",
        "abbreviation": "COP"
      },
      "exchange_paid": 50000,
      "exchange_currency": "COP",
      "tool_paid": true,
      "checkout_gateway_id": "019cb4aa-27ac-7079-bade-b21dcc0fcb72",
      "transaction_id": "019cb4aa-27e0-7080-85a2-4c4ad71fcdcf",
      "created_at": "2026-03-03 12:06:16",
      "updated_at": "2026-03-03 12:06:16",
      "deleted_at": null
    },
    "answer_form": null
  }
}

Consulta de una factura recauda

Sección titulada «Consulta de una factura recauda»

GET /api/v1/payment/recauda

Envía uno de los dos identificadores; si no envías ninguno, la petición se rechaza.

Nombre del campo Descripción Reglas
payment_gateway_id Id del cobro generado para la factura ['required_without:ref_payment', 'nullable', 'string', 'uuid']
ref_payment La referencia que le asignaste a la factura ['required_without:payment_gateway_id', 'nullable', 'string', 'max:191']
GEThttps://sag.efipay.co/api/v1/payment/recauda?ref_payment=FACT-00123
Ventana de terminal
curl -X GET \
'/api/v1/payment/recauda?ref_payment=FACT-00123' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H "Content-type: application/json"
404Not Found 
{
    "message": "Recauda or payment gateway not found."
}

Respuesta exitosa:

{
    "payment_gateway": {
        "id": "019cb4aa-f88c-7217-8a64-bc8bb0491cc1",
        "tool_name": "Recauda",
        "active": 1,
        "production": 1,
        "full_payment_at": "2026-03-03 12:08:54",
        "url": "https://efipay-sag.test/Checkout/Recauda/1/c4ca4238a0b923820dcc509a6f75849b",
        "created_at": "2026-03-03 12:07:09",
        "updated_at": "2026-03-03 12:08:54"
    },
    "recauda": {
        "id": "019cb4aa-f87a-70a1-a98f-ce9e1fe90dbb",
        "description": "prueba 2",
        "amount": 50000,
        "tax": null,
        "currency_type": {
            "name": "Peso Colombiano",
            "symbol": "$",
            "abbreviation": "COP"
        },
        "id_number": "123456789",
        "payer_name": "efipay",
        "ref_payment": "100",
        "expiration_date": null,
        "total": 50000,
        "include_tax": false,
        "has_advance": false,
        "created_at": "2026-03-03 12:07:09",
        "updated_at": "2026-03-03 12:07:09",
        "metadata": null
    },
    "summary": {
        "amount": 50000,
        "amount_cop": 50000,
        "amount_paid": 50000,
        "totalmente_pagado": "2026-03-03 12:08:54"
    },
    "checkout_gateway": {
        "id": "019cb4ab-c066-71d8-a5dd-1b8c0cb5328a",
        "total_advance": 50000,
        "total_pending": 0,
        "paid_at": "2026-03-03 12:08:54",
        "ongoing_transaction": 0,
        "comments": null,
        "created_at": "2026-03-03 12:08:00",
        "updated_at": "2026-03-03 12:08:54",
        "transactions": [
            {
                "transaction_id": 758,
                "amount": 100000,
                "currency_type": "COP",
                "value_cop": 100000,
                "payment_method": "pse",
                "payment_method_source": "BANCO CAJA SOCIAL",
                "trazability_id": "UGdRx2g4AH",
                "authorization_code": "UGdRx2g4AH",
                "reference_1": "example@email.com",
                "reference_2": "1772557680767",
                "reference_3": "Recauda : 2referencias a pagar",
                "transaction_details": {
                    "name": "dsfasd fas",
                    "user_type": "person",
                    "identification_type": "CedulaDeCiudadania",
                    "identification_number": "123456789",
                    "email": "exmaple@email.com",
                    "country": "+57",
                    "phone": "3001234567",
                    "address": "Calle 32 # 465 - 14",
                    "bank": "BANCO CAJA SOCIAL",
                    "status_message": "Test mock"
                },
                "status": "Aprobada",
                "url_response": "https://efipay-sag.test/Checkout/Transaction/019cb4ab-c080-72fa-b029-19841fe1d7c7/Response",
                "approved_at": "2026-03-03 12:08:54",
                "production": true,
                "created_at": "2026-03-03 12:08:00",
                "customer_payer": {
                    "id": "9d549c89-5633-439c-ba42-f2f275d21636",
                    "name": "dsfasd fas",
                    "email": "example@email.com",
                    "identification_type": "CC",
                    "id_number": "123456789",
                    "dialling_code": "+57",
                    "cellphone": "3001234567",
                    "country": "COL",
                    "zip_code": "0000",
                    "state": "Bogotá",
                    "city": "Bogota",
                    "address_2": "Apto",
                    "address_1": "Calle 32 32",
                    "created_at": "2024-10-25 04:41:30",
                    "updated_at": "2026-03-03 12:08:54"
                },
                "currency_rate_conversion": {
                    "id": 3,
                    "usd_to_cop": 4192.65,
                    "eur_to_cop": 4692.573296,
                    "trm_for_cop": 1,
                    "active": 1,
                    "created_at": "2025-05-15T09:24:57.000000Z",
                    "updated_at": "2025-05-15T09:24:57.000000Z",
                    "deleted_at": null
                },
                "description": "Test mock"
            }
        ]
    }
}

Posibles errores: 404: not found

Última actualización: