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

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 a 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 Clearance Notification is a document type that is applicable to be exchanged in clearance and CTC markets between Pagero and the issuer of a document.

It will inform the issuer 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.

PUF Clearance Notification 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 Clearance Notification 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 Clearance Notification in various markets.

If your ERP system already can receive documents in UBL 2.3 or if your ERP system can interpret 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

Clearance Notification

urn:pagero.com:puf:clearance_notification:1.0

urn:pagero.com:puf:clearance_notification:1.0

Example

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

Example
cbc:CustomizationID populated with correct value

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

Example
cbc:ProfileID populated with correct value

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

cbc:ID

Path Description

cbc:ID

Clearance notification identifer
A unique identifier of the clearance notification.

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 clearance notification
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

cac:PartyName/cbc:Name

Sender party name
Clearance authority name.

Example
cac:SenderParty with example values

<ApplicationResponse>
  <!-- Code omitted for clarity -->
  <cac:SenderParty>
      <cac:PartyName>
        <cbc:Name>Clearance authority name</cbc:Name>
      </cac:PartyName>
  </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.
Value according to code list
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 here: Response extension.

cbc:ResponseCode

Clearance/reporting response codes
Value according to code list PUF-017-CLEARANCESTATUSCODE.

cac:Status/cbc:StatusReasonCode

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

cac:Status/cbc:StatusReason

Status reason text
The description of the clarification given for the notification 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:ClearanceReferenceID>
                    <cbc:ID>4543f3ed-8c20-4eee-a19f-486025fe2773</cbc:ID>
                  </puf:ClearanceReferenceID>
                  <puf:ClearanceQR>
                    <puf:QRString>VGhlIFFSIENvZGU=</puf:QRString>
                  </puf:ClearanceQR>
                  <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: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

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

Response extension

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

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:RestrictedInformation/puf:Key

Key
Key defining the type of value.

puf:RestrictedInformation/puf:Value

Value
Value relevant to the assigned key.

puf:ReferencedDocumentInterchangeID/cbc:ID

Referenced document unique ID
The interchange id of the referenced document (if sent by the issuer).

puf:ClearanceReferenceID/cbc:ID

Clearance reference ID
The ID generated by the clearance authority or an ID used to reference the invoice at clearance authority.

puf:ClearanceQR/puf:QRString

Clearance QR code
The QR string as generated by clearance authority.

puf:AdditionalDocumentReference/cbc:ID

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

puf:AdditionalDocumentReference/cbc:DocumentTypeCode

Additional document type code
Type of attachment.
M = Miscellaneous

puf:AdditionalDocumentReference/cbc:DocumentDescription

Additional document description
Description of the attached document.

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

Additional document filename
Filename of the attached document.

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

Additional document 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 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:RestrictedInformation>
                    <puf:Key>TheKey</puf:Key>
                    <puf:Value>TheValue</puf:Value>
                  </puf:RestrictedInformation>
                  <puf:ReferencedDocumentInterchangeID>
                    <cbc:ID>123456789</cbc:ID>
                  </puf:ReferencedDocumentInterchangeID>
                  <puf:ClearanceReferenceID>
                    <cbc:ID>4543f3ed-8c20-4eee-a19f-486025fe2773</cbc:ID>
                  </puf:ClearanceReferenceID>
                  <puf:ClearanceQR>
                    <puf:QRString>VGhlIFFSIENvZGU=</puf:QRString>
                  </puf:ClearanceQR>
                  <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. Country specifics

This section will provide information regarding on how to include common country specific data in PUF.

The aim for PUF is to cover business requirements in legal domains and countries all over the world.

The below list should be seen as an overview to visualize where PUF currently is considered applicable.

If the country is marked as supported means that an analysis of country or regional requirements has been made.

It does not, however, automatically mean that all conceivable content requirements are supported within PUF.

If a country is not in the list it does not necessarily mean that PUF cannot be used in the specific region but it means that no extensive analysis has been done of the requirements.

The list of supported countries/regions are updated continuously as PUF is developed to follow new identified markets/requirements.

5.1. Supported countries

The following list gives an overview of country support in PUF Clearance Notification.

The "Require ext:UBLExtensions?"-column indicates whether or not the use of UBL extensions is required to be able to comply with the country requirements.
Table 7. Table of supported countries
Country Supported by PUF Require ext:UBLExtensions? Comment

Greece

Yes

Yes

-

Hungary

Yes

Yes

-

India

Yes

Yes

-

Israel

Yes

Yes

-

Poland

Yes

Yes

-

Saudi Arabia

Yes

Yes

-

Serbia

Yes

Yes

-

Spain (Basque Country)

Yes

Yes

Support for TicketBAI system in the Basque region.

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

6.1. Code lists for coded elements

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

Clearance/reporting response codes

cac:DocumentResponse/cac:Response/cbc:ResponseCode

PUF-017-CLEARANCESTATUSCODE

7. XML schemas

The PUF Clearance Notification XML schemas including Pagero/PUF Extension can be downloaded here:

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.