# Partner integration guidelines

# Introduction

This page provides an overview of the core technical concepts to familiarize yourself with before you begin an integration with the Pagero Network.

The guide is written in a sequential way to introduce you to all the key concepts as you move along. Please use this to gain valuable insight or refresh your memory of how we work.

---

# General platform access (Pagero API access)

Partners are granted access to Pagero APIs via unique client credentials issued by Pagero. These credentials are distinct for each partner and are intended for universal use across all their clients.

Maintaining the confidentiality of these credentials from end customers is crucial, as they are tailored to each partner and serve the sole purpose of identifying the partner's client system during integration.

The client_id and client_secret are the base for allowing the client system to connect with the Pagero Network platform using Pagero’s REST APIs.

---

# Specific access – accounts & users (Pagero account access)

The Pagero Network is comprised of Pagero Online Accounts, each tied to a distinct legal entity identified by a unique VAT (Value Added Tax) number.

All documents transmitted or received by this entity traverse through its respective Pagero Online Account. This is where all the customer-specific data is stored. Access to transaction and document data within Pagero Online Accounts is managed by users who are linked to one or more Pagero Online account.

A Pagero Online account can also have multiple users with different access rights connected to it. To begin transferring or retrieving data from end customers' Pagero Online Accounts, the partner client system must first be authorized by a user. This authorization is granted to the client system by an end-customer user through an API Authentication process, outlined further below in the Authentication section.

---

# Pagero Online account creation

The Pagero Online accounts are as mentioned the containers for all documents sent and received. As such, each new legal entity introduced to the Pagero Network will need to have its own account.

When new accounts are created, the Pagero platform will generate a unique companyId that is to be saved by the partner.

Upon onboarding of new customers, the accounts can be created in one out of two ways:

1. Pagero Delivery Team: The Pagero Delivery Team can create end customer accounts upon end customer onboarding. The Pagero Online platform will generate a unique companyId for each one, this ID should be provided with the API calls and therefore be saved in the partner system for future use. After the Pagero Delivery team has configured the account, they will distribute the companyId to relevant parties such as partner and customer. Along with the creation of the Pagero Online Accounts, one or multiple users are also created. Partners will allow the customers to relay access by signing in with the users from the partner system, granting the partner the possibility to send and receive documents on behalf of the customer.

   For Partners, Pagero will configure and share test accounts to use when testing connectivity and document flows. Once all functions in scope are tested with these accounts, the partner should be ready to start implementing pilot-customers.

2. Signup API: Pagero offers partners the possibility to create new end-customer accounts through the Signup API. This option is depending on a couple of factors. One factor is related to the type of customers the partner will be having. Another factor is the scope of operations the partner is doing business in. A dialogue between Pagero and the Partner should be had to establish if the Signup API is a valid approach.

   Should the Signup API be a feasible option, the partner can implement an automatic creation of new Pagero Online accounts from their platform. This option reduces the onboarding times for new end-customers and has some beneficial commercial impact for the partner. This is especially beneficial if the partner is signing up lots of new end customers regularly.

The basic concept of partners, accounts, and users and their relations are illustrated in the figure below:

---

# Authentication

The end user authorization is done using the Authorization Code Grant scenario.

This method has been selected due to its heightened security, improved user experience, and support for multi-factor and SSO authentication.

Additionally, it aligns with the OAuth2 specification, making it widely supported and ensuring interoperability and compatibility across a broad spectrum of integrators.

# Pre-requisites for the API authentication

• Pagero has generated client credentials (client ID + client secret) for the partner and client system.
• The partner has provided URLs to Pagero that are to be used for redirecting the end users back to the client environment after authentication. These must be registered by Pagero before authentication can be done.
• The end user has active Pagero Online user credentials that are connected to at least one Pagero Online Account.

---

# Mapping of company ID

To ensure the smooth operation of API calls, it's crucial to map the Pagero-generated companyId with the customer profile or tenant ID on the partner's end, as it is mandatory for the client system to provide the companyId in the scenarios where the user has access to multiple accounts.

There are two ways of mapping the company profiles:

# Automatic mapping

Call the Company API endpoint to receive a list of companyIds accessible by the calling user. This list will include identifiers such as VAT numbers for the companies.

If the calling user has access to more than one Pagero Account, a mapping based on the identifier will have to be done. Depending on what information about the customer the partner system has access to, a mapping is either feasible or not.

# Manual mapping

Alternatively, a partner can choose to give the end users the possibility to manually enter a Pagero companyId in a text-field that will save the value for the tenant.

This can be administered either by the customer from a settings view, or by the partner in the back end.

---

# Accounts receivable (outbound invoices)

When designing the posting process of documents through Pagero’s APIs, it is good to have an overview of the flow to understand what checks and when in time these should be made. We have summarized a happy path for how we view the best practice of handling files through the APIs below.

The following examples will demonstrate the posting of an invoice since this is the most common scenario. But the process is more or less the same for most document types.

# Posting a file

The partner system generates a formatted file and sends a POST request to the Pagero API using the post a file endpoint.

When sending a file, it is important to utilize a unique senderReference.

This senderReference should be linked to the fileId value received in the response, and both values should be stored in the partner system.

# Key success factors when posting a file

• Only send one document/invoice per file and call.
• File Format: Agreed upon XML format. For global partners, Pagero Universal Format XML is recommended.
• Parameters: sendingcompanyId, sendMode.
• Save fileId and senderReference locally.

API endpoint:

# Status handling & error management

Upon receiving a HTTP 200/201 response from the POST request, verify that the submitted file has been processed into a document.

Send a general request to the Get fileparts endpoint. This request will retrieve a list containing filepart IDs, corresponding fileIds, and their statuses for all file parts that encountered processing issues. Use this list to map against the fileIds that you have saved from the posting of the files to update their statuses.

API endpoint:

# Job queue for checking errors

We recommend that you have a recurring check for errors of all sent files. This is to catch any errors that show up during the processing of the file that will require that an action be taken for it to be processed correctly.

Schedule this job to run at appropriate intervals based on the frequency of sent files.

When deciding this interval, it is good to think proactively and try and predict what the frequency will look like in the future.

API endpoint:

# Take action on file

Once an error has been identified, an action will have to be taken on the file.

This can be either Resume, Restart, RestartWithReplacements or Cancel depending on the error code/description.

In most cases, the file will be cancelled and a new post request for the file will be issued with corrections made in the partner system.

API endpoint:

# Job queue for delivered documents

Much like the job queue for checking errors, there should be a job queue for the delivered documents where verification of delivery can be made.

This request will return a list of all documents that have fully passed through the processing. From here the partner can choose to download the source, target, and/or the presentation format of the documents using the provided API calls for each instance.

In the result of this call, both the fileId and the documentId can be found. The documentId should be saved locally by the partner, connected to the fileId saved from the posting of the file.

API endpoint:

# Fetch documents

Once a document has been treated in the Partner system, it should be marked as “Fetched” which is done by sending a list of all documentIds that are to be marked.

The next time the job queue is called these documents can easily be excluded from the result by using the parameter showFetchedOnly set to false.

API endpoint:

---

# Application responses

Some mandates require structured responses for sent invoices.

This could be from a tax authority in a country that has implemented a CTC (continuous transaction control) model, or it could be a reply from the invoice recipient.

If this is a requirement for the countries in scope, support for these should also be built by the partner.

# Job queue for application responses

Once again, a job queue should be created to receive any new Application Responses. This request should be configured to return received documents of the type ApplicationResponse.

This document has a senderReference that connects it to the correlating invoice. This value must be fetched from the content of the file.

This connection between the Application Response and the Invoice should be made in the partner system.

API endpoint:

---

# Accounts payable (inbound invoices)

When it comes to inbound documents, the complexity is lower than for Outbound since these documents will already have passed through any validation/clearance needed.

This means that a simple recurring fetch of documents often is enough.

Some mandates require an application response to be sent as verification of received/accepted documents.

# Receiving and handling documents

Receiving and handling can be divided into three steps: checking for new documents, getting attachments, and marking the document as fetched.

# Job queue for delivered documents

Similar to the job queue for checking errors, there should be a job queue for delivered documents, allowing identification and importation of newly arrived documents into the partner system. This is made using the Get documents endpoint.

This request will return a list of all documents that have been received. This list should be looped through and each item's documentId should be saved to the partner system.

API endpoint:

# Document attachments

Before any document is marked as “Fetched”, the required formats of the document should be fetched.

Depending on the mandates of countries and requirements from the partner system, the partner can choose what formats to fetch, and which to ignore.

• Target Format: The format configured for the receiver of the document.
• Source Format: The format sent out from the sender of the document.
• Presentation Format: The PDF representation of the document.

# Mark as fetched

Once the required formats have been fetched to the partner system, the documents can be marked as fetched by sending a POST request to the Fetch Documents endpoint.

Send in a list of all documents that have collected all related formats and this functionality will mark them as “fetched” by setting the value isFetched to true. This can be used to filter future get documents calls on.

API Endpoint:

# Structured responses

For countries that mandate a response to be sent out as confirmation of receiving documents, a structured response should be generated and posted back from the partner system.

API Endpoint:

---

# Testing

# Company test structure

Before a partner goes into the pilot phase with an end customer, testing is done on partner-specific test accounts that simulate a Supplier and a Buyer.

The purpose of these accounts is to simulate a production scenario where the buyer can represent either a buyer or a Tax Authority.

It will also verify that the payload is correctly formatted in accordance with the agreed scope, and to test any response messages that could be sent back.

# Send modes

Pagero does not have separated environments for testing and production. Instead, Pagero has implemented “Send modes” that instruct the platform on how to treat documents being sent.

The three send modes available are:

1. Certification: A file sent in certification send mode will never leave the Pagero platform, i.e., no communication to any other parties is sent out. This is useful for testing the Pagero verification and transformation process without involving the end recipient or middle layers such as tax authorities.
2. Test: A file sent in test send mode gets tagged as a “Test” file before sending onward from the Pagero system. It is important to make sure that any other parties that are involved in the processing of the file can handle this tag before using this send mode.
3. Production: A file sent in the production send mode will be treated as a production file.

---

# Partner links

# Document validation tool

Pagero and its partners have access to a tool used for verifying content and structure of files for a multitude of formats.

This is an especially useful tool to access during the format building phase of a project to make sure that the payload contains all the mandatory information in a correctly structured way.

Simply create an account and log in to Validex from the link below.