MAV Bill - Italy

The Bills service allows the integration of the payment service for the main types of bills via API:

MAV Bill

MAV is an acronym and stands for ‘Payment By Notice’. The MAV bulletin is a standardised interbank procedure, widely used for the settlement of debts, and generally involves the transfer of an amount from the collecting bank, i.e. the debtor's bank, to the redeeming bank, i.e. the creditor's bank.

The MAV mode is often used by public bodies and organisations such as universities to collect tuition fees.

This type of bulletin is characterised by the presence of a 17-digit numeric code that uniquely identifies the transaction and is essential for the creditor to correctly associate payments to the subjects. Together with the ID, fields such as debtor name, amount, reason and due date will be available.

The service consists of 3 endpoints that allow you to pay the bill, retrieve the list of requests made, and obtain the details of a specific payment request.

Pay Bill

The service in the request phase allows the bill payment form to be generated with the endpoint POST/pay/{endpoint}.

EXAMPLE REQUEST

The value ‘endpoint’ must be populated with the type of bill to be paid, in our case it will be MAV.

POST https://ws.pagasubito.it/pay/896

A series of values will need to be passed into the body of the request. These values depend on the type of bill to be paid. In the case of the MAV bill payment they will be:

This is an example of a payload for a request to pay the MAV bill.

{
  data{
    "email": "[email protected]",
    "tipo_veicolo": 2,
    "targa": "FE425LX",
    "callback": {
      "url": "https://your_domain.it/your_callback.php",
      "method": "POST",
      "field": "data",
      "headers": {
        "session_id": "oiwejdf89453urf945jfg"
      }
    }
  }

Remember that when making a request, it is also possible to set up a callback to get a response when the report with the final payment status is available.

EXAMPLE RESPONSE

The response will contain the request id and the link to the form to complete the request.

{
  data{
    "id": "6489ca34bf95b3541e0ccb25",
    "payment_url": "https://test.ws.pagasubito.it/payment/6489ca34bf95b3541e0ccb25"
  },
  "success": true,
  "message": "",
  "error": null
}

Payment receipt retrieval

EXAMPLE REQUEST

It is possible to obtain the receipt of a payment via endpoint GET/pay/{id}/ricevuta starting from the ID, i.e. the request identification code, available in the response after the payment request (POST/pay/{endpoint}), or retrievable from the response via the endpoint GET/pay.

GET https://ws.pagasubito.it/pay/{id}/ricevuta

EXAMPLE RESPONSE

The response will contain a pdf with the following information:

Access to payment list

EXAMPLE REQUEST

It is possible to obtain a list of all requests made via the endpoint GET/pay.

GET https://ws.pagasubito.it/pay/

EXAMPLE RESPONSE

The response will contain a list of the bulletins made with the request id, payment type, amount and timestamp (date of request).

{
  "data": [
    {
      "_id": "6481f66cf2129e73020e2e5d",
      "type": "pagopa",
      "importo": "0.00",
      "timestamp": "1686238828014"
    },
    {
      "_id": "6481f5cbd503bfa6cf061192",
      "type": "mav",
      "importo": "123.12",
     "timestamp":  "1686238667307"
    },
    {
      "_id": "6481f66cf2129e73020e2e5d",
      "type": "rav",
      "importo": "123.12",
      "timestamp": "1686238526070"
    },
    {
     "_id":  "6481f506b5fc59ab15049fe4",
      "type": "896",
     "importo":  "123.12",
     "timestamp":  "1686238470629"
    }
  ],
  "success": true,
  "message": "",
  "error": null
}

Specific payment retrieval with details

EXAMPLE REQUEST

It is possible to obtain information on a single request made via the endpoint GET/pay/{id}, starting from the ID.

GET https://ws.pagasubito.it/pay/{id}

EXAMPLE RESPONSE

The response will contain information entered at the payment stage and details of the payment status.

{
  "data": [
    {
      "_id": "6481f66cf2129e73020e2e5d", 
	  "email": "[email protected]", 
	  "cognome": "", 
	  "nome": "",
	  "telefono": "", 
	  "ente_pa": "134553", 
	  "avviso_pa": "2489567", 
	  "type": "pagopa", 
	  "timestamp": "1686238526070",
	  "owner": "[email protected]",
	  
	  

The service provides its customers with a quick and easy way to pay the main bills and has been integrated into service portals, private post offices and large retail outlets for payment at checkouts.