{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-products/tpp/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["partial"]},"type":"markdown"},"seo":{"title":"Developer Documentation","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"addresses-on-sepa-and-sepa-instant-payments","__idx":0},"children":["Addresses on SEPA and SEPA Instant payments"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you're integrating a payment flow that can route over the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SEPA"]}," or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SEPA Instant"]}," schemes, the postal address you attach to the creditor (and optionally the debtor) needs to meet the European Payments Council's structured address requirements from the 15th November 2026. It is recommended you consider this for your implementation as soon as possible."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"considerations","__idx":1},"children":["Considerations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You need to read this page if any of the following apply to your integration:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You initiate ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SEPA"]}," or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SEPA Instant"]}," payments (including via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTO_SELECT"]}," resolving to one of these rails), and you populate ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["creditor.address"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["debtor.address"]}," across our Payments v1 or Payments v2 API."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You integrate with a bank that ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["mandates a creditor address"]},". In Token.io's registry, 113 banks currently require one, concentrated in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Italy (94 banks, via CBI Globe)"]},", with the rest spread across the UK, Poland, Spain, Hungary, Norway, Finland and Sweden."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You're deciding how to model postal addresses in your own data layer before mapping them onto Token.io's API."]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can skip this if you only use rails outside the SEPA schemes — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FASTER_PAYMENTS"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ELIXIR"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BANKGIRO"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PLUSGIRO"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EU_DOMESTIC_NON_EURO"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EU_DOMESTIC_NON_EURO_INSTANT"]}," — or you never supply an address object and no bank in your flow requires one. Note that ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["no bank in Token.io's registry requires a debtor address"]}," — where an address is mandated, it's always on the creditor."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"why-the-address-format-matters","__idx":2},"children":["Why the address format matters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The European Payments Council's guidance ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["EPC153-22 v2.1"]},", ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Provision of Addresses under the EPC Payment Schemes"]},", removes the fully ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["unstructured"]}," postal address from the SEPA schemes from ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["15th November 2026"]},". From that date, any postal address carried in a SEPA Credit Transfer or SEPA Instant Credit Transfer must be either ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["structured"]}," or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["hybrid"]},":"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Format"},"children":["Format"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Structured ( townName + country )"},"children":["Structured (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["townName"]}," + ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["country"]},")"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"addressLine"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["addressLine"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Accepted from 15th November 2026"},"children":["Accepted from 15th November 2026"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Structured"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Not used"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Hybrid"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes — max 2 lines × 70 characters"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unstructured"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes, lines only"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Token.io's address object already supports the hybrid format — structured fields alongside a free-text line — so there's no need to wait for a schema change. The design goal for your integration is simple: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["never rely on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["addressLine"]}," alone."]}," Build your mapping so the structured fields are always populated when you have the data, and use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["addressLine"]}," only for what genuinely doesn't fit a structured field — a building name, floor, or department."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Getting this right at initiation means a bad address surfaces as an immediate 400 with the exact field to fix, rather than the payment failing later at the payer's bank, or being silently repaired or rejected downstream after the payer believes it's succeeded."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"field-reference","__idx":3},"children":["Field reference"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Purpose"},"children":["Purpose"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field (v2, address )"},"children":["Field (v2, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["address"]},")"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field (v1, customer_data.address )"},"children":["Field (v1, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customer_data.address"]},")"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Requirement"},"children":["Requirement"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Max length"},"children":["Max length"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Error code"},"children":["Error code"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Town / city"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["townName"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["city"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Mandatory"]}," whenever an address object is supplied"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["35"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Field.Expected"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Field.InvalidFormat"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Country"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["country"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["country"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Mandatory"]}," whenever an address object is supplied; ISO 3166-1 alpha-2, upper case"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["2"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Field.Expected"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Field.Invalid"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Street"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["streetName"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["street"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["70"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Field.InvalidFormat"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Building number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buildingNumber"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["houseNumber"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Recommended"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["16"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Field.InvalidFormat"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Post code"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["postCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["postCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Recommended"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["16"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Field.InvalidFormat"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Remaining unstructured text"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["addressLine"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["full"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Recommended, last resort"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["2 entries, 70 characters each"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Field.InvalidFormat"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," an earlier version of this content listed ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["streetName"]}," as the v2 field for Building number — that's been corrected to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buildingNumber"]}," above to match the field name used elsewhere in the API and in the reference docs. Worth a final check against the OpenAPI schema before this goes live."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These lengths aren't Token.io-specific limits — they're the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ISO 20022"]}," lengths that the SEPA schemes and the underlying open banking standards apply. Since the API doesn't currently enforce them, it's worth building your own client-side validation against this table rather than discovering the limits from a live rejection."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["townName"]}," is worth checking first."]}," At 35 characters it's the shortest of the two mandatory fields, and unlike ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["country"]},", town names vary a lot in length. If your own data model allows longer values, decide deliberately how you'll truncate or reject them, rather than letting the value pass through unexamined."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example-building-a-compliant-address","__idx":4},"children":["Example: building a compliant address"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An address expressed as a single free-text line ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["won't be considered structured or hybrid"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"\"address\": {\n  \"addressLine\": [\"Palazzo Vecchio, Piano 2, Via Roma 12, 50122 Firenze, Italia\"]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The same address, split into structured fields with only the non-structured remainder left in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["addressLine"]},", is the pattern to build towards:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"\"creditor\": {\n  \"iban\": \"IT60X0542811101000000123456\",\n  \"name\": \"Customer Inc.\",\n  \"address\": {\n    \"addressLine\": [\"Palazzo Vecchio, Piano 2\"],\n    \"streetName\": \"Via Roma\",\n    \"buildingNumber\": \"12\",\n    \"postCode\": \"50122\",\n    \"townName\": \"Firenze\",\n    \"country\": \"IT\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A couple of things to avoid when building your mapping:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Don't duplicate an element in both places."]}," If you populate ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["townName"]},", don't also repeat the town inside ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["addressLine"]}," — duplicated elements may be rejected or duplicated in the payment message by the payer's bank."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Don't let ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["addressLine"]}," grow past 2 entries or 70 characters each."]}," If your source address data doesn't fit, that's a sign it should be broken into structured fields instead of truncated."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handling-validation-errors","__idx":5},"children":["Handling validation errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A non-compliant address returns a 400 with the standard field-error object, listing the offending JSON paths:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"error\": {\n    \"errorCode\": \"Field.Expected\",\n    \"message\": \"The fields 'townName' and 'country' are required when an address is supplied for a SEPA payment.\",\n    \"paths\": [\n      \"initiation.creditor.address.townName\",\n      \"initiation.creditor.address.country\"\n    ],\n    \"tokenTraceId\": \"eASI3Onqkpi1unAM59O5\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These are existing error codes (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Field.Expected"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Field.Invalid"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Field.InvalidFormat"]},") already used for field validation elsewhere in the API — no new codes are introduced for this."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"where-the-address-object-appears","__idx":6},"children":["Where the address object appears"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The same address object is shared across several Token.io products. Design your address-handling logic once and reuse it everywhere you touch these endpoints:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payments v2"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v2/payments"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.token.io/products/tpp/api/reference/payments-v2/initiatepayment#payments-v2/initiatepayment/t=request&path=initiation/creditor&oneof=0/address"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["initiation.creditor.address"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.token.io/products/tpp/api/reference/payments-v2/initiatepayment#payments-v2/initiatepayment/t=request&path=initiation/debtor&oneof=0&oneof=0/address"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["initiation.debtor.address"]}]}," — applies when you supply full debtor account details (not when using an Account on File identifier), and is validated on the same terms as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["creditor.address"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payments v1"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /token-requests"]}," ","Uses a different address model with different field names: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfer_body.instructions.transfer_destinations.customer_data.address"]},". Field lengths are the same as v2 — they come from ISO 20022, not the API version. If you're integrating fresh, prefer v2's field names and structure. If you're on v1 and use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["full"]}," field, be aware it's documented as free text that \"typically cannot be parsed by software.\" Pair it with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["city"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["country"]},", and keep it within the 2×70 character limit."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Pay by Link"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v2/payment-links"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentTemplate.creditor.address"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Refunds"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /refunds"]}," doesn't take a postal address at all; a refund's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["creditor.address"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["debtor.address"]}," are derived from the original payment. No extra handling needed here."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Variable Recurring Payments"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /vrp-consents"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["initiation.creditor.address"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["initiation.debtor.address"]},". VRP consents currently only support UK Faster Payments accounts, which sit outside the SEPA schemes, so these rules don't currently bite on VRP — but the same object is used, so build to this standard now if you want to be ready should a SEPA rail be added later."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"integration-checklist","__idx":7},"children":["Integration checklist"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," Populate ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["townName"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["country"]}," (v1: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["city"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["country"]},") on every ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SEPA/SEPA"]}," Instant address you send. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["country"]}," must be upper-case ISO 3166-1 alpha-2."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," Map any single free-text address into structured fields, keeping only the genuine remainder in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["addressLine"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," Validate field lengths client-side against the table above before sending — don't rely on the API to catch it."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," Avoid duplicating the same address element across a structured field and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["addressLine"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," Populate ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["streetName"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["buildingNumber"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["postCode"]}," wherever you hold the data — recommended, not mandatory, but the safer default as more banks complete their own migrations."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," Parse the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paths"]}," array on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Field.*"]}," errors so validation failures surface as actionable, field-level messages to your own users."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," Test address handling in Sandbox before going live."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"further-reading","__idx":8},"children":["Further reading"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/epc-guidance-document-provision-addresses-under-epc-payment"},"children":["EPC153-22 v2.1 — Provision of Addresses under the EPC Payment Schemes"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.token.io/products/tpp/api/reference/payments-v2/initiatepayment"},"children":["POST /v2/payments API reference"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For help with any of the above, contact ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://support.token.io/"},"children":["Token.io Support"]}," or speak with your implementation manager."]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you have any feedback about the developer documentation, please contact ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"mailto:devdocs@token.io"},"children":["devdocs@token.io"]}]}]},"headings":[{"value":"Addresses on SEPA and SEPA Instant payments","id":"addresses-on-sepa-and-sepa-instant-payments","depth":1},{"value":"Considerations","id":"considerations","depth":2},{"value":"Why the address format matters","id":"why-the-address-format-matters","depth":2},{"value":"Field reference","id":"field-reference","depth":2},{"value":"Example: building a compliant address","id":"example-building-a-compliant-address","depth":2},{"value":"Handling validation errors","id":"handling-validation-errors","depth":2},{"value":"Where the address object appears","id":"where-the-address-object-appears","depth":2},{"value":"Integration checklist","id":"integration-checklist","depth":2},{"value":"Further reading","id":"further-reading","depth":2}],"frontmatter":{"PARENTCOMPANY":"Token.io","COMPANY":"Token.io","THIRDPARTY":"TPP","THIRDPARTYCAP":"TPP","PRODUCT":"tpp","seo":{"title":""}},"lastModified":"2026-08-21T15:00:44.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/tpp/integration-considerations/address-validation-sepa","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}