# Pagero HTTPS solutions

# Introduction

Hypertext Transfer Protocol Secure (HTTPS) is an extension of HTTP.

HTTPS is a widely used secure transfer protocol that is encrypted using transport layer security (TLS).

NOTE: HTTP is an excellent method for sending files over the internet due to its widespread adoption, reliability, and ability to support secure data transmission. It is a universally supported protocol, making integration with diverse systems and platforms straightforward. HTTP supports encryption through HTTPS, ensuring the confidentiality and integrity of sensitive data during transit.

As such, HTTPS is the protocol we recommend for connecting your system to Pagero Network.

# What we offer

Our Interchange API endpoint is used for posting files (to Pagero) over HTTP.

Our HTTP client is used for sending files from Pagero to external, 3rd party HTTP servers/API endpoints.

# What's included?

We offer two different HTTPS packages; Advanced and Enterprise.

Below is an overview of what's included in each of the two.

Feature	Advanced	Enterprise
Basic access authentication	✅	✅
Embedded attachments	✅	✅
OAuth2 authentication	✅	✅
Customized attachment handling		✅
Customized envelope- and/or batching handling		✅
Technical receipts/acknowledgements		✅
Customized protocol settings		✅
Pre-processing service/s		✅

NOTE: If you want to upgrade from Advanced to Enterprise, just reach out to your salesperson or our Support who will assist you further.

# Prerequisites

Prior to being able to utilize our Pagero HTTP offering, your internal integration solution needs to support the sending of data through an HTTP client and/or be able to receive data through an HTTP server.

When ordering the HTTP Connectivity Setup, either from Pagero Store or by your sales representative, and the setup has been finalized by Pagero you will receive an interconnect specification with the connectivity details.

# Pagero Interchange API

Our Interchange API is a simple and straightforward API/endpoint for sending files to us over HTTP.

We accept either raw or binary payloads.

An HTTP request is sent to the endpoint URL corresponding with the authentication method, document type and send mode for the expected use case.

# Authentication method

Our Interchange API supports two different authentication methods.

Basic access authentication (username/password)
Token authentication via OAuth2 (Resource owner password credentials flow)

# Basic authentication

Basic authentication is a simple and widely used method for authenticating users in web applications.

A username and password are combined in the format username:password and then encoded using Base64 encoding.

The resulting, encoded string is then used to construct the authorization HTTP header like this: Authorization: + Basic + Base64 encoded string.

Basic authentication example HTTP header
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

More information on basic authentication can be found here.

# OAuth2 token authentication (ROPC)

If the external system or application does not require user interaction for authentication and can securely store the user's username and password, the Resource Owner Password Credentials (ROPC) Flow can be used to obtain an access token. In this flow, the user's credentials are sent directly to the authorization server, which then issues an access token and a refresh token.

# Obtaining an access token

To obtain a new access_token, the following URL should be used:

https://sso.pageroonline.com/oauth/v2/oauth-token

Request method: POST

Required parameters in application/x-www-form-urlencoded:

Parameter	Required/optional	Description
`grant_type`	Required	Must be `password`.
`username`	Required	The username of a Pagero Online user to authorize.
`password`	Required	The password of a Pagero Online user to authorize.
`client_id`	Required	The client ID.
`client_secret`	Required	The client secret.

NOTE: All of these (except the grant_type) are generated by us at the time of the initial setup.

# Example with header option

Example request using curl
curl https://sso.pageroonline.com/oauth/v2/oauth-token \
  -d grant_type=password \
  -d username=<username> \
  -d password=<password> \
  --user 'client_id:client_secret'

The response will contain a JSON body that looks like this:

JSON response
{
  "token_type": "bearer",
  "access_token": "_0XBPWQQ_755ee1db-08e1-46a5-a121-538d37e5571d",
  "refresh_token": "_1XBPWQQ_d88969ce-25dc-40af-a558-fc647632d610",
  "scope": "",
  "expires_in": 600
}

# Making an API request using an access token

When making an API request, the access_token should be provided in an Authentication header as a bearer token.

# Example

Example with curl
curl https://api.pageroonline.com/someresource \
  -H 'Authorization: Bearer _0XBPWQQ_755ee1db-08e1-46a5-a121-538d37e5571d'

More information on OAuth2 can be found here.

# Endpoint URL

The endpoint URLs consist of hostname + subpath.

Hostname is api.pageroonline.com.

The subpath consists of document type + send mode.

Endpoint URL structure
https://api.pageroonline.com/incoming/v1/{documentType}/{sendMode}

incoming (static value, always the same).
v1 (API versioning, v1 for now but can be updated in the future).
Document type.
Send mode.

# Path parameters

# Document type

The following table shows the document types currently supported.

Document Type	URL subpath part
Application Response	`applicationresponse`
Catalogue	`catalogue`
Dispatch Advice	`dispatchadvice`
Invoice	`invoice`
Italian Invoice Report	`italianinvoicereport`
Order	`order`
Order Agreement	`orderagreement`
Order Change	`orderchange`
Order Cancellation	`ordercancellation`
Order Response	`orderresponse`
Payment Reminder	`paymentreminder`
Receipt Advice	`receiptadvice`
Technical Response	`receipt`
Transport Instruction	`transportinstruction`
Transport Status	`transportstatus`
Utility Statement	`utilitystatement`

NOTE: This list will be expanded over time, as we add support for new document types in our network.

# Send mode

Send mode is set as part of the subpath in the endpoint URL.

For more information about what different send modes is supported, see send mode section.

Send modes

../../../additional-functionality/send-modes/

# Full endpoint URL example

URL example of sending an invoice in production mode
https://api.pageroonline.com/incoming/v1/invoice/prod 

# Headers

The Pagero Interchange endpoint make use of the following HTTP headers.

Header name	Description
`x-interchange-id`	Sender's identifier for the payload. Filename is commonly used but could be a unique id such as UUID which is defined in RFC 4122.
`x-company-id`	Unique identifier supplied by Pagero. Only required in company group setups.

NOTE: The list of headers we support may be extended in the future.

NOTE: While you are free to send any additional HTTP headers you may wish, we will discard them and not be able to return any values from them in e.g. an asynchronous response such as a technical receipt.

# Body

Our Interchange API supports two types of request body.

raw - The payload is sent "raw" in the request body.
Content type here is dependent on and should match the actual payload, e.g. application/xml, application/json, text/plain.
binary - The payload is sent as binary data.
The content type expected here is application/octet-stream.

# Example request

Example of an UBL XML invoice sent to Pagero Online using HTTPS with the x-interchange-id-header as described above.

HTTP Request example to Pagero interchange
POST incoming/v1/invoice/test HTTP/1.1
x-interchange-id: Invoice-1234567890
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/xml
Content-Length: 151
Host: api.pageroonline.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.5 (Java/1.7.0_72)

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
         xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
         xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">
    <cbc:ID>1234567890</cbc:ID>
    <!-- Omitted for clarity -->
</Invoice>

# Request/Response

For each request, a response will be given according to standard HTTP protocol responses.

# Success

For a successful request, Pagero Online will return HTTP response code 200.

HTTP request

Positive HTTP 200 response

POST incoming/v1/invoice/test HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/xml
Content-Length: 151
Host: api.pageroonline.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.5 (Java/1.7.0_72)
x-interchange-id: Invoice-1234567890

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
         xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
         xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">
    <cbc:ID>1234567890</cbc:ID>
    <!-- Omitted for clarity -->
</Invoice>

HTTP/1.1 200 OK
Date: Mon, 27 Jul 2022 12:28:53 GMT
Server: Apache/2.2.14 (Win32)
Last-Modified: Wed, 22 Jul 2022 19:15:56 GMT
Content-Length: 88
Content-Type: text/html
Connection: Closed

# Error

Depending on the error, HTTP response codes 4xx or 5xx will be given.

HTTP request

Negative HTTP 400 response example

POST incoming/v1/invoice/test HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/xml
Content-Length: 1512
Host: api.pageroonline.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.5 (Java/1.7.0_72)
x-interchange-id: Invoice-1234567890

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
         xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
         xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">
    <cbc:ID>1234567890</cbc:ID>
    <!-- Omitted for clarity -->
</Invoice>

HTTP/1.1 400 Bad Request
Date: Sun, 18 Oct 2022 10:36:20 GMT
Server: Apache/2.2.14 (Win32)
Content-Length: 230
Content-Type: text/html; charset=iso-8859-1
Connection: Closed

For additional information on HTTP responses, see HTTP protocol level response.

# Pagero HTTP client

Pagero HTTP client is a simple client posting the business document in the body of a HTTP request.

# Authentication method

Our HTTP client supports the following methods of authentication.

Basic authentication (username/password)
Token authentication via OAuth2 (Grant Type: client_credentials)
Mutual authentication via client certificate
None (i.e. no authorization headers are sent in the HTTP request. Used when no authentication or authorization is required for the API.)

# Basic authentication

Basic authentication is a simple and widely used method for authenticating users in web applications.

A username and password are combined in the format username:password and then encoded using Base64 encoding.

The resulting, encoded string is then used to construct the authorization HTTP header like this: Authorization: + Basic + Base64 encoded string.

Basic authentication example HTTP header
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

# OAuth2 token authentication

OAuth2 is an industry-standard protocol for authorization that allows applications to securely access resources on behalf of a user.

Our HTTP client support the OAuth2 Client Credentials (client_credentials) grant type.

This following table outlines what input parameters we require in these flows.

Parameter	Required/optional	Description
Client ID	Required	A unique identifier for your application.
Client secret	Required	A confidential key used for authentication.
Grant type	Required	OAuth2 grant type to use for authentication. Currently, only the client credentials type is supported.
Access token URL	Required	The URL where the application can obtain access tokens.
Access refresh URL	Optional	The URL where the application can refresh access tokens, if required.
Custom token request body parameters	Optional	Additional key-value pairs to be included in the token request body.

The OAuth2 authentication process involves the following steps:

We send an HTTP request with your client credentials (ID + secret) to your authorization server.
Your authorization server validate the credentials.
Your authorization server respond with an access token.
We use this access token (as Authorization: Bearer <AccessToken>) in the subsequent HTTP request we post to your API endpoint, including the actual business document in the request body.

# Mutual authentication via client certificate

By default the TLS protocol only proves the identity of the server to the client using X.509 certificates and the authentication of the client to the server is left to the application layer.

TLS also offers client-to-server authentication using client-side X.509 authentication. As it requires provisioning of the certificates to the clients and involves less user-friendly experience, it's rarely used in end-user applications.

Mutual TLS authentication (mTLS) is more often used in business-to-business (B2B) applications, where a limited number of programmatic and homogeneous clients are connecting to specific web services, the operational burden is limited, and security requirements are usually much higher as compared to consumer environments.

Having said this, we support mTLS in our HTTP client. Let us know if you wish to use this authentication method as - naturally - it will require setup on our side.

# None

The "None” authorization type does not require any input parameters, and no authorization headers are sent in the HTTP request.

This method is used when no authentication or authorization is needed for the API.

# Headers

We can configure any specific HTTP header/s you may require.

# Static content

We can set any static content you may require. Examples we've done in the past:

Custom HTTP header examples
x-receiving-business-Unit: BU005
x-receiving-system: SAPS4

There is no real limitation on how many separate headers we can configure.

NOTE: Do note that we always respect "standard" HTTP headers (e.g. Content-Type, Content-Length, User-Agent etc.), and these cannot be overridden.

# Dynamic content

We can also use business document content to set dynamic content in HTTP headers.

Of course, a prerequisite for this is that the data needs to exist in the business document in order for it to be able to be fetched and added as an HTTP header.

Examples we've done in the past:

Dynamic HTTP header examples
x-sender-tax-number: SE123456789001
x-invoice-total: 123.33

# Body

By default, the body type is binary, meaning that the entire main document payload is sent as the entity in the HTTP POST request.

We also support JSON, XML and text.

# Settings

We support a variety of HTTP settings in our HTTP client.

Examples we've done in the past:

HTTP_X_RN_VERSION
HTTP_CONTENT_TYPE
ENABLE_CHUNKED_TRANSFER_ENCODING

Please let us know what you need when ordering the initial setup.

# Attachment handling

This section shows available options for sending and receiving attachments with Pagero Interchange and HTTP client solution.

For more information about attachments, please see the attachment section.

Attachments

../../../additional-functionality/attachments/

# Embedded in the format

Transfer of the attachment can also be done by embedding the attachment in the business document if the document format you send supports it.

There are several ways to embed an attachment but the most common one is to encode the attachment using base64 and add to the business document according to format specification.

Embedded attachments

../../../additional-functionality/attachments/#embedded

# Batched

There are several different ways to batch files, one of the most common alternatives is to compress the files into a zip file. Please note that even though all files are batched and sent as one file there would still need to be a file naming convention inside the zip file to match attachments to the main document.

We recommend sending one business document with corresponding attachments per batched file. We do not recommend sending several business documents within the same file.

Batched attachments

../../../additional-functionality/attachments/#batched-attachments

# Security

Security is achieved by using transport layer security (TLS).

TLS encrypts the connection and makes sure that only Pagero Online or the receiving server can read the transferred data.

# Supported TLS versions and cipher suites

For more information about supported TLS versions and cipher suites, please see the following section.

IPs, TLS and cipher suites

../../ips-tls-ciphers-suites/#transport-layer-security-tls

# Fetching our TLS certificate

# Via a browser

Click the "Settings" icon in the URL bar, to the left of the URL. This will trigger a dropdown.
In the dropdown, click the "Connection is secure" link.
Click the "Certificate is valid" link.
This will bring up the Certificate viewer where you can view the certificate contents (e.g. subject, validity period, algorithms).
Click the "Info" tab. On the bottom here is an "Export" button. Clicking this will export the TLS certificate.

# Via the command line

You can also scan the server for the TLS certificate from the command line.

To do this, you'll need the OpenSSL toolkit. This comes bundled with a lot of operating systems, so chances are you might already have it.

$ openssl s_client -connect pageroonline.com:443
CONNECTED(000001C0)
<!-- OMITTED FOR CLARITY -->
---
Certificate chain
 0 s:CN = *.pageroonline.com
   i:C = US, ST = Arizona, L = Scottsdale, O = "GoDaddy.com, Inc.", OU = http://certs.godaddy.com/repository/, CN = Go Daddy Secure Certificate Authority - G2
   a:PKEY: rsaEncryption, 2048 (bit); sigalg: RSA-SHA256
   v:NotBefore: Oct 11 11:48:18 2023 GMT; NotAfter: Nov 11 11:48:18 2024 GMT
 1 s:C = US, ST = Arizona, L = Scottsdale, O = "GoDaddy.com, Inc.", OU = http://certs.godaddy.com/repository/, CN = Go Daddy Secure Certificate Authority - G2
   i:C = US, ST = Arizona, L = Scottsdale, O = "GoDaddy.com, Inc.", CN = Go Daddy Root Certificate Authority - G2
   a:PKEY: rsaEncryption, 2048 (bit); sigalg: RSA-SHA256
   v:NotBefore: May  3 07:00:00 2011 GMT; NotAfter: May  3 07:00:00 2031 GMT
 2 s:C = US, ST = Arizona, L = Scottsdale, O = "GoDaddy.com, Inc.", CN = Go Daddy Root Certificate Authority - G2
   i:C = US, O = "The Go Daddy Group, Inc.", OU = Go Daddy Class 2 Certification Authority
   a:PKEY: rsaEncryption, 2048 (bit); sigalg: RSA-SHA256
   v:NotBefore: Jan  1 07:00:00 2014 GMT; NotAfter: May 30 07:00:00 2031 GMT
---
Server certificate
-----BEGIN CERTIFICATE-----
MIIGnDCCBYSgAwIBAgIJAJR4wEo/hFDUMA0GCSqGSIb3DQEBCwUAMIG0MQswCQYD
VQQGEwJVUzEQMA4GA1UECBMHQXJpem9uYTETMBEGA1UEBxMKU2NvdHRzZGFsZTEa
MBgGA1UEChMRR29EYWRkeS5jb20sIEluYy4xLTArBgNVBAsTJGh0dHA6Ly9jZXJ0
cy5nb2RhZGR5LmNvbS9yZXBvc2l0b3J5LzEzMDEGA1UEAxMqR28gRGFkZHkgU2Vj
dXJlIENlcnRpZmljYXRlIEF1dGhvcml0eSAtIEcyMB4XDTIzMTAxMTExNDgxOFoX
DTI0MTExMTExNDgxOFowHTEbMBkGA1UEAwwSKi5wYWdlcm9vbmxpbmUuY29tMIIB
IjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEApHls4voEMUk4o6UEipiWrGhS
4rVUMhfOcbBA10YqqHZXvEjpnOi+rAxHP0RB862ZnQ6vsUdYZ25YSBcJ8/Yqegtv
8tSxZLJeexsIs2mPFx3agp2tSWc1vHNE8+woFvvybtnOSSB26W5YOlRbWW4YOAEf
KBrHQPjCPQtYllu0RfQj/g8cZjcehLmexg0Ox4wH/y2QSiX27IzaOzvlcQhy+TP+
XPGttlKrkhv+PniWpmxdbYmYjgMJb3qKLserC4NIJzEKwmJSB4J1WXoDU6+E1UdS
MMUmDJPXwWne7X/7HRbuR232LlA0iwwXiXXmZZcL5bf1W8fZh5q6A/9TetvYLwID
AQABo4IDRTCCA0EwDAYDVR0TAQH/BAIwADAdBgNVHSUEFjAUBggrBgEFBQcDAQYI
KwYBBQUHAwIwDgYDVR0PAQH/BAQDAgWgMDgGA1UdHwQxMC8wLaAroCmGJ2h0dHA6
Ly9jcmwuZ29kYWRkeS5jb20vZ2RpZzJzMS05OTcyLmNybDBdBgNVHSAEVjBUMEgG
C2CGSAGG/W0BBxcBMDkwNwYIKwYBBQUHAgEWK2h0dHA6Ly9jZXJ0aWZpY2F0ZXMu
Z29kYWRkeS5jb20vcmVwb3NpdG9yeS8wCAYGZ4EMAQIBMHYGCCsGAQUFBwEBBGow
aDAkBggrBgEFBQcwAYYYaHR0cDovL29jc3AuZ29kYWRkeS5jb20vMEAGCCsGAQUF
BzAChjRodHRwOi8vY2VydGlmaWNhdGVzLmdvZGFkZHkuY29tL3JlcG9zaXRvcnkv
Z2RpZzIuY3J0MB8GA1UdIwQYMBaAFEDCvSeOzDSDMKIz1/tss/C0LIDOMC8GA1Ud
EQQoMCaCEioucGFnZXJvb25saW5lLmNvbYIQcGFnZXJvb25saW5lLmNvbTAdBgNV
HQ4EFgQUzk7vrxtXiPB8aXc3KUh2Msk5TTYwggF+BgorBgEEAdZ5AgQCBIIBbgSC
AWoBaAB2AO7N0GTV2xrOxVy3nbTNE6Iyh0Z8vOzew1FIWUZxH7WbAAABix6Q9owA
AAQDAEcwRQIgTffpz/QG5TCBsY/KAhe2l3gJskPV//uhGIFF+PqjOFsCIQC1JE5T
VeTHsarvHkvVylCe6JlAzww9OriGTBFqsIy6+wB2AEiw42vapkc0D+VqAvqdMOsc
UgHLVt0sgdm7v6s52IRzAAABix6Q95MAAAQDAEcwRQIhANX6mifnDLLxclwYyq77
sngtSsUmt/pTwn9WvODnboNWAiA0ZKgbRyksSXlt7HbIY4G9SI1XtSSiMLm+plTv
/FBl+gB2ANq2v2s/tbYin5vCu1xr6HCRcWy7UYSFNL2kPTBI1/urAAABix6Q9+0A
AAQDAEcwRQIgSSuunNdzvnVO/t5biYwYyMAlUMQyf/My40RdZRvS3HgCIQD+Ehle
nDiNwAl49Ky82j9E0FMhLnGOFrpzTfAvyO7nMDANBgkqhkiG9w0BAQsFAAOCAQEA
nWzne2tf98sd6IMO7LrCIHGGmv7Hc1YDPR6qqyqnOE53iIbli2mUpdKLlV8ywjv5
JUefUvJcmAXKaLknExK4MjtVRoGmzu+0qqij1phivZI56k/8Md4rJU8fm5lXBZuR
JONtUcLmhadXYm6loajxkp0h07uAsIjyRhEc6fRZsbCjEi8RA4qZ0fvKx3OAElQV
/Iy7of+R5z0vGiALAi8AHN8iVw65rxfp2AfmrtgHOqbgY7jGQG+IjqSn0w0hiEfV
jBmqPUqGbSQcvID8EYyJId6Fm3tWIdrG7/ASEQ2qv/Hq/I7rQd+KWX4LzUlH35nR
N1gFpRaAo5DVcAPVBBYNGg==
-----END CERTIFICATE-----
subject=CN = *.pageroonline.com
<!-- OMITTED FOR CLARITY -->
    Start Time: 1712838630
    Timeout   : 7200 (sec)
    Verify return code: 0 (ok)
    Extended master secret: yes
---

To get the full certificate chain - including the root and intermediate certificates - run the following instead:

$ openssl s_client -showcerts -connect pageroonline.com:443