Italian payment methods

1.Provider supported

On the Italian market, we support additional payment methods and alternative payment methods. Here is the supported list:

Payment Provider	StoredValueAccountID.ownerName	AmountsReq.StoredValueId
CIR	ARGENTEA_VOUCHER	102
SODEXO	ARGENTEA_VOUCHER	103
PELLEGRINI	ARGENTEA_VOUCHER	104
DAY	ARGENTEA_VOUCHER	105
EP	ARGENTEA_VOUCHER	106
EDENRED	ARGENTEA_VOUCHER	107
REPAS	ARGENTEA_VOUCHER	108
YES!TICKET	ARGENTEA_VOUCHER	109
MIG	ARGENTEA_VOUCHER	110
EATSREADY	ARGENTEA_VOUCHER	111
TODUBA	ARGENTEA_VOUCHER	112
GUDOL	ARGENTEA_VOUCHER	113
MONNI	ARGENTEA_VOUCHER	114
BITCOIN	ARGENTEA_ALTPAYMENT	0003
SATISPAY QR CODE	ARGENTEA_ALTPAYMENT	0004
CONAD PAY	ARGENTEA_ALTPAYMENT	0005
TINABA	ARGENTEA_ALTPAYMENT	0006
ALIPAY	ARGENTEA_ALTPAYMENT	0007
WECHAT	ARGENTEA_ALTPAYMENT	0008
POSTEPAY	ARGENTEA_ALTPAYMENT	0009
FIERAPAY	ARGENTEA_ALTPAYMENT	0010
SCALAPAY	ARGENTEA_ALTPAYMENT	0011
BANCOMATPAY	ARGENTEA_ALTPAYMENT	0012
CIPAY	ARGENTEA_ALTPAYMENT	0013

2. Payment

A. Payment Request

Payment Request for Italian specific payment methods are similar to a standard payment request, to which we have to add extra "PaymentData" element in the Request Body

Header

The standard SaleToPOIRequest.MessageHeader object, with MessageClass set to Service and MessageCategory set to Payment.

Body

To successfully initiate a PaymentRequest for italian payment methods, the body must contain the standard data expected for a PaymentRequest. In addition, you have to fulfill dedicated object: PaymentData.PaymentInstrumentData

Component Object	Required	Type	Description
`PaymentInstrumentType`	Yes	String	Static data to set to "StoredValue".
`StoredValueAccountID.EntryMode`	Yes	String	static data to set to "Manual"
`StoredValueAccountID.IdentificationType`	No	String	static data to set to "AccountNumber"
`StoredValueAccountID.ownerName`	No	Enum	refer to the provider table below
`StoredValueAccountID.StoredValueAccountType`	No	String	static data to set to "Other"
`StoredValueAccountID.StoredValueId`	No	Object	for Buono Pasto, set to "null" for alternative payment methods: refer to the provider table below

Card Acquisition Request example JSON

{
  "MessageHeader": {
    "MessageCategory": "Payment",
    "MessageClass": "Service",
    "MessageType": "Request",
    "POIID": "POI_01",
    "ProtocolVersion": "3.1",
    "SaleID": "POS_01",
    "ServiceID": "823"
  },
  "PaymentRequest": {
    "PaymentData": {
      "PaymentInstrumentData": [
        {
          "PaymentInstrumentType": "StoredValue",
          "StoredValueAccountID": {
            "EntryMode": "Manual",
            "IdentificationType": "AccountNumber",
            "ownerName": "ARGENTEA_VOUCHER",
            "StoredValueAccountType": "Other",
            "StoredValueId": "null"
          }
        }
      ]
    },
    "PaymentTransaction": {
      "AmountsReq": {
        "Currency": "EUR",
        "RequestedAmount": "11.99"
      }
    },
    "SaleData": {
      "OperatorID": "Cashier_01",
      "SaleTransactionID": {
        "TimeStamp": "2025-11-28T14:12:59.6+01:00",
        "TransactionID": "9991"
      }
    }
  }
}

Review the full schema on the API specification page for required fields.

Payment Request with extra data example XML

<SaleToPOIRequest>
    <MessageHeader MessageCategory="Payment" MessageClass="Service" MessageType="Request" POIID="321" SaleID="123" ServiceID="858"></MessageHeader>
    <PaymentRequest>
        <SaleData OperatorID="666">
            <SaleTransactionID TimeStamp="2024-08-09T07:38:40Z" TransactionID="123"></SaleTransactionID>
        </SaleData>
        <PaymentTransaction>
            <AmountsReq Currency="EUR" RequestedAmount="12.34"></AmountsReq>
        </PaymentTransaction>
        <PaymentData>
            <PaymentInstrumentData PaymentInstrumentType="StoredValue">
                <StoredValueAccountID EntryMode="Manual"
                    StoredValueAccountType="Other"
                    OwnerName="ARGENTEA_VOUCHER"
                    IdentificationType="Provider">"ProviderCode"</StoredValueAccountID>
            </PaymentInstrumentData>
        </PaymentData>
    </PaymentRequest>

</SaleToPOIRequest>

Review the full schema on the API specification page for required fields.

B. Intermediate Status

A payment request is running asynchronously, the Payment Terminal (POI) uses Display Request messages to inform the Point of Sale (POS) about the customer's required interaction or the current terminal state. The POS can interpret this information to update the customer display or cashier interface and then continue waiting for the final result. Refer to the Standard POS integration flow to manage it

C. Payment Response

The MessageHeader you receive in the response echoes the values you provided in the request. The only exception is the MessageType, which is Response.

As part of the response, we receive standard information related to a payment and additional data related to italian payment method used. Refer to the Standard POS integration flow to manage it.

Component Object	Description
`StoredValueAccountID.ownerName`	name of the payment provider
`AmountsReq.StoredValueId`	code of the payment provider

Payment Response example JSON

Example of a response using a Buono Pasto card

{
  "MessageHeader": {
    "MessageCategory": "Payment",
    "MessageClass": "Service",
    "MessageType": "Response",
    "POIID": "POS01",
    "ProtocolVersion": "3.0",
    "SaleID": "POS001",
    "ServiceID": "823"
  },
  "PaymentResponse": {
    "PaymentReceipt": [
      {
        "DocumentQualifier": "Voucher",
        "OutputContent": {
          "OutputFormat": "Text",
          "OutputText": [
            {
              "Text": "PAGAMENTO BUONO PASTO"
            },
            {
              "Text": ""
            },
            {
              "Text": "ARGENTEA BPE"
            },
            {
              "Text": "BPE ARGENTEA"
            },
            {
              "Text": "VIA TRENTO 15"
            },
            {
              "Text": ""
            },
            {
              "Text": "Data: 11/03/202409:29"
            },
            {
              "Text": "TML: 10777364"
            },
            {
              "Text": "RUPP: E016899310777364"
            },
            {
              "Text": "AuthCode: 3750"
            },
            {
              "Text": "CARD: 00001031"
            },
            {
              "Text": "EDENRED"
            },
            {
              "Text": ""
            },
            {
              "Text": "N.Buoni usati: 000"
            },
            {
              "Text": "001x 6,00 EUR"
            },
            {
              "Text": "002 x 8,00 EUR"
            },
            {
              "Text": ""
            },
            {
              "Text": "IMPORTO EUR 22,00"
            },
            {
              "Text": ""
            },
            {
              "Text": "Disponibilita:"
            },
            {
              "Text": ""
            },
            {
              "Text": "************************"
            },
            {
              "Text": "OPERAZIONE ESEGUITA"
            },
            {
              "Text": "************************"
            },
            {
              "Text": ""
            },
            {
              "Text": ""
            }
          ]
        }
      }
    ],
    "PaymentResult": {
      "PaymentInstrumentData": {
        "PaymentInstrumentType": "StoredValue",
        "StoredValueAccountID": {
          "EntryMode": "Manual",
          "IdentificationType": "AccountNumber",
          "ownerName": "ARGENTEA_VOUCHER",
          "StoredValueAccountType": "Other",
          "StoredValueId": "107",
          "storedValueProvider": "EDENRED"
        }
      }
    },
    "POIData": {
      "POITransactionID": {
        "TimeStamp": "2025-11-28T14:12:59.6+01:00",
        "TransactionID": "9991"
      }
    },
    "Response": {
      "AdditionalResponse": "OPERAZIONE ESEGUITA",
      "Result": "Success"
    },
    "SaleData": {
      "SaleTransactionID": {
        "TimeStamp": "2025-11-28T14:12:59.6+01:00",
        "TransactionID": "9991"
      }
    }
  }
}

Review the full schema on the API specification page for required fields.

3. Reversal

A. Reversal Request

Payment Request for Italian specific payment methods are similar to a standard payment request, to which we have to add extra "PaymentData" element in the Request Body

Header

The standard SaleToPOIRequest.MessageHeader object, with MessageClass set to Service and MessageCategory set to Reversal.

Body

To successfully initiate a ReversalRequest for italian payment methods, the body must contain the standard data expected for a ReversalRequest. In addition, you have to fulfill dedicated object: MarketpayPaymentExtensions.PaymentInstrumentData

Component Object	Required	Type	Description
`PaymentInstrumentType`	Yes	String	Static data to set to "StoredValue".
`StoredValueAccountID.EntryMode`	Yes	String	static data to set to "Manual"
`StoredValueAccountID.IdentificationType`	No	String	static data to set to "AccountNumber"
`StoredValueAccountID.ownerName`	No	Enum	refer to the provider table below
`StoredValueAccountID.StoredValueAccountType`	No	String	static data to set to "Other"
`StoredValueAccountID.StoredValueId`	No	Object	for Buono Pasto, set to "null" for alternative payment methods: refer to the provider table below

Reversal Acquisition Request example JSON

{
  "MessageHeader": {
    "MessageCategory": "Reversal",
    "MessageClass": "Service",
    "MessageType": "Request",
    "POIID": "PayOnSite",
    "ProtocolVersion": "3.1",
    "SaleID": "POS01",
    "ServiceID": "0"
  },
  "ReversalRequest": {
    "Currency": "EUR",
    "MarketpayPaymentExtensions": {
      "PaymentInstrumentData": {
        "PaymentInstrumentType": "StoredValue",
        "StoredValueAccountID": {
          "EntryMode": "Manual",
          "IdentificationType": "AccountNumber",
          "ownerName": "ARGENTEA_VOUCHER",
          "StoredValueAccountType": "Other",
          "StoredValueId": "null"
        }
      },
      "PaymentInstrumentType": "StoredValue"
    },
    "OriginalPOITransaction": {
      "POITransactionID": {
        "TimeStamp": "1970-01-01T00:00:00Z",
        "TransactionID": "POI_TRN_ID"
      }
    },
    "ReversalReason": "MerchantCancel",
    "ReversedAmount": 3,
    "SaleData": {
      "OperatorID": "OPERATOR_ID_IN_REVERSAL",
      "SaleTransactionID": {
        "TimeStamp": "1970-01-01T00:00:00Z",
        "TransactionID": "POS_TRN_ID"
      }
    }
  }
}

Review the full schema on the API specification page for required fields.

B. Reversal Response

The MessageHeader you receive in the response echoes the values you provided in the request. The only exception is the MessageType, which is Response.

As part of the response, we receive standard information related to a reversal and additional data related to italian payment method used. Refer to the Standard POS integration flow to manage it.

Component Object	Description
`StoredValueAccountID.ownerName`	name of the payment provider
`AmountsReq.StoredValueId`	code of the payment provider

Reversal Response example JSON

Example of a response using a Buono Pasto card

{
  "MessageHeader": {
    "MessageCategory": "Reversal",
    "MessageClass": "Service",
    "MessageType": "Response",
    "POIID": "POI_01",
    "ProtocolVersion": "3.1",
    "SaleID": "POS01",
    "ServiceID": "823"
  },
  "ReversalResponse": {
    "POIData": {
      "POITransactionID": {
        "TimeStamp": "2025-11-28T14:12:59.6+01:00",
        "TransactionID": "9991"
      }
    },
    "Response": {
      "ErrorCondition": "UnavailableDevice",
      "Result": "Failure"
    },
    "SaleData": {
      "SaleTransactionID": {
        "TimeStamp": "2025-11-28T14:12:59.6+01:00",
        "TransactionID": "9991\""
      }
    }
  }
}

Review the full schema on the API specification page for required fields.