Skip to main content

Merchant signing

About this feature​

Merchant signing, also known as business-to-business (B2B) signing or sealing, allows you to sign documents using a merchant certificate from a selected vendor. This is useful for automated signing processes where a legal entity, rather than an individual person, is the signer.

Limitation

The only vendor currently available for merchant signing is Norwegian BankID (NBID).

Configuration and setup​

To use merchant signing, Signicat Support will need to set up the client configuration for the selected vendor for you. This process will differ slightly between vendors.

For vendor-specific details and configuration, see the relevant documentation:

Norwegian BankID Merchant signing
Vendor-specific merchant signing details

Use cases​

  • Automated sealing: Automatically sign outgoing documents (like invoices or contracts) with your company's merchant certificate to ensure authenticity and integrity.
  • B2B signing: Sign documents on behalf of your organisation in a B2B context.
  • XML signing: Sign XML messages for services like Løsøreregisteret (Brønnøysundregistrene) using the XAdES format.
  • Mixed signing flows: Combine merchant signing with end-user signing. For example, a document can first be signed by an individual and then sealed by the organisation.

How it works​

Unlike the standard signing process in our Sign API v2, merchant signing does not use document collections or signing sessions. Instead, you make an API call to our Merchant signing endpoint that returns the signed document immediately.

Integration steps​

The process for merchant signing consists of three steps:

  1. Upload the document: Make an HTTP POST request with the document's binary data to the Documents endpoint. This returns a documentId.
  2. Perform merchant signing: Make an HTTP POST request to the Merchant signing endpoint with the documentId and the desired vendor. This returns a documentResultId.
  3. Download the result: Make an HTTP GET request using the documentResultId to the Documents endpoint to download the signed document.
Note

Since both the original document and the signed result are not connected to a "parent" object (like a signing session), they are not stored long-term in our system. We recommend downloading the result immediately after signing.

Request example​

To perform merchant signing, make an HTTP POST request to the Merchant signing endpoint:

{
  "vendor": "NBID",
  "toBeSignedDocuments": [
    {
      "documentId": "d1234567-89ab-cdef-0123-456789abcdef",
      "mimetype": "application/pdf",
      "format": "PADES",
      "description": "Invoice #12345"
    }
  ]
}

Response example​

The API returns an array of results, one for each document in the request:

[
  {
    "documentId": "d1234567-89ab-cdef-0123-456789abcdef",
    "documentResultId": "0197d5cb-d683-7451-9b21-1a2da906b353"
  }
]

You can then use the documentResultId to download the signed document, as described in our integration guide.

Signing already signed documents​

Merchant signing can be performed on documents that have already been signed, provided they meet certain criteria:

  • There is a strict validation of the certificate chain, and Signicat only supports a specific list of trust anchors.
  • Documents already signed through Signicat can be mixed with merchant signing.

XAdES support for XML documents​

You can use the Merchant signing endpoint to sign XML messages using the XAdES format. This is particularly useful for Business-to-Business (B2B) services that require signed XML payloads, such as Løsøreregisteret (Brønnøysundregistrene).

1. Prepare the XML document​

Before uploading the document, you must prepare the base XML payload. Add an empty node as the last child of the root node to hold the signatures. This node can be named anything (for example, <Signatur/>, as in the example below). It acts as a placeholder where the XAdES signature will be injected after the signing process is complete.

Example payload​
<Melding>
  <Innhold>
    ...
  </Innhold>
  <Signatur/>
</Melding>

2. Upload the document​

Currently, our document storage service does not natively support XML document types. Therefore, when you upload the XML document to the Documents endpoint, you must set the Content-Type header to text/plain.

3. Request the merchant signature​

Once the document is uploaded and you have the documentId, you can request the signature by calling the Merchant signing endpoint.

In the request body, specify the format as XADES and the mimetype as text/xml.

Example request​
{
  "vendor": "NBID",
  "toBeSignedDocuments": [
    {
      "documentId": "d1234567-89ab-cdef-0123-456789abcdef",
      "mimetype": "text/xml",
      "format": "XADES",
      "description": "Invoice #12345"
    }
  ]
}

4. Retrieve the signed document​

The response format for this request is identical to the default merchant signing response. When you retrieve the final signed document, the previously empty <Signatur/> node from our example payload will now be populated with the generated <ds:Signature> data.

Example result document​
<Melding>
  <Innhold>
    ...
  </Innhold>
  <Signatur>
    <ds:Signature>
      ...
    </ds:Signature>
  </Signatur>
</Melding>
Note

You can find provider-specific Sign API v2 integration guides in our ID methods documentation:

On this page