Void a receipt

This tutorial demonstrates how to handle the voiding of a sale receipt.
You'll learn how to:

• Void a sale receipt issued by the same PEM you are operating from
• Void a sale receipt issued by a different PEM
• Void a sale receipt that hasn't been issued by a PEM

Prerequisites

Receipts can be issued only by a merchant or a cashier with a valid certificate (PEM file).

Case 1: Void a sale receipt issued by the same PEM

Since our goal is to void a sale receipt, we will first issue one from a cash register associated to the PEM E001-000001 and use it as reference:

Python

import requests

CERT_PATH = '/var/certs/pems/E001-000001/cr-cert.pem'
KEY_PATH = '/var/certs/pems/E001-000001/cr-key.pem'
response = requests.post(
    'https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipts',
    cert=(CERT_PATH, KEY_PATH),
    headers={
      "Authorization": "Bearer <Merchant JWT Token>",
      "Content-Type": "application/json"
    },
    json={
    "electronic_payment_amount": "122",
		"items": [
      {
        "type": "goods",
        "quantity": "1",
        "description": "Product",
        "unit_price": "122",
        "vat_rate_code": "22"
      }
    ]
  }
)

JavaScript

const fs = require('fs');
const https = require('https');

const CERT = fs.readFileSync('/var/certs/pems/E001-000001/cr-cert.pem')
const KEY = fs.readFileSync('/var/certs/pems/E001-000001/cr-key.pem')
const req = https.request(
  {
    hostname: 'ereceipts-it-sandbox.acubeapi.com',
    headers: {
      "Authorization": "Bearer <Merchant JWT Token>",
      "Content-Type": "application/json"
    },
    port: 444,
    path: '/mf1/receipts',
    method: 'POST',
    cert: CERT,
    key: KEY
  },
  res => {
    let body = '';
    res.on('data', function(data) {
      body += data;
    });
    res.on('end', function() {
      console.log(body);
    })
  }
);
req.write(JSON.stringify({
  "electronic_payment_amount": "122",
  "items": [
     {
        "type": "goods",
        "quantity": "1",
        "description": "Product",
        "unit_price": "122",
        "vat_rate_code": "22"
      }
  ]
}));
req.end();

Bash

curl -X POST https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipts  \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Merchant JWT Token>' \
-d '{"electronic_payment_amount":"122","items":[{"type":"goods","quantity":"1","description":"Product","unit_price":"122","vat_rate_code":"22"}]}' \
--cert /var/certs/pems/E001-000001/cr-cert.pem \
--key /var/certs/pems/E001-000001/cer-key.pem

PHP

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipts');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode('{
    "electronic_payment_amount": "122",
    "items": [
       {
        "type": "goods",
        "quantity": "1",
        "description": "Product",
        "unit_price": "122",
        "vat_rate_code": "22"
      }
    ]
}'));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type:application/json', 'Authorization:Bearer <Merchant JWT Token>']);
curl_setopt($ch, CURLOPT_SSLCERT, '/var/certs/pems/E001-000001/cr-cert.pem');
curl_setopt($ch, CURLOPT_SSLKEY, '/var/certs/pems/E001-000001/cr-key.pem');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
curl_close($ch);

You will receive a 201 status code and the following response body:

{
  "uuid": "18a681da-a868-47ba-a931-2f702474c3d1",
  "type": "sale",
  "total_amount": "122",
  "document_number": "0001-0001",
  "document_datetime": "2025-09-01T10:00:00",
  "parent_receipt_uuid": null,
  "is_voidable": true,
  "is_returnable": true,
  "pdf_url": "https://ereceipts-it-sandbox.acubeapi.com/mf1/receipts/18a681da-a868-47ba-a931-2f702474c3d1/pdf"
}

Now that we have a sale receipt, we can void it using a DELETE request on mf1/receipts since we are operating from the same PEM that issued it:

Python

import requests

CERT_PATH = '/var/certs/pems/E001-000001/cer-cert.pem'
KEY_PATH = '/var/certs/pems/E001-000001/cer-key.pem'
response = requests.delete(
    'https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipts',
    cert=(CERT_PATH, KEY_PATH),
    json={
      "document_number": "0001-0001"
    }
)

JavaScript

const fs = require('fs');
const https = require('https');

const CERT = fs.readFileSync('/var/certs/pems/E001-000001/cr-cert.pem')
const KEY = fs.readFileSync('/var/certs/pems/E001-000001/cr-key.pem')
const req = https.request(
  {
    hostname: 'ereceipts-it-sandbox.acubeapi.com',
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer <Merchant JWT Token>"
    },
    port: 444,
    path: '/mf1/receipts',
    method: 'DELETE',
    cert: CERT,
    key: KEY
  },
  res => {
    let body = '';
    res.on('data', function(data) {
      body += data;
    });
    res.on('end', function() {
      console.log(body);
    })
  }
);
req.write(JSON.stringify({
    "document_number": "0001-0001"
}));
req.end();

Bash

curl -X DELETE https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipts  \
-H 'Content-Type: application/json' \
-d '{"document_number":"0001-0001"}' \
--cert /var/certs/pems/E001-000001/cr-cert.pem \
--key /var/certs/pems/E001-000001/cr-key.pem

PHP

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipts');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode('{
    "document_number": "0001-0001"
}'));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type:application/json', 'Authorization:Bearer <Merchant JWT Token>']);
curl_setopt($ch, CURLOPT_SSLCERT, '/var/certs/pems/E001-000001/cr-cert.pem');
curl_setopt($ch, CURLOPT_SSLKEY, '/var/certs/pems/E001-000001/cr-key.pem');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
curl_close($ch);

The HTTP response will have status code 204 and no content.

Case 2: Void a sale receipt issued by a different device

To void a sale receipt that was issued by a different kind of device (i.e an RT or RT Server) or by a different PEM from the one currently in use, submit a DELETE request to the endpoint /mf1/receipts/void-via-different-device.
For example, to void a sale receipt originally issued by the PEM E001-000001 while operating from the PEM E001-000002, do as follows:

Python

import requests

CERT_PATH = '/var/certs/pems/E001-000002/cr-cert.pem'
KEY_PATH = '/var/certs/pems/E001-000002/cr-key.pem'
response = requests.delete(
    'https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipts/void-via-different-device',
    cert=(CERT_PATH, KEY_PATH),
    headers={
      "Authorization": "Bearer <Merchant JWT Token>",
      "Content-Type": "application/json"
    },
    json={
      "device_id": "E001-000001",
      "document_number": "0001-0001",
      "document_datetime": "2025-09-01T10:00",
      "items": [
        {
          "type": "goods",
          "quantity": "1",
          "description": "Product",
          "unit_price": "122",
          "vat_rate_code": "22"
        }
      ]
    }
)

JavaScript

const fs = require('fs');
const https = require('https');
const CERT = fs.readFileSync('/var/certs/pems/E001-000002/cr-cert.pem')
const KEY = fs.readFileSync('/var/certs/pems/E001-000002/cr-key.pem')
const req = https.request(
  {
    hostname: 'ereceipts-it-sandbox.acubeapi.com',
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer <Merchant JWT Token>"
    },
    port: 444,
    path: '/mf1/receipts/void-via-different-device',
    method: 'DELETE',
    cert: CERT,
    key: KEY
  },
  res => {
    let body = '';
    res.on('data', function(data) {
      body += data;
    });
    res.on('end', function() {
      console.log(body);
    })
  }
);
req.write(JSON.stringify({
    "device_id": "E001-000001",
    "document_number": "0001-0001",
    "document_datetime": "2025-09-01T10:00",
    "items": [
      {
        "type": "goods",
        "quantity": "1",
        "description": "Product",
        "unit_price": "122",
        "vat_rate_code": "22"
      }
    ]
}));
req.end();

Bash

curl -X DELETE https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipts/void-via-different-device  \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Merchant JWT Token>' \
-d '{"device_id": "E001-0001", "document_number":"0001-0001", "document_datetime": "2025-09-01T10:00", "items":[{"type":"goods","quantity":"1","description":"Product","unit_price":"122","vat_rate_code":"22"}]}' \
--cert /var/certs/pems/E001-000002/cashregister.pem \
--key /var/certs/pems/E001-000002/cashregister.pem

PHP

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipts/void-via-different-device');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode('{
    "device_id": "E001-0001",
    "document_number": "0001-0001",
    "document_datetime": "2025-09-01T10:00",
    "items": [
      {
        "type": "goods",
        "quantity": "1",
        "description": "Product",
        "unit_price": "122",
        "vat_rate_code": "22"
      }
    ]
}'));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type:application/json', 'Authorization:Bearer <Merchant JWT Token>']);
curl_setopt($ch, CURLOPT_SSLCERT, '/var/certs/pems/E001-000002/cr-cert.pem');
curl_setopt($ch, CURLOPT_SSLKEY, '/var/certs/pems/E001-000002/cr-key.pem');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
curl_close($ch);

The HTTP response will have status code 204 and no content.

Case 3: Void a sale receipt identified by othjer supporting evidence

In accordance with Circular 3/E of February 21, 2020, merchants are permitted to issue a cancellation receipt based on alternative supporting evidence that can verify the original purchase, such as a POS payment slip or returnable packaging ("Vuoti a Rendere"). In these scenarios, a document_number cannot be provided. To process a void under these conditions, submit a POST request to the /mf1/receipts/void-with-proof endpoint.

Python

import requests

CERT_PATH = '/var/certs/pems/E001-000001/cr-cert.pem'
KEY_PATH = '/var/certs/pems/E001-000001/cr-key.pem'
response = requests.post(
  'https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipts/void-with-proof',
  cert=(CERT_PATH, KEY_PATH),
  json= {
    "items": [
      {
        "type": "goods",
        "quantity": "1",
        "description": "Product",
        "unit_price": "122",
        "vat_rate_code": "22"
      }
    ],
    "proof": "POS",
    "document_datetime": "2025-09-01T10:00:00"
  }
)

JavaScript

const fs = require('fs');
const https = require('https');
const CERT = fs.readFileSync('/var/certs/pems/E001-000001/cr-cert.pem')
const KEY = fs.readFileSync('/var/certs/pems/E001-000001/cr-key.pem')
const req = https.request(
  {
    hostname: 'ereceipts-it-sandbox.acubeapi.com',
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer <Merchant JWT Token>"
    },
    port: 444,
    path: '/mf1/receipts/void-with-proof',
    method: 'POST',
    cert: CERT,
    key: KEY
  },
  res => {
    let body = '';
    res.on('data', function(data) {
      body += data;
    });
    res.on('end', function() {
      console.log(body);
    })
  }
);
req.write(JSON.stringify( {
    "items": [
      {
        "type": "goods",
        "quantity": "1",
        "description": "Product",
        "unit_price": "122",
        "vat_rate_code": "22"
      }
    ],
    "proof": "POS",
    "document_datetime": "2025-09-01T10:00:00"
}));
req.end();

Bash

curl -X POST https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipts/void-with-proof  \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Merchant JWT Token>' \
-d '{"items":[{"good_or_service":"B","quantity":"1","description":"Product","unit_price":"122","vat_rate_code":"22"}],"proof":"POS","document_datetime":"2025-09-01T10:00:00"}' \
--cert /var/certs/pems/E001-000001/cr-cert.pem \
--key /var/certs/pems/E001-000001/cr-key.pem

PHP

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://ereceipts-it-sandbox.acubeapi.com:444/mf1/receipts/void-with-proof');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode('{
    "items": [
      {
        "type": "goods",
        "quantity": "1",
        "description": "Product",
        "unit_price": "122",
        "vat_rate_code": "22"
      }
    ],
    "proof": "POS",
    "document_datetime": "2025-09-01T10:00:00"
}'));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type:application/json', 'Authorization:Bearer <Merchant JWT Token>']);
curl_setopt($ch, CURLOPT_SSLCERT, '/var/certs/pems/E001-000001/cr-cert.pem');
curl_setopt($ch, CURLOPT_SSLKEY, '/var/certs/pems/E001-000001/cr-key.pem');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
curl_close($ch);

info

the field proof can be set to one of "POS", "VR" (vuoti a rendere), or "ND" (non definito).