Verifacti Integration

About Verifactu

Verifactu is the new anti-fraud regulation enforced by the Spanish Tax Agency (AEAT). It mandates that all billing software must guarantee that invoice records are traceable, unalterable, and secure.

Essentially, it prevents the manipulation of accounting data by requiring strict technical standards for record integrity.

Verifacti API Integration with Ecart Pay

This integration streamlines the billing process for Spanish merchants using Ecart Pay by connecting directly with Verifacti's certified API. It handles the complexities of the Verifactu system such as chaining invoice records, calculating secure fingerprints, and managing QR codes transparently in the background.

Key Capabilites

Automated Submission

Invoices are submitted to the AEAT immediately upon creation.

Compliance Metadata

Automatically appends the required QR code and VeriFactu fingerprint to your invoice documents.

Hybrid Document Generation

Provides both the official XML for fiscal purposes and a visual PDF for customers.

Multiple Format Support

Capable of issuing standard (F1), simplified (F2), and rectifying (R1-R5) invoices through a unified API endpoint.

Multi-language PDF Generation

Generate invoice PDFs in Spanish, Italian, or French based on the billing configuration, including localized currency formatting and legal disclaimers.

Passthrough Support

Flexible payload structure allows you to pass advanced fiscal fields like clave_regimen or calificacion_operacion directly to Verifacti without waiting for backend updates.

Supported Invoice Types

This integration supports all standard AEAT invoice formats dynamically via the Passthrough feature.

F1 (Complete Invoice): Standard B2B invoice with full customer identification. (Default behavior).
F2 (Simplified Invoice): "Ticket" style invoice for B2C or simplified scenarios.
R1 - R5 (Rectifying Invoices): For corrections, refunds, or credit notes.
Equivalence Surcharge Invoices: These invoices include the Recargo de Equivalencia (RE) special VAT regime for retailers.

Note: To generate specific types (e.g., R1), simply include the tipo_factura and required fields (like facturas_rectificadas) inside the billing_information object. The backend will automatically pass these fields to Verifacti.

Verifacti Integration Endpoints

Beyond standard creation and cancellation, this integration exposes specific endpoints for AEAT compliance, status tracking and more.

Invoice Creation Endpoint

POST

Create Order Invoice (Verifactu)

Create and register an electronic invoice via Verifacti to complain with AEAT fiscal regulations for Verifactu. The billing record will be generated and submitted to the AEAT.

Billings Management Endpoints

GET

Verifacti API Status

Connection verification and credential validation upon saving your Verifacti API Key in the Billing gateways dashboard.

PUT

Cancel invoice

This endpoint allows you to cancel existing invoices. By doing so, new information is sent to the AEAT.

GET

Invoice Status

This endpoint allows you to consult the status of an invoice in the AEAT system.

GET

Submission Status

Technical query to the AEAT about the invoice submission status using the uuid.

POST

List invoices

Consultation of invoices presented to the AEAT with filters.

GET

Responsible Declaration

Obtain the Verifacti responsible declaration document.

PATCH

Change Invoice Language

Used to choose in which language the invoice PDF will be rendered.

NIFs Management Endpoints

GET

Verifacti API Key from a NIF

This endpoint returns the API key for a specific NIF and in a specific environment.

GET

List NIFs

This endpoint returns a list of all NIFs. By default, it returns both active and inactive in both environments, although it allows you to filter only active or inactive and the environment.

POST

Add NIF

New NIFs are added through this endpoint to enable Verifactu invoicing. Please note that each NIF requires a unique Verifacti API Key, which Verifacti generates upon adding a new NIF.

GET

NIF Information

This endpoint returns the information of a specific NIF.

PUT

Update NIF

This endpoint allows you to modify the information of a specific NIF.

DELETE

Deactivate NIF

This endpoint allows you to deactivate a NIF. Any deactivated NIF can be reactivated at any time to continue sending invoices.

PUT

Activate NIF

This endpoint allows you to activate a NIF that has been previously deactivated.

POST

VIES Validation

This endpoint allows you to validate that an intra-community VAT number is in the VIES census.

POST

AEAT Validation

This endpoint allows you to validate that a NIF is identified in the AEAT.

Passthrough Example: Creating a Rectifying Invoice (R1)

To create a rectifying invoice (credit note), send the standard Ecart Pay payload but include the specific Verifacti fields inside billing_information like tipo_factura, facturas_rectificadas, serie, etc..

Endpoint: POST /api/billings?country=ES

{
    "currency": "EUR",
    "items": [
        {
            "name": "Servicio Rectificado",
            "price": 1000,
            "quantity": 2,
            "discount": 0,
            "tax": 420,
            "total": 2420,
            "is_service": false
        }
    ],
    "billing_information": {
        "first_name": "Sergio",
        "last_name": "Ramos",
        "razons": "Rio Ramos SA",
        "nif": "A15022510",
        "address": "Dirección del cliente",
        "country": "España",
        "tipo_factura": "R1",
        "tipo_rectificativa": "S",
        "fecha_expedicion": "03-12-2025",
        "fecha_operacion": "01-12-2025",
        "descripcion": "Rectificacion por sustitucion en un paso",
        "importe_rectificativa": {
            "base_rectificada": "2000",
            "cuota_rectificada": "240"
        },
        "facturas_rectificadas": [
            {
                "serie": "RECT",
                "numero": "1",
                "fecha_expedicion": "10-04-2025"
            }
        ]
    }
}

⚠️
IMPORTANT
To follow the steps below, it is essential to have the corresponding Authorization Token. For more information, please refer to the following documentation page: Authorization Token

Verifacti API Status

This endpoint returns the status of the API key. It is mainly used to verify that the API is active and to know which NIF and environment it refers to.

💻
Visit our API Reference to test this endpoint.

Endpoint

https://ecartpay.com/api/billings/health-check
https://sandbox.ecartpay.com/api/billings/health-check

Headers

Authorization: token

Examples

Request

curl --location 'https://sandbox.ecartpay.com/api/billings/health-check' \
--header 'Authorization: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY4YTRjMzE1MGIyOGE5NTg0MzA1YTJhYSIsImFjY291bnRfaWQiOiI2OGE0YzMxNTBiMjhhOTU4NDMwNWEyYTYiLCJhY2NvdW50Ijp7ImVtYWlsIjoiaHVnby5tb3JpbkBlY2FydHBheS5jb20iLCJmaXJzdF9uYW1lIjoiSHVnbyIsImxhc3RfbmFtZSI6Ik1vcsOtbiIsInBob25lIjoiNTI......' \
--header 'Cookie: __cf_bm=_h31xA6xIlq3DQ9SuCN8WTtHiM.AxyaFToOnwojSI8A-1765472330-1.0.1.1-qfZRCG2WOQURGq3zTm8JrKTAKME9rNoPTU__tL7TuZM1aqGPGPSHGENRAgLeukv5XtHJsYc3kUCQybOfLW810OBY_7ogYXqGRoxQwjZDrlA; lang=en'

Response

{
    "CODE": 337,
    "MESSAGE": "Connection to billing provider is successful."
}