Canonical Payment Order / Remittance Advice 820 Format Specification

Modified on Thu, Aug 27 at 8:38 AM

ECGrid Simplify

Version: 1.0 Date: June 2026 Owner: ECGrid Product

1. Purpose

This document defines the canonical Payment Order / Remittance Advice format used by ECGrid Simplify. It is the single source of truth for document structure, field definitions, data types, required fields, and serialisation rules across XML and JSON.

Both XML and JSON representations convey the same logical Payment Order message. The 820 transaction set communicates payment information and remittance detail from a payer to a payee, enabling downstream accounts-receivable systems to match invoices against received payments.

Direction Note: The Canonical Payment Order flows inbound to ECGrid from the trading partner. ECGrid receives the X12 820 EDI and translates it to this canonical format for delivery to internal systems that process accounts-receivable cash application.

2. Scope

In scope:

Payment Order document structure (envelope, payment header, party blocks, remittance detail).
Field-level definitions, data types, required fields, and EDI source mapping.
Canonical XML and JSON representations.
Payment method codes (BPR-04): CHK, ACH, FWT, BOP, NON.
Party qualifier routing: PR=Payer and PE=Payee blocks from LoopN1.
Remittance detail: LoopENT with nested LoopRMR invoice lines.

Out of scope:

Transport (HTTPS, AS2, SFTP). Covered in ECGrid Simplify API docs.
Functional acknowledgments and application responses.
Optional 820 loops not in canonical: LoopTXP, LoopDED, LoopLX, LoopN9, LoopRYL.
X12 820 EDI mapping rules. See Map_ANSI X12 820 004010 To Simplify XML Payment Order 820 - Global.csv.

3. Document Structure

A canonical Payment Order payload contains a PaymentOrderMessage root element with exactly one PaymentOrder child. The child holds all envelope fields from ISA/GS, payment header fields from BPR/TRN/NTE/CUR/REF/DTM, one Payer block and one Payee block (each from LoopN1 routed by N1-01 qualifier), and one or more RemittanceDetail entries from the LoopENT loop. Each RemittanceDetail contains one or more InvoiceDetail entries from the nested LoopRMR.

XML vs JSON Naming: Both XML and JSON use PascalCase field names throughout. The JSON root key is "PaymentOrderMessage" — matching the XML root element exactly. RemittanceDetail and InvoiceDetail are arrays in JSON even when only one entry is present.

Top-level shape:

PaymentOrderMessage

└── PaymentOrder (required, exactly one)

├── TradingPartnerId / Sender / Receiver … (envelope, ISA/GS)

├── TransactionHandlingCode / TotalPaymentAmount … (payment, BPR)

├── TraceTypeCode / CheckNumber … (trace, TRN)

├── NoteReferenceCode / Note (NTE)

├── CurrencyEntityIdCode / CurrencyCode … (CUR)

├── ReferenceQualifier / Reference … (REF)

├── DateQualifier / Date (DTM)

├── Payer (single block, LoopN1 where N1-01=PR)

├── Payee (single block, LoopN1 where N1-01=PE)

└── RemittanceDetail (1..n, one per LoopENT)

├── EntityNumber / EntityIdCode … (ENT)

└── InvoiceDetail (1..n, one per LoopRMR)

├── InvoiceReferenceQualifier / InvoiceNumber … (RMR)

├── InvoiceNote (NTE inside LoopRMR)

├── InvoiceReferenceQualifier2 / InvoiceReference2 (REF)

└── InvoiceDateQualifier / InvoiceDate (DTM)

3.1 Payment Method Codes (BPR-04)

BPR-04 identifies the payment method. It determines which BPR fields are populated and how the payment is transmitted:

BPR-04 Code	Payment Method	Notes
CHK	Check	Paper check. BPR06-BPR16 bank fields are not used.
ACH	Automated Clearing House	Electronic transfer. BPR06-BPR16 carry originating/receiving bank data.
FWT	Wire Transfer (Fedwire)	Same-day wire via Federal Reserve. BPR06-BPR16 carry bank data.
BOP	Financial Institution Option	Bank-selected payment option.
NON	Non-Payment Data	Remittance advice only — no funds are transferred.

3.2 Party Qualifier Codes (N1-01)

LoopN1 appears multiple times in the 820, each block identified by N1-01. ECGrid routes each block to the canonical party element based on this qualifier:

N1-01	Party Role	Canonical Mapping
PR	Payer	Canonical Payer block. The entity originating the payment.
PE	Payee	Canonical Payee block. The entity receiving the payment.
RI	Remit-to Party	Not mapped to canonical. Use Payee for the remittance target.
OR	Originating Financial Inst.	Not mapped to canonical (bank routing handled in BPR fields).
BF	Beneficiary's Financial Inst.	Not mapped to canonical (bank routing handled in BPR fields).

4. Envelope Fields

Sourced from ISA (interchange) and GS (functional group) segments. GS-01 for 820 is RA (Remittance Advice).

ISA fixed-width: ISA-06 (Sender) and ISA-08 (Receiver) are 15-character fixed-width fields padded with trailing spaces. ECGrid always trims before populating TradingPartnerId, Sender, and Receiver.

XML Element	JSON Property	Req	Description
TradingPartnerId	TradingPartnerId	Yes	ISA-06 — ECGrid trading partner identifier. 15-char fixed-width; always trimmed.
Sender	Sender	Yes	ISA-06 — Interchange sender identifier value. Trimmed.
SenderQualifier	SenderQualifier	Yes	ISA-05 — Qualifies the sender identifier type (e.g. 01=DUNS, ZZ=Mutually Defined).
Receiver	Receiver	Yes	ISA-08 — Interchange receiver identifier value. Trimmed.
ReceiverQualifier	ReceiverQualifier	Yes	ISA-07 — Qualifies the receiver identifier type.
InterchangeDate	InterchangeDate	Yes	ISA-09 — Interchange date. YYMMDD format.
InterchangeControlNumber	InterchangeControlNumber	Yes	ISA-13 — Interchange control number.
TestProductionIndicator	TestProductionIndicator	Yes	ISA-15 — T=Test, P=Production.
GroupFunctionCode	GroupFunctionCode	Yes	GS-01 — Functional identifier code (RA=Remittance Advice).

5. Header Fields

Sourced from BPR (payment order), TRN (trace), NTE (note), CUR (currency), REF (reference), and DTM (date/time) segments at the transaction header level. BPR-01 and BPR-02 are always required. All other fields are conditional on the payment method.

ACH bank fields (BPR-06 to BPR-16): These fields only carry data for ACH (Automated Clearing House) payments. For CHK (Check) payments, BPR-05 through BPR-16 are empty in the EDI and the canonical fields will be empty strings.

TRN-02 as check number: For CHK payments, TRN-02 typically carries the check number or payment reference. For ACH, TRN-02 carries the ACH trace number assigned by the originating bank.

XML Element	JSON Property	Req	Description
TransactionHandlingCode	TransactionHandlingCode	Yes	BPR-01 — C=Credit, D=Debit, H=Notification, I=Remittance Info Only, U=Unknown.
TotalPaymentAmount	TotalPaymentAmount	Yes	BPR-02 — Total monetary amount of the payment.
CreditDebitFlagCode	CreditDebitFlagCode	Yes	BPR-03 — C=Credit, D=Debit.
PaymentMethodCode	PaymentMethodCode	Yes	BPR-04 — Payment method. CHK=Check, ACH=ACH, FWT=Wire Transfer, NON=No payment.
PaymentFormatCode	PaymentFormatCode	No	BPR-05 — ACH payment format code (e.g. CCD, CTX, PPD). Empty for CHK payments.
SenderBankIdQualifier	SenderBankIdQualifier	No	BPR-06 — DFI ID qualifier for originating bank (01=ABA routing number). ACH only.
SenderBankId	SenderBankId	No	BPR-07 — Originating DFI routing/transit number. ACH only.
SenderAccountQualifier	SenderAccountQualifier	No	BPR-08 — Account qualifier for originating account (DA=Demand Deposit, SG=Savings). ACH only.
SenderAccountNumber	SenderAccountNumber	No	BPR-09 — Originating bank account number. ACH only.
OriginatingCompanyIdQualifier	OriginatingCompanyIdQualifier	No	BPR-10 — Qualifier for originating company ID. ACH only.
OriginatingCompanyId	OriginatingCompanyId	No	BPR-11 — Company identification for ACH originator. ACH only.
OriginatingCompanySupplData	OriginatingCompanySupplData	No	BPR-12 — Supplemental originating company data. ACH only.
ReceiverBankIdQualifier	ReceiverBankIdQualifier	No	BPR-13 — DFI ID qualifier for receiving bank. ACH only.
ReceiverBankId	ReceiverBankId	No	BPR-14 — Receiving DFI routing/transit number. ACH only.
ReceiverAccountQualifier	ReceiverAccountQualifier	No	BPR-15 — Account qualifier for receiving account. ACH only.
ReceiverAccountNumber	ReceiverAccountNumber	No	BPR-16 — Receiving bank account number. ACH only.
EffectiveDate	EffectiveDate	No	BPR-17 — Effective date for the payment. YYYYMMDD format.
TraceTypeCode	TraceTypeCode	No	TRN-01 — Trace type code. 1=Current Transaction Trace, 2=Referenced Transaction.
CheckNumber	CheckNumber	No	TRN-02 — Check or trace reference number (e.g. CHK-2026-0001).
OriginatingCompanyIdentifier	OriginatingCompanyIdentifier	No	TRN-03 — Originating company identifier from TRN segment.
TraceReferenceId	TraceReferenceId	No	TRN-04 — Additional trace reference identification.
NoteReferenceCode	NoteReferenceCode	No	NTE-01 — Note reference code qualifying the note text.
Note	Note	No	NTE-02 — Free-form note or memo text at transaction header level.
CurrencyEntityIdCode	CurrencyEntityIdCode	No	CUR-01 — Entity identifier code for the currency (e.g. PR=Payer).
CurrencyCode	CurrencyCode	No	CUR-02 — ISO 4217 currency code (e.g. USD, CAD, EUR).
ExchangeRate	ExchangeRate	No	CUR-03 — Exchange rate between transaction currency and local currency.
ReferenceQualifier	ReferenceQualifier	No	REF-01 — Reference qualifier code at header level (e.g. VV=Voucher, BM=Bill of Lading).
Reference	Reference	No	REF-02 — Reference identification value.
ReferenceDescription	ReferenceDescription	No	REF-03 — Free-form reference description.
DateQualifier	DateQualifier	No	DTM-01 — Date qualifier code at header level (e.g. 097=Transaction Creation Date).
Date	Date	No	DTM-02 — Date value. YYYYMMDD format.

6. Party Blocks (LoopN1)

Party blocks are extracted from header-level LoopN1 segments. ECGrid routes each LoopN1 to the Payer or Payee canonical element by inspecting N1-01 (the entity identifier qualifier). Only PR and PE blocks are mapped to the canonical. Other qualifiers (RI, OR, BF) are not included in the canonical output.

Qualifier routing: The mapping uses a SegmentLink filter: if(getChildValue("N1/N101") == "PR") routes to Payer; if(getChildValue("N1/N101") == "PE") routes to Payee. If neither block is present in the EDI, the respective canonical element will be empty.

6.1 Payer (N1-01 = PR)

The party initiating the payment (buyer / accounts payable entity).

XML Element	JSON Property	Req	Description
EntityIdentifierCode	EntityIdentifierCode	Yes	N1-01 — Entity identifier code (PR=Payer, PE=Payee). Set by qualifier routing.
Name	Name	Yes	N1-02 — Party legal or trading name.
IdentificationCodeQualifier	IdentificationCodeQualifier	No	N1-03 — Code qualifying the identifier type (e.g. 91=Assigned by Seller, 01=DUNS).
IdentificationCode	IdentificationCode	No	N1-04 — Party identifier value (e.g. account number, vendor code).
AdditionalName	AdditionalName	No	N2-01 — Additional name line (e.g. DBA or department name).
StreetAddress1	StreetAddress1	No	N3-01 — Primary street address line.
StreetAddress2	StreetAddress2	No	N3-02 — Secondary address line (suite, unit, etc.).
City	City	No	N4-01 — City name.
StateCode	StateCode	No	N4-02 — Two-letter state or province code.
PostalCode	PostalCode	No	N4-03 — Postal / ZIP code.
CountryCode	CountryCode	No	N4-04 — ISO 3166-1 alpha-2 country code (e.g. US, CA).

6.2 Payee (N1-01 = PE)

The party receiving the payment (supplier / accounts receivable entity).

XML Element	JSON Property	Req	Description
EntityIdentifierCode	EntityIdentifierCode	Yes	N1-01 — Entity identifier code (PR=Payer, PE=Payee). Set by qualifier routing.
Name	Name	Yes	N1-02 — Party legal or trading name.
IdentificationCodeQualifier	IdentificationCodeQualifier	No	N1-03 — Code qualifying the identifier type (e.g. 91=Assigned by Seller, 01=DUNS).
IdentificationCode	IdentificationCode	No	N1-04 — Party identifier value (e.g. account number, vendor code).
AdditionalName	AdditionalName	No	N2-01 — Additional name line (e.g. DBA or department name).
StreetAddress1	StreetAddress1	No	N3-01 — Primary street address line.
StreetAddress2	StreetAddress2	No	N3-02 — Secondary address line (suite, unit, etc.).
City	City	No	N4-01 — City name.
StateCode	StateCode	No	N4-02 — Two-letter state or province code.
PostalCode	PostalCode	No	N4-03 — Postal / ZIP code.
CountryCode	CountryCode	No	N4-04 — ISO 3166-1 alpha-2 country code (e.g. US, CA).

7. Remittance Detail (LoopENT / LoopRMR)

The remittance detail section carries the invoice-level matching data. Each LoopENT block represents a payee entity grouping. Within each LoopENT, each LoopRMR block represents one invoice or debit memo being paid.

ENT-to-RMR relationship: One RemittanceDetail (ENT) may contain multiple InvoiceDetail (RMR) entries — one per invoice being settled in this payment. All RMR entries inside the same ENT block belong to the same payee entity identified by the ENT fields.

Partial vs full payment: RMR-03 PaymentActionCode signals payment intent: PI=Payment in Full, PP=Partial Payment. When PP, InvoicePaidAmount (RMR-05) will differ from InvoiceAmount (RMR-04). AdjustmentAmount (RMR-06) carries the net deduction or addition amount.

7.1 RemittanceDetail (ENT segment)

Header fields for the remittance entity block.

XML Element	JSON Property	Req	Description
EntityNumber	EntityNumber	Yes	ENT-01 — Assigned sequence number for this remittance entity block (1, 2, 3…).
EntityIdCode	EntityIdCode	No	ENT-02 — Entity identifier code qualifying the entity type (e.g. PE=Payee, 2P=Vendor).
EntityId	EntityId	No	ENT-03 — Secondary entity identifier code.
EntityIdQualifier	EntityIdQualifier	No	ENT-04 — Reference identification for the entity (e.g. vendor code).

7.2 InvoiceDetail (LoopRMR)

Per-invoice remittance fields. Repeats once per invoice within the parent RemittanceDetail.

XML Element	JSON Property	Req	Description
InvoiceReferenceQualifier	InvoiceReferenceQualifier	Yes	RMR-01 — Reference qualifier for the invoice (IV=Invoice, PO=Purchase Order, VN=Vendor Order Number).
InvoiceNumber	InvoiceNumber	Yes	RMR-02 — Invoice or document reference number being paid.
PaymentActionCode	PaymentActionCode	No	RMR-03 — Payment action code (PI=Payment in Full, PP=Partial Payment).
InvoiceAmount	InvoiceAmount	No	RMR-04 — Original invoice amount (monetary amount from the invoice).
InvoicePaidAmount	InvoicePaidAmount	No	RMR-05 — Amount being paid against this invoice in this remittance.
AdjustmentAmount	AdjustmentAmount	No	RMR-06 — Net adjustment amount (negative=deduction, positive=addition).
AdjustmentReasonCode	AdjustmentReasonCode	No	RMR-07 — Reason code for the adjustment (e.g. 01=Pricing Error, 11=Defective).
AdjustmentDescription	AdjustmentDescription	No	RMR-08 — Free-form description of the adjustment reason.
InvoiceNote	InvoiceNote	No	NTE-02 (inside LoopRMR) — Free-form note specific to this invoice line.
InvoiceReferenceQualifier2	InvoiceReferenceQualifier2	No	REF-01 (inside LoopRMR) — Secondary reference qualifier for this invoice line.
InvoiceReference2	InvoiceReference2	No	REF-02 — Secondary reference identification value (e.g. PO number, contract number).
InvoiceDateQualifier	InvoiceDateQualifier	No	DTM-01 (inside LoopRMR) — Date qualifier (003=Invoice Date, 004=PO Date, 011=Shipped Date).
InvoiceDate	InvoiceDate	No	DTM-02 — Date value for this invoice line. YYYYMMDD format.

8. Naming Conventions

Both XML and JSON use PascalCase field names throughout (e.g. TotalPaymentAmount, InvoiceNumber, PaymentActionCode). XML and JSON field names are identical.

The JSON root key is "PaymentOrderMessage" — matching the XML root element exactly. RemittanceDetail and InvoiceDetail are always represented as JSON arrays.

Empty optional values: XML: <FieldName></FieldName>. JSON: "FieldName": "". Every field is always present in the output even when absent from the EDI.

All values are strings: All canonical values are typed as string — including numeric-looking fields such as TotalPaymentAmount, InvoiceAmount, and EntityNumber.

Invoice-level vs header-level REF/DTM: Header REF maps to ReferenceQualifier/Reference/ReferenceDescription. Invoice-level REF (inside LoopRMR) maps to InvoiceReferenceQualifier2/InvoiceReference2. Same pattern applies for DTM: header DTM maps to DateQualifier/Date; invoice DTM maps to InvoiceDateQualifier/InvoiceDate.

9. Validation Rules

Rule	Detail
Required fields	TradingPartnerId, Sender, SenderQualifier, Receiver, ReceiverQualifier, GroupFunctionCode, TransactionHandlingCode, TotalPaymentAmount, CreditDebitFlagCode, and PaymentMethodCode are always populated.
Missing fields	Every field in the canonical structure is always present — no fields are omitted even when absent from the EDI.
ISA trimming	ISA-06 and ISA-08 are 15-character fixed-width; always trim trailing spaces.
ACH bank fields	BPR-06 through BPR-16 only carry data for ACH/FWT payments. For CHK payments these fields are empty strings.
Party routing	Payer requires N1-01=PR. Payee requires N1-01=PE. If a qualifier block is absent from the EDI, the canonical block will be empty.
RemittanceDetail array	JSON: RemittanceDetail is always an array, even for a single ENT block.
InvoiceDetail array	JSON: InvoiceDetail is always an array, even for a single RMR line.
RMR-04 vs RMR-05	InvoiceAmount (RMR-04) is the original invoice amount. InvoicePaidAmount (RMR-05) is the amount paid in this remittance. Both may differ when PaymentActionCode=PP (Partial Payment).
AdjustmentAmount sign	A negative AdjustmentAmount (RMR-06) represents a deduction (short-pay). A positive value represents an addition to the invoice amount.
Multiple transactions	Multiple ST-SE blocks produce separate PaymentOrder elements (XML) or array entries (JSON).

10. XML Example

Canonical 820 Payment Order in XML format. Shows a check payment (CHK) of $2,000 with two invoice lines: INV-2026-001 ($1,500 paid in full) and INV-2026-002 ($500 paid in full).

<?xml version="1.0" encoding="UTF-8"?>

<Payer>

<StreetAddress1>100 Corporate Dr</StreetAddress1>

<City>Chicago</City>

</Payer>

<Payee>

<Name>BestSupply Inc</Name>

<IdentificationCode>SUPPLIER-001</IdentificationCode>

<StreetAddress1>200 Vendor Ave</StreetAddress1>

<City>Dallas</City>

</Payee>

</InvoiceDetail>

</InvoiceDetail>

</RemittanceDetail>

</PaymentOrder>

</PaymentOrderMessage>

11. JSON Example

The same canonical 820 Payment Order in JSON format. RemittanceDetail and InvoiceDetail are JSON arrays. Empty string ("") represents optional fields not present in the source EDI.

{

"PaymentOrderMessage": {

"PaymentOrder": {

"TradingPartnerId": "112084681",

"Sender": "112084681",

"SenderQualifier": "01",

"Receiver": "609195581",

"ReceiverQualifier": "01",

"InterchangeDate": "260617",

"InterchangeControlNumber": "000000820",

"TestProductionIndicator": "P",

"GroupFunctionCode": "RA",

"TransactionHandlingCode": "C",

"TotalPaymentAmount": "2000.00",

"CreditDebitFlagCode": "C",

"PaymentMethodCode": "CHK",

"PaymentFormatCode": "",

"SenderBankIdQualifier": "",

"SenderBankId": "",

"SenderAccountQualifier": "",

"SenderAccountNumber": "",

"OriginatingCompanyIdQualifier": "",

"OriginatingCompanyId": "",

"OriginatingCompanySupplData": "",

"ReceiverBankIdQualifier": "",

"ReceiverBankId": "",

"ReceiverAccountQualifier": "",

"ReceiverAccountNumber": "",

"EffectiveDate": "",

"TraceTypeCode": "1",

"CheckNumber": "CHK-2026-0001",

"OriginatingCompanyIdentifier": "1112084681",

"TraceReferenceId": "",

"NoteReferenceCode": "",

"Note": "",

"CurrencyEntityIdCode": "",

"CurrencyCode": "",

"ExchangeRate": "",

"ReferenceQualifier": "VV",

"Reference": "INV-REF-001",

"ReferenceDescription": "",

"DateQualifier": "097",

"Date": "20260617",

"Payer": {

"EntityIdentifierCode": "PR",

"Name": "ACME Corp",

"IdentificationCodeQualifier": "91",

"IdentificationCode": "ACME-HQ",

"AdditionalName": "",

"StreetAddress1": "100 Corporate Dr",

"StreetAddress2": "",

"City": "Chicago",

"StateCode": "IL",

"PostalCode": "60601",

"CountryCode": "US"

"Payee": {

"EntityIdentifierCode": "PE",

"Name": "BestSupply Inc",

"IdentificationCodeQualifier": "91",

"IdentificationCode": "SUPPLIER-001",

"AdditionalName": "",

"StreetAddress1": "200 Vendor Ave",

"StreetAddress2": "",

"City": "Dallas",

"StateCode": "TX",

"PostalCode": "75201",

"CountryCode": "US"

"RemittanceDetail": [

{

"EntityNumber": "1",

"EntityIdCode": "",

"EntityId": "",

"EntityIdQualifier": "",

"InvoiceDetail": [

{

"InvoiceReferenceQualifier": "IV",

"InvoiceNumber": "INV-2026-001",

"PaymentActionCode": "PI",

"InvoiceAmount": "1500.00",

"InvoicePaidAmount": "1500.00",

"AdjustmentAmount": "",

"AdjustmentReasonCode": "",

"AdjustmentDescription": "",

"InvoiceNote": "",

"InvoiceReferenceQualifier2": "",

"InvoiceReference2": "",

"InvoiceDateQualifier": "003",

"InvoiceDate": "20260601"

{

"InvoiceReferenceQualifier": "IV",

"InvoiceNumber": "INV-2026-002",