Data Items Reference

alias

Name of the Buyer Bank to be showed to the Buyer within the MyBank selection list

Max 35 upper case characters from A-Z, 0-9, dot (“.”), dash (“-“) and space (“ “).

aliasLanguage

Specifies the language (ISO 639-1) of the Alias selected by the Buyer.

ISO 639-1 language code
Example: it, fr, es

amount

Amount of the transaction in Euro.

Between 0.01 and 999999999.99

/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/IntrBkSttlmAmt
This field can be used for reconciliation purpose

branch

Technical data.

Must be "10000".

buyerBankBIC

Business Identifier Code (BIC) related to the Buyer’s payment account held by the Buyer Bank.

8AN or 11AN character ISO code

Only for some Payer PSPs:
/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/DbtrAgt/FinInstnId/BIC

buyerIBAN

The International Bank Account Number of the Buyer’s payment account held by the Buyer Bank.

ISO 13616 - MAX 34AN

Depending on the Payer PSP, either:
/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/DbtrAcct/Id/IBAN

or:
/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/UltmtDbtr/Id/OrgId/Othr/Id

buyerName

Name of Buyer.

Max 70UTF8

Depending on the Payer PSP, either:
/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/Dbtr/Nm

or:
/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/UltmtDbtr/Nm

confirmedExecutionDate

Effective date for the debit on the buyer's account.

YYYY”-“MM”-“DD”T”hh”:”mm”:”ss[“.”1*(n)][“.”1*(n)]”Z”
Time part will be zero.

confirmedQualifiedApplicationID

Technical data with no business meaning for the APIs' caller

country

Country of the Buyer Bank

ISO 3166-1 alpha-2 country code Example: IT, FR, ES

durationMillis

Duration of transaction’s validity in milliseconds (Between 3 and 30 minutes, default is 15) specified by the Client calling the APIs. The durationMillis specifies the time at disposal to the Buyer to authorise the MyBank transaction. The countdown starts immediately after that the MyBank transaction is created, from the UX point of view, when the Buyer is redirected to his Home Banking environment.
Please pay attention that the durationMillis may differ from the time by which a Merchant wants to know the final status of a MyBank transaction.
Example 1:

1. The Merchant set the cart's expiration to 15 minutes (the value includes the time for the payment)
2. When the Buyer selects MyBank as payment method and leaves the Merchant's website, the remaining time is 10 minutes
3. The User lands on the Payee PSP's MyBank selection page and takes 1 minutes to search and select his Bank
4. The Payee PSP must set the durationMIllis to 9 minutes
   Example 2:
5. The Merchant set the cart's expiration to 15 minutes (the value includes the time for the payment)
6. The merchant manages the choose of the Buyer Bank on his checkout page
7. When the Buyer selects MyBank, choose his Bank from the list and leaves the Merchant's website, the remaining time is 10 minutes
8. The Payee PSP must set the durationMillis to 10 minutes

Between 180000 and 1800000 (milliseconds)

endToEndID

The application level reference of the MyBank transaction as assigned by the First Beneficiary of the funds, as it is the subject that receives the MyBank SCT from the Buyer Bank. This will be included in the SCT underlying the MyBank transaction.

Max 35AN

/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/PmtId/EndToEndId
This field can be used for reconciliation purpose

Note: in case a refund Credit Transfer is instructed, it also MUST contain the endToEndID of the original MyBank Transaction in the field CdtTrfTxInf/PmtId/EndToEndId.

errorCode

Error Code.

Max 35AN

expectedSettlementDate

Expected Settlement Date of the related Sepa Credit Transfer.

YYYY”-“MM”-“DD”T”hh”:”mm”:”ss[“.”1*(n)][“.”1*(n)]”Z”
Time part will be zero.

flagAuthorisingUserAuthenticated

It indicates if the Buyer has sucessfully authenticated himself on the Home Banking environment

Boolean ("0","1")

flagMobileDevice

It indicates if the Buyer is using a mobile device.

Must be set to "1" if the Buyer is using a mobile device and "0" otherwise.

flagRejectionReasonTransac-
tionPreConditionNotMet

It indicates if, after the Login, some reason has prevented the Buyer to see the transaction data and to proceed with the authorisation.

Boolean ("0","1")

flagTransactionDataDisplayed

It indicates if the transaction data have been displayed to the Buyer.

Boolean ("0","1")

flagValidationServiceURLConsumed

It indicates if the ValidationServiceURL has been retrieved.

Boolean ("0","1")

idInitiatingParty

The technical identifier attributed by PRETA.

INTEGER Numeric
The value will be communicated by the Solution Manager after the onboarding phase

initiatingPartyID

The business identifier attributed by PRETA. In some cases it may identify the Initiating Party and a further PSP that is contractualised by the Initiating Party.

MAX 35AN
The value will be communicated by the Solution Manager after the onboarding phase. Depending on the presence of a further PSP, the format of the initatingPartyID is one of the following:
<InitiatingPartyCode>
<InitiatingPartyCode> / <PSPCode>
Examples:
PPRO
PPRO / PAYPAL

/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/Cdtr/Id/OrgId/Othr/Id
This field can be used for reconciliation purpose

initiatingPartyReturnURL

The unique and per-transaction URL provided by the Merchant that is used to redirect the Buyer back to him after completing the authorisation. Note that this URL needs not necessarily point to the domain of the Merchant. The domain may belong to an intermediate party involved in the processing of MyBank transactions on behalf of the Merchant. As an example, this might occur when a payment gateway is being used by the Merchant.
Reminders (please refer to the documentation for the Payment Initiation API for more details):

• the handling of this URL must not rely on any "session";
• in case the payment flow is initiated from an App, it is recommended that the App is registered to handle this URL.

Max 512UTF8.
The URL MUST use the HTTPS URI scheme.

initiatingPartySubID

The identifier of the Merchant as attributed by the Merchant PSP. The initiatingPartySubID is univocally bound with a merchantTradingName.

Max 35AN

/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/UltmtCdtr/Id/OrgId/Othr/Id
This field can be used for reconciliation purpose

institute

Technical data.

Must be "1000".

language

Specifies the language (ISO 639-1) of the Alias selected by the Buyer.

ISO 639-1 language code
Example: it, fr, es

maxOccurence

It is the maximum number of MyBank transactions that can be generated from a specific Payment Request.

Must be set to "1"

merchantBankBIC

Business Identifier Code (BIC) of the bank account of the first beneficiary of the funds. The SCT underlying the MyBank transaction is sent to this BIC.

8AN or 11AN character ISO code

/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/CdtrAgt/FinInstnId/BIC

merchantCountryCode

The country of the Merchant.

ISO 3166-1 alpha-2 country code
Example: IT, FR, ES

merchantIBAN

International Bank Account Number (IBAN) of the bank account of the first beneficiary of the funds. The SCT underlying the MyBank transaction is sent to this IBAN.

ISO 13616 - MAX 34AN

/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/CdtrAcct/Id/IBAN

merchantName

As a general rule, this attribute should be set to the name of the holder of the account associated to the merchantIBAN.
To avoid any confusion for the Payer (which may lead to lower authorisation rate), it is recommended to set this attribute to the same value as the merchantTradingName.

MAX 70AN

/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/Cdtr/Nm
This field can be used for reconciliation purpose

merchantTaxNumberClassification

A compound element containing both the country that issued the Merchant Tax Number as well as the fiscal classification of the Merchant.
This attribute must be used only if the optional feature "SCT for fiscal benefits" is requested.

CountryCode is the ISO 3166-1 alpha-2 (2 letters) country code of the issuing country of the MerchantTaxNumberID. FiscalClassification is either “PYPE” (Physical Person) or “LEEN” (Legal Entity).
Valid examples are: IT:PYPE FR:LEEN

merchantTaxNumberID

Merchant Tax Number.
This attribute must be used only if the optional feature "SCT for fiscal benefits" is requested.

MAX 35AN

merchantTradingName

The trading name of the Merchant as known by the Buyer.

MAX 70UTF8

/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/UltmtCdtr/Nm
Attention: Payer PSPs have the faculty to modify (or even omit) this value, in particular if the original value includes any non-SEPA characters

merchantWebsite

The url of the website of the Merchant.

Max 255UTF8.
Ex: www.preta.eu

orderDescription

A free text field used by the Merchant to describe the goods being ordered by the Buyer, to assist the Buyer to recognise the transaction. The order Description must be human-readable. If the Merchant has a non-Euro account, the currency conversion must be done before calling the Payment Initiation (that requires the amount always in Euro). In this case the OrderDescription must also contain information regarding the amount conversion from the currency of the account to the Euro. The currency conversion related information that must be present are:

• Amount in account’s currency
• Exchange rate applied for currency conversion
• Any currency conversion fee or commission applied

MAX 128AN

participantID

Identifier of the Buyer Bank as assigned by PRETA.

MAX 35AN

paymentRequestID

Identifier of the Payment Request as assigned by PRETA.

uuid - 12AN

qualifiedApplicationID

Technical data item.

Must be MBNKCT01.

remittanceInformation

A Merchant may specify in this attribute the unique reference to unambiguously refer the payment. This will be included in the SCT underlying the MyBank transaction.
If the final beneficiary of the MyBank payment is a physical person (e.g., the holder of a gaming account, offered by the Merchant), then remittanceInformation *MUST have the following format:\ FB/<full name of the final beneficiary>/<other information>
(e.g.: FB/John Doe/Order 123).

MAX 140AN

/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/RmtInf/Ustrd
This field can be used for reconciliation purpose

requestedExecutionDate

Requested date for the debit on the buyer's account.

YYYY”-“MM”-“DD”Z”

routingServiceID

Technical parameter.

Must be set to "CT000245" in TEST and "CT000400" in LIVE.

settlementDate

Settlement Date

YYYY”-“MM”-“DD”Z”

/Document/FIToFICstmrCdtTrf/GrpHdr/IntrBkSttlmDt

status

Payment Request status: ACTIVE: the Payment Request is payable, unless one of the following conditions occur:

• The validityStartDateTime is in the future. The Payment Request is not payable yet.
• There is already an ongoing MyBank transaction without a final status (transactionStatus = PENDING). The Payment Request is not payable. EXPIRED: the Payment Request is expired. The Payment Request is not payable anymore.
  • *DISABLED**: the Payment Request has been cancelled by the Payee. The Payment Request is not payable anymore.
  • *COMPLETED**: There is a MyBank transaction with transactionStatus = AUTHORISED. The Payment Request is not payable anymore.

ACTIVE, EXPIRED or DISABLED, PROCESSING, COMPLETED

transactionID

Unique identifier of the transaction attributed by PRETA

INTEGER Numeric (max 35 digits)

transactionStatus

MyBank transaction status as assigned by the Buyer Bank. Note that the Buyer Bank is the only subject allowed to assign a final status to a MyBank transaction. The possible status are:

• *PENDING**: the initial status of a transaction. It is not a final status.
• *AUTHORISED**: the transaction was authorised
• *AUTHORISINGPARTYABORTED**: The Buyer refused to authorise the payment, for example, the Buyer clicked the “cancel” button in the Buyer Bank’s online banking environment or closed the browser window (if detected by the Bank). The Seller will not receive any funds for this transaction.
• *TIMEOUT**: The Buyer did not authorise the transaction within the the durationMillis. The transaction can no longer be authorised by the Buyer. The Seller will not receive any funds for this transaction.
• *ERROR**: An application level issue prevented the authorisation of the transaction. For example the Buyer failed to provide correct SCA during authorisation, the Buyer Bank refused the Buyer’s request for authorisation (block imposed by the Buyer Bank’s beneficiary “black list” procedures), a software issue at the Buyer Bank prevented authorisation. The Seller will not receive any funds for this transaction.

PENDING, AUTHORISED or ERROR, AUTHORISINGPARTYABORTED, TIMEOUT

transactionStatusModifyDate

DateTime of change of the transaction status

YYYY”-“MM”-“DD”T”hh”:”mm”:”ss[“.”1*(n)][“.”1*(n)]”Z”

transactionToken

It is a unique identifier of a MyBank transaction assigned by the MyBank Gateway. It can be used instead of the transactionID due to security reasons.

uuid - 12AN

transactionValidityEnd

End DateTime of the transaction's validity.

YYYY”-“MM”-“DD”T”hh”:”mm”:”ss[“.”1*(n)][“.”1*(n)]”Z”

transactionValidityStart

Starting DateTime of the transaction.

YYYY”-“MM”-“DD”T”hh”:”mm”:”ss[“.”1*(n)][“.”1*(n)]”Z”

validationServiceAlias

The different names by which the Buyer identifies his bank.

Max 35 upper case characters from A-Z, 0-9, dot (“.”), dash (“-“) and space (“ “).

validationServiceID

The MyBank identifier of the Validation Service (Buyer Bank).

MAX 35AN
For testing, it is recommended to set this to "CT000000" (this is the only Test Buyer Bank under the control of the Solution Manager, and thus guaranteed to be accessible at all times).

validationServiceTransactionID

Identifier of the transaction as assigned by the Buyer Bank.

MAX 35AN

Only for some Payer PSPs:
/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/PmtId/TxId

validationServiceURL

The unique and per-transaction URL provided by the Buyer Bank for the authorisation of the transaction by the Buyer. Note that this URL needs not necessarily point to the domain of the Buyer Bank. The domain may belong to an intermediate party involved in the processing of MyBank transactions.

Max 512UTF8.
The URL MUST use the HTTPS URI scheme.

validityEndDateTime

Time after which it is not possible anymore to fulfil the Payment Request. The Maximum validity for a Payment Request is set to 365 days. The Payment Request Validity End can’t be in the past when the Payment Request is created.

YYYY”-“MM”-“DD”T”hh”:”mm”:”ss[“.”1*(n)][“.”1*(n)]”Z”

validityStartDateTime

Time from which it is possible to fulfil the Payment Request.

YYYY”-“MM”-“DD”T”hh”:”mm”:”ss[“.”1*(n)][“.”1*(n)]”Z”