--- title: Wires postal address update (November 2027) slug: apis/payments/wires/wires-postal-code-update description: Changes to FedWire postal address format for ISO 20022 compliance and Cross River's implementation approach docTags: createdAt: 2026-06-15T14:30:00.000Z --- ## Overview The Federal Reserve is updating the FedWire Funds Service to require structured postal addresses, effective **November 2027**. This change aligns FedWire with the **ISO 20022** international messaging standard. Instead of three unstructured address lines, you will provide address components in clearly defined fields. This ensures address information is transmitted more clearly and accurately, reducing errors and manual intervention across the payment chain. :::hint{type="warning"} **Action Required:** All Cross River partners must update their integrations as soon as possible to allow sufficient time for testing before the Federal Reserve's go-live date. The functionality is already live in production in Crossriver with full backward compatibility. ::: ## What's changing ### Federal Reserve timeline | Milestone | Date | | ------------------------ | ----------------- | | Testing opens | May 2026 | | Crossriver go-live date | June 2026 | | **FedWire go-live date** | **November 2027** | ### Cross River timeline | Milestone | Date | Status | | -------------------------------- | ------------- | ------------------------------------------------------- | | Sandbox environment available | Now | ✅ Available for Testing | | **Partner integration deadline** | **TDB** | ⚠️ Required | | Federal Reserve go-live | November 2027 | Waiting for confirmation from the Fed on the exact date | ## How Cross River is implementing this change ### The new postalAddress object We're adding a new `postalAddress` object to replace the current `address1`, `address2`, and `address3` fields. **Instead of this:** ```json { "address1": "123 Main Street, Suite 400", "address2": "New York, NY 10001", "address3": "" } ``` **Use this:** ```json { "postalAddress": { "adrLine1": "123 Main Street", "adrLine2": "Suite 400", "city": "New York", "state": "NY", "postalCode": "10001", "country": "US" } } ``` ### Required fields | Field | Description | Example | | ---------- | --------------------------------------- | ------------------- | | `adrLine1` | Street address (up to 35 characters) | `"123 Main Street"` | | `city` | City or town name (up to 35 characters) | `"New York"` | | `country` | Two-letter country code (ISO 3166-1) | `"US"` | ### Optional fields | Field | Description | Example | | ------------ | ------------------------------------------------ | ------------- | | `adrLine2` | Additional address info (up to 35 characters) | `"Suite 400"` | | `state` | State, province, or region (up to 35 characters) | `"NY"` | | `postalCode` | Postal or ZIP code (up to 16 characters) | `"10001"` | :::hint{type="success"} **Future Enhancement:** Character limits for `adrLine1` and `adrLine2` expand from 35 to 70 characters in a future release to match the Federal Reserve's full capacity. ::: ## Where this applies The new `postalAddress` object is used anywhere you currently provide address information in wire transfer requests: ### [Wire transfer](docId\:mC0d1W1u80umazO85mEIz) You must provide addresses for: - **Originator** - The party sending the wire - **Originator financial institution** - The bank sending the wire (if different from originator) - **Beneficiary** - The party receiving the wire - **Beneficiary financial institution** - The receiving bank - **Intermediary financial institution** - Any intermediary banks (optional) ### [Drawdown request](docId\:DOrha8h1ksr9-M_CT3ac-) Addresses are required for: - **Originator** (Creditor) - The party requesting funds - **Originator financial institution** - The requesting bank - **Drawdown debit account holder** (Debtor) - The party from whom funds are drawn - **Beneficiary financial institution** - The debit account holder's bank ### [Drawdown response](docId\:coz5emuCrFZLGzd59RdnA) Addresses are required for: - **Originator** - The party responding to the drawdown request ### [Webhook events: Wires](docId\:OA3cg-apKn_510VPq2yYe) All webhooks containing wire transfer information will also include the new postal address information for all parties in the transaction (as there are no embedded objects in webhooks, the new fields are listed ## Migration guide ### Step 1: Review (now) - Review this documentation and understand the new `postalAddress` structure - Identify all systems that send wire transfer requests or process wire webhooks - Note that three fields are now required: street address, city, and country ### Step 2: Update your code (as soon as possible) - Replace `address1`, `address2`, `address3` with the `postalAddress` object - Ensure you provide all three required fields: `adrLine1`, `city`, `country` - Update webhook handlers to read from `postalAddress` instead of `address1/2/3` - Add validation to ensure required fields are present before sending requests ### Step 3: Test in sandbox (now) - Use Cross River's sandbox environment to test your changes - Test all wire transfer types: standard transfers, drawdown requests, drawdown responses - Verify webhooks are processed correctly with the new format - Test with both domestic (US) and international addresses ### Step 4: Deploy to production (TBD) - Deploy your updated integration to production - Monitor for any validation errors - Confirm webhooks are processing correctly ### Step 5: Monitor after go-live (November 2027) - Monitor for any FedWire rejections related to address formatting - Ensure payments continue to process successfully ## Transition Period **During transition (Now through November 2027):** - Cross River accepts either old and new format but not both **After November 2027:** - The Federal Reserve **will reject wire transfers using the old unstructured format** - Payments using the old format will fail after November 2027 - All partners must use the new `postalAddress` format ## Common questions **Q: Can I continue using address1, address2, address3 during the transition?** A: Yes, Cross River supports either formats until November 2027. However, after that date, the Federal Reserve will reject wires with the old format. **Q: What if my address doesn't fit in 35 characters?** A: Cross River will expand the character limit to 70 characters in a future release. For now, abbreviate as needed or split the address across `adrLine1` and `adrLine2`. **Q: What if I only have street address and city, but no state or postal code?** A: That's fine. Only `adrLine1`, `city`, and `country` are required. The `adrLine2`, `state`, and `postalCode` fields are optional. **Q: How do I format international addresses?** A: Use the appropriate 2-letter country code (e.g., "GB" for United Kingdom, "CA" for Canada) and format the address according to that country's conventions. The `state` field can be used for provinces or regions. **Q: What are valid country codes?** A: Use ISO 3166-1 alpha-2 codes (2 uppercase letters). Examples: US (United States), GB (United Kingdom), CA (Canada), DE (Germany), FR (France), JP (Japan). See the [full list here](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). **Q: Can I test the new format now?** A: Yes! Our sandbox environment is already live and supports the new format. We encourage you to begin testing as soon as possible. ## API changes - request examples ### Wire transfer request ### Before (current format) ```json { "accountNumber": "1234567890", "businessFunctionCode": "CTR", "receiverRoutingNumber": "021000021", "amount": 1000000, "purpose": "Invoice payment", "originator": { "idCode": "D", "identifier": "1234567890", "name": "Acme Corporation", "address1": "456 Business Blvd", "address2": "New York, NY 10002", "address3": "" }, "beneficiaryFi": { "idCode": "D", "identifier": "021000021", "name": "JP Morgan Chase Bank", "address1": "270 Park Avenue", "address2": "New York, NY 10017", "address3": "" }, "beneficiary": { "idCode": "D", "identifier": "9876543210", "name": "Example LLC", "address1": "789 Commerce Ave", "address2": "Los Angeles, CA 90001", "address3": "" } } ``` ### After (new format) ```json { "accountNumber": "1234567890", "businessFunctionCode": "CTR", "receiverRoutingNumber": "021000021", "amount": 1000000, "purpose": "Invoice payment", "originator": { "idCode": "D", "identifier": "1234567890", "name": "Acme Corporation", "postalAddress": { "adrLine1": "456 Business Blvd", "city": "New York", "state": "NY", "postalCode": "10002", "country": "US" } }, "beneficiaryFi": { "idCode": "D", "identifier": "021000021", "name": "JP Morgan Chase Bank", "postalAddress": { "adrLine1": "270 Park Avenue", "city": "New York", "state": "NY", "postalCode": "10017", "country": "US" } }, "beneficiary": { "idCode": "D", "identifier": "9876543210", "name": "Example LLC", "postalAddress": { "adrLine1": "789 Commerce Ave", "city": "Los Angeles", "state": "CA", "postalCode": "90001", "country": "US" } } } ``` ### Webhook example As partners and other FedWire users adopt the new structured postal address elements the following additional fields can be populated *potentially before and after* November 2027: - Originator**Country** - Originator**State** - Originator**PostalCode** - Originator**City** - Beneficiary**Country** - Beneficiary**State** - Beneficiary**PostalCode** - Beneficiary**City** In addition, the following webhook fields will continue to exist and be populated as follows: - OriginatorAddress1 – populated from Originator.Address1 if present or Originator.PostalAddress.AdrLine1 if present - OriginatorAddress2 – populated from Originator.Address2 if present or Originator.PostalAddress.AdrLine2 if present - OriginatorAddress3 – populated from Originator.Address3 if present otherwise NOT populated (null) - BeneficiaryAddress1 – populated from Beneficiary.Address1 if present or Beneficiary.PostalAddress.AdrLine1 if present - BeneficiaryAddress2 – populated from Beneficiary.Address2 if present or Beneficiary.PostalAddress.AdrLine2 if present - BeneficiaryAddress3 – populated from Beneficiary.Address3 if present otherwise NOT populated (null) ```json { "eventType: "Wire.Payment.Processed", "eventId": "evt_12345", "timestamp": "26-06-30T10:12:130Z" { "paymentId": "9d63d00b-ba29-4102-9298-b4790091c7e4", "accountNumber": "358449449133", "direction": "Outbound", "imad": "20260630MFP00057000347", "omad": null, "paymentType": "Transfer", "purpose": "COINBASE WALLET USD WITHDRAWAL", "amount": "100", "clientIdentifier": null, "originatingFiName": "CROSS RIVER BANK", "originatingFiIdentifier": "021214891", "originatorName": "COINBASE INC", "originatorIdentifier": "358449449133", "originatorAddress1": "100 PINE STREET", "originatorAddress2": "SUITE 1250", "originatorAddress3": "SAN FRANCISCO CA 94111 US", "beneficiaryFiName": "CROSS RIVER BANK", "beneficiaryFiIdentifier": "021214891", "beneficiaryName": "SYNTH FEDWIRE PAYIN", "beneficiaryIdentifier": "000043400588", "beneficiaryAddress1": "123 MAIN ST APT 4B", "beneficiaryAddress2": "ARVADA CO 80001", "beneficiaryAddress3": "US", "beneficiaryReference": "RTL-7W4624TZ", "senderReference": "75F1NOVN045", "originatorToBeneficiary1": null, "originatorToBeneficiary2": null, "originatorToBeneficiary3": null, "originatorToBeneficiary4": null, "coreTransactionId": "6eb8c8a6-9145-485b-9513-b4790091c7e4", "senderRoutingNumber": "021214891", "originalPaymentId": "9d63d00b-ba29-4102-9298-b4790091c7e4", "originatorCountry": null, "originatorState": null, "originatorPostalCode": null, "originatorCity": null, "beneficiaryCountry": null, "beneficiaryState": null, "beneficiaryPostalCode": null, "beneficiaryCity": null } } ``` :::hint{type="warning"} During migration all webhook address information will continue to be provided in the old format while the new structured postal address elements will be provided with NULL values. ::: ## Validation rules The API validates the following: | Rule | Result if Not Met | | ----------------------------------------------------------------------------------------------- | ---------------------------------- | | `adrLine1` is required, max length 35 | Request rejected (400 Bad Request) | | `city` is required | Request rejected (400 Bad Request) | | `country` is required | Request rejected (400 Bad Request) | | `country` must be a valid 2-letter code (e.g., US, GB, CA) | Request rejected (400 Bad Request) | | `adrLine2` cannot exceed 35 characters, cannot be provided unless adrLine1 is provided | Request rejected (400 Bad Request) | | Cannot use both old format (`address1/2/3`) and new format (`postalAddress`) for the same party | Request rejected (400 Bad Request) | :::hint{type="warning"} **Important:** You cannot use both the old format (address1/2/3) and the new format (postalAddress) for the same party in a request. Choose one format per party. ::: ## Related resources **Support:** For questions or assistance with this migration, contact your Cross River representative.