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.1

2023-05-04

Added ErrorClassificationCode

1.2. Response messages in general

This specification concerns the Technical Acknowledgement 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 document types involved and 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 or application 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 Technical Acknowledgement is a document type that is applicable to be exchanged between Pagero and sender/issuer to inform the about the transport of a message but can also contain information on a technical level regarding rejections due to for example schematron errors.

This message type is often referred to as transport level acknowledgement or message level response.

PUF Techical Acknowledgement 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 Technical Acknowledgement 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 Technical Acknowledgement 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

Technical Acknowledgement

urn:pagero.com:puf:technical_acknowledgement:1.0

urn:pagero.com:puf:technical_acknowledgement:1.0

Example

<ApplicationResponse>
  <!-- Code omitted for clarity -->
  <cbc:CustomizationID>urn:pagero.com:puf:technical_acknowledgement:1.0</cbc:CustomizationID>
  <cbc:ProfileID>urn:pagero.com:puf:technical_acknowledgement: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>
</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. Release management

PUF will be continuously updated to meet new market demands.

2.5.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.5.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:technical_acknowledgement:1.0'.

Example
cbc:CustomizationID populated with correct value

<ApplicationResponse>
  <!-- Code omitted for clarity -->
  <cbc:CustomizationID>urn:pagero.com:puf:technical_acknowledgement: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:technical_acknowledgement:1.0'.

Example
cbc:ProfileID populated with correct value

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

cbc:ID

Path Description

cbc:ID

Technical acknowledgement identifer
A unique identifier of the technical acknowledgement.

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 Techical acknowledgement
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>

cac:SenderParty

cac:SenderParty is required according to the UBL XML schema but will not be populated in PUF Technical Acknowledgement.

Example
cac:SenderParty

<ApplicationResponse>
  <!-- Code omitted for clarity -->
  <cac:SenderParty/> (1)
  <!-- Code omitted for clarity -->
</ApplicationResponse>
1 Please note the empty party!

cac:ReceiverParty

cac:ReceiverParty is required according to the UBL XML schema but will not be populated in PUF Technical Acknowledgement.

Example
cac:ReceiverParty

<ApplicationResponse>
  <!-- Code omitted for clarity -->
  <cac:ReceiverParty/>(1)
  <!-- Code omitted for clarity -->
</ApplicationResponse>
1 Please note the empty party!

cac:DocumentResponse

cac:Response

Table 2. 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

Message response code
A code stating whether the referenced message was cleared through validation and advanced to the next step in the process.
A negative response states that the document was not processed because of identified issues.
PUF-018-APPLICATIONRESPONSECODE.

cbc:Description

Response textual notes
A textual note containing comments or instructions relevant to the response.

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:ErrorClassificationCode>18100</puf:ErrorClassificationCode>
              </puf:ResponseExtension>
            </puf:PageroExtension>
          </ext:ExtensionContent>
        </ext:UBLExtension>
      <ext:UBLExtensions>
      <cbc:ResponseCode>RE</cbc:ResponseCode>
        <cbc:Description>Rejected due to schematron validation errors</cbc:Description>
    </cac:Response>
  <!-- Code omitted for clarity -->
</ApplicationResponse>

cac:DocumentReference

Table 3. Elements available in cac:DocumentReference
Path Description

cbc:ID

Document identifier
Identifer of the referenced document (e.g. invoice number).

cbc:IssueDate

Issue date
The date on which the referenced document was issued.
Format must be "YYYY-MM-DD".

cbc:DocumentTypeCode

Document type code
Type code of the referenced document (e.g. 380=Invoice, 381 Credit note etc.). For valid values see code list
PUF-019-DOCUMENTREFERENCEDOCTYPECODE.

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 4. 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:ErrorClassificationCode

Error classification code
An internal error code set by Pagero in the case that the error is classifiable.
See PUF-020-ERRORCLASSIFICATIONCODE.

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:ErrorClassificationCode>18100</puf:ErrorClassificationCode>
              </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 5. Table of the code lists used
Business Term Path listID

Message response code

cac:DocumentResponse/cac:Response/cbc:ResponseCode

PUF-018-APPLICATIONRESPONSECODE.

Error Classification Code

cac:DocumentResponse/cac:Response/ext:UBLExtensions /ext:UBLExtension/ext:ExtensionContent/puf:PageroExtension /puf:ResponseExtension/puf:ErrorClassificationCode

PUF-020-ERRORCLASSIFICATIONCODE.

6. XML schemas

The PUF Technical Acknowledgement XML schemas including Pagero/PUF Extension can be downloaded here:

7. 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.

8. Examples

Example files can be downloaded here:

9. Support

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