{"templateId":"markdown","versions":[{"version":"v2026.03","label":"v2026.03","link":"/products/payments-direct-2/api-docs/integration-resources/na/us/usd","default":true,"active":true,"folderId":"eb16255d"},{"version":"v2025.11","label":"v2025.11","link":"/products/payments-direct-2/v2025.11/api-docs/integration-resources/na/us/usd","default":false,"active":false,"folderId":"eb16255d"}],"sharedDataIds":{"sidebar":"sidebar-products/payments-direct-2/@v2025.11/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"United States (USD) Transaction Data Requirements","description":"User guides, API reference, and support resources.","siteUrl":"https://docs.ripple.com/products/custody","lang":"en-US","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":"united-states-usd-transaction-data-requirements","__idx":0},"children":["United States (USD) Transaction Data Requirements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following transaction-level fields apply to all USD payments to the United States, regardless of payment rail or use case."]},{"$$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":{"width":"15%","data-label":"Field"},"children":["Field "]},{"$$mdtype":"Tag","name":"th","attributes":{"width":"20%","data-label":"Description"},"children":["Description "]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"width":"40%","data-label":"Constraints"},"children":["Constraints "]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["purposeCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Purpose of payment"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ENUM"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#purpose-of-payment-codes"},"children":["valid values"]}," below"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentMemo"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payment memo"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["STRING"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["0–500 chars. ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Pattern: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["^[\\w #@!,.&()\\/\\\\-]{0,500}$"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"identity-address-field-requirements","__idx":1},"children":["Identity address field requirements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following constraints apply to address fields on identities used in US USD payments. The payout partner enforces stricter formatting than the base identity schema allows, so values that pass identity creation may still cause payment failures if the format does not match."]},{"$$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":{"width":"15%","data-label":"Field"},"children":["Field "]},{"$$mdtype":"Tag","name":"th","attributes":{"width":"20%","data-label":"Description"},"children":["Description "]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"width":"40%","data-label":"Constraints"},"children":["Constraints "]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stateOrProvince"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["State or territory"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["STRING"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Use the 2-letter USPS state abbreviation (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NY"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CA"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TX"]},"). Full state names such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["New York"]}," are not accepted. For Puerto Rico, use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Puerto Rico"]},", not ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PR"]},". Pattern: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["^[A-Za-z]{2,25}$"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"purpose-of-payment-codes","__idx":2},"children":["Purpose of payment codes"]},{"$$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":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCT"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Account Management"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EDUC"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Education"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAMI"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Family Support Related Payments"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FEES"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payment of Fees"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GDDS"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Purchase or Sale of Goods"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INSU"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Insurance Premium"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IVPT"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invoice Payment"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ROYA"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Royalties"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SALA"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Salary Payment"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SAVG"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Savings"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SCVE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Purchase or Sale of Services"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UBIL"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Utility Bill Payments"]}]}]}]}]}]},"headings":[{"value":"United States (USD) Transaction Data Requirements","id":"united-states-usd-transaction-data-requirements","depth":1},{"value":"Identity address field requirements","id":"identity-address-field-requirements","depth":2},{"value":"Purpose of payment codes","id":"purpose-of-payment-codes","depth":2}],"frontmatter":{"title":"United States — USD Transaction Data Requirements","description":"Transaction-level field requirements and valid values for USD payments to the United States.","seo":{"title":"United States (USD) Transaction Data Requirements"}},"lastModified":"2026-03-31T03:43:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/payments-direct-2/api-docs/integration-resources/na/us/usd","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}