Conexión a ERP

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 numero de identificación, nosotros consultaremos el endpoint proporcionado y poder mostrarle los pagos pendientes.

Documentación de la Estructura de Datos

Método Uri Query Params
Get https://your.domain.com/... id_number

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 body

  • payments (array, requerido): Array de objetos con los recauda a ser consultados.
  • payments.[].recauda_information (Object, requerido): Objeto con la información del cobro de cada recauda.
  • payments.[].recauda_information.description (string, requerido, min:4, max:191): Descripción de la recaudación ERP por API Success.
  • payments.[].recauda_information.amount (string, requerido, min:4, max:191): Monto de la recaudación.
  • payments.[].recauda_information.currency_type (string, enum:COP,USD,EUR requerido, min:4, max:191): Tipo de moneda del monto.
  • payments.[].recauda_information.id_number (string, numero, min_digitos:5): Número de identificación del cliente.
  • payments.[].recauda_information.payer_name (string, requerido, min:5, max:191): Nombre del pagador.
  • payments.[].recauda_information.advance (string, opcional, max:191): para indicar si permite adelantos.
  • payments.[].recauda_information.advance.type (string, enum:Valor Minimo,Porcentaje Minimo): Indica el tipo de adelanto.
  • payments.[].recauda_information.advance.value (numero, requerido): Indicar el monto minimo permitido para el adelanto.
  • payments.[].recauda_information.ref_payment (string, requerido, único): Referencia de pago, debe ser un valor único y se usara para prevenir duplicar los recauda.
  • payments.[].recauda_information.expiration_date (fecha:yyyy-mm-dd, opcional): Indica la fecha de expiración de manera informativa al cliente quien realizara el pago, se seguirá mostrando y permitirá pagar aun si la fecha ya esta vencida
  • payments.[].recauda_information.metadata (array, opcional,): Agregar data adicional que el comercio requiera.
  • payments.[].advanced_options (object, opcional): Descripción de la recaudación ERP por API Success.
  • payments.[].advanded_options.picture (string, opcional, max:250): Imagen relacionada.
  • payments.[].advanded_options.limit_date (string, opcional, fecha:Y-m-d mayor o igual a hoy): Fecha límite para realizar el pago, solo se mostrará y se permitirá el pago si la fecha es mayor a la fecha de consulta del recaudo.
  • payments.[].advanded_options.references (array, opcional, max:3): Contenedor de las referencias.
  • payments.[].advanded_options.references.3 (string, requerido, max:50): Referencias a agregar.
  • payments.[].advanded_options.result_urls (object, opcional): Contenedor para las url de respuesta.
  • payments.[].advanded_options.result_urls.webhook (string, requerido, url): url para recibir actualizaciones via webhook.
  • payments.[].advanded_options.delivery_service (object, opcional): para indicar si tiene servicio a domicilio.
  • payments.[].advanded_options.delivery_service.type (enum:Gratis,Con Valor, requerido): tipo de entrega.
  • payments.[].advanded_options.delivery_service.value (decimal:2): Valor de la entrega.
  • payments.[].advanded_options.request_address_delivery (bool, opcional): Indica si se solicita la dirección de entrega.
  • payments.[].advanded_options.discount (object, opcional): Indicar si se realiza algun descuento al pago.
  • payments.[].advanded_options.discount.before_on (string, fecha:Y-m-d igual o despues de hoy): Indicar fecha maxima para aplicar el descuento.
  • payments.[].advanded_options.discount.type (enum:Porcentaje,Valor): Tipo de descuento a aplicar.
  • payments.[].advanded_options.discount.value (decimal:2): Valor del descuento a aplicar.
  • payments.[].advanded_options.has_comments (bool, requerido): Indica si permite comentarios.
  • payments.[].advanded_options.comments_label (string, opcional, max:100): Personalizar el campo para adicionar comentarios.

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

El webhook se usara 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 encuenta 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 recuada.

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

Body params

payment_gateway_id: opcional uuid, id del pago de la factura generada

ref_payment: opcional, referencia asignada a la factura creada

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, // null
        "amount_cop": 50000, // null
        "amount_paid": 50000, //0
        "totalmente_pagado": "2026-03-03 12:08:54" //false
    },
    "checkout_gateway": { // null when therse no any payment yet
        "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