Data Items Reference
Permitted Character Sets and Formats
Character set AN
The MyBank character set AN consists of only the following characters
a b c d e f g h i j k l m n o p q r s t u v w x y z
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
0 1 2 3 4 5 6 7 8 9
/ - ? : ( ) . , ' +
Space
Within the individual Data Element definitions terms such as “Max 140 AN” are used. This is a short way of writing, in this case, “Between 1 and 140 characters from the AN character set”.
Note that empty Data Elements are not allowed so that the minimum length is always 1.
Character set UTF8
This is the native ISO schema character set. MyBank does not impose further restrictions.
The UTF8 character set is used for data elements such as email addresses, URLs and specific elements which allow local language names.
Within the individual Data Element definitions terms such as “Max 2048 UTF8” are used. This is a short way of writing, in this case, “Between 1 and 2048 characters from the UTF8 character set”.
Note that empty Data Elements are not allowed so that the minimum length is always 1.
Date format
All dates and date-time stamps used within the Server are ISO 8601 that MUST include an explicit time-zone indicator set to UTC and MUST conform to the following rules:
Format
Date MUST have the form: YYYY”-“MM”-“DD”Z”
DateTime MUST have the form: YYYY”-“MM”-“DD”T”hh”:”mm”:”ss[“.”1*(n)]”Z”Where:
- YYYY is any valid four-digit year number (e.g. 2021)
- MM is any valid two-digit month number (e.g. 10 which indicates October)
- DD is any valid two-digit day number (e.g. 03 which indicates the third day of the month)
- hh is any valid two-digit hour number (24-hour notation) in the range 00 to 23 (e.g. 10 indicates 10 a.m.)
- mm is any valid two-digit minute number in the range 00 to 59 (e.g. 04 which indicates 4 minutes into the hour)
- ss is any valid two-digit seconds number in the range 00 to 59 (e.g. 09 which indicates 9 seconds into the minute).Note that the number 60 is used to represent leap seconds.
- n is any digit.
Data Items
The following table lists all the MyBank data items included within one or more APIs.
The last column of the table specifies the SCT path for the data items included within the SCT underlying the MyBank transaction and if the data item can be used for reconciliation purposes. Please take into account that no other data must be used.
| Parameter | Description | Format / Value | SCT Path |
|---|---|---|---|
| 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)]”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: 1) The Merchant set the cart's expiration to 15 minutes (the value includes the time for the payment) 2) The merchant manages the choose of the Buyer Bank on his checkout page 3) When the Buyer selects MyBank, choose his Bank from the list and leaves the Merchant's website, the remaining time is 10 minutes 4) 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)]”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 This field can be used for reconciliation purpose |
| 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 This field can be used for reconciliation purpose |
| 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. | 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 Merchant is required to provide the Ultimate Beneficiary's name (that is, if the Ultimate Beneficiary is different from both merchantName and merchantTradingName), then remittanceInformation *MUST have the following format:FB/<ultimate beneficiary name>/<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)]”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)]”Z” | |
| transactionValidityStart | Starting DateTime of the transaction. | YYYY”-“MM”-“DD”T”hh”:”mm”:”ss[“.”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)]”Z” | |
| validityStartDateTime | Time from which it is possible to fulfil the Payment Request. | YYYY”-“MM”-“DD”T”hh”:”mm”:”ss[“.”1*(n)]”Z” |
Updated about 1 month ago