Payments and Invoices

The accounting data API allows the Registrar to view and manage payments, invoices, and credit. The billing scope in the token is required for all methods.

Registrar credit

Get the credit

1.0 | billing | admin / billing |

GET https://api.nic.it/v1/credit

The Registrar can get the current credit, available for operations, as in the following example:

HTTPcURLHTTPie

GET /v1/credit HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token....

HTTP/1.1 200 OK
Content-Type: application/json

{
  "credit" : 199.11,
  "threshold" : 12.0,
  "lastupdate" : "2024-02-11T15:01:00+01:00",
  "status" : "normalBalance"
}

curl https://api.nic.it/v1/credit \
    -H "Accept: application/json" \
    -H "Authorization: Bearer token..."

{
  "credit" : 199.11,
  "threshold" : 12.0,
  "lastupdate" : "2024-02-11T15:01:00+01:00",
  "status" : "normalBalance"
}

http https://api.nic.it/v1/credit "Authorization: Bearer token..."

{
  "credit" : 199.11,
  "threshold" : 12.0,
  "lastupdate" : "2024-02-11T15:01:00+01:00",
  "status" : "normalBalance"
}

Get the historical credit

1.0 | billing | admin / billing |

GET https://api.nic.it/v1/credit/untilDate?date={date}

You can get a historical credit by indicating the date of interest in the request.

Info

Note that the specified date is included in the calculation, and therefore all credit changes up to 23:59:59 on the specified date will be considered.

The following example requests the value of the credit at the end of 2023.

HTTPcURLHTTPie

GET /v1/credit/untilDate?date=2023-12-31 HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token....

HTTP/1.1 200 OK
Content-Type: application/json

{
  "credit" : 245.5,
}

curl "https://api.nic.it/v1/credit/untilDate?date=2023-12-31" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "credit" : 245.5,
}

http https://api.nic.it/v1/credit/untilDate \
    "Authorization: Bearer token..." \
    date==2023-12-31

{
  "credit" : 245.5,
}

Warning

Depending on the number of credit variations, the calculation of historical credit may take time to compute.

Get the credit threshold

1.0 | billing | admin / billing |

GET https://api.nic.it/v1/credit/warnThreshold

The Registrar can set a credit threshold below which a warning will be sent (via EPP message). You can get the current threshold value as follows:

HTTPcURLHTTPie

GET /v1/credit/warnThreshold HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token....

HTTP/1.1 200 OK
Content-Type: application/json

{
  "threshold" : 100.0
}

curl "https://api.nic.it/v1/credit/warnThreshold \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "threshold" : 100.0
}

http "https://api.nic.it/v1/credit/warnThreshold \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "threshold" : 100.0
}

Modify the credit threshold

1.0 | billing | admin / billing |

PUT https://api.nic.it/v1/credit/warnThreshold

The Registrar can set a credit threshold below which a warning will be sent (via EPP message). You can set the threshold value as follows:

HTTPcURLHTTPie

PUT /v1/credit/warnThreshold HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: api.nic.it
Authorization: Bearer token....

{
  "threshold" : 200
}

HTTP/1.1 204 No Content

curl -X PUT  "https://api.nic.it/v1/credit/warnThreshold" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer token...." \
-d '
{
    "threshold" : 200
}'

http PUT https://api.nic.it/v1/credit/warnThreshold  \
    "Authorization: Bearer token...." \
    threshold=200

Payments

Payments are the method used by the Registrars to charge the credit needed for domain operations. The available credit recharge methods (creating a payment) are:

• Payment by bank transfer
• Payment by credit card

Create a bank payment

1.0 | billing | admin / billing |

POST https://api.nic.it/v1/payments/bank

Allows you to create a bank payment following a bank transfer made by the Registrar. Example:

HTTPcURLHTTPie

POST /v1/payments/bank HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: api.nic.it
Authorization: Bearer token...

{
  "amount" : 200.0,
  "bankPayment" : {
    "european" : true,
    "applicant" : "Giulio Cesare",
    "applicantRole" : "admin",
    "bankName" : "Una Banca Spa",
    "branchName" : "Test",
    "paymentDate" : "2024-02-26",
    "valueDate" : "2024-02-27",
    "transactionId" : "ABC12345"
  }
}

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id" : 14,
  "amount" : 200.0,
  "type" : "bank",
  "status" : "submitted",
  "statusDate" : "2024-02-26T16:57:18+01:00",
  "lastupdate" : "2024-02-26T16:57:18+01:00",
  "created" : "2024-02-26T16:57:18+01:00",
  "bankPayment" : {
    "european" : true,
    "applicant" : "Giulio Cesare",
    "applicantRole" : "admin",
    "bankName" : "Una Banca Spa",
    "branchName" : "Test",
    "paymentDate" : "2024-02-26",
    "valueDate" : "2024-02-27",
    "transactionId" : "ABC12345"
  }
}

curl -X POST https://api.nic.it/v1/payments/bank \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer token..." \
-d '
{
    "amount" : 200.0,
    "bankPayment" : {
        "european" : true,
        "applicant" : "Giulio Cesare",
        "applicantRole" : "admin",
        "bankName" : "Una Banca Spa",
        "branchName" : "Test",
        "paymentDate" : "2024-02-26",
        "valueDate" : "2024-02-27",
        "transactionId" : "ABC12345"
    }
}'

{
  "id" : 14,
  "amount" : 200.0,
  "type" : "bank",
  "status" : "submitted",
  "statusDate" : "2024-02-26T16:57:18+01:00",
  "lastupdate" : "2024-02-26T16:57:18+01:00",
  "created" : "2024-02-26T16:57:18+01:00",
  "bankPayment" : {
    "european" : true,
    "applicant" : "Giulio Cesare",
    "applicantRole" : "admin",
    "bankName" : "Una Banca Spa",
    "branchName" : "Test",
    "paymentDate" : "2024-02-26",
    "valueDate" : "2024-02-27",
    "transactionId" : "ABC12345"
  }
}

http https://api.nic.it/v1/payments/bank  \
    "Authorization: Bearer token...." \
    --raw \
'{
  "id" : 14,
  "amount" : 200.0,
  "type" : "bank",
  "status" : "submitted",
  "statusDate" : "2024-02-26T16:57:18+01:00",
  "lastupdate" : "2024-02-26T16:57:18+01:00",
  "created" : "2024-02-26T16:57:18+01:00",
  "bankPayment" : {
    "european" : true,
    "applicant" : "Giulio Cesare",
    "applicantRole" : "admin",
    "bankName" : "Una Banca Spa",
    "branchName" : "Test",
    "paymentDate" : "2024-02-26",
    "valueDate" : "2024-02-27",
    "transactionId" : "ABC12345"
  }
}'

{
  "id" : 14,
  "amount" : 200.0,
  "type" : "bank",
  "status" : "submitted",
  "statusDate" : "2024-02-26T16:57:18+01:00",
  "lastupdate" : "2024-02-26T16:57:18+01:00",
  "created" : "2024-02-26T16:57:18+01:00",
  "bankPayment" : {
    "european" : true,
    "applicant" : "Giulio Cesare",
    "applicantRole" : "admin",
    "bankName" : "Una Banca Spa",
    "branchName" : "Test",
    "paymentDate" : "2024-02-26",
    "valueDate" : "2024-02-27",
    "transactionId" : "ABC12345"
  }
}

Get a payment by id

1.0 | billing | admin / billing |

GET https://api.nic.it/v1/payments/{paymentId}

You can get the payment data using the numeric id assigned by the Registry. Payment data may vary depending on the payment type.

Example related to a bank payment:

HTTPcURLHTTPie

GET /v1/payments/4 HTTP/1.1
Accept: application/json
Host: api.nic.it

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id" : 4,
  "amount" : 300.0,
  "debitedAmount" : 20.0,
  "previousResidual" : 3.0,
  "type" : "bank",
  "status" : "approved",
  "statusDate" : "2023-02-15T15:01:00+01:00",
  "lastupdate" : "2023-02-15T15:01:00+01:00",
  "created" : "2023-02-15T15:01:00+01:00",
  "bankPayment" : {
    "european" : true,
    "applicant" : "Galileo Galilei",
    "applicantRole" : "admin",
    "bankName" : "Banca Galilei",
    "branchName" : "Online",
    "paymentDate" : "2023-02-13",
    "valueDate" : "2023-02-15",
    "transactionId" : "123456"
  }
}

curl https://api.nic.it/v1/payments/4 \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "id" : 4,
  "amount" : 300.0,
  "debitedAmount" : 20.0,
  "previousResidual" : 3.0,
  "type" : "bank",
  "status" : "approved",
  "statusDate" : "2023-02-15T15:01:00+01:00",
  "lastupdate" : "2023-02-15T15:01:00+01:00",
  "created" : "2023-02-15T15:01:00+01:00",
  "bankPayment" : {
    "european" : true,
    "applicant" : "Galileo Galilei",
    "applicantRole" : "admin",
    "bankName" : "Banca Galilei",
    "branchName" : "Online",
    "paymentDate" : "2023-02-13",
    "valueDate" : "2023-02-15",
    "transactionId" : "123456"
  }
}

http https://api.nic.it/v1/payments/4 "Authorization: Bearer token..."

{
  "id" : 4,
  "amount" : 300.0,
  "debitedAmount" : 20.0,
  "previousResidual" : 3.0,
  "type" : "bank",
  "status" : "approved",
  "statusDate" : "2023-02-15T15:01:00+01:00",
  "lastupdate" : "2023-02-15T15:01:00+01:00",
  "created" : "2023-02-15T15:01:00+01:00",
  "bankPayment" : {
    "european" : true,
    "applicant" : "Galileo Galilei",
    "applicantRole" : "admin",
    "bankName" : "Banca Galilei",
    "branchName" : "Online",
    "paymentDate" : "2023-02-13",
    "valueDate" : "2023-02-15",
    "transactionId" : "123456"
  }
}

Search for payments

1.0 | billing | admin / billing |

GET https://api.nic.it/v1/payments

You can search for payments made by the Registrar using multiple search parameters and operators (advanced search).

Below is the list of parameters and operators available for searching for payments:

Parameter	Type	Cardinality	Description	Supported operators	Default operator
amount	Number	Single	Total payment amount	eq, ne, gt, lt, ge, le, in, notIn, between	eq
type	String	Single	Payment type (bank, creditCard, registry, contractTransfer)	eq, ne, in, notIn	eq
status	String	Single	Payment status (submitted, approved, suspended, rejected)	eq, ne, in, notIn	eq
created	DateTime	Multiple	Creation date	eq, ne, gt, lt, ge, le, between	eq

Example of a search for payments made by bank transfer or credit card (type=in:bank,creditCard) with an amount of at least 500 Euros (amount=ge:500):

HTTPcURLHTTPie

GET /v1/payments?type=in%3Abank%2CcreditCard&amount=ge%3A200 HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token....

HTTP/1.1 200 OK
Content-Type: application/json

{
    "elements": [
        {
          "id" : 4,
          "amount" : 550.0,
          "debitedAmount" : 551.0,
          "previousResidual" : 3.0,
          "finalResidual" : 2.0,
          "type" : "bank",
          "status" : "approved",
          "statusDate" : "2023-02-15T15:01:00+01:00",
          "lastupdate" : "2023-02-15T15:01:00+01:00",
          "created" : "2023-02-15T15:01:00+01:00",
          "bankPayment" : {
            "european" : true,
            "applicant" : "Galileo Galilei",
            "applicantRole" : "admin",
            "bankName" : "Banca Galilei",
            "branchName" : "Online",
            "paymentDate" : "2023-02-13",
            "valueDate" : "2023-02-15",
            "transactionId" : "123456"
          }
        },
        {
            "id": 10,
            "amount": 644.0,
            "debitedAmount": 100,
            "previousResidual": 2.0,
            "type": "creditCard",
            "status": "approved",
            "statusDate": "2024-02-11T09:19:09+01:00",
            "lastupdate": "2024-02-11T09:19:09+01:00",
            "created": "2024-02-11T09:19:09+01:00",
            "creditCardTransaction": {
                "transactionId": "abc-123-cde",
                "service": "phey"
            }
        }
    ],
    "page": {
        "number": 0,
        "size": 20,
        "totalElements": 2,
        "totalPages": 1
    }
}

curl "https://api.nic.it/v1/payments?type=?type=in:bank,creditCard&amount=ge:200" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..." 

{
    "elements": [
        {
          "id" : 4,
          "amount" : 550.0,
          "debitedAmount" : 551.0,
          "previousResidual" : 3.0,
          "finalResidual" : 2.0,
          "type" : "bank",
          "status" : "approved",
          "statusDate" : "2023-02-15T15:01:00+01:00",
          "lastupdate" : "2023-02-15T15:01:00+01:00",
          "created" : "2023-02-15T15:01:00+01:00",
          "bankPayment" : {
            "european" : true,
            "applicant" : "Galileo Galilei",
            "applicantRole" : "admin",
            "bankName" : "Banca Galilei",
            "branchName" : "Online",
            "paymentDate" : "2023-02-13",
            "valueDate" : "2023-02-15",
            "transactionId" : "123456"
          }
        },
        {
            "id": 10,
            "amount": 644.0,
            "debitedAmount": 100,
            "previousResidual": 2.0,
            "type": "creditCard",
            "status": "approved",
            "statusDate": "2024-02-11T09:19:09+01:00",
            "lastupdate": "2024-02-11T09:19:09+01:00",
            "created": "2024-02-11T09:19:09+01:00",
            "creditCardTransaction": {
                "transactionId": "abc-123-cde",
                "service": "phey"
            }
        }
    ],
    "page": {
        "number": 0,
        "size": 20,
        "totalElements": 2,
        "totalPages": 1
    }
}

http https://api.nic.it/v1/payments \
    "Authorization: Bearer token..." \
    type==in:bank,creditCard \
    amount==ge:200

{
    "elements": [
        {
          "id" : 4,
          "amount" : 550.0,
          "debitedAmount" : 551.0,
          "previousResidual" : 3.0,
          "finalResidual" : 2.0,
          "type" : "bank",
          "status" : "approved",
          "statusDate" : "2023-02-15T15:01:00+01:00",
          "lastupdate" : "2023-02-15T15:01:00+01:00",
          "created" : "2023-02-15T15:01:00+01:00",
          "bankPayment" : {
            "european" : true,
            "applicant" : "Galileo Galilei",
            "applicantRole" : "admin",
            "bankName" : "Banca Galilei",
            "branchName" : "Online",
            "paymentDate" : "2023-02-13",
            "valueDate" : "2023-02-15",
            "transactionId" : "123456"
          }
        },
        {
            "id": 10,
            "amount": 644.0,
            "debitedAmount": 100,
            "previousResidual": 2.0,
            "type": "creditCard",
            "status": "approved",
            "statusDate": "2024-02-11T09:19:09+01:00",
            "lastupdate": "2024-02-11T09:19:09+01:00",
            "created": "2024-02-11T09:19:09+01:00",
            "creditCardTransaction": {
                "transactionId": "abc-123-cde",
                "service": "phey"
            }
        }
    ],
    "page": {
        "number": 0,
        "size": 20,
        "totalElements": 2,
        "totalPages": 1
    }
}

The search results are paginated.

Get the payment report

1.0 | billing | admin / billing |

GET https://api.nic.it/v1/payments/{paymentId}/report

This method provides an aggregated report of operations (domains, bulk transfers and penalties) charged on a payment.

Example:

HTTP

GET /v1/payments/4/report HTTP/1.1
Accept: application/json
Host: api.nic.it

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
    "amount": 244.0,
    "previousResidual": 2.86,
    "finalResidual": 2.738,
    "domainsOperations": [
        {
            "operation": "domain-renew",
            "quantity": 57,
            "operationCost": -4.026,
            "amount": -229.482
        },
        {
            "operation": "domain-create",
            "quantity": 3,
            "operationCost": -4.88,
            "amount": -14.64
        }
    ],
    "lastupdate": "2025-02-12T12:44:04+01:00"
}
```

cURLHTTPie

curl https://api.nic.it/v1/payments/4/report \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

 {
    "amount": 244.0,
    "previousResidual": 2.86,
    "finalResidual": 2.738,
    "domainsOperations": [
        {
            "operation": "domain-renew",
            "quantity": 57,
            "operationCost": -4.026,
            "amount": -229.482
        },
        {
            "operation": "domain-create",
            "quantity": 3,
            "operationCost": -4.88,
            "amount": -14.64
        }
    ],
    "lastupdate": "2025-02-12T12:44:04+01:00"
}

http https://api.nic.it/v1/payments/4/report "Authorization: Bearer token..."

 {
    "amount": 244.0,
    "previousResidual": 2.86,
    "finalResidual": 2.738,
    "domainsOperations": [
        {
            "operation": "domain-renew",
            "quantity": 57,
            "operationCost": -4.026,
            "amount": -229.482
        },
        {
            "operation": "domain-create",
            "quantity": 3,
            "operationCost": -4.88,
            "amount": -14.64
        }
    ],
    "lastupdate": "2025-02-12T12:44:04+01:00"
}

Get the invoice linked to a payment

1.0 | billing | admin / billing |

GET https://api.nic.it/v1/payments/{paymentId}/invoice

You can get invoice data linked to a payment (if available) as in the following example:

HTTPcURLHTTPie

GET /v1/payments/1111/invoice HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token....

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id" : 2789,
  "fiscalYear" : 2023,
  "invoiceNumber" : 10,
  "totalAmount" : 1000.0,
  "taxAmount" : 220.0,
  "taxRate" : "22%",
  "invoiceDate" : "2023-12-11"
}

curl https://api.nic.it/v1/payments/1111/invoice \
-H "Accept: application/json" \
-H "Authorization: Bearer token..." 

{
    "id" : 2789,
    "fiscalYear" : 2023,
    "invoiceNumber" : 10,
    "totalAmount" : 1000.0,
    "taxAmount" : 220.0,
    "taxRate" : "22%",
    "invoiceDate" : "2023-12-11"
}

http https://api.nic.it/v1/payments/1111/invoice "Authorization: Bearer token..."

{
    "id" : 2789,
    "fiscalYear" : 2023,
    "invoiceNumber" : 10,
    "totalAmount" : 1000.0,
    "taxAmount" : 220.0,
    "taxRate" : "22%",
    "invoiceDate" : "2023-12-11"
}

Start a credit card payment

1.0 | billing | admin / billing |

POST https://api.nic.it/v1/payments/creditCard/transactions

This method is used to start a credit card payment to be completed on the bank's website. Example:

HTTPcURLHTTPie

POST /v1/payments/creditCard/transactions HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: api.nic.it
Authorization: Bearer token....

{
  "language" : "it",
  "amount" : 500,
  "redirectSuccessUrl" : "http://success.url",
  "redirectFailureUrl" : "http://failure.url"
}

HTTP/1.1 201 OK
Content-Type: application/json

{
  "id" : "cdc8555b-2cca-4f7f-ae80",
  "gatewayId" : "test-1-1-1",
  "amount" : "500.00",
  "language" : "it",
  "status" : "pending",
  "created" : "2024-05-09T09:41:17+02:00"
}

curl -X POST https://api.nic.it/v1/payments/creditCard/transactions \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer token..." \
-d '
{
  "language" : "it",
  "amount" : 500,
  "redirectSuccessUrl" : "http://success.url",
  "redirectFailureUrl" : "http://failure.url"
}`

{
  "id" : "cdc8555b-2cca-4f7f-ae80",
  "gatewayId" : "test-1-1-1",
  "amount" : "500.00",
  "language" : "it",
  "status" : "pending",
  "created" : "2024-05-09T09:41:17+02:00"
}

http POST https://api.nic.it/v1/payments/creditCard/transactions \
    "Authorization: Bearer token..." \
    --raw \
    '{
      "language" : "it",
      "amount" : 500,
      "redirectSuccessUrl" : "http://success.url",
      "redirectFailureUrl" : "http://failure.url"
    }`

{
  "id" : "cdc8555b-2cca-4f7f-ae80",
  "gatewayId" : "test-1-1-1",
  "amount" : "500.00",
  "language" : "it",
  "status" : "pending",
  "created" : "2024-05-09T09:41:17+02:00"
}

Get the credit card payment data

1.0 | billing | admin / billing |

GET https://api.nic.it/v1/payments/creditCard/transactions/{transactionId}

You can get credit card transaction data by id as in the following example:

HTTPcURLHTTPie

GET /v1/payments/creditCard/transactions/cdc8555b-2cca-4f7f-ae80 HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token....

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id" : "cdc8555b-2cca-4f7f-ae80 ",
  "gatewayId" : "trn-2",
  "amount" : "500.00",
  "language" : "it",
  "status" : "approved",
  "paymentId": 1234,
  "response" : {
    "description" : "TRANSAZIONE OK",
    "creditCard" : {
      "brand" : "ANY",
      "number" : "4111********1111",
      "expire" : "04/27",
      "name" : "Giulio Cesare"
    }
  },
  "created" : "2024-05-09T09:41:17+02:00"
}

curl https://api.nic.it/v1/payments/creditCard/transactions/cdc8555b-2cca-4f7f-ae80 \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
    "id" : "cdc8555b-2cca-4f7f-ae80 ",
    "gatewayId" : "trn-2",
    "amount" : "500.00",
    "language" : "it",
    "status" : "approved",
    "paymentId": 1234,
    "response" : {
        "description" : "TRANSAZIONE OK",
        "creditCard" : {
            "brand" : "ANY",
            "number" : "4111********1111",
            "expire" : "04/27",
            "name" : "Giulio Cesare"
        }
    },
    "created" : "2024-05-09T09:41:17+02:00"
}

http https://api.nic.it/v1/payments/creditCard/transactions/cdc8555b-2cca-4f7f-ae80 \
    "Authorization: Bearer token..."

{
    "id" : "cdc8555b-2cca-4f7f-ae80 ",
    "gatewayId" : "trn-2",
    "amount" : "500.00",
    "language" : "it",
    "status" : "approved",
    "paymentId": 1234,
    "response" : {
        "description" : "TRANSAZIONE OK",
        "creditCard" : {
            "brand" : "ANY",
            "number" : "4111********1111",
            "expire" : "04/27",
            "name" : "Giulio Cesare"
        }
    },
    "created" : "2024-05-09T09:41:17+02:00"
}

Info

The example above is for a successful credit card transaction. For unsuccessful transactions, there is no response section.

Invoices

Get an invoice by id

1.0 | billing | admin / billing |

GET https://api.nic.it/v1/invoices/{invoiceId}

You can get invoice data by id as in the following example:

HTTPcURLHTTPie

GET /v1/invoices/1 HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token....

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id" : 1,
  "fiscalYear" : 2023,
  "invoiceNumber" : 10,
  "totalAmount" : 1000.0,
  "taxAmount" : 220.0,
  "taxRate" : "22%",
  "invoiceDate" : "2023-12-11"
}

curl https://api.nic.it/v1/invoices/1 \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "id" : 1,
  "fiscalYear" : 2023,
  "invoiceNumber" : 10,
  "totalAmount" : 1000.0,
  "taxAmount" : 220.0,
  "taxRate" : "22%",
  "invoiceDate" : "2023-12-11"
}

http https://api.nic.it/v1/invoices/1 \
    "Authorization: Bearer token..."

{
  "id" : 1,
  "fiscalYear" : 2023,
  "invoiceNumber" : 10,
  "totalAmount" : 1000.0,
  "taxAmount" : 220.0,
  "taxRate" : "22%",
  "invoiceDate" : "2023-12-11"
}

Info

The invoice id used to retrieve the data is not the invoice number generated by the accounting system

Search for invoices

1.0 | billing | admin / billing |

GET https://api.nic.it/v1/invoices

It is possible to search for invoices generated for the Registrar using multiple search parameters and several operators (advanced search).

Below is the list of parameters and operators available for searching for invoices:

Parameter	Type	Cardinality	Description	Supported operators	Default operator
invoiceNumber	Number	Single	Invoice number	eq, ne, in, notIn	eq
totalAmount	Number	Single	Total invoice amount	eq, ne, gt, lt, ge, le, between, in, notIn	eq
invoiceDate	DateTime	Multiple	Invoice date	eq, ne, gt, lt, ge, le, between	eq
paymentId	Number	Single	Id of linked payment	eq, ne, in, notIn	eq

Example of s search for invoices with the total amount of at least 500 Euros (totalAmount=ge:500):

HTTPcURLHTTPie

GET /v1/invoices?totalAmount=ge:500 HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token....

HTTP/1.1 200 OK
Content-Type: application/json

{
  "elements" : [ {
    "id" : 1,
    "fiscalYear" : 2023,
    "invoiceNumber" : 10,
    "totalAmount" : 1000.0,
    "taxAmount" : 220.0,
    "taxRate" : "22%",
    "invoiceDate" : "2023-12-11"
  } ],
  "page" : {
    "number" : 0,
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1
  }
}

curl "https://api.nic.it/v1/invoices?totalAmount=ge:500" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "elements" : [ {
    "id" : 1,
    "fiscalYear" : 2023,
    "invoiceNumber" : 10,
    "totalAmount" : 1000.0,
    "taxAmount" : 220.0,
    "taxRate" : "22%",
    "invoiceDate" : "2023-12-11"
  } ],
  "page" : {
    "number" : 0,
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1
  }
}

http https://api.nic.it/v1/invoices \
    "Authorization: Bearer token..." \
    totalAmount==ge:500

{
  "elements" : [ {
    "id" : 1,
    "fiscalYear" : 2023,
    "invoiceNumber" : 10,
    "totalAmount" : 1000.0,
    "taxAmount" : 220.0,
    "taxRate" : "22%",
    "invoiceDate" : "2023-12-11"
  } ],
  "page" : {
    "number" : 0,
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1
  }
}

Search results are paginated.

Get a invoice PDF

1.0 | billing | admin / billing |

GET https://api.nic.it/v1/invoices/{invoiceId}/pdf

You can retrieve the PDF (if available) of an invoice as in the following example:

HTTPcURLHTTPie

GET /v1/invoices/1/pdf HTTP/1.1
Accept: application/pdf
Host: api.nic.it
Authorization: Bearer token....

HTTP/1.1 200 OK
Content-Type: application/pdf

<PDF CONTENT>

curl --output invoice.pdf "https://api.nic.it/v1/invoices/1/pdf" \
-H "Accept: application/pdf" \
-H "Authorization: Bearer token..."

http --download https://api.nic.it/v1/invoices/1/pdf \
    "Accept: application/pdf" \
    "Authorization: Bearer token..."

PDF invoice availability check

1.0 | billing | admin / billing |

HEAD https://api.nic.it/v1/invoices/{invoiceId}/pdf

The following example is used to check whether the PDF of an invoice is available (HTTP 200) or not (HTTP 404):

HTTPcURLHTTPie

HEAD /v1/invoices/1/pdf HTTP/1.1
Host: api.nic.it
Authorization: Bearer token....

HTTP/1.1 200 OK

curl --head https://api.nic.it/v1/invoices/1/pdf \
    -H "Authorization: Bearer token..."

http HEAD https://api.nic.it/v1/invoices/1/pdf "Authorization: Bearer token..."

Get payment linked to an invoice

1.0 | billing | admin / billing |

GET https://api.nic.it/v1/invoices/{invoiceId}/payment

You can get the payment linked to the invoice as in the following example:

HTTPcURLHTTPie

GET /v1/invoices/1212/payment HTTP/1.1
Accept: application/json
Host: api.nic.it
Authorization: Bearer token....

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id" : 5,
  "amount" : 1000.0,
  "debitedAmount" : 250.0,
  "type" : "creditCard",
  "status" : "approved",
  "statusDate" : "2023-02-15T15:11:00+01:00",
  "lastupdate" : "2023-02-15T15:11:00+01:00",
  "created" : "2023-02-15T15:11:00+01:00",
  "creditCardTransaction" : {
    "transactionId" : "trn123",
    "service" : "phey"
  }
}

curl "https://api.nic.it/v1/invoices/1212/payment" \
-H "Accept: application/json" \
-H "Authorization: Bearer token..."

{
  "id" : 5,
  "amount" : 1000.0,
  "debitedAmount" : 250.0,
  "type" : "creditCard",
  "status" : "approved",
  "statusDate" : "2023-02-15T15:11:00+01:00",
  "lastupdate" : "2023-02-15T15:11:00+01:00",
  "created" : "2023-02-15T15:11:00+01:00",
  "creditCardTransaction" : {
    "transactionId" : "trn123",
    "service" : "phey"
  }
}

http https://api.nic.it/v1/invoices/1212/payment \
    "Authorization: Bearer token..."

{
  "id" : 5,
  "amount" : 1000.0,
  "debitedAmount" : 250.0,
  "type" : "creditCard",
  "status" : "approved",
  "statusDate" : "2023-02-15T15:11:00+01:00",
  "lastupdate" : "2023-02-15T15:11:00+01:00",
  "created" : "2023-02-15T15:11:00+01:00",
  "creditCardTransaction" : {
    "transactionId" : "trn123",
    "service" : "phey"
  }
}