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

Column names must not be included as header.

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.

PreviousAppendix 11 - List of output and log filesNextGlossary

Last updated