bollettini.openapi.json

{"openapi":"3.0.0","info":{"description":"Web service that allows you to pay bills, mav, rav, pago pa and car tax.","version":"1.0.0","title":"Bollettini","termsOfService":"https://openapi.it/en/terms-and-conditions","contact":{"url":"https://openapi.it/en/support","name":"Support"},"license":{"name":"Apache 2.0","url":"http://www.apache.org/licenses/LICENSE-2.0.html"}},"servers":[{"url":"https://ws.pagasubito.it","description":"Production"},{"url":"https://test.ws.pagasubito.it","description":"Sandbox"}],"tags":[{"name":"Pay","description":"Methods for handling payments"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"BodyPost896":{"type":"object","properties":{"email":{"type":"string","description":"customer email","format":"email"},"cognome":{"type":"string","description":"customer last name"},"nome":{"type":"string","description":"customer first name"},"indirizzo":{"type":"string","description":"customer address"},"telefono":{"type":"string","description":"customer phone"},"importo":{"type":"number","description":"amount to be paid","maximum":2496.99},"cap":{"type":"string","description":"customer zip code","maxLength":5},"localita":{"type":"string","description":"customer town"},"provincia":{"type":"string","description":"customer province","maxLength":2},"ccp":{"type":"string","description":"postal account","maxLength":12},"codice_bollettino":{"type":"string","description":"postal order code","minLength":18,"maxLength":18},"callback":{"$ref":"#/components/schemas/Callback"}},"required":["email","importo","ccp","codice_bollettino"]},"BodyPostRav":{"type":"object","properties":{"email":{"type":"string","description":"customer email","format":"email"},"telefono":{"type":"string","description":"customer phone"},"importo":{"type":"number","description":"amount to be paid","maximum":2496.99},"codice_rav":{"type":"string","description":"rav code","maxLength":18,"minLength":17},"callback":{"$ref":"#/components/schemas/Callback"}},"required":["email","importo","codice_rav"]},"BodyPostMav":{"type":"object","properties":{"email":{"type":"string","description":"customer email","format":"email"},"telefono":{"type":"string","description":"customer phone"},"importo":{"type":"number","description":"amount to be paid","maximum":2496.99},"codice_mav":{"type":"string","description":"mav code","maxLength":18,"minLength":17},"callback":{"$ref":"#/components/schemas/Callback"}},"required":["email","importo","codice_mav"]},"BodyPostPagopa":{"type":"object","properties":{"email":{"type":"string","description":"customer email","format":"email"},"cognome":{"type":"string","description":"customer last name"},"nome":{"type":"string","description":"customer first name"},"telefono":{"type":"string","description":"customer phone"},"ente_pa":{"type":"string","description":"public administration body code"},"avviso_pa":{"type":"string","description":"public administration notice code"},"callback":{"$ref":"#/components/schemas/Callback"}},"required":["email","importo","ente_pa","avviso_pa"]},"BodyPostBolloauto":{"type":"object","properties":{"email":{"type":"string","description":"customer email","format":"email"},"cognome":{"type":"string","description":"customer last name"},"nome":{"type":"string","description":"customer first name"},"telefono":{"type":"string","description":"customer phone"},"tipo_veicolo":{"type":"string","description":"vehicle type: 1 - Cars; 2 - Trailers; 3 - Motorcycle","enum":["1","2","4"]},"targa":{"type":"string","description":"vehicle license plate"},"callback":{"$ref":"#/components/schemas/Callback"}},"required":["email","importo","ente_pa","tipo_veicolo","targa"]},"Get":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"importo":{"type":"string"},"timestamp":{"type":"string"}}},"Get896":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"cognome":{"type":"string"},"nome":{"type":"string"},"cap":{"type":"string"},"provincia":{"type":"string"},"localita":{"type":"string"},"indirizzo":{"type":"string"},"telefono":{"type":"string"},"ccp":{"type":"string"},"codice_bollettino":{"type":"string"},"causale":{"type":"string"},"type":{"type":"string"},"importo":{"type":"string"},"timestamp":{"type":"string"},"owner":{"type":"string"},"callback":{"$ref":"#/components/schemas/Callback"},"report":{"type":"object","properties":{"payment_status":{"type":"string"},"payment_id":{"type":"string"},"email":{"type":"string"},"payment_date":{"type":"string"},"total_amount":{"type":"string"},"ccp":{"type":"string"},"bulletin_type":{"type":"string"},"causal":{"type":"string"},"operation_id":{"type":"string"},"code":{"type":"string"}}}}},"Getmav-rav":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"telefono":{"type":"string"},"mav":{"type":"string"},"rav":{"type":"string"},"type":{"type":"string"},"importo":{"type":"string"},"timestamp":{"type":"string"},"owner":{"type":"string"},"callback":{"$ref":"#/components/schemas/Callback"},"report":{"type":"object","properties":{"payment_status":{"type":"string"},"payment_id":{"type":"string"},"email":{"type":"string"},"payment_date":{"type":"string"},"total_amount":{"type":"string"},"ccp":{"type":"string"},"bulletin_type":{"type":"string"},"causal":{"type":"string"},"operation_id":{"type":"string"},"code":{"type":"string"}}}}},"Getpagopa":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"importo":{"type":"string"},"cognome":{"type":"string"},"nome":{"type":"string"},"telefono":{"type":"string"},"avviso_pa":{"type":"string"},"ente_pa":{"type":"string"},"type":{"type":"string"},"timestamp":{"type":"string"},"owner":{"type":"string"},"callback":{"$ref":"#/components/schemas/Callback"},"report":{"type":"object","properties":{"payment_status":{"type":"string"},"payment_id":{"type":"string"},"email":{"type":"string"},"payment_date":{"type":"string"},"total_amount":{"type":"string"},"ente_pa":{"type":"string"},"avviso_pa":{"type":"string"}}}}},"Getbolloauto":{"type":"object","properties":{"_id":{"type":"string"},"email":{"type":"string"},"importo":{"type":"string"},"cognome":{"type":"string"},"nome":{"type":"string"},"telefono":{"type":"string"},"tipo_veicolo":{"type":"string"},"targa":{"type":"string"},"type":{"type":"string"},"timestamp":{"type":"string"},"owner":{"type":"string"},"callback":{"$ref":"#/components/schemas/Callback"},"report":{"type":"object","properties":{"payment_status":{"type":"string"},"payment_id":{"type":"string"},"email":{"type":"string"},"payment_date":{"type":"string"},"total_amount":{"type":"string"},"tipo_veicolo":{"type":"string"},"targa":{"type":"string"},"pagatore":{"type":"string"}}}}},"Callback":{"type":"object","properties":{"method":{"type":"string","description":"Indicate through which method you want to receive data with the callback, by default it is POST","enum":["POST","JSON"]},"field":{"type":"string","description":"Name of the field containing the callback return data (required with method: POST)"},"url":{"type":"string","description":"Url where the callback call will be made","example":"https://www.mysite.it/callback.php"},"headers":{"type":"object","properties":{"key":{"type":"string"}},"description":"contains key:value strings that you want to arrive as headers","example":{"session_id":"9834r5fh589494"}},"data":{"type":"object","description":"Object to be completed at your convenience with additional data that you can use back with the callback"}}}}},"paths":{"/pay/{endpoint}":{"post":{"tags":["Pay"],"summary":"Bill payment request","description":"Method that allows you to request a payment. The result will be a url that will redirect you to the payment portal.","parameters":[{"in":"path","name":"endpoint","required":true,"schema":{"enum":[896,"rav","mav","pagopa","bolloauto"]},"description":"Type of service requested"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BodyPost896"},{"$ref":"#/components/schemas/BodyPostRav"},{"$ref":"#/components/schemas/BodyPostMav"},{"$ref":"#/components/schemas/BodyPostPagopa"},{"$ref":"#/components/schemas/BodyPostBolloauto"}]},"examples":{"896":{"value":{"email":"email@prova.com","importo":123.12,"ccp":"35456","codice_bollettino":"123445543434677780","callback":{"url":"https://your_domain.it/your_callback.php","method":"POST","field":"data","headers":{"session_id":"oiwejdf89453urf945jfg"}}}},"rav":{"value":{"email":"email@prova.com","importo":123.12,"codice_rav":"12121212121212120","callback":{"url":"https://your_domain.it/your_callback.php","method":"POST","field":"data","headers":{"session_id":"oiwejdf89453urf945jfg"}}}},"mav":{"value":{"email":"email@prova.com","importo":123.12,"codice_mav":"12121212121212120","callback":{"url":"https://your_domain.it/your_callback.php","method":"POST","field":"data","headers":{"session_id":"oiwejdf89453urf945jfg"}}}},"pagopa":{"value":{"email":"email@prova.com","ente_pa":"435341","avviso_pa":"2349843895","callback":{"url":"https://your_domain.it/your_callback.php","method":"POST","field":"data","headers":{"session_id":"oiwejdf89453urf945jfg"}}}},"bolloauto":{"value":{"email":"email@prova.com","tipo_veicolo":"2","targa":"TH67DX","callback":{"url":"https://your_domain.it/your_callback.php","method":"POST","field":"data","headers":{"session_id":"oiwejdf89453urf945jfg"}}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"payment_url":{"type":"string"}}},"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"integer"}}},"example":{"data":{"id":"6489ca34bf95b3541e0ccb25","payment_url":"https://test.ws.pagasubito.it/payment/6489ca34bf95b3541e0ccb25"},"success":true,"message":"","error":null}}}},"400":{"description":"Bad Request","content":{"application/json":{"example":{"success":false,"message":"you have not specified the type of payment","error":200,"data":null}}}},"404":{"description":"Not Found","content":{"application/json":{"example":{"success":false,"message":"non-existent type of payment:{endpoint}","error":201,"data":null}}}},"406":{"description":"Not Acceptable","content":{"application/json":{"examples":{"emails":{"value":{"success":false,"message":"email is considered invalid!","error":203,"data":null}},"telefono":{"value":{"success":false,"message":"telefono can only take numeric values!","error":204,"data":null}},"importo(numeric)":{"value":{"success":false,"message":"importo can only take numeric values!","error":206,"data":null}},"importo(formatted)":{"value":{"success":false,"message":"importo not properly formatted: E.G. 15.00","error":207,"data":null}},"cap(numeric)":{"value":{"success":false,"message":"cap can only take numeric values!","error":209,"data":null}},"cap(length)":{"value":{"success":false,"message":"cap consists of 5 values!","error":210,"data":null}},"provincia(length)":{"value":{"success":false,"message":"provincia consists of 2 values!","error":211,"data":null}},"ccp":{"value":{"success":false,"message":"ccp can only take numeric values!","error":213,"data":null}},"ccp(length)":{"value":{"success":false,"message":"ccp is 12 digits maximum!","error":214,"data":null}},"codice_bollettino(numeric)":{"value":{"success":false,"message":"codice_bollettino can only take numeric values!","error":216,"data":null}},"codice_bollettino(length)":{"value":{"success":false,"message":"codice_bollettino consists of 18 values!","error":217,"data":null}},"codice_mav(numeric)":{"value":{"success":false,"message":"codice_mav can only take numeric values!","error":220,"data":null}},"codice_mav(length)":{"value":{"success":false,"message":"codice_mav consists of 17 or 18 values!","error":221,"data":null}},"codice_rav(numeric)":{"value":{"success":false,"message":"codice_rav can only take numeric values!","error":223,"data":null}},"codice_rav(length)":{"value":{"success":false,"message":"codice_rav consists of 17 or 18 values!","error":224,"data":null}},"ente_pa":{"value":{"success":false,"message":"ente_pa can only take numeric values!","error":226,"data":null}},"avviso_pa":{"value":{"success":false,"message":"avviso_pa can only take numeric values!","error":228,"data":null}},"tipo_veicolo":{"value":{"success":false,"message":"tipo_veicolo can only take one of this three values: 1, 2, 4!","error":"230  231","data":null}},"targa":{"value":{"success":false,"message":"targa required!","error":232,"data":null}},"callback_length":{"value":{"success":false,"message":"exceeded maximum length (16 kb) of the callback: 17867","error":300,"data":null}},"callback_method":{"value":{"success":false,"message":"method = JSON, field is not required","error":302,"data":null}},"callback_url_1":{"value":{"success":false,"message":"malformed url in 'callback'","error":304,"data":null}},"callback_url_2":{"value":{"success":false,"message":"required http or https","error":305,"data":null}},"callback_headers_1":{"value":{"success":false,"message":"headers not valid, must be an object with key : value","error":307,"data":null}},"callback_headers_2":{"value":{"success":false,"message":"exceeded maximum length (256 chr) of the key: ","error":308,"data":null}},"callback_headers_3":{"value":{"success":false,"message":"the value of 'test' must be a string","error":309,"data":null}},"callback_headers_4":{"value":{"success":false,"message":"exceeded maximum length (2 kb) of the headers: 3314","error":310,"data":null}}}}}},"428":{"description":"Precondition Required","content":{"application/json":{"examples":{"emails":{"value":{"success":false,"message":"email required!","error":202,"data":null}},"importo":{"value":{"success":false,"message":"importo required!","error":205,"data":null}},"ccp":{"value":{"success":false,"message":"ccp required!","error":212,"data":null}},"codice_bollettino":{"value":{"success":false,"message":"codice_bollettino required!","error":215,"data":null}},"causale":{"value":{"success":false,"message":"causale required!","error":218,"data":null}},"codice_mav":{"value":{"success":false,"message":"codice_mav required!","error":219,"data":null}},"codice_rav":{"value":{"success":false,"message":"codice_rav required!","error":222,"data":null}},"ente_pa":{"value":{"success":false,"message":"ente_pa required!","error":225,"data":null}},"avviso_pa":{"value":{"success":false,"message":"avviso_pa required!","error":227,"data":null}},"tipo_veicolo":{"value":{"success":false,"message":"tipo_veicolo required!","error":229,"data":null}},"targa":{"value":{"success":false,"message":"targa required!","error":232,"data":null}},"callback_method":{"value":{"success":false,"message":"method = POST and field not set in 'callback', required","error":301,"data":null}},"callback_url":{"value":{"success":false,"message":"url not set in 'callback', required","error":303,"data":null}},"callback_headers":{"value":{"success":false,"message":"object headers not set in 'callback', required","error":306,"data":null}}}}}}}}},"/pay/":{"get":{"tags":["Pay"],"summary":"All request","description":"Method that allows you to see all your payment requests.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Get"},"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"integer"}}},"example":{"data":[{"id":"6481f66cf2129e73020e2e5d","type":"pagopa","importo":"","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}}}},"404":{"description":"Not Found","content":{"application/json":{"example":{"success":false,"message":"no payments in database","error":233,"data":null}}}}}}},"/pay/{id}":{"get":{"tags":["Pay"],"summary":"Single request","description":"Method that allows you to see the single request identified by the id. The 'report' field is entered only after finalizing the payment and contains data on the outcome of the payment.","parameters":[{"name":"id","in":"path","description":"Request id","required":true,"schema":{"type":"string","example":"64772d88496e98e849017aa8"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"oneOf":[{"$ref":"#/components/schemas/Get896"},{"$ref":"#/components/schemas/Getmav-rav"},{"$ref":"#/components/schemas/Getpagopa"},{"$ref":"#/components/schemas/Getbolloauto"}]},"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"integer"}}},"examples":{"896":{"value":{"data":{"id":"6481f506b5fc59ab15049fe4","email":"email@prova.com","cognome":"","nome":"","indirizzo":"","cap":"","localita":"","provincia":"","telefono":"","importo":"12312","ccp":"12345","causale":"","type":896,"timestamp":"1686238470629","owner":"useremail@prova.com","codice_bollettino":"123445543434677780","callback":{"url":"https://your_domain.it/your_callback.php","headers":{"session_id":"9834thjf9fhj8907yf4"},"method":"POST","field":"data","data":{}},"report":{"payment_status":"OK","payment_id":"12020000340229","email":"useremail@prova.com","payment_date":"2020-04-06 17:23:10","total_amount":"126.12","ccp":"12345","bulletin_type":"896","causal":"exemple causal","operation_id":"111111","code":"123445543434677780"}},"success":true,"message":"","error":null}},"mav":{"value":{"data":[{"id":"6481f5cbd503bfa6cf061192","email":"email@prova.com","telefono":"","importo":"12312","codice_mav":"12121212121212120","causale":"","type":"mav","timestamp":"1686238667307","owner":"useremail@prova.com","codice_rav":"","callback":null,"report":{"payment_status":"OK","payment_id":"12020000340229","email":"useremail@prova.com","payment_date":"2020-04-06 17:23:10","total_amount":"126.12","ccp":"","bulletin_type":"MAV","causal":"","operation_id":"111111","code":""}}],"success":true,"message":"","error":null}},"rav":{"value":{"data":[{"id":"6481f53e0ca1fc214d0258c2","email":"email@prova.com","telefono":"","importo":"12312","codice_mav":"","causale":"","type":"rav","timestamp":"1686238526070","owner":"useremail@prova.com","codice_rav":"12121212121212120","callback":{"url":"https://your_domain.it/your_callback.php","headers":{"session_id":"9834thjf9fhj8907yf4"},"method":"POST","field":"data","data":{}},"report":{"payment_status":"OK","payment_id":"12020000340229","email":"useremail@prova.com","payment_date":"2020-04-06 17:23:10","total_amount":"126.12","ccp":"","bulletin_type":"RAV","causal":"","operation_id":"111111","code":""}}],"success":true,"message":"","error":null}},"pagopa":{"value":{"data":[{"id":"6481f66cf2129e73020e2e5d","email":"email@prova.com","importo":"","cognome":"","nome":"","telefono":"","ente_pa":"134553","avviso_pa":"2489567","type":"pagopa","timestamp":"1686238526070","owner":"useremail@prova.com","callback":{"url":"https://your_domain.it/your_callback.php","headers":{"session_id":"9834thjf9fhj8907yf4"},"method":"POST","field":"data","data":{}},"report":{"payment_status":"OK","payment_id":"12020000340229","email":"useremail@prova.com","payment_date":"2020-04-06 17:23:10","total_amount":"123.12","ente_pa":"134553","avviso_pa":"2489567"}}],"success":true,"message":"","error":null}},"bolloauto":{"value":{"data":[{"id":"6481a5751ca871c53c052bb8","email":"email@prova.com","importo":"","cognome":"","nome":"","telefono":"","tipo_veicolo":"2","targa":"24TY78","type":"bolloauto","timestamp":"1686218101888","owner":"useremail@prova.com","callback":null,"report":{"payment_status":"OK","payment_id":"12020000340229","email":"useremail@prova.com","payment_date":"2020-04-06 17:23:10","total_amount":"123.15","tipo_veicolo":"2","targa":"24TY78","pagatore":"Luca Rossi"}}],"success":true,"message":"","error":null}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"example":{"success":false,"message":"nvalid id","error":234,"data":null}}}},"404":{"description":"Not Found","content":{"application/json":{"example":{"success":false,"message":"no payment matches this id 6481f5cbd503bfa6cf061192","error":235,"data":null}}}}}}},"/pay/{id}/ricevuta":{"get":{"tags":["Pay"],"summary":"Get the receipt","description":"Method that allows you to download the receipt identified by the ID. If the receipt exists a pdf file is returned.","parameters":[{"name":"id","in":"path","description":"Request id","required":true,"schema":{"type":"string","example":"64772d88496e98e849017aa8"}}],"responses":{"200":{"description":"A PDF file","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Bad Request","content":{"application/json":{"example":{"success":false,"message":"invalid id","error":234,"data":null}}}},"404":{"description":"Not Found","content":{"application/json":{"example":{"success":false,"message":"no report matches this id 6481f5cbd503bfa6cf061192","error":237,"data":null}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"example":{"success":false,"message":"Service unreachable","error":236,"data":null}}}}}}}},"externalDocs":{"description":"First time here? Generate a new access token","url":"https://console.openapi.com/oauth"},"security":[{"bearerAuth":[]}]}