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
- Where to send. The partner's ebMS endpoint (an HTTP or HTTPS address), and the address they must send to: your gateway's
/ebms/inbound. - The agreement. The CPA ID, the Service and the Action that go in every message. A partnership is found by these three.
- Party IDs. The ID you send as (the "From PartyId") and the ID of the partner (the "To PartyId").
- Security. Whether messages are signed, encrypted and compressed, with which algorithms, and the certificates to be exchanged. How the certificates are kept is in Security & Certificate Management.
- Acknowledgements. Whether an acknowledgement is required, whether it comes back in the same HTTP exchange (synchronous reply) or as a separate message later, and how many times and how often a message should be sent again if none arrives.
How a message travels
Sending.
- 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.
- 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).
- 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.
- 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.
- The partner posts the message to
/ebms/inbound. The gateway accepts messages up to 50 MB. - 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.
- 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.
- 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:
| Setting | What it does |
|---|---|
| Partnership ID | Your own name for the partnership. It is what you give the API when you send. |
| Remote Partner ID | The 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, Action | The 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 Source | What 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 Endpoint | HTTP, and the partner's address. |
| Local Signing Keypair | The keypair, with its private key, that signs your messages. See Security & Certificate Management. |
| Partner Encryption Certificate | Needed when encryption is on and no Remote Partner ID is chosen. |
| Sign Requested | Sign every message you send. |
| Envelope Signature Algorithm | The 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 Algorithm | The digest of the separate CMS signature over the document: sha512, sha384, sha256 or sha1. Leave sha512 for PontonXP-style partners. |
| Encrypt Requested, Encrypt Algorithm | Encrypt the document for the partner's certificate with aes128-cbc, aes192-cbc, aes256-cbc or 3des. |
| Compression Algorithm | None, 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 Format | How the document is written in its MIME part: raw binary or base64. |
| Acknowledgment Requested, Acknowledgment Sign Requested | Ask the partner to acknowledge each message, and to sign the acknowledgement. |
| Duplicate Elimination | The 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 Key | Optional. 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. |
| Disabled | Switch 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.
{
"partnershipId": "acme-ebms",
"toPartyId": "urn:duns:123456789",
"conversationId": "order-1001",
"payload": "PEludm9pY2U+PE51bWJlcj5JTlYtMTAwMTwvTnVtYmVyPjwvSW52b2ljZT4=",
"headers": { "ErpReference": "INV-1001" }
}curl -X POST https://<your-gateway>/api/ebms/message/send ^
-H "X-Api-Key: <your key>" ^
-H "Content-Type: application/json" ^
-d @send.jsonThe answer is the message's ID:
{ "id": "20261117-093012-0001@gateway" }To send several documents in one message, give payloads instead of payload, each with its content type:
{
"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).
{
"messageId": "20261117-093012-0001@gateway",
"messageBox": "OUTBOX",
"status": "AG",
"statusDescription": null,
"timeStamp": "2026-11-17T09:30:14Z",
"partnershipId": "acme-ebms"
}| Code | A message you sent | A message you received |
|---|---|---|
| PS | Waiting to be sent, or sent and waiting for an acknowledgement that comes later. | Received. |
| PR | Being sent. | Still arriving (a transfer in segments). |
| HD | On hold: a certificate it needs has lapsed. It is accepted, but not yet built or sent. | |
| DL | Delivered to the partner's endpoint. | Received. |
| AG | Acknowledged by the partner. | Received, and the gateway's own acknowledgement was sent. |
| PE, DF | Failed 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 partner answers with an error about the signature. Check the Envelope Signature Algorithm against what the partner accepts (sha1 for some), and that they hold your current certificate.
- A message you receive is not accepted. Look for it on the Messages page: a message that failed a required signature check is stored as rejected, with the reason. Check that a partnership exists with the same
CPA ID, Service and Action, or
*as the Action. - Messages stay waiting. With asynchronous acknowledgements a message waits for one. If the partner cannot send it back to
/ebms/inbound, the message is sent again until the retries are used up. Check the partner's endpoint for sending back, and the Retries and Retry Interval. - A message is on hold, or refused with 422. A certificate has lapsed. Renew it (see Security & Certificate Management).
- The partner has trouble with the document. Try the other Payload Format, or a different Compression Algorithm, as agreed with the partner.
The same pattern, with its own settings, is used for AS2 and SFRM.