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
- Where to send. The partner's AS2 address, and the address they must send to: your gateway's
/as2/inbound. - The AS2 names. The AS2-From and AS2-To of the messages in each direction.
- Security. Whether messages are signed, encrypted and compressed, with which algorithms, and the certificates to be exchanged: yours to sign with, and theirs to encrypt for and to verify their signatures with. How certificates are kept is in Security & Certificate Management.
- The receipt. Whether a receipt is required and whether it must be signed, and whether it comes back in the same HTTP exchange (synchronous) or is posted to you later (asynchronous), and if so to which address.
- The algorithms. Many partners, PontonXP among them, only accept sha1 for the signature. Ask before you choose sha256 or stronger.
How a message travels
Sending.
- 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.
- 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.
- 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).
- 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. - 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.
- The partner posts the message to
/as2/inbound, with theAS2-FromandAS2-Toheaders. A request without them, or without a body, is refused with 400. - The gateway finds the partnership from the two names, and checks the message ID, so that a message that arrives twice is stored once.
- 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.
- It computes the MIC, stores the message and the document, and returns the receipt in the HTTP answer.
- 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.
| 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. |
| AS2-From, AS2-To | The names in the AS2 headers. For messages you receive they find the partnership. |
| Subject | The 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 Keypair | The keypair, with its private key, that signs your messages. |
| Partner Encryption Certificate | Needed when encryption is on and no Remote Partner ID is chosen. |
| Sign Required, Encrypt Required, Compress Required | Sign, 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 Algorithm | The digest of the S/MIME signature: sha256, sha384, sha512 or sha1. |
| Encrypt Algorithm | aes128-cbc, aes192-cbc, aes256-cbc or 3des. |
| MIC Algorithm | The 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 Format | The 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 MDN | Ask 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 Key | Optional. 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. |
| 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 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:
{
"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:
{ "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.
| 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. |
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 partner rejects the signature or the receipt does not match. Use the algorithm they accept (sha1 for some), and keep the MIC Algorithm the same as the Sign Algorithm.
- The partner cannot read the message. Try the other Payload Format. Some receivers do not decode base64.
- The message is delivered but never acknowledged. For an asynchronous receipt, check that the partner can reach the gateway's
/as2/mdnand that it is the Receipt Address they were given. - A message you receive is not accepted. Check that the two names match a partnership, and look at the Messages page: a message that failed a required signature check is stored as rejected, with the reason.
- A message is on hold, or refused with 422. A certificate has lapsed. Renew it (see Security & Certificate Management).
The same pattern, with its own settings, is used for ebMS and SFRM.