Technical Reference

AS2 guide: setting up and running AS2 (RFC 4130)

What to agree with your partner, how a message and its receipt (MDN) travel, what each setting of an AS2 partnership does, how to send and receive, and what to try when a partner rejects a message.

AS2 sends a business document as a MIME message over HTTP or HTTPS, protected with S/MIME, and the receiver answers with a signed receipt, the MDN (Message Disposition Notification), which proves that it arrived intact. It is the protocol most often asked for in retail, logistics and EDI. This guide takes you from the first agreement with a partner to following a message in the Admin UI. For what AS2 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. The gateway answers at once with the message's ID.
  2. The gateway builds the AS2 message from the partnership: it compresses, signs and encrypts the document as the partnership asks (encrypting last, for the partner's certificate), and when a receipt is wanted it adds the headers that ask for one, for a signed receipt too.
  3. A background sender posts it to the partner's address with the AS2 headers. When the partner's server accepts it, the message is delivered (DL).
  4. If a receipt was requested, it is checked against the message you sent, using the message integrity check (the MIC). A synchronous receipt is read from the HTTP answer. An asynchronous one is posted by the partner to the gateway's /as2/mdn (give the partner that address as the receipt address). A matching receipt marks the message acknowledged.
  5. If sending fails, the message is sent again up to the number of retries, and then it is marked failed (DF) with the reason.

Receiving.

  1. The partner posts the message to /as2/inbound, with the AS2-From and AS2-To headers. A request without them, or without a body, is refused with 400.
  2. The gateway finds the partnership from the two names, and checks the message ID, so that a message that arrives twice is stored once.
  3. It decrypts the message, then verifies the signature and decompresses, in whichever order the partner used them (partners differ). A message that fails a required signature check is stored as rejected, so that you can see it.
  4. It computes the MIC, stores the message and the document, and returns the receipt in the HTTP answer.
  5. Your system reads the message from the API or the Messages page, or the gateway publishes it to a message-queue topic.

Set up a partnership

In the Admin UI choose Partnership > AS2 and add a partnership. A partnership has one AS2-From and one AS2-To. Where the two directions of a trading relationship need different settings, make a partnership for each direction.

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.
AS2-From, AS2-ToThe names in the AS2 headers. For messages you receive they find the partnership.
SubjectThe subject of the messages you send.
Recipient Address (Endpoint)Where the partner receives AS2 messages.
Receipt Address (Async MDN)Where the partner posts an asynchronous receipt: the gateway's /as2/mdn.
Local Signing KeypairThe keypair, with its private key, that signs your messages.
Partner Encryption CertificateNeeded when encryption is on and no Remote Partner ID is chosen.
Sign Required, Encrypt Required, Compress RequiredSign, encrypt and compress the messages you send. For a message you receive through the partnership, Sign Required means that an unsigned message is rejected. A missing encryption or compression is noted in the gateway's log, and the message is still accepted.
Sign AlgorithmThe digest of the S/MIME signature: sha256, sha384, sha512 or sha1.
Encrypt Algorithmaes128-cbc, aes192-cbc, aes256-cbc or 3des.
MIC AlgorithmThe hash of the message integrity check. It should normally be the same as the Sign Algorithm, because it is announced in the request for a signed receipt.
Payload FormatThe transfer encoding of the parts you send: base64 (the default) or raw binary. Some receivers read the raw bytes of a part and do not decode base64; pick raw binary if a partner mishandles base64.
Request MDN Receipt, Request Signed MDNAsk the partner for a receipt, and for a signed one.
Synchronous Reply (vs. Async MDN)On: the receipt comes back in the same HTTP exchange. Off: the partner posts it to the Receipt Address.
Retries, Retry Interval (seconds)How often, and how long apart, a message is sent again when sending fails.
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 the receipt for a message you sent arrives, and the name of the header, in your send request, whose value is carried back on that event.
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 answer.

Send a message

Call the API with your API key (created under Programmability > API Keys) in the X-Api-Key header, as in the ebMS guide, but to /api/as2/message/send. The document is base64, and the content type is the document's own:

JSON (send.json)
{
  "partnershipId": "acme-as2",
  "payload": "PEludm9pY2U+PE51bWJlcj5JTlYtMTAwMTwvTnVtYmVyPjwvSW52b2ljZT4=",
  "payloadContentType": "application/xml",
  "headers": { "ErpReference": "INV-1001" }
}

The answer is the message's ID, and a refused certificate is a 422 as for ebMS:

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

Follow a message

GET /api/as2/message/status?id=<id> returns the state of a message, and the Admin UI's Messages > AS2 page lists them, with a detail view and downloads. For AS2 the receipt is recorded on the message: a delivered message whose receipt has arrived shows as acknowledged.

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.

For a message you received, PE means that it was rejected: its signature failed a required check. A failed message can be put back in the send queue with Retry on the Messages page.

When something goes wrong

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

← Back to the technical reference