gridpin

Structured postal addresses for ISO 20022 payments

Payment messages are moving to structured addresses: street, building number, postcode and town in their own elements, not one free line. Most address lists hold the free line.

New Mail and payments Command line

What you have

An address line as you have it, and the country file. One line at a time:

Steps

1. Ask for the ISO 20022 form as JSON: the elements, the checks and the mode:

terminalCLI
$ gridpin format usa.bin "233 S Wacker Dr, Chicago, IL 60606" --out iso20022
{"PstlAdr":{"BldgNb":"233","Ctry":"US","PstCd":"60606","StrtNm":"South WACKER Drive","TwnNm":"Chicago"},"checks":[],"exists":{"exists":"yes","reason":"house_found"},"mode":"structured"}

2. The same as the <PstlAdr> element:

terminalCLI
$ gridpin format usa.bin "233 S Wacker Dr, Chicago, IL 60606" --out iso20022 --xml
<PstlAdr><StrtNm>South WACKER Drive</StrtNm><BldgNb>233</BldgNb><PstCd>60606</PstCd><TwnNm>Chicago</TwnNm><Ctry>US</Ctry></PstlAdr>

3. German street abbreviations are expanded and the town is the postal town:

terminalCLI
$ gridpin format germany.bin "Friedrichstr. 100, Berlin" --out iso20022 --xml
<PstlAdr><StrtNm>Friedrichstraße</StrtNm><BldgNb>100</BldgNb><PstCd>10117</PstCd><TwnNm>Berlin</TwnNm><Ctry>DE</Ctry></PstlAdr>

4. A line the file cannot confirm is not turned into a structured address. It stays hybrid: the line as written, the town and the country.

terminalCLI
$ gridpin format usa.bin "350 Fifth Avenue, New York" --out iso20022
{"PstlAdr":{"AdrLine":["350 Fifth Avenue"],"Ctry":"US","TwnNm":"New York"},"checks":["weak_answer","street_unknown"],"exists":{"exists":"no","reason":"wrong_city"},"mode":"hybrid"}

What you get

modeWhenWhat is filled
structuredthe file confirms the house as written: exists is yes, in the town the line namesStrtNm, BldgNb, PstCd, TwnNm, Ctry
hybridthe answer is weak, the street unknown, the number between known houses, or the house is in another town than the one namedAdrLine as written, TwnNm, Ctry
nonenothing can be madenothing; checks says why

Why it works

The line is geocoded first, and the elements are copied from the house the file found, not cut out of the text. A weak answer would put somebody else's street into a payment, so it is not used: the line stays as written and checks names the reason (weak_answer, street_unknown).

Limits

  • It builds the address element only, not the whole message, and does not check names or accounts.
  • One line per call; for a whole file run it in a loop or see the audit, which counts structured, hybrid and none for every row.
  • Only the countries GridPin has files for; the country code comes from the file.
  • A whole pain.001 message is checked by gridpin-pro iso20022-check; --rewrite writes a copy where an address changes only when the file's answer keeps the written postcode, house number with its letter and town, and the report names why the others were kept. It was tested on pain.001 messages we built, not yet on a bank's; pacs.008, encodings other than UTF-8 and XSD validation are not tested yet.
  • The town is read from the line after its first comma. A town the file does not have gives mode none, even when the street is right.
  • The letter of a house number is not compared: “7B” answered by house 7 gives BldgNb 7. Check BldgNb against your line when numbers carry letters.

All its keys: command reference. The function: print an address the way the post writes it.

More