A specification based on Universal Business Language (UBL) that enables the exchange of compliant business documents worldwide via our e-business platform Pagero Online.

1. Introduction

Pagero Universal Format, hereafter referred to as "PUF", is a collection of business document specifications developed and maintained by Pagero Group.

All response message types within the PUF suite implement the UBL 2.3 XML structure.

The PUF landing page lists all document types supported in the suite and in which directions these are available.

To align with new regulation and business needs throughout the world, the core idea of PUF is to enable its users to send/receive the data required to meet requirements in these markets and jurisdictions.

Based on extensive analysis, PUF has been designed to meet various country-, industry-, format- and/or system-specific requirements.

Another core idea of PUF is to create flexible, extendable business document specifications which can be updated quickly to meet the requirements of the fast-changing global electronic document landscape.

PUF will to a large extent try to follow and align with the work done in OpenPeppol and other UBL based specifications.

1.1. Version and changelog

Table 1. Version

Version

Date

Description

1.0

2023-01-27

First version published.

1.2. Response messages in general

This specification concerns the Invoice Response message type.

When issuing an electronic document (e.g. electronic invoice or other document type) there might be a need to inform about the process status of that document during its lifecycle.

This can include information about the transport of a message, status regarding clearance/reporting of a message or status of a message concerning the recipients approval or rejection etc.

Depending on which legal domain the document issuer operates in, the need for various response messages might differ.

The response message types available in the PUF suite for use in Pagero Online are:

Example: A possible orchestation of messages supporting a market where invoices are required to be reported to a clearance authority and where a buyer has the possibility to send an invoice response.

response messages overview

1.2.1. Technical acknowledgement

This type of response message is mainly used to inform a sender about the transport of a document from
point A to B.

In addition, in Pagero Online the use of technical acknowledgements is used for informing the sender about technical validation results such as XML schema validations, schematron errors etc.

1.2.2. Clearance notification

The use of the Clearance Notification message type is applicable in clearance and CTC markets where documents needs to be cleared or reported to the government or another assigned authority.

It will inform the issuer of an document of the clearance/reporting status (i.e. rejected or accepted) but can also contain clearance artefacts such as QR codes or a signed cleared document.

1.2.3. Invoice response

This is often referred to as business level response.

It is a document issued by the recipient/buyer to inform the issuer of an invoice about business decisions.

The delivered invoice may be technically correct and delivered to the recipient/buyer but there might be the need for a buyer to inform the issuer if the invoice is accepted or if there is a reason for a rejection.

2. Guidelines

PUF Invoice Response is a document type that is applicable to be exchanged between buyer/receiver and supplier/issuer to inform the issuer of an invoice about business decisions.

This is often referred to as business level response.

PUF Invoice Response is developed to be compliant to the UBL 2.3 schema.

In areas where support for certain information is available in the existing UBL 2.3 schema, PUF implements these elements.

In other areas where there are no suitable elements in the existing UBL 2.3 schema, PUF implements ext:UBLExtensions.

2.1. How to get started

In the following chapters you can see which elements and what type of information that PUF Invoice Response supports.

In some cases we provide longer snippets of code and implementation guidelines describing how to properly interpret the data.

There is also a section with Examples that can be useful when building support for PUF Invoice Response in various markets.

If your ERP system already can receive/issue documents in UBL 2.3 or if your ERP system can interpret/create another UBL 2.3 based format you can easily use this as stepping stone when moving towards PUF.

2.2. Namespaces

Target root name space - ApplicationResponse:

  • urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2

Example:
ApplicationResponse example for target namespace

<ApplicationResponse xmlns="urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2">
  <!-- Code omitted for clarity -->
</ApplicationResponse>

2.3. Customization and Profile ID

To indicate the correct PUF specification identifer and the profile identifier, the values in below table must be sent in cbc:CustomizationID and cbc:ProfileID.

Type Element cbc:CustomizationID Element cbc:ProfileID

Invoice Response

urn:pagero.com:puf:invoice_response:1.0

urn:pagero.com:puf:invoice_response:1.0

Example

<ApplicationResponse>
  <!-- Code omitted for clarity -->
  <cbc:CustomizationID>urn:pagero.com:puf:invoice_response:1.0</cbc:CustomizationID>
  <cbc:ProfileID>urn:pagero.com:puf:invoice_response:1.0</cbc:ProfileID>
  <!-- Code omitted for clarity -->
</ApplicationResponse>

2.4. Working with extensions

This chapter provides an overview the use of extensions.

In order to facilitate the use of PUF specific extensions, an additional XML schema is provided.

The PUF-ExtensionComponent.xsd can be found together with the other schemas in chapter XML schemas.

To be able to use the PUF-ExtensionComponent, its namespace must be included in the document file.

Example
Example from ApplicationResponse

<ApplicationResponse ... xmlns:puf="urn:pagero:ExtensionComponent:1.0">
  <!-- Code omitted for clarity -->
</ApplicationResponse>

Depending on in which context the UBLExtensions are used, there are different options for what types of values that can be provided.

To identify which context the UBLExtensions is in, the element ExtensionURI is used.

When using these Pagero extensions, the URI always has the same base:

  • urn:pagero:ExtensionComponent:1.0:PageroExtension

After this URI, the specific resource name is added.

Example
UBLExtension used in the cac:Response structure.

<ApplicationResponse>
  <!-- Code omitted for clarity -->
  <cac:Response>
    <ext:UBLExtensions>
      <ext:UBLExtension>
        <ext:ExtensionURI>urn:pagero:ExtensionComponent:1.0:PageroExtension:ResponseExtension</ext:ExtensionURI>
        <!-- Code omitted for clarity -->
  </cac:Response>
  <!-- Code omitted for clarity -->
</ApplicationResponse>

For detailed examples and how to use possible values in each extension please see the chapters where PUF-specific elements are described.

2.5. Document reference matching

Below information is only applicable when sending PUF Invoice Response to Pagero.

An Invoice Response always corresponds to an Invoice document. When transmitting the PUF Invoice Response, there are several methods by which Pagero Online establishes a connection between the Invoice Response and its corresponding Invoice (assuming the Invoice is present within Pagero Online).

Pagero Online will attempt to match the response based on specific values. The xpaths for these are prioritized and used in the sequence listed below:

  1. cac:DocumentResponse/cac:Response/ext:UBLExtensions/ext:UBLExtension[ext:ExtensionURI = 'urn:pagero:ExtensionComponent:1.0:PageroExtension:ResponseExtension']/ext:ExtensionContent/puf:PageroExtension/puf:ResponseExtension/puf:DocumentMatchingID/cbc:ID

  2. cac:DocumentResponse/cac:Response/ext:UBLExtensions/ext:UBLExtension[ext:ExtensionURI = 'urn:pagero:ExtensionComponent:1.0:PageroExtension:ResponseExtension']/ext:ExtensionContent/puf:PageroExtension/puf:ResponseExtension/puf:DocumentMatchingID/cbc:UUID

  3. Combined segment information:

    • cac:DocumentResponse/cac:Response/cac:DocumentReference/cbc:ID

    • cac:DocumentResponse/cac:Response/cac:DocumentReference/cbc:IssueDate

    • cac:SenderParty/cac:PartyIdentification/cbc:ID

    • cac:ReceiverParty/cac:PartyIdentification/cbc:ID

For this last option, the identifiers (cac:PartyIdentification/cbc:ID) from both the sender and receiver parties must correspond to those present in the Invoice document within Pagero Online. Additionally, the invoice number and date should also align.

You can read more about DocumentMatchingID in puf:ResponseExtension

If Pagero Online is unable to match the referenced document, the identifiers provided in cac:ReceiverParty will be used for routing the response to the recipient.

2.6. Release management

PUF will be continuously updated to meet new market demands.

2.6.1. Minor release

A minor release will always be backward compatible and will take place without prior notice and will be implemented whenever needed.

Minor releases may include bugfixes, new elements, schematron updates and other features.

To be automatically notified of all releases, please "Watch" the project repository on GitHub.

2.6.2. Major release

A major release may include changes that are not backward compatible.

Such a release will be notified at least three months prior to date of implementation, to users who registered an account on Pagero validex or on GitHub.

To register for PUF major release notification you can create a free account on Pagero Validex.

But we strongly urge all interested parties to "Watch" the project repository on GitHub where all releases will trigger automatic notifications.

3. Syntax

The chapter describes the ApplicationResponse syntax binding and all available document content.

ApplicationResponse

This is the root element in the UBL XML schema.

cbc:CustomizationID

Path Description

cbc:CustomizationID

Document specification identifier
Must be value 'urn:pagero.com:puf:invoice_response:1.0'.

Example
cbc:CustomizationID populated with correct value

<ApplicationResponse>
  <!-- Code omitted for clarity -->
  <cbc:CustomizationID>urn:pagero.com:puf:invoice_response:1.0</cbc:CustomizationID>
  <!-- Code omitted for clarity -->
</ApplicationResponse>

cbc:ProfileID

Path Description

cbc:ProfileID

Business process type
Identifies the business process.
Must be value 'urn:pagero.com:puf:invoice_response:1.0'.

Example
cbc:ProfileID populated with correct value

<ApplicationResponse>
  <!-- Code omitted for clarity -->
  <cbc:ProfileID>urn:pagero.com:puf:invoice_response:1.0</cbc:ProfileID>
  <!-- Code omitted for clarity -->
</ApplicationResponse>

cbc:ID

Path Description

cbc:ID

Invoice reponse identifer
A unique identifier of the invoice reponse.

Example
cbc:ID with example value

<ApplicationResponse>
  <!-- Code omitted for clarity -->
  <cbc:ID>51234882</cbc:ID>
  <!-- Code omitted for clarity -->
</ApplicationResponse>

cbc:IssueDate

Path Description

cbc:IssueDate

Issue date of the invoice reponse
Format must be "YYYY-MM-DD".

Example
cbc:IssueDate with example value

<ApplicationResponse>
  <!-- Code omitted for clarity -->
  <cbc:IssueDate>2021-01-30</cbc:IssueDate>
  <!-- Code omitted for clarity -->
</ApplicationResponse>

cbc:IssueTime

Path Description

cbc:IssueTime

The time at which the transaction instance was issued.
Format must be "HH:mm:ss".

Example
cbc:IssueTime with example value

<ApplicationResponse>
  <!-- Code omitted for clarity -->
  <cbc:IssueTime>21:32:52</cbc:IssueTime>
  <!-- Code omitted for clarity -->
</ApplicationResponse>

cbc:Note

Path Description

cbc:Note

Note
Free text, can be repeated multiple times.

Example
cbc:Note example

<ApplicationResponse>
  <!-- Code omitted for clarity -->
  <cbc:Note>This</cbc:Note>
  <cbc:Note>is a</cbc:Note>
  <cbc:Note>free text example</cbc:Note>
  <!-- Code omitted for clarity -->
</ApplicationResponse>

cac:SenderParty

Table 2. Elements available in cac:SenderParty
Path Description

cbc:EndpointID

Electronic Identifier
Sender’s electronic address.

cbc:EndpointID/@schemeID

Electronic Identifier scheme ID
Scheme identifier of electronic address.
According to code list PUF-007-ENDPOINTSCHEME.

cac:PartyIdentification/cbc:ID

Sender party identifier
Identifier of the sender.

cac:PartyIdentification/cbc:ID/@schemeID

Sender party identifier scheme id
Scheme identifier of sender identifier.
Value according to code list
PUF-008-IDENTIFICATIONSCHEME.

cac:PartyLegalEntity/cbc:RegistrationName

Sender party name
Sender party name.

cac:Contact/cbc:Name

Sender party contact point name
Name of the sending party contact point for communication regarding this message.

cac:Contact/cbc:Telephone

Sender party contact point telephone
Telephone number of the sending party contact point for communication regarding this message.

cac:Contact/cbc:ElectronicMail

Sender party contact point email
Email of the sending party contact point for communication regarding this message.

Example
cac:SenderParty with example values

<ApplicationResponse>
  <!-- Code omitted for clarity -->
  <cac:SenderParty>
    <cbc:EndpointID schemeID="0088">7310000000000</EndpointID>
      <cac:PartyLegalEntity>
        <cbc:RegistrationName>Sender party name</cbc:Name>
      </cac:PartyLegalEntity>
  </cac:SenderParty>
  <!-- Code omitted for clarity -->
</ApplicationResponse>

cac:ReceiverParty

Table 3. Elements available in cac:ReceiverParty
Path Description

cbc:EndpointID

Electronic Identifier
Receiver’s electronic address.

cbc:EndpointID/@schemeID

Electronic Identifier scheme ID
Scheme identifier of electronic address.
According to code list PUF-007-ENDPOINTSCHEME.

cac:PartyIdentification/cbc:ID

Receiver party identifier
Identifier of the receiver.

cac:PartyIdentification/cbc:ID/@schemeID

Receiver party identifier scheme id
Scheme identifier of receiver identifier.
PUF-008-IDENTIFICATIONSCHEME.

cac:PartyLegalEntity/cbc:RegistrationName

Receiver’s party name
The name of the party receiving the response.

Example
cac:ReceiverParty with example values

<ApplicationResponse>
  <!-- Code omitted for clarity -->
  <cac:ReceiverParty>
      <cbc:EndpointID schemeID="0088">7310000000000</EndpointID>
      <cac:PartyLegalEntity>
        <cbc:RegistrationName>Receiver party name</cbc:Name>
      </cac:PartyLegalEntity>
  </cac:ReceiverParty>
  <!-- Code omitted for clarity -->
</ApplicationResponse>

cac:DocumentResponse

cac:Response

Table 4. Elements available in cac:Response
Path Description

ext:UBLExtensions

Extension Content
Extension is added to provide additional information in the cac:Response element, added elements in regards to ext:UBLExtensions for cac:Response can be found below:
Response extension.

cbc:ResponseCode

Invoice status
A code stating the status of the invoice in the process.
Value according to code list
PUF-016-INVOICESTATUSCODE.

cac:Status/cbc:StatusReasonCode

Status reason code
A code defining a clarification given for the status.

cac:Status/cbc:StatusReasonCode/@listID

Status reason code list identifier
List identifier for clarification
Should only be used if following Peppol Status Clarification Reason codes.

cac:Status/cbc:StatusReason

Status reason text
The description of the clarification given for the status.

Example
cac:Response with example values

<ApplicationResponse>
    <!-- Code omitted for clarity -->
    <cac:DocumentResponse>
        <cac:Response>
            <ext:UBLExtensions>
                <ext:UBLExtension>
                    <ext:ExtensionURI>urn:pagero:ExtensionComponent:1.0:PageroExtension:ResponseExtension</ext:ExtensionURI>
                    <ext:ExtensionContent>
                        <puf:PageroExtension>
                            <puf:ResponseExtension>
                                <puf:ReferencedDocumentInterchangeID>
                                    <cbc:ID>123456789</cbc:ID>
                                </puf:ReferencedDocumentInterchangeID>
                                <puf:DocumentMatchingID>
                                    <!-- Either cbc:ID or cbc:UUID can be used, see Extensions documentation -->
                                    <cbc:ID>123456789</cbc:ID>
                                    <cbc:UUID>4408ca72-f3c0-11ed-a05b-0242ac120003</cbc:UUID>
                                </puf:DocumentMatchingID>
                                <puf:AdditionalDocumentReference>
                                    <cbc:ID>1456123</cbc:ID>
                                    <cbc:DocumentTypeCode>M</cbc:DocumentTypeCode>
                                    <cbc:DocumentDescription>LCD</cbc:DocumentDescription>
                                    <cac:Attachment>
                                        <cbc:EmbeddedDocumentBinaryObject filename="123456789_12345.xml" mimeCode="application/xml">U29tZSBkb2N1bWVudA==</cbc:EmbeddedDocumentBinaryObject>
                                    </cac:Attachment>
                                </puf:AdditionalDocumentReference>
                            </puf:ResponseExtension>
                        </puf:PageroExtension>
                    </ext:ExtensionContent>
                </ext:UBLExtension>
            </ext:UBLExtensions>
            <cbc:ResponseCode>APPROVED</cbc:ResponseCode>
            <cac:Status>
                <cbc:StatusReasonCode>XSD_ZATCA_VALID</cbc:StatusReasonCode>
                <cbc:StatusReason>Complied with UBL 2.1 standards in line with ZATCA specifications</cbc:StatusReason>
            </cac:Status>
        </cac:Response>
        <!-- Code omitted for clarity -->
</ApplicationResponse>

cac:DocumentReference

Table 5. Elements available in cac:DocumentReference
Path Description

cbc:ID

Invoice identifier
Reference to the invoice (invoice number).

cbc:IssueDate

Invoice issue date
The date on which the referenced invoice was issued.
Format must be "YYYY-MM-DD".

cbc:DocumentTypeCode

Document type code
Type code of the referenced invoice (e.g. 380=Invoice, 381 Credit note etc.). For valid values see code list:
PUF-019-DOCUMENTREFERENCEDOCTYPECODE.
Note that not all codes are applicable in PUF Invoice Response.

Example
cac:DocumentReference with example values

<ApplicationResponse>
  <!-- Code omitted for clarity -->
  <cac:DocumentResponse>
    <cac:Response>
      <!-- Code omitted for clarity -->
      <cac:DocumentReference>
            <cbc:ID>INV002</cbc:ID>
            <cbc:IssueDate>2022-09-07</cbc:IssueDate>
            <cbc:DocumentTypeCode>380</cbc:DocumentTypeCode>
        </cac:DocumentReference>
      <!-- Code omitted for clarity -->
    </cac:Response>
  <!-- Code omitted for clarity -->
</ApplicationResponse>

4. Extensions

4.1. Response extension

Below chapter describes the elements added in cac:DocumentResponse/cac:Response/ext:UBLExtensions.

4.1.1. puf:ResponseExtension

Below table shows the definition of elements added to the extension puf:PageroExtension/puf:ResponseExtension.

Table 6. Elements added in puf:ResponseExtension
Element Description

puf:ReferencedDocumentInterchangeID/cbc:ID

Referenced document interchange identifier
The interchange id of the referenced document (if sent by the issuer).
This ID is applicable when you receive a response. Then this ID will be the interchange ID (if sent) of the Invoice.

puf:DocumentMatchingID/cbc:ID

Referenced document matching identifier
The unique Pagero ID used to match the response to an Invoice.
This ID is applicable when you send a response.
Then this ID can be sent to facilitate a matching/connection between the response to the Invoice in Pagero Online.

puf:DocumentMatchingID/cbc:UUID

Referenced API document matching identifier
The unique Pagero UUID used to match the response to an Invoice.
This ID is applicable when you send a response.
The UUID is only availble via Document API when using GET documents.

puf:AdditionalDocumentReference/cbc:ID

Additional document reference identifier
If there are any attachments that relates to the response.
Identifier of the additional document reference.

puf:AdditionalDocumentReference/cbc:DocumentTypeCode

Additional document reference type code
Type of attachment.
M = Miscellaneous

puf:AdditionalDocumentReference/cbc:DocumentDescription

Additional document reference description
Description of the attached document.

puf:AdditionalDocumentReference/cac:Attachment/
cbc:EmbeddedDocumentBinaryObject/@filename

Additional document reference filename
Filename of the attached document.

puf:AdditionalDocumentReference/cac:Attachment/
cbc:EmbeddedDocumentBinaryObject/@mimeCode

Additional document reference MIME code
MIME code of the attached document.
Supported MIME codes can be found in the code list
PUF-006-MIMECODES.

puf:AdditionalDocumentReference/cac:Attachment/
cbc:EmbeddedDocumentBinaryObject

Additional document reference binary object
The attached document embedded as binary object (Base64).

See example below as well as the URI to be used for this extension.

Example
puf:ResponseExtension with sample values.

<ApplicationResponse>
    <!-- Code omitted for clarity -->
    <cac:DocumentResponse>
        <cac:Response>
            <ext:UBLExtensions>
                <ext:UBLExtension>
                    <ext:ExtensionURI>urn:pagero:ExtensionComponent:1.0:PageroExtension:ResponseExtension</ext:ExtensionURI>
                    <ext:ExtensionContent>
                        <puf:PageroExtension>
                            <puf:ResponseExtension>
                                <puf:ReferencedDocumentInterchangeID>
                                    <cbc:ID>123456789</cbc:ID>
                                </puf:ReferencedDocumentInterchangeID>
                                <puf:DocumentMatchingID>
                                    <!-- Either cbc:ID or cbc:UUID can be used, see Extensions documentation -->
                                    <cbc:ID>123456789</cbc:ID>
                                    <cbc:UUID>4408ca72-f3c0-11ed-a05b-0242ac120003</cbc:UUID>
                                </puf:DocumentMatchingID>
                                <puf:AdditionalDocumentReference>
                                    <cbc:ID>1456123</cbc:ID>
                                    <cbc:DocumentTypeCode>M</cbc:DocumentTypeCode>
                                    <cbc:DocumentDescription>LCD</cbc:DocumentDescription>
                                    <cac:Attachment>
                                        <cbc:EmbeddedDocumentBinaryObject filename="123456789_12345.xml" mimeCode="application/xml">U29tZSBkb2N1bWVudA==</cbc:EmbeddedDocumentBinaryObject>
                                    </cac:Attachment>
                                </puf:AdditionalDocumentReference>
                            </puf:ResponseExtension>
                        </puf:PageroExtension>
                    </ext:ExtensionContent>
                </ext:UBLExtension>
            </ext:UBLExtensions>
        </cac:Response>
        <!-- Code omitted for clarity -->
</ApplicationResponse>

5. Code lists

Certain elements require the use of PUF specific code lists. Below you will find the lists and where the lists are applicable.

In some of these code lists PUF only points towards an external code list to be used.

Other times the code list to be used is a mix between values defined specifically for PUF and other external list(s).

Lastly, in some cases, all the values are defined solely for PUF.

5.1. Code lists for coded elements

Table 7. Table of the code lists used
Business Term Path listID

Mime code

cac:DocumentResponse/cac:Response/ext:UBLExtensions/ext:UBLExtension
[ext:ExtensionURI='urn:pagero:ExtensionComponent:1.0:PageroExtension
:ResponseExtension']/ext:ExtensionContent/puf:PageroExtension/
puf:ResponseExtension/puf:AdditionalDocumentReference/
cac:Attachment/cbc:EmbeddedDocumentBinaryObject/@mimeCode

PUF-006-MIMECODES

Electronic address scheme

cac:AccountingSupplierParty/cac:Party/cbc:EndpointID/@schemeID
cac:AccountingCustomerParty/cac:Party/cbc:EndpointID/@schemeID

PUF-007-ENDPOINTSCHEME

Identification scheme

cac:AccountingSupplierParty/cac:Party/cac:PartyIdentification/
cbc:ID/@schemeID
cac:AccountingSupplierParty/cac:Party/cac:PartyLegalEntity/
cbc:CompanyID/@schemeID

PUF-008-IDENTIFICATIONSCHEME

Invoice status codes

cac:DocumentResponse/cac:Response/cbc:ResponseCode

PUF-016-INVOICESTATUSCODE

6. XML schemas

The PUF Invoice Response XML schemas including Pagero/PUF Extension can be downloaded here:

7. Excel specification

This document refers to an Excel file that serves as an additional mapping guide for the Pagero Universal Format (PUF) in complement to the online documentation. It’s designed to provide an essential understanding of the structure and core components of the PUF.

Please note that the guide is intended to be used only when sending PUF Invoice Response.

The Excel file can be accessed through the following link:

8. Validation

To validate PUF documents please create a free account on Pagero Validex.

The validations available on Validex are:

  1. XML well-formedness

  2. XSD schema

  3. PUF business (schematron) rules (if applicable)

The validation artefacts are also available on GitHub.

9. Examples

Example files can be downloaded here:

10. Support

If you have any questions related to PUF, please create a support ticket via Pagero Support.