Technical Reference

ebMS guide: setting up and running ebXML Messaging (ebMS 2.0)

What to agree with your partner, how a message travels, what each setting of an ebMS partnership does, how to send and receive, and how to follow a message to its acknowledgement.

ebMS 2.0 is the messaging layer of the ebXML standards. A message is a SOAP envelope that carries the addressing and agreement details, with the business documents attached as MIME parts. Signing, encryption and acknowledgements are part of the protocol. This guide takes you from the first agreement with a partner to following a message in the Admin UI. For what ebMS is, see the short overview.

Agree these with your partner first

How a message travels

Sending.

  1. Your system sends the document to the gateway's API, or puts it on a message-queue topic (see Tags below). The gateway answers at once with the message's ID.
  2. The gateway builds the ebMS message from the partnership: the ebXML header, the document as an attachment, and the signing, encryption and compression the partnership asks for. The message is stored and waits to be sent (status PS).
  3. A background sender posts it to the partner's endpoint (PR). What happens next depends on the acknowledgement settings:
    • No acknowledgement requested: the message is delivered (DL) as soon as the partner's server accepts it.
    • Synchronous reply: the acknowledgement is in the answer to the same HTTP request, and the message becomes acknowledged (AG).
    • Asynchronous acknowledgement: the message waits. If no acknowledgement arrives within the retry interval it is sent again, up to the partnership's number of retries (so retries + 1 sends in all), and it fails if none arrives by then. When the partner's acknowledgement arrives the message becomes acknowledged.
  4. If the partner answers with an ebMS error that names your message (for example that its time to live has passed), the gateway marks the message failed with the partner's reason, because sending the same message again would only be refused again. If a message's own time to live has passed before it is sent, for example after a long outage or a manual retry, it is re-issued with fresh times first.

Receiving.

  1. The partner posts the message to /ebms/inbound. The gateway accepts messages up to 50 MB.
  2. The message is read, checked against the partnerships (by CPA ID, Service and Action), checked for a duplicate, its signature is verified where the partnership requires one, and it is decrypted. A message that fails a required signature check is kept, as rejected, so that you can see it in the Admin UI.
  3. The message is stored in the inbox. If the partner asked for a synchronous reply, the acknowledgement is returned in the HTTP answer. Otherwise the answer is an empty 200, and the acknowledgement is sent later, as a message of its own, with retries.
  4. Your system reads the message from the API (GET /api/ebms/message/receive, or the Messages page), or the gateway publishes it to a message-queue topic (see Tags).

Set up a partnership

In the Admin UI choose Partnership > ebXML and add a partnership. The settings:

SettingWhat it does
Partnership IDYour own name for the partnership. It is what you give the API when you send.
Remote Partner IDThe partner, chosen from Partner Management > Remote Partners, where their certificates are kept. Choose it, or give the partner's encryption certificate below.
Local Party ID (sender id)The "From PartyId" of every message you send. Set it explicitly, whether or not you sign.
CPA ID, Service, ActionThe agreement. For messages you receive they find the partnership. Action can be *, which accepts any Action: for a sender whose Action changes with every message.
Outbound Action SourceWhat the Action of a message you send is set to. Custom sends the Action above unchanged. The others take it from the message being sent: the sender ID, the receiver ID, the message ID, the conversation ID, or the message type found in the document.
Transport Protocol, Transport EndpointHTTP, and the partner's address.
Local Signing KeypairThe keypair, with its private key, that signs your messages. See Security & Certificate Management.
Partner Encryption CertificateNeeded when encryption is on and no Remote Partner ID is chosen.
Sign RequestedSign every message you send.
Envelope Signature AlgorithmThe algorithm of the XML signature on the SOAP envelope: sha256, sha384, sha512, sha1 or the rsawith variants. Some partners, PontonXP among them, only accept sha1.
Detached Signature AlgorithmThe digest of the separate CMS signature over the document: sha512, sha384, sha256 or sha1. Leave sha512 for PontonXP-style partners.
Encrypt Requested, Encrypt AlgorithmEncrypt the document for the partner's certificate with aes128-cbc, aes192-cbc, aes256-cbc or 3des.
Compression AlgorithmNone, Zip, GZip, ZLib, Custom or Deflate. GZip is the algorithm the gateway is built around; ZLib has been proven with PontonXP. Use the one your partner accepts.
Payload FormatHow the document is written in its MIME part: raw binary or base64.
Acknowledgment Requested, Acknowledgment Sign RequestedAsk the partner to acknowledge each message, and to sign the acknowledgement.
Duplicate EliminationThe duplicate-elimination setting of the agreement, as you and your partner agree it. Separately, a message you receive whose ID is already in the inbox is not stored a second time.
Retries, Retry Interval (seconds)How often, and how long apart, a message is sent again when it has not been acknowledged.
Tags (message queue topic)Optional. A topic name used as it is written. With IN among the tags, every message received through this partnership is published to the topic. Without it, a message that arrives on the topic is sent through this partnership.
Acknowledgement Topic, Acknowledgement Reference KeyOptional. A topic on which an event is published when a message you sent is acknowledged, and the name of the header, in your send request, whose value is carried back on that event so that you can match it to your own record.
DisabledSwitch the partnership off without deleting it.

When it is saved, use the Test button on the partnership: choose a file, and the gateway sends it through the partnership and shows the partner's HTTP answer.

Send a message

Call the API with your API key (created under Programmability > API Keys) in the X-Api-Key header. The document is base64. The Partnership ID is yours; the To PartyId is the partner's.

JSON (send.json)
{
  "partnershipId": "acme-ebms",
  "toPartyId": "urn:duns:123456789",
  "conversationId": "order-1001",
  "payload": "PEludm9pY2U+PE51bWJlcj5JTlYtMTAwMTwvTnVtYmVyPjwvSW52b2ljZT4=",
  "headers": { "ErpReference": "INV-1001" }
}
Command
curl -X POST https://<your-gateway>/api/ebms/message/send ^
  -H "X-Api-Key: <your key>" ^
  -H "Content-Type: application/json" ^
  -d @send.json

The answer is the message's ID:

JSON
{ "id": "20261117-093012-0001@gateway" }

To send several documents in one message, give payloads instead of payload, each with its content type:

JSON
{
  "partnershipId": "acme-ebms",
  "toPartyId": "urn:duns:123456789",
  "payloads": [
    { "payload": "PEludm9pY2U+PE51bWJlcj5JTlYtMTAwMTwvTnVtYmVyPjwvSW52b2ljZT4=", "contentType": "application/xml" },
    { "payload": "T1JERVJTK0RBVEEgMTAwMQ==", "contentType": "text/plain" }
  ]
}

If a certificate the message needs (to sign or to encrypt) has expired or is not yet valid, the call is refused with status 422 and the reason, and nothing is queued.

Follow a message

GET /api/ebms/message/status?id=<id> returns the state of a message, and the Admin UI's Messages > ebXML page lists them, with filters and a detail view that shows the envelope and the documents (which you can download).

JSON
{
  "messageId": "20261117-093012-0001@gateway",
  "messageBox": "OUTBOX",
  "status": "AG",
  "statusDescription": null,
  "timeStamp": "2026-11-17T09:30:14Z",
  "partnershipId": "acme-ebms"
}
CodeA message you sentA message you received
PSWaiting to be sent, or sent and waiting for an acknowledgement that comes later.Received.
PRBeing sent.Still arriving (a transfer in segments).
HDOn hold: a certificate it needs has lapsed. It is accepted, but not yet built or sent. 
DLDelivered to the partner's endpoint.Received.
AGAcknowledged by the partner.Received, and the gateway's own acknowledgement was sent.
PE, DFFailed for good: the retries ran out, or the partner rejected it. The reason is kept with the message.Received, but the gateway could not deliver its acknowledgement.

A message that failed can be put back in the send queue with Retry on the Messages page, once the cause has been put right.

When something goes wrong

The same pattern, with its own settings, is used for AS2 and SFRM.

← Back to the technical reference