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.

`PAID`¶

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"
    },
}

DropPay API - Payments v.3¶

PagoPA¶

PagoPA payment procedure explained¶

The Payment Form¶

DRAFT¶

READY¶

BOOKED¶

PAID¶

FAILED¶

REST Entities¶

PagoPA¶

REST Endpoints¶

Security¶

PagoPa / Form¶

Create a new PagoPA form¶

Example¶

Request¶

Read an existent PagoPA form¶

Example¶

Request¶

Modify an existent PagoPA form¶

Example¶

Request¶

Delete an existent PagoPA form¶

Example¶

Request¶

PagoPa / Form Disposition¶

Create a new PagoPA form disposition¶

Example¶

Request¶

The Payment `Form`¶

`DRAFT`¶

`READY`¶

`BOOKED`¶

`PAID`¶

`FAILED`¶