XML Format
The XML (Extensible Markup Language) format provides a structured, industry-standard approach to payment imports based on the ISO 20022 standard. This format is ideal for automated system-to-system integration and SEPA credit transfers.
Overviewβ
XML format benefits:
β
ISO 20022 Standard - International banking standard
β
SEPA Compliant - pain.001.001.03 and pain.001.001.09 message formats
β
Machine-readable - Structured hierarchical data
β
Validation - XSD schema validation
β
Multilingual - UTF-8 encoding support
β
Automation - Perfect for system integration
β
Character conversion - EPC recommended conversion table
File Requirementsβ
Basic Specificationsβ
- File extension:
.xml - Encoding: UTF-8
- Standard: ISO 20022 pain.001.001.03 or pain.001.001.09
- Schema: XSD (XML Schema Definition)
- Message: CustomerCreditTransferInitiationV03 (pain.001.001.03) or CustomerCreditTransferInitiationV09 (pain.001.001.09)
- Purpose: Credit transfer initiation
Type of Messagesβ
The XML format supports:
| Message | Description |
|---|---|
| pain.001.001.03 | Customer Credit Transfer Initiation |
| pain.001.001.09 | Customer Credit Transfer Initiation |
| Bank statements | Account operations report (future) |
Message Structureβ
XML Document Structureβ
<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03 pain.001.001.03.xsd">
<!-- Message content -->
</Document>
A pain.001.001.09 file uses the namespace urn:iso:std:iso:20022:tech:xsd:pain.001.001.09. The examples on this page are pain.001.001.03; each version follows its own XSD schema. For example, in pain.001.001.09 a bank BIC goes in FinInstnId/BICFI instead of FinInstnId/BIC, and ReqdExctnDt holds the date in ReqdExctnDt/Dt (or ReqdExctnDt/DtTm). In pain.001.001.09, GrpHdr/CtrlSum, PmtInf/NbOfTxs and PmtInf/CtrlSum are required.
Main Elementsβ
The message consists of three main parts:
Document
βββ CstmrCdtTrfInitn (Customer Credit Transfer Initiation)
βββ GrpHdr (Group Header) - Mandatory, No repeat
βββ PmtInf (Payment Information) - Mandatory, Repeatable
β βββ CdtTrfTxInf (Transaction Information) - Mandatory, Repeatable
βββ PmtInf (additional payment batches...)
1. Group Header (GrpHdr)β
Mandatory | No Repeat
Contains characteristics shared by all transactions in the message.
Key Fieldsβ
| Element | Description | Example |
|---|---|---|
| MsgId | Unique message identification | MSG-2023-12-15-001 |
| CreDtTm | Creation date and time | 2023-12-15T14:30:25 |
| NbOfTxs | Number of transactions | 3 |
| CtrlSum | Total of all amounts | 2500.00 |
| InitgPty | Initiating party name | Company Name |
Exampleβ
<GrpHdr>
<MsgId>MSG-2023-12-15-001</MsgId>
<CreDtTm>2023-12-15T14:30:25</CreDtTm>
<NbOfTxs>3</NbOfTxs>
<CtrlSum>2500.00</CtrlSum>
<InitgPty>
<Nm>ABC Company Ltd</Nm>
</InitgPty>
</GrpHdr>
2. Payment Information (PmtInf)β
Mandatory | Repeatable
Contains debit-side characteristics that apply to a group of transactions.
Key Fieldsβ
| Element | Description | Example |
|---|---|---|
| PmtInfId | Payment information ID | PMT-BATCH-001 |
| PmtMtd | Payment method | TRF (Transfer) |
| BtchBookg | Batch booking | true or false (optional) |
| NbOfTxs | Number of transactions | Count (optional in pain.001.001.03, required in pain.001.001.09) |
| CtrlSum | Control sum | Total amount (optional in pain.001.001.03, required in pain.001.001.09) |
| PmtTpInf | Payment type information; see Payment Urgency and SEPA Instant | Service level (SEPA) |
| ReqdExctnDt | Requested execution date | 2023-12-20 |
| Dbtr | Debtor (payer) information | Name, account |
| DbtrAcct | Debtor account | IBAN |
| DbtrAgt | Debtor agent (bank) | BIC |
| UltmtDbtr | Ultimate debtor | Final payer information |
| ChrgBr | Charge bearer | SLEV, SHAR, CRED, DEBT |
Charge Bearer Codesβ
| Code | Name | Description |
|---|---|---|
| SLEV | Service Level | Following service level agreement |
| SHAR | Shared | Charges shared between debtor and creditor |
| CRED | Creditor | All charges borne by creditor |
| DEBT | Debtor | All charges borne by debtor |
Example with SEPAβ
<PmtInf>
<PmtInfId>PMT-BATCH-001</PmtInfId>
<PmtMtd>TRF</PmtMtd>
<PmtTpInf>
<SvcLvl>
<Cd>SEPA</Cd>
</SvcLvl>
</PmtTpInf>
<ReqdExctnDt>2023-12-20</ReqdExctnDt>
<Dbtr>
<Nm>ABC Company Ltd</Nm>
</Dbtr>
<DbtrAcct>
<Id>
<IBAN>LT123456789012345678</IBAN>
</Id>
</DbtrAcct>
<DbtrAgt>
<FinInstnId>
<BIC>HABALT22</BIC>
</FinInstnId>
</DbtrAgt>
<UltmtDbtr>
<Nm>John Doe</Nm>
<Id>
<OrgId>
<Othr>
<Id>123456789</Id>
<SchmeNm>
<Cd>COID</Cd>
</SchmeNm>
</Othr>
</OrgId>
</Id>
</UltmtDbtr>
<ChrgBr>SLEV</ChrgBr>
<!-- Transaction Information follows -->
</PmtInf>
3. Transaction Information (CdtTrfTxInf)β
Mandatory | Repeatable (within PmtInf)
Contains individual transaction details.
Key Fieldsβ
| Element | Description | Example |
|---|---|---|
| PmtId | Payment identification | Instruction ID, End-to-End ID |
| PmtTpInf | Payment type information for this transaction only (optional); see Payment Urgency and SEPA Instant | Local instrument (INST) |
| Amt | Amount | Currency and value |
| Cdtr | Creditor (beneficiary) | Name |
| CdtrAcct | Creditor account | IBAN |
| CdtrAgt | Creditor agent (bank) | BIC (optional for SEPA) |
| RmtInf | Remittance information | Payment description |
Exampleβ
<CdtTrfTxInf>
<PmtId>
<InstrId>TXN-001</InstrId>
<EndToEndId>INV-2023-001</EndToEndId>
</PmtId>
<Amt>
<InstdAmt Ccy="EUR">500.00</InstdAmt>
</Amt>
<Cdtr>
<Nm>John Smith</Nm>
</Cdtr>
<CdtrAcct>
<Id>
<IBAN>LT987654321098765432</IBAN>
</Id>
</CdtrAcct>
<RmtInf>
<Ustrd>Invoice payment for December 2023</Ustrd>
</RmtInf>
</CdtTrfTxInf>
Payment Urgency and SEPA Instantβ
The codes in PmtTpInf (payment type information) set the urgency of each imported payment and can request SEPA Instant for a EUR payment. The urgency is shown in the Urgency field of the payment as Non-urgent, Urgent or Very urgent.
When INST and URGP Are Recognisedβ
INST and URGP are recognised only for account holders that Paysera has switched them on for. What counts is the holder of the account the payments are made from (DbtrAcct), not the user who imports the file. To have them switched on, the account holder contacts Paysera support.
For other account holders, rows 1 and 3 of How Urgency Is Decided do not apply: INST and URGP are ignored and rows 2, 4 and 5 decide. For example, a EUR payment with only LclInstrm/Cd = INST is Non-urgent, and one with SvcLvl/Cd = SDVA and LclInstrm/Cd = INST is Very urgent.
Where to Put PmtTpInfβ
PmtTpInf can be given in PmtInf, where it applies to all transactions of that payment information block, and in CdtTrfTxInf, where it applies to that one transaction:
| Element | In PmtInf | In CdtTrfTxInf |
|---|---|---|
| InstrPrty | Applies to all its transactions | Replaces the PmtInf value for this transaction |
| SvcLvl | Applies to all its transactions | Ignored |
| LclInstrm | Applies to all its transactions | Replaces the PmtInf value for this transaction |
SvcLvl is read only in PmtInf, so a transaction-level LclInstrm does not cancel SvcLvl/Cd = INST given in PmtInf. Give at most one SvcLvl in each PmtTpInf: the pain.001.001.09 schema allows more, but a file with a repeated SvcLvl is rejected.
Inside PmtTpInf the elements go in this order: InstrPrty, SvcLvl, LclInstrm, CtgyPurp. In PmtInf the PmtTpInf block goes after PmtMtd, the optional BtchBookg, and NbOfTxs and CtrlSum (optional in pain.001.001.03, required in pain.001.001.09), right before ReqdExctnDt; in CdtTrfTxInf it goes right after PmtId, before Amt.
How Urgency Is Decidedβ
The first matching row decides. Rows 1 and 3 apply only where INST and URGP are recognised:
| # | Codes in the file | Currency | Urgency shown | How a EUR payment is executed |
|---|---|---|---|---|
| 1 | LclInstrm/Cd = INST, LclInstrm/Prtry = INST or SvcLvl/Cd = INST | EUR | Urgent | SEPA Instant when it is offered for the payment, for example when the beneficiary's bank accepts SEPA Instant payments; otherwise a regular transfer. See When a Payment Cannot Go Instant |
| 2 | SvcLvl/Cd = SDVA | Any | Very urgent | Regular transfer (SEPA within the SEPA area), not instant |
| 3 | SvcLvl/Cd = URGP | EUR | Urgent | As in row 1 |
| 4 | InstrPrty = HIGH | Any | Urgent | As in row 1 |
| 5 | Anything else | Any | Non-urgent | Regular transfer |
- Codes must match exactly. They are case-sensitive:
instorurgpis not recognised, and neither isLclInstrm/Cd=INSTANT; the next rows decide. In a pain.001.001.09 file, a value that the schema does not allow, for exampleInstrPrty=high, rejects the whole file. INSTandURGPcount only for EUR. In other currencies they are ignored and the next rows decide:InstrPrty=HIGHmakes such a payment Urgent andSDVAmakes it Very urgent.SDVAdoes not request SEPA Instant. A payment withSDVAis Very urgent, and a EUR payment withSDVAis executed as a regular transfer. To request SEPA Instant, useLclInstrm/Cd=INSTwhere it is recognised; there, a EUR payment with bothSDVAandINSTis Urgent, because row 1 comes first.
Requesting SEPA Instantβ
A SEPA Instant credit transfer file in the EPC format sets the service level to SEPA and the local instrument to INST. This requests SEPA Instant only where INST is recognised. For all transactions of a PmtInf block:
<PmtTpInf>
<SvcLvl>
<Cd>SEPA</Cd>
</SvcLvl>
<LclInstrm>
<Cd>INST</Cd>
</LclInstrm>
</PmtTpInf>
For one transaction only, give the local instrument in the transaction's own PmtTpInf:
<CdtTrfTxInf>
<PmtId>
<InstrId>TXN-001</InstrId>
<EndToEndId>INV-2023-001</EndToEndId>
</PmtId>
<PmtTpInf>
<LclInstrm>
<Cd>INST</Cd>
</LclInstrm>
</PmtTpInf>
<Amt>
<InstdAmt Ccy="EUR">500.00</InstdAmt>
</Amt>
<Cdtr>
<Nm>John Smith</Nm>
</Cdtr>
<CdtrAcct>
<Id>
<IBAN>LT987654321098765432</IBAN>
</Id>
</CdtrAcct>
<RmtInf>
<Ustrd>Invoice payment for December 2023</Ustrd>
</RmtInf>
</CdtTrfTxInf>
When a Payment Cannot Go Instantβ
- SEPA Instant is not offered for the payment (for example, the beneficiary's bank does not accept SEPA Instant payments) - the payment is executed as a regular transfer and is still shown as Urgent.
- SEPA Instant or the beneficiary's bank is temporarily unavailable when the file is processed - that payment fails with an error saying that SEPA Instant is currently unavailable or that the recipient's bank does not accept instant payments at the moment. The other payments of the file are imported. Import the payment again later, or import it as a non-urgent payment, without
INST,URGPorHIGH.
Signing and Feesβ
- The urgency is decided when the file is imported and does not change when the payments are signed.
- For fees, see Paysera fees for euro transfers.
Complete Example: SEPA Paymentβ
<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03 pain.001.001.03.xsd">
<CstmrCdtTrfInitn>
<!-- GROUP HEADER -->
<GrpHdr>
<MsgId>018be78e4c6aa105d2e26fb28fe6ae40</MsgId>
<CreDtTm>2016-06-23T09:21:13</CreDtTm>
<NbOfTxs>1</NbOfTxs>
<CtrlSum>120</CtrlSum>
<InitgPty>
<Nm>SiuntΔjas</Nm>
</InitgPty>
</GrpHdr>
<!-- PAYMENT INFORMATION -->
<PmtInf>
<PmtInfId>43164652</PmtInfId>
<PmtMtd>TRF</PmtMtd>
<!-- SEPA Service Level -->
<PmtTpInf>
<SvcLvl>
<Cd>SEPA</Cd>
</SvcLvl>
</PmtTpInf>
<ReqdExctnDt>2016-06-23</ReqdExctnDt>
<!-- DEBTOR (PAYER) -->
<Dbtr>
<Nm>SiuntΔjas</Nm>
</Dbtr>
<DbtrAcct>
<Id>
<IBAN>LV70HABA0551016193780</IBAN>
</Id>
</DbtrAcct>
<DbtrAgt>
<FinInstnId>
<BIC>HABALV22XXX</BIC>
</FinInstnId>
</DbtrAgt>
<!-- ULTIMATE DEBTOR -->
<UltmtDbtr>
<Nm>Vardenis Pavardenis</Nm>
<Id>
<OrgId>
<Othr>
<Id>C56251</Id>
<SchmeNm>
<Cd>COID</Cd>
</SchmeNm>
</Othr>
</OrgId>
</Id>
</UltmtDbtr>
<!-- CHARGE BEARER -->
<ChrgBr>SLEV</ChrgBr>
<!-- TRANSACTION -->
<CdtTrfTxInf>
<PmtId>
<InstrId>43164652</InstrId>
<EndToEndId>43164652</EndToEndId>
</PmtId>
<Amt>
<InstdAmt Ccy="EUR">10.00</InstdAmt>
</Amt>
<CdtrAgt>
<FinInstnId>
<BIC>HABALV22XXX</BIC>
</FinInstnId>
</CdtrAgt>
<Cdtr>
<Nm>Vardenis Pavardenis</Nm>
</Cdtr>
<CdtrAcct>
<Id>
<IBAN>LV30HABA0551020958461</IBAN>
</Id>
</CdtrAcct>
<RmtInf>
<Ustrd>Paskirtis</Ustrd>
</RmtInf>
</CdtTrfTxInf>
</PmtInf>
</CstmrCdtTrfInitn>
</Document>
Complete Example: Multiple Paymentsβ
<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03 pain.001.001.03.xsd">
<CstmrCdtTrfInitn>
<!-- GROUP HEADER -->
<GrpHdr>
<MsgId>MSG-SALARIES-2023-12</MsgId>
<CreDtTm>2023-12-15T14:30:25</CreDtTm>
<NbOfTxs>3</NbOfTxs>
<CtrlSum>3500.00</CtrlSum>
<InitgPty>
<Nm>ABC Company Ltd</Nm>
</InitgPty>
</GrpHdr>
<!-- PAYMENT INFORMATION BATCH -->
<PmtInf>
<PmtInfId>SALARY-BATCH-DEC-2023</PmtInfId>
<PmtMtd>TRF</PmtMtd>
<BtchBookg>false</BtchBookg>
<NbOfTxs>3</NbOfTxs>
<CtrlSum>3500.00</CtrlSum>
<ReqdExctnDt>2023-12-30</ReqdExctnDt>
<!-- DEBTOR -->
<Dbtr>
<Nm>ABC Company Ltd</Nm>
</Dbtr>
<DbtrAcct>
<Id>
<IBAN>LT123456789012345678</IBAN>
</Id>
</DbtrAcct>
<DbtrAgt>
<FinInstnId>
<BIC>HABALT22</BIC>
</FinInstnId>
</DbtrAgt>
<!-- TRANSACTION 1 -->
<CdtTrfTxInf>
<PmtId>
<InstrId>SAL-001</InstrId>
<EndToEndId>SALARY-JOHN-DEC</EndToEndId>
</PmtId>
<Amt>
<InstdAmt Ccy="EUR">1200.00</InstdAmt>
</Amt>
<Cdtr>
<Nm>John Smith</Nm>
</Cdtr>
<CdtrAcct>
<Id>
<IBAN>LT111111111111111111</IBAN>
</Id>
</CdtrAcct>
<RmtInf>
<Ustrd>Salary December 2023</Ustrd>
</RmtInf>
</CdtTrfTxInf>
<!-- TRANSACTION 2 -->
<CdtTrfTxInf>
<PmtId>
<InstrId>SAL-002</InstrId>
<EndToEndId>SALARY-JANE-DEC</EndToEndId>
</PmtId>
<Amt>
<InstdAmt Ccy="EUR">1300.00</InstdAmt>
</Amt>
<Cdtr>
<Nm>Jane Doe</Nm>
</Cdtr>
<CdtrAcct>
<Id>
<IBAN>LT222222222222222222</IBAN>
</Id>
</CdtrAcct>
<RmtInf>
<Ustrd>Salary December 2023</Ustrd>
</RmtInf>
</CdtTrfTxInf>
<!-- TRANSACTION 3 -->
<CdtTrfTxInf>
<PmtId>
<InstrId>SAL-003</InstrId>
<EndToEndId>SALARY-BOB-DEC</EndToEndId>
</PmtId>
<Amt>
<InstdAmt Ccy="EUR">1000.00</InstdAmt>
</Amt>
<Cdtr>
<Nm>Bob Johnson</Nm>
</Cdtr>
<CdtrAcct>
<Id>
<IBAN>LT333333333333333333</IBAN>
</Id>
</CdtrAcct>
<RmtInf>
<Ustrd>Salary December 2023</Ustrd>
</RmtInf>
</CdtTrfTxInf>
</PmtInf>
</CstmrCdtTrfInitn>
</Document>
Character Setβ
Supported Charactersβ
XML format supports multilingual UTF-8 encoding. The following Latin character set is mandatory:
Letters:
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
Digits:
0 1 2 3 4 5 6 7 8 9
Special characters:
/ - ? : ( ) . , ' + Space
Character Conversionβ
All other UTF-8 characters in payments are converted according to the EPC recommended conversion table.
Examples of conversion:
| Original | Converted | Description |
|---|---|---|
| Δ | a | Lithuanian |
| Δ | e | Lithuanian |
| Ε³ | u | Lithuanian |
| ΕΎ | z | Lithuanian |
| Γ€ | a | German |
| ΓΆ | o | German |
| β¬ | EUR | Euro symbol |
Validationβ
XSD Schema Validationβ
XML files must be validated against the XSD schema of their version: pain.001.001.03.xsd for pain.001.001.03 files, pain.001.001.09.xsd for pain.001.001.09 files.
xsi:schemaLocation="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03 pain.001.001.03.xsd"
xsi:schemaLocation="urn:iso:std:iso:20022:tech:xsd:pain.001.001.09 pain.001.001.09.xsd"
Control Validationβ
Group Header CtrlSum must equal sum of all amounts:
GrpHdr/CtrlSum = Sum of all CdtTrfTxInf/Amt
Group Header NbOfTxs must equal total transaction count:
GrpHdr/NbOfTxs = Count of all CdtTrfTxInf elements
Payment Info CtrlSum must equal sum of batch amounts:
PmtInf/CtrlSum = Sum of CdtTrfTxInf/Amt in that PmtInf
ISO 20022 Message Elementsβ
For complete message element definitions, refer to:
π ISO 20022 Message Definitions
This includes detailed descriptions of:
- pain.001.001.03 and pain.001.001.09 structures
- Element data types
- Business rules
- Usage guidelines
Downloadsβ
Official Filesβ
π₯ Example XML file - SEPA payment example
π₯ ISO 20022 Documentation - Official standard documentation
Common Use Casesβ
1. SEPA Credit Transfersβ
<PmtMtd>TRF</PmtMtd>
Standard SEPA euro payments within EU/EEA.
2. Salary Paymentsβ
<PmtInf>
<PmtInfId>SALARY-BATCH-2023-12</PmtInfId>
<BtchBookg>false</BtchBookg>
<!-- Multiple employee payments -->
</PmtInf>
Batch processing of multiple salary payments.
3. Supplier Paymentsβ
<RmtInf>
<Ustrd>Invoice INV-2023-001 payment</Ustrd>
</RmtInf>
Payment with invoice reference.
4. International Transfersβ
<CdtrAgt>
<FinInstnId>
<BIC>CHASUS33</BIC>
</FinInstnId>
</CdtrAgt>
Non-SEPA payments with BIC code.
Best Practicesβ
β DOβ
- Validate against XSD schema before sending
- Use UTF-8 encoding
- Include unique message IDs
- Verify control sums match totals
- Provide clear payment descriptions
- Use IBAN format for all accounts
- Include BIC for international transfers
- Use
LclInstrm/Cd=INSTto request SEPA Instant (EUR), where it is switched on for you - Test with small batches first
β DON'Tβ
- Use unsupported special characters
- Exceed field length limits
- Mix different currency in same batch
- Forget namespace declarations
- Use invalid date formats
- Omit mandatory fields
- Use
SDVAto request an instant payment - Create files with multiple Document tags
Error Handlingβ
Common Validation Errorsβ
| Error | Cause | Solution |
|---|---|---|
| Schema validation failed | Invalid XML structure | Check against XSD schema |
| Control sum mismatch | Sum doesn't match total | Recalculate CtrlSum |
| Invalid IBAN | Incorrect account format | Validate IBAN checksum |
| Missing namespace | xmlns not declared | Add proper namespace |
| Invalid characters | Unsupported UTF chars | Use conversion table |
| Wrong date format | Incorrect datetime | Use ISO 8601 format |
XML vs Other Formatsβ
| Feature | XML | MOKESIS | TARESIS | XLS |
|---|---|---|---|---|
| Standard | ISO 20022 | Paysera | Paysera | Manual |
| Structure | Hierarchical | Flat | Flat | Table |
| Validation | XSD schema | Manual | Manual | Manual |
| SEPA | β Native | β | β | β |
| Automation | βββββ | ββββ | ββββ | ββ |
| International | β Full | β Limited | β Full | β |
| Complexity | High | Medium | High | Low |
| Best for | Systems | Bulk | Intl routing | Manual |
When to Use XMLβ
β Use XML format for:
- SEPA credit transfers
- System-to-system integration
- ERP/accounting software exports
- Large volume automated payments
- International standard compliance
- Banking APIs and web services
- Multi-currency transactions
- Structured payment data
β Use other formats for:
- Manual data entry β XLS
- Simple bulk imports β MOKESIS
- Complex routing needs β TARESIS
- FiDAViSta systems β FiDAViSta
Supportβ
Need help with XML format?
- π§ Email: support@paysera.com
- π Phone: Contact Information
- π ISO 20022: www.iso20022.org
Next Stepsβ
- Download example β - Get sample XML file
- Review ISO 20022 β - Study standard
- Generate from your system - Export XML from ERP
- Validate - Check against XSD schema
- Import to Paysera - Upload and process
Additional Resourcesβ
- MOKESIS Format β - Alternative bulk format
- TARESIS Format β - International transfers
- FiDAViSta Format β - ERP integration
- View all formats β - Return to overview