Skip to content
Xferity

Tutorial: AS2 Partner Exchange

Tutorial: AS2 Partner Exchange

Section titled “Tutorial: AS2 Partner Exchange”

This tutorial walks through configuring an AS2 trading partner in Xferity, binding the required certificates, and sending a signed and encrypted AS2 message.

Prerequisites: Xferity with Postgres backend enabled (AS2 persistence requires Postgres), and certificate material from your trading partner

What AS2 Exchange Requires

Section titled “What AS2 Exchange Requires”

Before you can send an AS2 message, you need:

  • your own signing certificate and private key
  • the partner’s public certificate for encryption
  • the partner’s public certificate for MDN signature verification (often the same cert)
  • the partner’s AS2 endpoint URL and AS2 ID

Step 1: Add certificates to the inventory

Section titled “Step 1: Add certificates to the inventory”

In the Xferity UI (or API), add certificates to the Certificate inventory:

  1. Navigate to Certificates
  2. Add your signing certificate: import the PEM file and mark it as a signing certificate
  3. Add the partner’s certificate: import their public PEM and mark it for encryption and verification

Note the certificate IDs assigned by the inventory.

Step 2: Create the partner definition

Section titled “Step 2: Create the partner definition”

Create partners/retail-edi.yaml:

id: retail-edi
display_name: Retail Trading Partner EDI
protocol: as2
as2:
  as2_id: "RETAIL-PARTNER-EDI"
  url: "https://edi.retailpartner.example/as2/receive"
  receipt_mode: sync
  signing_algorithm: sha256
  encryption_algorithm: aes256
  expect_signed_mdn: true
  https_tls:
    ca_cert: file:./keys/retail-partner-ca.pem

Step 3: Bind certificates to the partner

Section titled “Step 3: Bind certificates to the partner”

In the Xferity UI:

  1. Navigate to the partner’s Partner Crypto Policy page
  2. Bind your signing certificate to the signing role
  3. Bind the partner’s public certificate to the encryption role
  4. Bind the partner’s public certificate to the verification role (MDN verification)

The Partner Crypto Policy view will show green status for all required roles when correctly bound.

Step 4: Validate configuration

Section titled “Step 4: Validate configuration”
Terminal window
xferity validate
xferity diag retail-edi-outbound

Diagnostics will test connectivity to the AS2 endpoint and verify certificate bindings.

Step 5: Create the AS2 flow

Section titled “Step 5: Create the AS2 flow”

Create flows/retail-edi-outbound.yaml:

flows:
  retail-edi-outbound:
    direction: upload
    enabled: true
    target:
      partner: retail-edi
    local:
      path: ./storage/retail/outgoing
    files:
      - pattern: "*.edi"
    idempotency_mode: hash
    delete_after_upload: true

Step 6: Send a test message

Section titled “Step 6: Send a test message”
Terminal window
xferity run retail-edi-outbound

After the run, check:

  • xferity flow history retail-edi-outbound for the outcome
  • xferity logs retail-edi-outbound for detailed MDN handling
  • The UI’s AS2 Messages page for the inbound MDN record

What a successful AS2 exchange looks like

Section titled “What a successful AS2 exchange looks like”

In logs, a successful exchange shows:

  • message signed with your certificate
  • message encrypted with the partner’s public certificate
  • MDN received
  • MDN signature verified (if expect_signed_mdn=true)

Async MDN

Section titled “Async MDN”

If the partner uses asynchronous MDN (they send the receipt to a callback URL), configure:

as2:
  receipt_mode: async
  mdn_url: "https://xferity.yourcompany.example/as2/mdn"

Your Xferity instance must be reachable by the partner on this URL.

Section titled “Related pages”