Skip to content

DropPay API - Payments v.3

PagoPA

With DropPay API you can verify and submit PagoPA payments orders.

PagoPA payment orders are issued by Italian public institutions toward citizens. For further informations please visit PagoPA web site.

When you commit a PagoPA payment order the authorised DropPay Account is charged with order amount and payment is processed by DropPay.

Warning

DropPay API uses English as main language but, to avoid a misleading translation of regional symbols and strings as they are shown on regional payment methods, rules, slips, forms, applications, and so on, we decided to mix-up the common DropPay API English lexicon with regional specific nouns, verbs and symbols.

PagoPA payment procedure explained

In order to get a payment order committed your application must perform the following steps:

  • Create a PagoPA Order (POST) using data retrieved from "Avviso di Pagamento"
  • Verify the data returned by DropPay are what your user is asked to pay
  • Commit the PagoPA Order (PATCH) to make DropPay prepare it for execution
  • Command DropPay to execute the PagoPA order

The diagram below shows the procedure from actors point of view.

sequenceDiagram
    participant Client
    participant PPA as DropPay PagoPa


    Client ->> PPA: Create a PagoPA Order (POST)
    PPA -->> Client: PagoPA Order

    Client ->> PPA: Update PagoPA Order (PATCH)
    PPA -->> Client: PagoPA Order

    Client ->> PPA: Execute PagoPA Order Disposition (POST)
    PPA -->> Client: PagoPA Order execution

The Payment Form

DropPay Payments API uses a base class object common to all methods: the form. From here on, we call form the resource that identifies the PagoPA order procedure.

A form is the resource's instance you create when initiating the payment procedure.

Form gets across different states, among which we list the followings ones:

DRAFT

When the Form is created with the first POST request. The PagoPA data are fetched from Nodo dei Pagamenti and populate the resource.

READY

When you want the form is been validated against account balance in order to finally execute it, you can PATCH the rest resource with this state value.

BOOKED

When you want the form is been validated against account balance in order to finally execute it, and you want the needed amount of money is been reserved for the fortcoming execution, you can PATCH the rest resource with this state value.

If you later need to free the booked money you can PATCH the form back to DRAFT.

Once the PagoPa form is successfully executed, further readings of it will return the final state of PAID

FAILED

Once the PagoPa form has been failure to be exceuted, further readings of it will return the final state of FAILED

Order processing without DropPay account instant charging

If your application and connected DropPay account are granted to complete the payment with funds trasferred by an other payment scheme (i.e. credit cards), you can **replace the order source_account with the ID of the alternative allowed scheme transaction.

Please get through Payment with your own POS


REST Entities

Every REST entity is described listing her properties with the following formatting conventions:

  • this is a property name
  • this is an example of property value
  • (type, policy, direction) is the specification of a property
    • type can be "string", "number", "object" or a proper object class name
    • policy can be "optional" or "required"
    • direction can be "posted" or "received" depending on whether you set it in the request or you got it from the response
  • after the dash "-" there's the property description

name: example_value (type, policy, direction) - Property description

PagoPA

PagoPA
  • id: PPA8K195PZ1Q (string,required,returned) - Unique ID of the PagoPA form
  • description: Pagamento Multa (string, required, posted) - Narrative description of service order
  • date_creation: 2016-07-16T19:20:30+01:00 (string, required,rerturned) - Date the form has been created
  • date_last_modified: 2016-07-16T19:20:30+01:00 (string, required, returned) - Last date the form has been modified
  • date_scheduled: 2016-07-16 (string, optional, returned/posted) - Date the order must be exceuted
  • date_settlement: 2016-07-17 (string, optional, returned) - Date the payment must be settle to recipient data)
  • amount: 100.00 (number, required, returned) - total amount of payment
  • source (object[PayerInfo], required,posted )
  • fee: (object[FeeInfo], required,returned )
  • agio: 0.70 (number, optional, returned) - valued only if a commission is due DropPay account owner
  • status: DRAFT (enum[string], required,returned/posted) - payment status
    • enum members
      • DRAFT - form is being filled
      • BOOKED - amount is booked from source account
      • READY - form is ready to be scheduled
      • SCHEDULED - payment is scheduled and will be performed at date_scheduled
      • RUNNING - payment has been processed
      • PAID - payment has been executed
      • PROMISED - payment can be considered paid but funds accounting are going to be delayed
      • FAILED - payment execution has failed
      • DELETED - order has been deleted when in state READY or DRAFT
      • CANCELLED - order has been deleted when in state SCHEDULED
      • ABORTED - order has been deleted when RUNNING
  • sharing: https://dp.link/u/10/BLL8K195PZ1Q (string, optional, returned) - Universal Link
  • webhooks
    • all: https://credenA:credenB@app.server.com/listener (string, optional, posted) - listener for all Bollettino events
  • codice_avviso_2d: PAGOPA|002|123456789012345678|12345678901|10000 (string, optional, posted) - Payment description as specified in QR code
  • codice_avviso: 001123456789012345678 (string, required, posted) - Identifier of payment into domain of payee (IUV)
  • iuv: 123456789012345678 (string, required, returned) - Identifier of payment into domain of payee
  • codice_ente: 12345678901 (string, required, posted) - Indentifier code of payee
  • nome_ente: Comune di Firenze (string, optional, returned) -
  • logo_ente: https://cdn.aws.com/public/assets/hashfile (string, optional, returned) -
  • importo_avviso: 100.00 (number, required, returned) - Total amount of payment on notice
  • causale: Multa verbale CV987A1 - targa XX123ZZ (string, required, returned) - narrative string of the payment reason
  • psp_code: 2384761938746 (string, required, returned) - PSP identifier
  • causale_tipo: GENERIC (enum, required, returned)
    • enum members
      • GENERIC - all kind of PagoPA reasons
      • PRABOLLOAUTO - Italian car ownership tax PagoPA reason
  • causale_dati (object, optional, returned/posted) - specific attributes payload depending upon causale_tipo
  • identificativo_unico_riscossione: z77MlnNNpoRRy (string, optional, returned)
  • destinatario_avviso_presentato (object, optional, posted)
    • nome: Luke Duke (string, optional, posted) -
    • indirizzo: Country House (string, optional, posted) -
    • cap: 123898 (string, optional, posted) -
    • citta: Hazzard (string, optional, posted) -
    • cf: DKULKU51S06Z404U (string, optional, posted) -
  • destinatario_avviso_nodo (object, optional, returned)
    • nome: Luke Duke (string,optional, returned) -
    • indirizzo: Country House, 123898 Hazzard (string, optional, returned) -
    • cf: DKULKU51S06Z404U (string, optional, returned) -
FeeInfo
  • value: 1.0 (number, required returned) -
  • reason: STANDARD (string, required, returned) -
  • description: Commissione offerta Over 70 (string, required, returned) -
SourceInfo
  • id: BAC123456789 (string, required, returned) - Source DropPay Account Public ID
  • username: 3351234567 (string, optional, returned) - Source user's username
  • acccount_iban: IT63B3606400003351234567 (string, required, returned) - sending account IBAN;
  • account: IT63B3606400003351234567 (string, required, posted) - source DropPay account, an IBAN.
  • account_class: "BUSINESS" (string, optional, returned) - DropPay account class
  • balance_available: 24850.95 (number, optional, returned) - DropPay account current available balance
  • owner
    • name: John Kennedy (string, optional,returned) - source user's name
    • logo: http (string, optional,returned) - source user's logo icon if available

REST Endpoints

Security

Requests must be authenticated with User Access Token. User Access Token can be obtained requesting it with and active Connection Code.

Details at Authentication v.1 API Reference

PagoPa / Form

DropPay PagoPA API publishes the following methods :

  • POST a new PagoPA form entity to send money
  • GET the PagoPA form entity to read the order status;
  • PATCH the PagoPA form entity to modify the order attributes until it is set with second factor disposition protocol;
  • DELETE the PagoPA form entity
POST Create a new PagoPA form

Create a new PagoPA form

Example

⬆ Request
curl --request POST
--url https://api.drop-pay.io/payments/v3/methods/pagopa/form
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'
--header 'content-type:application/json'

Request with only "codice avviso"

{
    "codice_avviso":"123456789012345678",
    "codice_ente":"12345678901",
}

Response 200
{
    "id": "PPA8K195PZ1Q",
    "description": "Pagamento Multa",
    "date_creation": "2016-07-16T19:20:30+01:00",
    "date_last_modified": "2016-07-16T19:20:30+01:00",
    "date_scheduled": "2016-07-16",
    "date_settlement": "2016-07-17",
    "amount": 100,
    "source": {
        "id" : "BAC0O6L3GN49L",
        "account": "BAC0O6L3GN49L",
        "account_class" : "BUSINESS",
        "username": "3351234567",
        "account_iban": "IT63B3606400003351234567",
        "balance_available" : 24850.95,
        "owner" : {
            "name" : "Me Ipso Srl" },
    },
    "fee" : {
        "value" : 1.3,
        "reason" : "STANDARD",
        "description" : "Commissione standard"
    },
    "agio": 0.7,
    "status": "DRAFT",
    "sharing": "https://dp.link/u/10/BLL8K195PZ1Q",
    "webhooks": {
        "all": "https://credenA:credenB@app.server.com/listener"
    },
    "codice_avviso_2d": "PAGOPA|002|123456789012345678|12345678901|10000",
    "codice_avviso": "001123456789012345678",
    "codice_ente": "12345678901",
    "nome_ente": "Comune di Firenze",
    "logo_ente": "https://image.org/logo.jpg",
    "importo_avviso": 100,
    "causale": "Multa verbale CV987A1 - targa XX123ZZ",
    "psp_code": "2384761938746",
    "iuv": "123456789012345678",
    "causale_tipo": "GENERICO",
    "identificativo_unico_riscossione": "z77MlnNNpoRRy",
    "destinatario_avviso_presentato": {
        "nome": "Luke Duke",
        "indirizzo": "Country House, 123898 Hazzard",
        "cap": "12000",
        "citta": "Hazzard",
        "cf": "DKULKU51S06Z404U"
    },
    "destinatario_avviso_nodo": {
        "nome": "Luke Duke",
        "indirizzo": "Country House, 123898 Hazzard",
        "cf": "DKULKU51S06Z404U"
    },
}
Response 400 / Code 100
    {
        "code": "100",
        "description": "Missing arguments"
    }
Response 404 / Code 310
    {
        "code": "310",
        "description": "Unable to find payment referred data"
    }
Response 409 / Code 310
    {
        "code": "310",
        "description": "PagoPA central service payment status violation"
    }
Response 409 / Code 311
    {
        "code": "311",
        "description": "PagoPA duplicated"
    }
Response 409 / Code 312
    {
        "code": "312",
        "description": "PagoPA expired"
    }
Response 409 / Code 313
    {
        "code": "313",
        "description": "Order amount conflicts with current PagoPA paymen data"
    }
Response 500 / Code 310
    {
        "code": "310",
        "description": "PagoPA central service unavailable"
    }
Response 500 / Code 311
    {
        "code": "311",
        "description": "PagoPA central service rejected the request"
    }
GET Read a PagoPA form

Read an existent PagoPA form

Example

⬆ Request
curl --request GET
--url https://api.drop-pay.io/payments/v3/methods/pagopa/form/PPA8K195PZ1Q
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'
Response 200
{
    "id": "PPA8K195PZ1Q",
    "description": "Pagamento Multa",
    "date_creation": "2016-07-16T19:20:30+01:00",
    "date_last_modified": "2016-07-16T19:20:30+01:00",
    "date_scheduled": "2016-07-16",
    "date_settlement": "2016-07-17",
    "amount": 100,
    "source": {
        "id" : "BAC0O6L3GN49L",
        "account": "BAC0O6L3GN49L",
        "account_class" : "BUSINESS",
        "username": "3351234567",
        "account_iban": "IT63B3606400003351234567",
        "balance_available" : 24850.95,
        "owner" : {
            "name" : "Me Ipso Srl" },
        },
    "fee" : {
        "value" : 1.3,
        "reason" : "STANDARD",
        "description" : "Commissione standard"
    },
    "agio": 0.7,
    "status": "DRAFT",
    "sharing": "https://dp.link/u/10/BLL8K195PZ1Q",
    "webhooks": {
        "all": "https://credenA:credenB@app.server.com/listener"
    },
    "codice_avviso_2d": "PAGOPA|002|123456789012345678|12345678901|10000",
    "codice_avviso": "001123456789012345678",
    "codice_ente": "12345678901",
    "nome_ente": "Comune di Firenze",
    "logo_ente": "https://image.org/logo.jpg",
    "importo_avviso": 100,
    "causale": "Multa verbale CV987A1 - targa XX123ZZ",
    "psp_code": "2384761938746",
    "iuv": "123456789012345678",
    "causale_tipo": "GENERICO",
    "identificativo_unico_riscossione": "z77MlnNNpoRRy",
    "destinatario_avviso_presentato": {
        "nome": "Luke Duke",
        "indirizzo": "Country House, 123898 Hazzard",
        "cap": "12000",
        "citta": "Hazzard",
        "cf": "DKULKU51S06Z404U"
    },
    "destinatario_avviso_nodo": {
        "nome": "Luke Duke",
        "indirizzo": "Country House, 123898 Hazzard",
        "cf": "DKULKU51S06Z404U"
    },
}
PATCH Modify a PagoPA form

Modify an existent PagoPA form

Example

⬆ Request
curl --request PATCH
--url https://api.drop-pay.io/payments/v3/methods/pagopa/form/PPA8K195PZ1Q
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'
{
    "status": "READY"
}
Response 200
    {
        "id": "PPA8K195PZ1Q",
        "description": "Pagamento Multa",
        "date_creation": "2016-07-16T19:20:30+01:00",
        "date_last_modified": "2016-07-16T19:20:30+01:00",
        "date_scheduled": "2016-07-16",
        "date_settlement": "2016-07-17",
        "amount": 100,
        "source": {
            "id" : "BAC0O6L3GN49L",
            "account": "BAC0O6L3GN49L",
            "account_class" : "BUSINESS",
            "username": "3351234567",
            "account_iban": "IT63B3606400003351234567",
            "balance_available" : 24850.95,
            "owner" : {
                "name" : "Me Ipso Srl" },
        },
        "fee" : {
            "value" : 1.3,
            "reason" : "STANDARD",
            "description" : "Commissione standard"
        },
        "agio": 0.7,
        "status": "READY",
        "sharing": "https://dp.link/u/10/BLL8K195PZ1Q",
        "webhooks": {
            "all": "https://credenA:credenB@app.server.com/listener"
        },
        "codice_avviso_2d": "PAGOPA|002|123456789012345678|12345678901|10000",
        "codice_avviso": "001123456789012345678",
        "codice_ente": "12345678901",
        "nome_ente": "Comune di Firenze",
        "logo_ente": "https://image.org/logo.jpg",
        "importo_avviso": 100,
        "causale": "Multa verbale CV987A1 - targa XX123ZZ",
        "psp_code": "2384761938746",
        "iuv": "123456789012345678",
        "causale_tipo": "GENERICO",
        "destinatario_avviso_presentato": {
            "nome": "Luke Duke",
            "indirizzo": "Country House, 123898 Hazzard",
            "cap": "12000",
            "citta": "Hazzard",
            "cf": "DKULKU51S06Z404U"
        },
        "identificativo_unico_riscossione": "z77MlnNNpoRRy",
        "destinatario_avviso_nodo": {
            "nome": "Luke Duke",
            "indirizzo": "Country House, 123898 Hazzard",
            "cf": "DKULKU51S06Z404U"
        },
    }
Response 400 / Code 100
    {
        "code": "100",
        "description": "Missing arguments"
    }
Response 404 / Code 310
    {
        "code": "310",
        "description": "Unable to find payment referred data"
    }
Response 409 / Code 310
    {
        "code": "310",
        "description": "PagoPA central service payment status violation"
    }
Response 409 / Code 311
    {
        "code": "311",
        "description": "PagoPA duplicated"
    }
Response 409 / Code 312
    {
        "code": "312",
        "description": "PagoPA expired"
    }
Response 409 / Code 313
    {
        "code": "313",
        "description": "Order amount conflicts with current PagoPA paymen data"
    }
Response 409 / Code 314
    {
        "code": "314",
        "description": "PagoPA already presented in {PPA7345276354}"
    }
Response 409 / Code 314
    {
        "code": "314",
        "description": "PagoPA already presented in {PPA7345276354}"
    }
Response 500 / Code 310
    {
        "code": "310",
        "description": "PagoPA central service unavailable"
    }
Response 500 / Code 311
    {
        "code": "311",
        "description": "PagoPA central service rejected the request"
    }
DELETE Delete a PagoPA form

Delete an existent PagoPA form

Delete method changes semanthic depending upon origin status, so :

  • if origin status is DRAFT or READY, delete moves order to CANCELLED

Example

⬆ Request
curl --request DELETE
--url https://api.drop-pay.io/payments/v3/methods/pagopa/form/PPA8K195PZ1Q
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'
--header 'content-type: application/www-form-urlencoded'
Response 200
{
    "id": "PPA8K195PZ1Q",
    "description": "Pagamento Multa",
    "date_creation": "2016-07-16T19:20:30+01:00",
    "date_last_modified": "2016-07-16T19:20:30+01:00",
    "date_scheduled": "2016-07-16",
    "date_settlement": "2016-07-17",
    "amount": 100,
    "source": {
        "id" : "BAC0O6L3GN49L",
        "account": "BAC0O6L3GN49L",
        "account_class" : "BUSINESS",
        "username": "3351234567",
        "account_iban": "IT63B3606400003351234567",
        "balance_available" : 24850.95,
        "owner" : {
            "name" : "Me Ipso Srl" },
    },
    "fee": 1,
    "agio": 0.7,
    "status": "CANCELLED",
    "sharing": "https://dp.link/u/10/PPA8K195PZ1Q",
    "webhooks": {
        "all": "https://credenA:credenB@app.server.com/listener"
    },
    "codice_avviso": "001123456789012345678",
    "codice_ente": "12345678901",
    "nome_ente": "Comune di Firenze",
    "logo_ente": "https://image.org/logo.jpg",
    "importo_avviso": 100,
    "causale": "Multa verbale CV987A1 - targa XX123ZZ",
    "psp_code": "2384761938746",
    "iuv": "123456789012345678",
    "causale_tipo": "GENERICO",
    "destinatario_avviso_presentato": {
        "nome": "Luke Duke",
        "indirizzo": "Country House, 123898 Hazzard",
        "cap": "12000",
        "citta": "Hazzard",
        "cf": "DKULKU51S06Z404U"
    },
    "identificativo_unico_riscossione": "z77MlnNNpoRRy",
    "destinatario_avviso_nodo": {
        "nome": "Luke Duke",
        "indirizzo": "Country House, 123898 Hazzard",
        "cf": "DKULKU51S06Z404U"
    },
}
Response 400
    {
        "code": "100",
        "description": "Missing arguments"
    }

PagoPa / Form Disposition

DropPay PagoPA API publishes the following methods to commit the payment :

  • POST a new PagoPA form entity
POST Create a new PagoPA form disposition

Create a new PagoPA form disposition

Example

⬆ Request
curl --request POST
--url https://api.drop-pay.io/payments/v3/methods/pagopa/form/disposition/PPA8K195PZ1Q
--header 'authorization: Bearer ac9185e9f2984867b11069fd2881ff1a'
--header 'content-type: application/json'

Request with

{

}

Response 200
{
    "id": "PPA8K195PZ1Q",
    "description": "Pagamento Multa",
    "date_creation": "2016-07-16T19:20:30+01:00",
    "date_last_modified": "2016-07-16T19:20:30+01:00",
    "date_scheduled": "2016-07-16",
    "date_settlement": "2016-07-17",
    "amount": 100,
    "source": {
        "id" : "BAC0O6L3GN49L",
        "account": "BAC0O6L3GN49L",
        "account_class" : "BUSINESS",
        "username": "3351234567",
        "account_iban": "IT63B3606400003351234567",
        "balance_available" : 24850.95,
        "owner" : {
            "name" : "Me Ipso Srl" },
    },
    "fee": 1,
    "agio": 0.7,
    "status": "RUNNING",
    "sharing": "https://dp.link/u/10/PPA8K195PZ1Q",
    "webhooks": {
        "all": "https://credenA:credenB@app.server.com/listener"
    },
    "codice_avviso": "001123456789012345678",
    "codice_ente": "12345678901",
    "nome_ente": "Comune di Firenze",
    "logo_ente": "https://image.org/logo.jpg",
    "importo_avviso": 100,
    "causale": "Multa verbale CV987A1 - targa XX123ZZ",
    "psp_code": "2384761938746",
    "iuv": "123456789012345678",
    "causale_tipo": "GENERICO",
    "destinatario_avviso_presentato": {
        "nome": "Luke Duke",
        "indirizzo": "Country House, 123898 Hazzard",
        "cap": "12000",
        "citta": "Hazzard",
        "cf": "DKULKU51S06Z404U"
    },
    "identificativo_unico_riscossione": "z77MlnNNpoRRy",
    "destinatario_avviso_nodo": {
        "nome": "Luke Duke",
        "indirizzo": "Country House, 123898 Hazzard",
        "cf": "DKULKU51S06Z404U"
    },
}