DropPay API - Payments v.1

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 PDEV as POS Device 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: 1.00 (number, optional, returned) - operation fee
  • 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, posted) - 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
      • GENERICO - all kind of PagoPA reasons
      • PRABOLLOAUTO - Italian car ownership tax PagoPA reason
  • causale_dati (object, optional, returned/posted) - specific attributes payload depending upon reason_type
  • 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, required, returned)
    • nome: Luke Duke (string, required, returned) -
    • indirizzo: Country House, 123898 Hazzard (string, required, returned) -
    • cf: DKULKU51S06Z404U (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, optional, returned) - sending account IBAN;
  • account: IT63B3606400003351234567 (string, optional, posted) - source DropPay account, an IBAN.
  • 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/payment/v1/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": {
        "username": "3351234567",
        "iban": "IT63B3606400003351234567",
        "email": "user@domain.com",
        "name": "John Kennedy",
    },
    "fee": 1,
    "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",
    "destinatario_avviso_nodo": {
        "nome": "Luke Duke",
        "indirizzo": "Country House, 123898 Hazzard",
        "cf": "DKULKU51S06Z404U"
    }
}
Response 400
    {
        "code": "100",
        "description": "Missing arguments"
    }
GET Read a PagoPA form

Read an existent PagoPA form

Example

⬆️ Request
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": {
        "username": "3351234567",
        "iban": "IT63B3606400003351234567",
        "email": "user@domain.com",
        "name": "John Kennedy",
    },
    "fee": 1,
    "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_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/payment/v1/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": {
        "username": "3351234567",
        "iban": "IT63B3606400003351234567",
        "email": "user@domain.com",
        "name": "John Kennedy",
    },
    "fee": 1,
    "agio": 0.7,
    "status": "READY",
    "sharing": "https://dp.link/u/10/PPA8K195PZ1Q",
    "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_nodo": {
        "nome": "Luke Duke",
        "indirizzo": "Country House, 123898 Hazzard",
        "cf": "DKULKU51S06Z404U"
    }
}
Response 400
    {
        "code": "100",
        "description": "Missing arguments"
    }
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/payment/v1/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": {
        "username": "3351234567",
        "iban": "IT63B3606400003351234567",
        "email": "user@domain.com",
        "name": "John Kennedy",
    },
    "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_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 to send money
POST Create a new PagoPA form disposition

Create a new PagoPA form disposition

Example

⬆️ Request
curl --request POST
--url https://api.drop-pay.io/payment/v1/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": {
        "username": "3351234567",
        "iban": "IT63B3606400003351234567",
        "email": "user@domain.com",
        "name": "John Kennedy",
    },
    "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_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_nodo": {
        "nome": "Luke Duke",
        "indirizzo": "Country House, 123898 Hazzard",
        "cf": "DKULKU51S06Z404U"
    }
}