Mapping a SEPA payment to the CESOP XML schema
Mapping a SEPA payment to the CESOP XML schema is mostly mechanical — until you hit the parts where the schema asks for data your payment messages do not carry. This is the technical companion to our CESOP overview: a field-by-field walkthrough of how a single euro-zone credit transfer turns into one CESOP record, and where most engineering teams spend the longest.
1. Recap — what CESOP wants
CESOP captures cross-border payments where the payee is the focus. For each reportable payment, the schema asks for:
- The payee’s identification (name, address, IBAN, BIC, VAT number where known).
- The payment amount, currency and date.
- The payment-method code.
- The location of the payee (member-state-of-payee designation).
- A flag indicating whether the payment is a refund of an earlier reportable transaction.
The payer is not in scope. The schema is concerned with the merchant or recipient side of the transaction.
2. The CESOP XML structure, in plain terms
The schema (CESOP-XSD-v4.04 at the time of writing, maintained by DG TAXUD at the European Commission) has three tiers:
- Message header — identifies the reporting PSP, the reporting period and the recipient member-state tax authority.
- Reporting PSP block — the PSP’s BIC, country and identifier.
- Reported transactions — one element per reportable payment, repeated for as many records as exist in the reporting period.
Each transaction element carries the payee block, the payment block, and the optional refund linkage block.
3. Mapping a pacs.008 credit transfer, field by field
SEPA credit transfers travel as ISO 20022 pacs.008 (FIToFICstmrCdtTrf) messages between PSPs. The mapping into CESOP fields, for the payee’s PSP perspective:
| CESOP field | Source in pacs.008 | Notes |
|---|---|---|
| Payee name | CdtrAcct/Cdtr/Nm | Use the registered customer name from your customer master if present and reconciled; the message field is canonical. |
| Payee IBAN | CdtrAcct/Id/IBAN | Strip whitespace; preserve as ISO 13616 canonical form. |
| Payee BIC | CdtrAgt/FinInstnId/BICFI | BIC of the payee’s PSP; from this you derive the member-state of the payee. |
| Payee address | Cdtr/PstlAdr or customer master | Where pacs.008 omits address, fall back to the customer master entry. |
| Payee VAT number | Customer master only | Not carried in pacs.008; CESOP wants it where you hold it. |
| Payment amount | IntrBkSttlmAmt | Settlement amount in original currency. |
| Payment date | IntrBkSttlmDt | The settlement date is the CESOP reference date. |
| End-to-end reference | EndToEndId | Used to link refunds to original payments. |
| Payment-method code | Derived | Set per CESOP code list — for SEPA SCT or SCT Inst this is a SEPA-credit-transfer code. |
| Member-state-of-payee | Derived from CdtrAgt/BICFI country prefix and IBAN country code | The two should agree; investigate when they do not. |
| Refund flag | Derived | Set true when the payment links to an earlier reportable record via OrgnlEndToEndId on a pacs.002 / pacs.004. |
4. Refunds — the pacs.002 / pacs.004 link
For SEPA, refunds and reversals come as pacs.004 (PaymentReturn) messages or pacs.002 (FIToFIPaymentStatusReport) for cancellations. Both carry an OrgnlEndToEndId referencing the original payment. The CESOP refund flag is set, the refund amount populated, and the original record’s identifier referenced.
5. The 25-payment threshold — applied at output, not intake
CESOP requires reporting of every cross-border payment to a payee that received at least 25 cross-border payments from your PSP in the quarter. The implication for the data pipeline:
- You cannot report transactions in real time — you need a quarterly aggregation step that counts payments per payee.
- Once a payee crosses 25 in a quarter, every payment to that payee in that quarter is reportable, including the first 24.
- The aggregation runs at the level of payee identifier — typically IBAN or, where present, VAT number. Pick a stable identifier and document it.
6. Determining the payee’s member state
CESOP wants the member state where the payee is located. For SEPA, this is derived from:
- The IBAN country code (positions 1–2) — the country of the account.
- The BIC’s country (positions 5–6) — the country of the payee’s PSP.
The two usually agree. They diverge in cases where a PSP serves customers across borders — for example, a Spanish PSP holding a French IBAN for a French resident. The CESOP guidance is to use the IBAN country code as the primary signal, but document the rule and apply it consistently.
7. Validation gotchas
Most CESOP submissions that fail validation fail for one of three reasons:
- Date format. CESOP wants ISO 8601 in the schema’s specific tightenings. A pacs.008 date that looks valid can be rejected on a CESOP namespace check.
- Country codes. ISO 3166-1 alpha-2 throughout. Three-letter codes from internal systems will fail.
- Empty optional blocks. Optional fields must be omitted, not present-with-empty. A self-closing tag in place of an absent VAT number breaks validation.
8. The multi-state submission problem
The CESOP schema produces one XML file. The submission obligation runs to each member state where you have a payment leg — typically up to 27, depending on your reach. For a PSP under Freedom of Services, this is the structural cost of the regime. Each member state’s tax authority operates its own portal with its own credentials. The XML body is the same; the wrapper, authentication and submission acknowledgement differs per portal.
The build / buy / hybrid choice on this is covered in our CESOP overview piece.
9. FAQ
Where can I download the official CESOP XML schema?
The schema and reporting guidelines are published by the European Commission’s Directorate-General for Taxation and Customs Union (DG TAXUD). They are versioned — keep an eye on the version number across reporting periods.
Does pacs.008 carry the VAT number?
No. ISO 20022 SEPA messages do not carry VAT numbers. CESOP requires it where the PSP holds it — the data must come from your customer master, not from the message stream.
What is the CESOP code for an SCT Inst payment?
The payment-method codes are listed in the reporting guidelines. SCT and SCT Inst share the same family of codes; the schema distinguishes via a sub-attribute.
How do I handle a payment where the payer’s IBAN and BIC disagree on country?
The payer is not in scope of CESOP. Only the payee’s location matters for the report. Diverging payer-side metadata is not a CESOP problem.
What about card payments?
Card payments are in scope of CESOP through a different processing flow — typically captured at the acquiring PSP via card-scheme settlement messages, not pacs.008. The CESOP schema accommodates both with separate payment-method codes.
Can I batch refunds with their original payments in one record?
No. The schema requires one record per reportable payment, with refunds appearing as separate records that reference the original via the refund-linkage block.
10. What to do, today
- Pull a sample week of pacs.008 messages from your settlement bus and dry-map them through the table above.
- Identify the fields that come from your customer master rather than the message — those are the longest data-quality work.
- Decide your payee-identifier strategy (IBAN vs VAT) and document it.
- Build the quarterly threshold aggregation as a batch step before the XML generator, not inside it.
- Validate against the published XSD before sending, on every submission cycle.
Related: What is CESOP reporting? · What is the IPR report? · How to launch Dutch IBANs
