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 in csv format containing the files sent to PagoPA in the last 15 days.
Description | API | Method | Required Headers |
Get File Report | rtd/file-reporter/file-report | GET | Ocp-Apim-Subscription-Key |
Returned value:
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
Notes
Sender_Code is a fixed value equal to Acquirer Abi or a code assigned by PagoPA
output file must contain the following columns in reported order
Sender_Code
Operation_type
Transmission_date
Operation_date (accounting date)
Transaction number (number of transactions)
Total_amount
Currency
Acquirer_id
Merchant_id
Terminal_id
Fiscal_code
VAT
Pos_type
If VAT is null or not unique in the aggregate record, use the following placeholder string: ###na###
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:
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
Example:
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
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:
Step 10
Upload each encrypted chunk
Description | API | Method | Required Headers |
---|---|---|---|
Upload Encrypted Chunk | PUT |
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 | GET | Ocp-Apim-Subscription-Key |
Returned value:
Step 15
Download each ADE ack contained in list returned in Step 14.
Description | API | Method | Required Headers |
---|---|---|---|
Download a single ACK | 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 | 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.
Last updated