Skip to main content
This guide walks you through setting up phoss SMP as a fully operational Peppol SMP — from obtaining a certificate to verifying your first participant lookup.
Peppol has two environments: test/pilot and production. Work through this guide in the test environment first. The steps are identical; only the certificate authority, SML endpoint, and truststore differ.

​
Prerequisites

  • phoss SMP deployed and reachable over HTTPS at a public URL
  • A domain name registered in DNS (required for SML registration)
  • A Peppol SMP ID agreed with your Peppol Authority (e.g. SMP-MYCOMPANY-001)

​
Step 1: Obtain a Peppol SMP certificate

1

Contact your Peppol Authority

Apply for an SMP certificate through your regional OpenPeppol member authority. The authority issues certificates under the Peppol PKI.
Request a Peppol Test SMP certificate (also called AP Test certificate). No production traffic can use this certificate.
2

Convert the certificate to PKCS#12

Peppol Authorities typically deliver a .p12 or .pfx file. If you receive separate certificate and key files, combine them:
openssl pkcs12 -export \
  -in smp-cert.pem \
  -inkey smp-key.pem \
  -out smp.p12 \
  -name "smp keypair" \
  -passout pass:changeit
3

Verify the keystore

Confirm the keystore contains exactly one entry:
keytool -list -v -keystore smp.p12 -storetype PKCS12 -storepass changeit
phoss SMP requires the keystore to contain exactly one key entry. The key password and keystore password must match.

​
Step 2: Configure the keystore

Place the keystore file on the server (e.g. /etc/smp/keystore/smp.p12) and update application.properties: 
smp.keystore.type         = pkcs12
smp.keystore.path         = /etc/smp/keystore/smp.p12
smp.keystore.password     = changeit
smp.keystore.key.alias    = smp keypair
smp.keystore.key.password = changeit
Select the correct truststore for your environment: 
# Test environment
smp.truststore.path = truststore/2025/smp-test-truststore.p12

# Production environment
# smp.truststore.path = truststore/2025/smp-prod-truststore.p12

smp.truststore.type     = pkcs12
smp.truststore.password = peppol
The bundled truststores (from peppol-commons) are embedded in the WAR. You can reference them by classpath-relative path as shown above.

​
Step 3: Set Peppol identifier and REST mode

smp.identifiertype = peppol
smp.rest.type      = peppol
smp.identifiertype = peppol enforces strict Peppol identifier validation (case-insensitive scheme, lowercase value). Use peppol-lax only if you need to support legacy identifiers with mixed case.

​
Step 4: Configure SML integration

The SML (Service Metadata Locator) is the DNS-based directory that lets Peppol buyers find your SMP. Enable it and set your SMP ID: 
sml.enabled = true
sml.smpid   = SMP-MYCOMPANY-001
The test SML is acc.edelivery.tech.ec.europa.eu. No additional property is needed — phoss SMP uses the test SML by default when operating in test mode.
SML registration requires outbound HTTPS access from your server to the SML endpoint on port 443.

​
Step 5: Set the public URL

phoss SMP must know its own public URL so it can construct correct self-referential links in SMP responses: 
smp.publicurl = https://smp.mycompany.com
If the server runs behind a reverse proxy: 
smp.forceroot       = true
smp.publicurl       = https://smp.mycompany.com
smp.publicurl.mode  = request   # or x-forwarded-header, forwarded-header

​
Step 6: Register with the SML (DNS registration)

1

Start the server

Deploy phoss SMP and verify it starts without errors. Check the log for keystore loading messages.
2

Open the management UI

Navigate to https://smp.mycompany.com/secure/ and log in. Default credentials are [email protected] / password — change the password immediately.
3

Register the SMP in SML

Go to Administration > SML > Register SMP in SML. Click Register.phoss SMP sends a registration request to the SML, which creates a DNS CNAME record pointing <smpid>.publisher.<sml-domain> to your server’s public URL.
4

Verify DNS propagation

nslookup SMP-MYCOMPANY-001.publisher.acc.edelivery.tech.ec.europa.eu
The record should resolve within a few minutes.

​
Step 7: Create your first service group

A service group represents one participant (e.g. a company receiving invoices). Create one via the UI or REST API. Via management UI: Go to Service Groups > Create and enter the participant’s identifier scheme and value (e.g. scheme 0088, value 5060000000001). Via REST API: 
curl -X PUT \
  -u [email protected]:password \
  -H 'Content-Type: application/xml' \
  -d '<ServiceGroup xmlns="http://busdox.org/serviceMetadata/publishing/1.0/"><ParticipantIdentifier scheme="iso6523-actorid-upis">0088:5060000000001</ParticipantIdentifier></ServiceGroup>' \
  https://smp.mycompany.com/iso6523-actorid-upis%3A%3A0088%3A5060000000001

​
Step 8: Add service metadata

Service metadata tells Peppol senders which document types a participant accepts and which Access Point endpoint to use. 
curl -X PUT \
  -u [email protected]:password \
  -H 'Content-Type: application/xml' \
  -d @service-metadata.xml \
  'https://smp.mycompany.com/iso6523-actorid-upis%3A%3A0088%3A5060000000001/services/busdox-docid-qns%3A%3Aurn%3Aoasis%3Anames%3Aspecification%3Aubl%3Aschema%3Axsd%3AInvoice-2%3A%3AInvoice%23%23urn%3Acen.eu%3Aen16931%3A2017%23compliant%23urn%3Afdc%3Apeppol.eu%3A2017%3Apoacc%3Abilling%3A3.0%3A%3A2.1'
The management UI (Service Groups > select group > Service Metadata) provides a guided form that is easier to use than constructing raw XML.

​
Step 9: Verify with a Peppol lookup

Use the Peppol Directory or any SMP client to resolve the participant: 
# Using curl directly against the SML-derived URL:
curl https://B-$(echo -n 'iso6523-actorid-upis::0088:5060000000001' | md5sum | cut -d' ' -f1).iso6523-actorid-upis.acc.edelivery.tech.ec.europa.eu/iso6523-actorid-upis%3A%3A0088%3A5060000000001
A successful response contains the <ServiceGroup> XML with your document type references.

​
Production vs test differences

AspectTest / pilotProduction
CertificatePeppol Test SMP certPeppol Production SMP cert
Truststoresmp-test-truststore.p12smp-prod-truststore.p12
SML endpointacc.edelivery.tech.ec.europa.euedelivery.tech.ec.europa.eu
global.productionfalsetrue
Peppol Directorytest-directory.peppol.eudirectory.peppol.eu

​
Troubleshooting SML registration

The SML validates that your certificate was issued by the Peppol PKI. Make sure you are using the correct certificate for the environment (test vs production) and that it has not expired.
SML DNS changes can take up to 5 minutes to propagate. If the record still does not appear after 10 minutes, verify that sml.smpid matches the SMP ID registered with your Peppol Authority, and check the phoss SMP log for errors during the registration call.
Your server needs outbound HTTPS access to the SML. Check firewall rules. You can verify connectivity with:
curl -v https://acc.edelivery.tech.ec.europa.eu
Confirm that smp.publicurl resolves correctly from outside your network, and that the URL registered in the SML matches the URL where phoss SMP is actually running.

Build docs developers (and LLMs) love

Get started for freeTalk to us