Api Integration

describe the api integration

Functional view

Dynamic View

Protocols

Communication between Acquirer/Sender domain and PagoPa takes place through HTTPS (RestFul API) and is authorized by

• an API Key

• a client certificate

APIs are available under the base uri https://api.cstar.pagopa.it

Step 1

Get a file report containing the files sent to PagoPA in the last 15 days.

Description	API	Method	Required Headers	Format
Get File Report (Deprecated)	rtd/file-reporter/file-report	GET	Ocp-Apim-Subscription-Key	CSV
Get File Report v2	rtd/file-reporter/v2/file-report	GET	Ocp-Apim-Subscription-Key	JSON

Returned value Get File Report (Deprecated) :

 {
    "filesRecentlyUploaded": [
        {
            "name": file_name_pgp,
            "size": file_size,
            "status": "SENT_TO_AGENZIA_DELLE_ENTRATE",
            "transmissionDate": "2023-01-09T09:11:25.316"
        },
        {
            "name": file_name_pgp,
            "size": file_size,
            "status": "SENT_TO_AGENZIA_DELLE_ENTRATE",
            "transmissionDate": "2023-01-05T16:54:16.545"
        }
    ]
}    

Returned value Get File Report v2 :

{
    "filesRecentlyUploaded": [
        {
            "name": file_name_pgp,
            "size": file_size,
            "status": "SENT_TO_AGENZIA_DELLE_ENTRATE",
            "transmissionDate": "2024-05-04T09:11:25.316"
            "dataSummary":{
                "minAccountingDate": "2024-04-30",
                "maxAccountingDate": "2024-05-03",
                "numberOfMerchants": 8,
                "countNegativeTransactions": 5,
                "countPositiveTransactions": 28,
                "sumAmountNegativeTransactions": 585069,
                "sumAmountPositiveTransactions": 8231489,
                "sha256OriginFile": "#sha256sum:8301c8df0a760e8e688086dsdsde243r436d81851901c08f83d92aa3867a833d2"
            }
        }, 
        {
            "name": file_name_pgp,
            "size": file_size,
            "status": "SENT_TO_AGENZIA_DELLE_ENTRATE",
            "transmissionDate": "2024-07-04T09:11:25.316"
            "dataSummary":{
                "minAccountingDate": "2024-06-30",
                "maxAccountingDate": "2024-07-03",
                "numberOfMerchants": 12,
                "countNegativeTransactions": 53,
                "countPositiveTransactions": 238,
                "sumAmountNegativeTransactions": 32343242,
                "sumAmountPositiveTransactions": 3423423432423,
                "sha256OriginFile": "#sha256sum:8301c8df0a7604342488086dsdsde243r436d81851901c08f83d92aa3867a833d2"
            }
        }
    ]
}   

Order	Possible step	Description
1	RECEIVED_BY_PAGOPA	The file has been sent and received by PagoPA
2	VALIDATED_BY_PAGOPA	The file is formally correct and validated
3	SENT_TO_AGENZIA_DELLE_ENTRATE	The file has been sent to AdE

Step 2

Description	API	Method	Required Headers
Get PagoPA Public Key	rtd/csv-transaction/publickey	GET	User-Agent Ocp-Apim-Subscription-Key

Notes

User-Agent must be set to custom_integration

Step 3

A file containing daily electronic transactions must be available in the standard PagoPA format documented here.

Step 4

Compute a sha256sum of the Transactions File, it must be sent to PagoPA to detect duplicates.

Note:

You can skip steps 3 and 4 just using this placeholder string: “#sha256sum:0000000000000000000000000000000000000000000000000000000000000000”

Step 5

Aggregate transactions to compute the total amount and total number of transactions settled on each terminal. In order to clarify and better specify the aggregation condition, let’s imagine that the Transaction File is a SQL table named acquirer_transaction. The output file should contain the result of the following SQL query

SELECT
  Sender_Code, 
  Operation_type,
  Transmission_date, 
  Operation_date (AccountigDate), 
  COUNT(*) AS Transaction number, 
  SUM(total_amount) AS Total_amount,
  Currency (fixed value 978 = EUR), 
  Acquirer_id, 
  Merchant_id, 
  Terminal_id, 
  Fiscal_code, 
  VAT, 
  Pos_type
  FROM acquirer_transactions
GROUP BY (
  Acquirer_id,
  Fiscal_code,
  Terminal_id,
  Merchant_id,
  Operation_type  ,
  DATE_PART('YYYY-MM-DD', date_time),
  Transmission_date,
  Currency,
  VAT,
  Pos_type
)

Notes

1. Sender_Code is a fixed value equal to Acquirer Abi or a code assigned by PagoPA

2. output file must contain the following columns in reported order

   1. Sender_Code

   2. Operation_type

   3. Transmission_date

   4. Operation_date (accounting date)

   5. Transaction number (number of transactions)

   6. Total_amount

   7. Currency

   8. Acquirer_id

   9. Merchant_id

   10. Terminal_id

   11. Fiscal_code

   12. VAT

   13. Pos_type

3. If VAT is null or not unique in the aggregate record, use the following placeholder string: ###na###

4. Aggregates must be summed according to operation_type, this means that for each day there may be 2 aggregates for the same POS: one for the payments and one for the reversal/reimbursement

Step 6

Each file submitted must have a unique name compared to all the previous ones.

If aggregate file is too large (> 2 millions rows), split it in chunks of 2 millions rows. Identify each chunk with a two digit sequential number - starting from 01 - and use it in the last field of the filename.

The name must follow the following format:

ADE.[Sender Code].TRNLOG.[yyyymmdd].[hhmmss].[acquirer internal id].[chunk number].csv

Notes

• [acquirer internal id] is a 3 digit number left for acquirer internal purposes. If it’s not used, PagoPA expects it to be 001

Step 7

The sha256sum of the Transaction File computed in Step 3 must be added as first line of each chunk. The format must be the following

#sha256sum:[computed sha256sum]

Example:

#sha256sum:cf832e6bb27c719d4a784a9688b490540448cbaf888d23742deae60831f282de

Step 8

Each chunk must be encrypted using the PagoPA public key obtained in Step 1. The encryption must produce the same result as the following command run with gpg <=2.4.0

gpg --recipient 85286E3AC9C03C5B69AF61C589580E7CC3771ED4 --output ADE.T5555.TRNLOG.20220908.150818.001.01.csv.pgp --openpgp --encrypt ADE.T5555.TRNLOG.20220908.150818.001.01.csv

Output filename must end with .pgp.

Step 9

Encrypted chunks must be uploaded to a Blob Storage Container via RestFul API. In order to be authenticated a SaS Token must be obtained for granting to upload files.

Description	API	Method	Required Headers
Obtain Sas Token	rtd/csv-transaction/ade/sas	POST	Ocp-Apim-Subscription-Key

Returned value:

{
 "sas": "sas_token",
 "authorizedContainer": "container_name"
}

Step 10

Upload each encrypted chunk

Description	API	Method	Required Headers
Upload Encrypted Chunk	"/pagopastorage" + "/" + container_name + "/" + filename_to_upload + "?" + sas_token;	PUT	"x-ms-blob-type": "BlockBlob" "x-ms-version": "2021-08-06" “Content-type”: “application/octet-stream” "Ocp-Apim-Subscription-Key": <api key>

Returns

Description	Http Status Code
Chunk Uploaded	201
Chunk Exists	409

Step 14

Download list of ACKs returned by Agenzia delle Entrate. Note that acknowledge process is asynchronous, as a result files uploaded in Step 9 can’t be acknowledged immediately

Description	API	Method	Required Headers
Get List of Available ACKs	rtd/file-register/sender-ade-ack	GET	Ocp-Apim-Subscription-Key

Returned value:

{
  "fileNameList":[
    "fileName1",
    "fileName2"
  ]
}

Step 15

Download each ADE ack contained in list returned in Step 14.

Description	API	Method	Required Headers
Download a single ACK	/ade/{id}	GET	Ocp-Apim-Subscription-Key

id must be one of the file names returned in previous step.

The file format is described here.

Step 16

Inform PagoPA that the ack has been downloaded.

Description	API	Method	Required Headers
Acknowledge the ACK	/rtd/file-register/ack-received/{id}	PUT	Ocp-Apim-Subscription-Key

id must be one of the file names returned in Step 13.

API Swagger

You can explore API swagger on the developer portal, under the product: RTD_API_Product

Here is the list of the APIs you have to integrate:

• rtd/file-reporter/file-report

• rtd/csv-transaction/publickey

• rtd/csv-transaction/ade/sas

• /pagopastorage

• rtd/file-register/sender-ade-ack

• /ade/{id}

• /rtd/file-register/ack-received/{id}

The swaggers may be subject to minor changes, you will be notified before changes apply.