{"templateId":"markdown","versions":[{"version":"v2026.04","label":"v2026.04","link":"/pt-br/products/payments-direct-2/introduction/concepts/payment-identities","default":true,"active":false,"folderId":"7e5507fe"},{"version":"v2026.03","label":"v2026.03","link":"/pt-br/products/payments-direct-2/v2026.03/introduction/concepts/payment-identities","default":false,"active":true,"folderId":"7e5507fe"},{"version":"v2025.11","label":"v2025.11","link":"/pt-br/products/payments-direct-2/v2025.11/introduction/concepts/payment-identities","default":false,"active":false,"folderId":"7e5507fe"}],"sharedDataIds":{"sidebar":"sidebar-@l10n/pt-BR/products/payments-direct-2/@v2025.11/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Payment identities","description":"User guides, API reference, and support resources.","siteUrl":"https://docs.ripple.com","lang":"en-US"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"payment-identities","__idx":0},"children":["Payment identities"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Identity Management v3"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This topic describes the v3 identity model. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Identity Management v3"]}," is recommended for all new integrations."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For supported payment corridors, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/v2026.03/introduction/payout-network"},"children":["Payout network"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For migration details or questions, contact your Ripple representative."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["payment identity"]}," is a structured record that represents either the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["originator"]}," or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["beneficiary"]}," of a payment. Identities hold personally identifiable information (PII) such as names, addresses, nationality, contact details, and identifying documents."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["With ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Identity Management v3"]},", identities are first-class resources that you create once and reuse across payments. They sit alongside financial instruments (bank accounts, local payment rails, wallets) and are referenced by ID from the ","Payments Direct"," API, instead of sending raw PII in every payment request."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Identity Management v3"]}," lets you:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create reusable identities instead of of embedding PII in each payment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Maintain a clear separation between ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["who"]}," is involved in a payment (identities) and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["how"]}," funds move (financial instruments)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Track identity history through immutable versions for audit and compliance."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enforce a one-to-one mapping between your ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["customer records"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ACTIVE identities"]}," via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This topic focuses on the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["v3 identity model"]},". The v3 API can also read legacy v2 identities, but v3 is the recommended model for new integrations."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-youll-learn","__idx":1},"children":["What you’ll learn"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this topic, you’ll learn:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["How identities are classified by ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["identityType"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INDIVIDUAL"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BUSINESS"]},") and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["paymentRole"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ORIGINATOR"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BENEFICIARY"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Which PII fields are available on ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["INDIVIDUAL"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["BUSINESS"]}," identities, and how corridor rules affect which fields are required."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["How identity versioning and lifecycle states (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACTIVE"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BLOCKED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DEACTIVATED"]},") work."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["How ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," provides ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["idempotency and deduplication"]},", so that at most one ACTIVE identity in your organization uses a given upstream customer ID."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["How identities relate to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["financial instruments"]},", which hold bank account and payout details."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"identity-types-and-payment-roles","__idx":2},"children":["Identity types and payment roles"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every identity is defined by two key properties:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityType"]}]}," – whether the identity is an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["individual"]}," or a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["business"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paymentRole"]}]}," – whether the identity acts as an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["originator"]}," or a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["beneficiary"]}," in payments"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"identity-types","__idx":3},"children":["Identity types"]},{"$$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":"Identity type"},"children":["Identity type"]},{"$$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":["INDIVIDUAL"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Used for natural persons. Includes personal details such as name, date of birth, address, contact information, and government ID data."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["BUSINESS"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Used for companies, institutions, or other organizations. Includes legal name, registered address, business identifiers (such as incorporation certificate or tax ID), and contact information."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The identity type determines which section of the identity object is populated:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["individual – for ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["INDIVIDUAL"]}," identities"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["business – for ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["BUSINESS"]}," identities"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Only one of these sections is populated for a given identity."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"payment-roles","__idx":4},"children":["Payment roles"]},{"$$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":"Payment role"},"children":["Payment role"]},{"$$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":["ORIGINATOR"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The party that initiates the payment and acts as the ultimate source of funds. This role represents the person or entity funding the transaction, even if the payment request is submitted through an intermediary or a nested payment flow."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["BENEFICIARY"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The party that acts as the ultimate destination of funds. This role represents the final recipient of the payment value, distinct from the financial institution, payout partner, or intermediary facilitating the transfer."]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"identity-lifecycle-and-versioning","__idx":5},"children":["Identity lifecycle and versioning"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Identities are immutable and versioned:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Each identity has a stable ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityId"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Each update creates a new ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["version"]},", leaving previous versions intact for audit."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The service tracks a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["schema version"]}," and timestamps for creation and updates."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"identity-states","__idx":6},"children":["Identity states"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityState"]}," field describes where an identity is in its lifecycle:"]},{"$$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":"State"},"children":["State"]},{"$$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":["ACTIVE"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Identity exists and can be used for payments."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["BLOCKED"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Identity exists but cannot be used until unblocked (for example, due to compliance review)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["DEACTIVATED"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Identity has been deactivated and should no longer be used for new payments."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["State changes are tracked per version; callers typically use the latest version when building new payments."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"relationship-to-financial-instruments","__idx":7},"children":["Relationship to financial instruments"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A payment identity represents the party, not the account."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Identities hold ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["who"]}," the party is (PII)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Financial instruments"]}," hold ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["where"]}," money is sent or received (for example, bank account details or wallet addresses)."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Identities and financial instruments"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each identity has ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["one active financial instrument"]},". This keeps a single KYC record for a party while letting you replace that party’s account details without re-creating the identity. Support for multiple financial instruments per identity is planned for a future release."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For details, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/v2026.03/introduction/concepts/financial-instruments"},"children":["Financial instruments"]},"."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"identity-object-reference","__idx":8},"children":["Identity object reference"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The sections below describe the core identity object returned by ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Identity Management v3"]}," responses."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"identity-metadata","__idx":9},"children":["Identity metadata"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These fields apply to every identity, regardless of type or role."]},{"$$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":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example"},"children":["Example"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["identityId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Server-generated unique identifier for the identity. Stable across all versions."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"2f4ac57f-c5ba-4051-b51f-b3565778717b\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["identityType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Identity category. Allowed values: INDIVIDUAL, BUSINESS."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"INDIVIDUAL\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["paymentRole"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payment role for this identity. Allowed values: ORIGINATOR, BENEFICIARY."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"BENEFICIARY\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["internalId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Client-provided unique identifier that links this identity to your upstream customer or account record. Required for ORIGINATOR identities; optional but recommended for BENEFICIARY identities.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Must be unique across all ACTIVE identities in your organization."]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"If you attempt to create or update an identity with an internalId that matches a different ACTIVE identity, the request will fail with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HTTP 409 Conflict"]},". This provides idempotency and helps prevent duplicate identities for the same real-world party.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"This is your own reference key, not the originator's account number. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#the-originators-account-number"},"children":["The originator's account number"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"customer-12345-uuid\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["originatorAccountNumber"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The originator's account number, or your customer identifier for the originator. Ripple forwards this value to the payout partner.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Required on ORIGINATOR identities validated against ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CN_CFXPS"]},"; optional elsewhere. It is only sent to payout partners for originators, so there is normally no reason to set it on a beneficiary.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Must be unique across all ACTIVE identities in your organization, including BENEFICIARY identities."]}," Duplicate values fail with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HTTP 409 Conflict"]},".",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Corridor length and character limits apply but are not validated on this field. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#the-originators-account-number"},"children":["The originator's account number"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"6222021001125874\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["nickName"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Human-readable alias to simplify management in your systems."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"primary-gbp-sender\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["tags"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["array"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Free-form labels (strings) for categorizing or filtering identities (for example by segment, region, or customer tier)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["[\"vip\", \"gb-smb\"]"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["validatePayoutRails"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["array"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["List of payout methods (financial instrument types) that this identity should be validated against. When provided, the identity's PII is validated to ensure it meets the requirements for the specified payment rails.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Values include: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["US_ACH"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["US_FEDWIRE"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MX_SPEI"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EU_SEPA"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GB_FPS"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CA_EFT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NG_BANK_PAYOUT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_PIX"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_TED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CO_PSE"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GH_BANK_PAYOUT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RW_BANK_PAYOUT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ZA_BANK_PAYOUT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UG_BANK_PAYOUT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ZM_BANK_PAYOUT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ETH_WALLET"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRON_WALLET"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SOL_WALLET"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AE_IPI"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IN_NEFT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CN_CFXPS"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CL_TEF"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TH_PROMPTPAY"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["KR_KFTC"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AU_NPP"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["JP_ZENGIN"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PE_LBTR"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AR_INTERBANKING"]},".",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#validating-identities-for-specific-payment-rails"},"children":["Validating identities for specific payment rails"]}," for details."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["[\"US_ACH\", \"MX_SPEI\"]"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["version"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Sequential version number for this identity. Increments with each successful update."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["2"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["schemaVersion"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Schema version used to validate this identity’s PII payload."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"1.0.0\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["identityState"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Lifecycle state of the identity: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACTIVE"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BLOCKED"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DEACTIVATED"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"ACTIVE\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["createdAt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["RFC 3339 timestamp when the identity was first created."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"2025-11-02T18:26:00.000Z\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["updatedAt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["RFC 3339 timestamp when the identity was last updated (latest version created)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"2025-11-03T18:26:00.000Z\""]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"idempotency-and-deduplication-with-internalid","__idx":10},"children":["Idempotency and deduplication with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each identity can carry a client-provided ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," that links it back to your own customer or account record. This allows ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Identity Management v3"]}," to help you avoid duplicate identities for the same real-world party and makes it easier to reconcile identities across systems."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["At a high level:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["required"]}," for ORIGINATOR identities and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["optional"]}," for BENEFICIARY identities."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," must be ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["unique across all ACTIVE identities"]}," within your organization."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If you try to create or update an identity so that its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," matches a different ACTIVE identity, the request fails with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HTTP 409 Conflict"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," is your own reference key. It is not the originator's account number: send that in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["originatorAccountNumber"]},". See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#the-originators-account-number"},"children":["The originator's account number"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This behavior gives you a simple, reliable way to enforce a one-to-one relationship between your upstream customer record and an ACTIVE identity in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Identity Management v3"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"how-internalid-is-used","__idx":11},"children":["How ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," is used"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Identity Management v3"]}," uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," in three main places:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create identity (v3)"]},": When you call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v3/identities"]},", you can (and for ORIGINATORs, must) provide ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," in the request body. If another ACTIVE identity in your organization already uses the same value, the request fails with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["409 Conflict"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Update identity (v3)"]}," When you call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /v3/identities/{identity-id}"]},", you can change ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]},". If the new value is already assigned to a different ACTIVE identity, the update fails with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["409 Conflict"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Identity responses"]},": Identity responses include the current ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]},", so you can easily map an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityId"]}," back to your own customer record."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The uniqueness check is scoped to your organization. Different organizations can reuse the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," values without conflict."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"recommended-patterns","__idx":12},"children":["Recommended patterns"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When choosing and using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]},", we recommend that you:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["stable upstream key"]},", such as a CRM customer ID, core-banking customer ID, or KYC master record ID. You do not need to adapt it for any corridor: corridors that need the originator's account number read ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#the-originators-account-number"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["originatorAccountNumber"]}]}," instead."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Avoid embedding PII (for example, emails, phone numbers, national IDs) directly in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Treat ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," as effectively immutable for the life of an identity whenever possible."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Handle ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["409 Conflict"]}," responses as “duplicate identity” signals:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Look up and reuse the existing identity instead of creating a new one."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Investigate your upstream systems if multiple records are attempting to reuse the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]},"."]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For step-by-step examples of how to send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," in create and update calls, and how to handle 409 conflicts, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/v2026.03/api-docs/developer-guides/create-and-manage-identities"},"children":["Create and manage identities"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"the-originators-account-number","__idx":13},"children":["The originator's account number"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Some payout partners need the originator's own account number, not just a reference to the identity. Send that value in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["originatorAccountNumber"]}," on the ORIGINATOR identity. Ripple forwards it to the payout partner."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["originatorAccountNumber"]}," is optional on most corridors. On the corridor below it is required, and creating or updating the identity without it fails with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400 Bad Request"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USR_111"]},"). On that corridor a randomly generated UUID or other arbitrary reference causes the payout to be rejected."]},{"$$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":"20%","data-label":"Corridor"},"children":["Corridor "]},{"$$mdtype":"Tag","name":"th","attributes":{"width":"30%","data-label":"Required when"},"children":["Required when "]},{"$$mdtype":"Tag","name":"th","attributes":{"width":"25%","data-label":"Value to send"},"children":["Value to send "]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Format"},"children":["Format"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["China (USD)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The identity is validated against ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CN_CFXPS"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The originator's bank account number, or your customer identifier for the originator"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Maximum 34 characters, matching ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/^[A-Za-z0-9/?:().,'+ -]+$/"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Corridor formats are not validated on this field"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The API accepts any string in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["originatorAccountNumber"]},". The length and character limits above come from the payout partner and are applied when the payment is sent, not when you create the identity. A value that breaks them is accepted at identity creation and fails later, at payout."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"how-originatoraccountnumber-behaves","__idx":14},"children":["How ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["originatorAccountNumber"]}," behaves"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Uniqueness spans both roles."]}," The value must be unique across all ACTIVE identities in your organization. A duplicate returns ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["409 Conflict"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USR_122"]},"). A beneficiary identity that already carries a value blocks a later originator from using it, so you cannot reuse one shared account number across several identities."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["One value per identity."]}," The value is sent on every payment that identity originates. If an originator sends on the corridor above, its value must satisfy that corridor's limits, even when the same originator also sends on corridors that place no constraints on it."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["PUT replaces state."]}," Omitting ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["originatorAccountNumber"]}," on an update clears it, the same way ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," behaves. Send the value again on every update you want it preserved through."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Withheld from list responses."]}," As PII, the field is omitted from the identity list operation. It is returned when you retrieve a single identity, retrieve by internal ID, or update one."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Omitting it falls back to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]},"."]}," When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["originatorAccountNumber"]}," is empty, Ripple sends ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," to the payout partner in its place, as the originator's account number. On the corridor above that is almost always the wrong value, and in ","Payments Direct UI"," it is a generated UUID the sender never sees."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Not the same as internalId"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," is your own reference key for the identity, and it has its own separate uniqueness rule. It is not the originator's account number."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It is, however, what the payout partner receives as the account number whenever ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["originatorAccountNumber"]}," is empty. Send the account number in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["originatorAccountNumber"]}," so that fallback never applies."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For corridor-specific detail, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/v2026.03/api-docs/integration-resources"},"children":["Integration resources"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"validating-identities-for-specific-payment-rails","__idx":15},"children":["Validating identities for specific payment rails"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]}," field allows you to specify which payout methods (financial instrument types) an identity should be validated against when it is created or updated. This ensures that the identity's PII meets all the requirements for the payment rails you plan to use."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"what-validatepayoutrails-does","__idx":16},"children":["What ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]}," does"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you provide ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]}," in a create or update request:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Identity Management v3"]}," validates the identity's PII against the corridor-specific requirements for each specified payment rail."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If the identity is missing required fields for any of the specified rails, the request fails with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400 Bad Request"]}," and details about which fields are missing."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If validation passes, the identity is created or updated, and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]}," value is stored with the identity."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]}," field is optional."]}," If you omit it, the identity is created with only basic structural validation, covering fields such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["firstName"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lastName"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["address"]},". What happens after that depends on the payment role:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Beneficiary identities"]}," are checked against the corridor when you add a financial instrument, because the instrument names the payment rail."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Originator identities"]}," are not. An originator cannot have a financial instrument, so there is no later checkpoint. Corridor-required fields go unchecked, and the first sign of a missing one is the payout partner rejecting the payment."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For an originator that will send on a corridor with its own requirements, naming the rail in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]}," is the only way to catch a missing field when you create the identity rather than when a payment fails."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"when-to-use-validatepayoutrails","__idx":17},"children":["When to use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]}," when you want to:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Validate upfront"]}," that an identity has all required PII for specific corridors before creating financial instruments or payments."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Prevent downstream errors"]}," by catching missing or invalid PII early in the identity creation flow."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Support multiple corridors"]}," by validating that a single identity can be used across different payment rails (for example, both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["US_ACH"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MX_SPEI"]},")."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"supported-values","__idx":18},"children":["Supported values"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]}," array accepts any of the following financial instrument types:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["US_ACH"]}," – U.S. domestic bank transfers (RTP-primary, ACH fallback)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["US_FEDWIRE"]}," – U.S. Fedwire real-time gross settlement"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MX_SPEI"]}," – Mexico's SPEI interbank transfer system"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EU_SEPA"]}," – SEPA credit transfers for EUR payments"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GB_FPS"]}," – UK Faster Payments Service"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CA_EFT"]}," – Canada's Electronic Funds Transfer"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NG_BANK_PAYOUT"]}," – Nigeria bank payout (NGN)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_PIX"]}," – Brazil's instant payment platform (PIX)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_TED"]}," – Brazil's Electronic Funds Transfer (TED)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CO_PSE"]}," – Colombia's secure online banking payment system"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GH_BANK_PAYOUT"]}," – Ghana bank payout (GHS), via GIS"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RW_BANK_PAYOUT"]}," – Rwanda bank payout (RWF), via RSwitch"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ZA_BANK_PAYOUT"]}," – South Africa bank payout (ZAR), via PayShap"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UG_BANK_PAYOUT"]}," – Uganda bank payout (UGX)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ZM_BANK_PAYOUT"]}," – Zambia bank payout (ZMW), via ZECHL"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ETH_WALLET"]}," – Ethereum network wallet payouts (USDT, USDC, RLUSD)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRON_WALLET"]}," – Tron network wallet payouts (USDT)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SOL_WALLET"]}," – Solana network wallet payouts (USDC)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AE_IPI"]}," – UAE Instant Payment Interface (AED), with FTS fallback"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IN_NEFT"]}," – India National Electronic Funds Transfer (INR)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CN_CFXPS"]}," – China USD payouts via China Foreign Exchange Payment System (CFXPS)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CL_TEF"]}," – Chile TEF (CLP)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TH_PROMPTPAY"]}," – Thailand PromptPay (THB)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["KR_KFTC"]}," – South Korea KFTC (KRW)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AU_NPP"]}," – Australia New Payments Platform (AUD), with Direct Entry (BECS) fallback"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["JP_ZENGIN"]}," – Japan Zengin (JPY), with Zengin Prompt Service for real-time low-value transfers"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PE_LBTR"]}," – Peru LBTR (PEN)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AR_INTERBANKING"]}," – Argentina Interbanking (ARS)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can specify one or more values. For example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"validatePayoutRails\": [\"US_ACH\", \"MX_SPEI\", \"EU_SEPA\"]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"how-validation-works","__idx":19},"children":["How validation works"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each payment rail has specific PII requirements based on:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payment role"]}," (ORIGINATOR vs BENEFICIARY)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Identity type"]}," (INDIVIDUAL vs BUSINESS)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Destination country and local regulations"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For example:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["US_ACH"]}," for BENEFICIARY INDIVIDUAL"]}," requires: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["firstName"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lastName"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["address"]},", and at least one ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityDocument"]}," (typically SSN or Tax ID)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_PIX"]}," for BENEFICIARY INDIVIDUAL"]}," requires: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["firstName"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lastName"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["address"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dateOfBirth"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["phone"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["citizenship"]},", and at least one ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityDocument"]}," (typically CPF)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MX_SPEI"]}," for BENEFICIARY BUSINESS"]}," requires: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["businessName"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["address"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["phone"]},", and at least one ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["registration"]}," (typically RFC tax ID)."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you specify ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Identity Management v3"]}," checks that all required fields for each rail are present and valid. If any required field is missing, the request fails with a detailed error response."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"example-create-an-identity-with-payment-rail-validation","__idx":20},"children":["Example: Create an identity with payment rail validation"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://{base-url}/v3/identities\" \\\n  -H \"Authorization: Bearer <access_token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"identityType\": \"INDIVIDUAL\",\n    \"paymentRole\": \"BENEFICIARY\",\n    \"internalId\": \"customer-12345\",\n    \"validatePayoutRails\": [\"US_ACH\", \"MX_SPEI\"],\n    \"individual\": {\n      \"firstName\": \"Jane\",\n      \"lastName\": \"Doe\",\n      \"dateOfBirth\": \"1990-01-15\",\n      \"email\": \"jane.doe@example.com\",\n      \"phone\": \"+12025551234\",\n      \"address\": {\n        \"streetAddress\": [\"123 Main St\"],\n        \"city\": \"Boston\",\n        \"stateOrProvince\": \"MA\",\n        \"postalCode\": \"02125\",\n        \"country\": \"US\"\n      },\n      \"identityDocuments\": [\n        {\n          \"idType\": \"SSN\",\n          \"idNumber\": \"123-45-6789\"\n        }\n      ]\n    }\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this example:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The identity is validated against both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["US_ACH"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MX_SPEI"]}," requirements."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If the identity is missing any required fields for either rail (for example, missing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityDocuments"]}," for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["US_ACH"]},"), the request fails with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400 Bad Request"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If validation passes, the identity is created and can be used with both US ACH and MX SPEI financial instruments."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"relationship-to-financial-instruments-1","__idx":21},"children":["Relationship to financial instruments"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]}," on the identity is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["independent"]}," from the financial instruments you create:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You can validate an identity against ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["US_ACH"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MX_SPEI"]},", then create only a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["US_ACH"]}," financial instrument initially."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Later, you can add an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MX_SPEI"]}," financial instrument to the same identity without re-validating the identity."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The identity's PII remains validated for both rails, even if you haven't created financial instruments for all of them yet."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Validation is advisory"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]}," provides ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["upfront validation"]}," but does not restrict which financial instruments you can create. You can still create financial instruments for rails not listed in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]},", but those instruments may fail validation if the identity's PII is incomplete for that rail."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"updating-validatepayoutrails","__idx":22},"children":["Updating ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can update ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]}," using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /v3/identities/{identity-id}"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X PUT \"https://{base-url}/v3/identities/{identity-id}\" \\\n  -H \"Authorization: Bearer <access_token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"validatePayoutRails\": [\"US_ACH\", \"MX_SPEI\", \"EU_SEPA\"]\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you update ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The identity's PII is re-validated against the new set of rails."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If the identity is missing required fields for any newly added rail, the update fails with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400 Bad Request"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If validation passes, a new identity version is created with the updated ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]}," value."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"best-practices","__idx":23},"children":["Best practices"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Specify all rails you plan to use"]}," for an identity upfront to catch PII issues early."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use it for BENEFICIARY identities"]}," where you may not know which payment rail will be used until later (for example, a vendor who might receive payments via ACH or SPEI depending on currency)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Combine with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}]}," to ensure each customer has exactly one validated identity across all corridors."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Handle 400 errors gracefully"]}," by prompting users to provide missing PII fields before retrying."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"individual-identity-properties-individual","__idx":24},"children":["Individual identity properties (individual)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityType"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INDIVIDUAL"]},", the individual object contains the person’s PII data."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Conditional requirements"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Many of these fields are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["conditionally required"]}," for specific payment rails and roles (for example, certain local regulations may require date of birth or national ID). Those conditions are summarized in the “Conditional requirements” column."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"core-personal-details","__idx":25},"children":["Core personal details"]},{"$$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":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Conditional requirements (examples)"},"children":["Conditional requirements (examples)"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example"},"children":["Example"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["firstName"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["First name of the individual."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"John\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["lastName"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Last name of the individual."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"Smith\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["address"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Postal address for the individual, including street, city, postal code, state/province, and country."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Country must use ISO 3166-1 alpha-2 code (for example, US, GB, BR). Some corridor validations may require all address lines to be present and formatted correctly."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"address-structure","__idx":26},"children":["Address structure"]},{"$$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":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example"},"children":["Example"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["streetAddress"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string[]"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One or more free-form address lines (for example, street, building, apartment)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["[\"123 Example St. Apt 4B\"]"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["city"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["City or locality."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"Boston\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["stateOrProvince"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["State, province, or region, as defined by local postal services.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Required for most corridors, but not for the African bank payout corridors (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NG_BANK_PAYOUT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GH_BANK_PAYOUT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RW_BANK_PAYOUT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UG_BANK_PAYOUT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ZA_BANK_PAYOUT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ZM_BANK_PAYOUT"]},"). Use the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/v2026.03/api-docs/integration-resources/payload-schema-utility"},"children":["Payload Schema Utility"]}," to check a specific corridor and role."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"Massachusetts\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["postalCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Postal or ZIP code.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Required for most corridors, but not for the African bank payout corridors (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NG_BANK_PAYOUT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GH_BANK_PAYOUT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RW_BANK_PAYOUT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UG_BANK_PAYOUT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ZA_BANK_PAYOUT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ZM_BANK_PAYOUT"]},"). Use the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/v2026.03/api-docs/integration-resources/payload-schema-utility"},"children":["Payload Schema Utility"]}," to check a specific corridor and role."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"02125\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["country"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Country of residence, using ISO 3166-1 alpha-2 code."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"US\""]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"contact-details-and-identification","__idx":27},"children":["Contact details and identification"]},{"$$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":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Conditional requirements (examples)"},"children":["Conditional requirements (examples)"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example"},"children":["Example"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["email"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Email address of the individual."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required for BENEFICIARY on some rails (for example, BR_PIX, BR_TED, CO_PSE) where payout partners require email as part of KYC or notification flows."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"fake@example.com\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["phone"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Mobile or contact phone number in international format (+ and country code)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required for some payment rails (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_PIX"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_TED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NG_BANK_PAYOUT"]},") for either the originator, beneficiary, or both, depending on corridor-specific regulations."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"+1234567890\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["identityDocuments"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["array"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One or more identification documents used to verify the individual (for example, passport, national ID, tax ID)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required for BENEFICIARY on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AR_INTERBANKING"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_PIX"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_TED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CL_TEF"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CO_PSE"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PE_LBTR"]},", and for ORIGINATOR on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AR_INTERBANKING"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_PIX"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CL_TEF"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PE_LBTR"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["dateOfBirth"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Date of birth in YYYY-MM-DD format."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Commonly required for BENEFICIARY on rails like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EU_SEPA"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GB_FPS"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_PIX"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_TED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CA_EFT"]},", and for ORIGINATOR on some corridors (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EU_SEPA"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GB_FPS"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_PIX"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_TED"]},")."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"2001-01-24\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["countryOfBirth"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Country of birth, ISO 3166-1 alpha-2 code."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required for ORIGINATOR on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AR_INTERBANKING"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_PIX"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_TED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CL_TEF"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PE_LBTR"]},", where local regulations mandate this data. Not required for beneficiaries."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"US\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["citizenship"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Country of citizenship, ISO 3166-1 alpha-2 code."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required for BENEFICIARY on some rails (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_PIX"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_TED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["KR_KFTC"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TH_PROMPTPAY"]},"), and sometimes for ORIGINATOR depending on corridor rules."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"US\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["gender"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Gender of the individual. Allowed values include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MALE"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FEMALE"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OTHER"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Not required on any corridor. Send it only if your own compliance processes call for it."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"FEMALE\""]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"identity-document-structure","__idx":28},"children":["Identity document structure"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each element of individual.identityDocuments has the following structure:"]},{"$$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":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example"},"children":["Example"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["idNumber"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Identification number printed on the document (for example, passport number, national ID)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"123ABC\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["idType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Type of identification document. The full enum is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ALIEN_REGISTRATION"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CUSTOMER_ID"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DRIVERS_LICENSE"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PASSPORT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EMPLOYEE_ID"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NATIONAL_ID_NUMBER"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SSN"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TAX_ID"]},". Accepted values vary by corridor and payment role, and the API rejects unsupported types with a 400 error. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#accepted-document-types-by-corridor"},"children":["Accepted document types by corridor"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"PASSPORT\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["expiryDate"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Expiration date of the identification document, as an ISO 8601 date (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["YYYY-MM-DD"]},").",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Required on ORIGINATOR identities validated against ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IN_NEFT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["KR_KFTC"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TH_PROMPTPAY"]},"; optional elsewhere."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"2030-01-15\""]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"business-identity-properties-business","__idx":29},"children":["Business identity properties (business)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityType"]}," is BUSINESS, the business object contains the organization’s PII data."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"core-business-details","__idx":30},"children":["Core business details"]},{"$$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":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Conditional requirements (examples)"},"children":["Conditional requirements (examples)"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example"},"children":["Example"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["businessName"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Legal name of the business or institution."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"Widgets Org\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["address"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Registered or primary operating address of the business, including street, city, postal code, state, and country."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Country must use ISO 3166-1 alpha-2 code (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["US"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GB"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR"]},"). Some corridor validations may require all address lines to be present and formatted correctly."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"address-structure-1","__idx":31},"children":["Address structure"]},{"$$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":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example"},"children":["Example"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["streetAddress"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string[]"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One or more free-form address lines for the business."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["[\"123 Example St. Boston, MA\"]"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["city"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["City or locality."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"Boston\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["stateOrProvince"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["State, province, or region, as defined by local postal services.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Required for most corridors, but not for the African bank payout corridors (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NG_BANK_PAYOUT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GH_BANK_PAYOUT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RW_BANK_PAYOUT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UG_BANK_PAYOUT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ZA_BANK_PAYOUT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ZM_BANK_PAYOUT"]},"). Use the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/v2026.03/api-docs/integration-resources/payload-schema-utility"},"children":["Payload Schema Utility"]}," to check a specific corridor and role."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"Massachusetts\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["postalCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Postal or ZIP code.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Required for most corridors, but not for the African bank payout corridors (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NG_BANK_PAYOUT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GH_BANK_PAYOUT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RW_BANK_PAYOUT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UG_BANK_PAYOUT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ZA_BANK_PAYOUT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ZM_BANK_PAYOUT"]},"). Use the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/v2026.03/api-docs/integration-resources/payload-schema-utility"},"children":["Payload Schema Utility"]}," to check a specific corridor and role."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"02125\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["country"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Country of the business address, using ISO 3166-1 alpha-2 code."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"US\""]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"contact-details-and-registration","__idx":32},"children":["Contact details and registration"]},{"$$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":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Conditional requirements (examples)"},"children":["Conditional requirements (examples)"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example"},"children":["Example"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["email"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["General contact email address for the business."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required for some rails for ORIGINATOR and/or BENEFICIARY (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AR_INTERBANKING"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_PIX"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_TED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CO_PSE"]},") where the destination rail requires email contact details."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"fake@example.com\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["phone"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Primary business phone number in international format (+ and country code)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required on selected rails such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_PIX"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_TED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NG_BANK_PAYOUT"]}," for originators and beneficiaries, depending on corridor."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"+1234567890\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["registration"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["array"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One or more business registration identifiers (for example, incorporation certificate, tax ID)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required for specific rails where local regulations require a business registration number (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_PIX"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_TED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CA_EFT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CO_PSE"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EU_SEPA"]},")."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["incorporationCountry"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Country where the business is incorporated, using ISO 3166-1 alpha-2 code."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required for BENEFICIARY on some payment rails (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_TED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NG_BANK_PAYOUT"]},") and for ORIGINATOR on selected rails (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_PIX"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_TED"]},")."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"US\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["incorporationDate"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Date the business was incorporated, in YYYY-MM-DD format."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"2020-01-15\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["legalEntityType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Classification of the business legal entity. Determines regulatory treatment and compliance requirements for certain payment corridors. Values: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BANK_CENTRAL"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BANK_COMMERCIAL"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYMENT_INSTITUTION"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CORPORATE_PRIVATE"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CORPORATE_PUBLIC"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GOVERNMENT_ENTITY"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NON_PROFIT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SOLE_TRADER"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required for ORIGINATOR on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_PIX"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"CORPORATE_PRIVATE\""]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"business-registration-structure","__idx":33},"children":["Business registration structure"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each element of business.registration has the following structure:"]},{"$$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":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example"},"children":["Example"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["number"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unique registration identifier issued to the business (for example, company registration number)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"123ABC\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Type of registration identifier. The full enum is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INCORPORATION_CERTIFICATE"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TAX_ID"]},". Accepted values vary by corridor and payment role, and the API rejects unsupported types with a 400 error. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#accepted-document-types-by-corridor"},"children":["Accepted document types by corridor"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["\"TAX_ID\""]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"corridor-specific-and-rail-specific-requirements","__idx":34},"children":["Corridor-specific and rail-specific requirements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["PII requirements vary depending on:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payment role"]},": originator vs beneficiary"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payment rail / financial instrument type"]},": for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["US_ACH"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MX_SPEI"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_PIX"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NG_BANK_PAYOUT"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Destination country and local regulations"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-requiredByOriginatorFor"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-requiredByBeneficiaryFor"]}," annotations in the API schema capture these conditions for each field. In practice:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Identity Management v3"]}," and related tooling validate identities against the appropriate rules for the selected payment rails."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You should provide all fields that may be required for the corridors you plan to use, even if they are not globally required for every identity."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For corridor-level schema details and validation rules, refer to the Financial instruments topic."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"jurisdiction-based-requirements","__idx":35},"children":["Jurisdiction-based requirements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Jurisdiction"]}," is a regulatory region Ripple records against your organization's account. A jurisdiction is a property of your organization, not a value you send in a request, so it applies to every identity you create, on every corridor."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your jurisdiction is your own, and it does not change with the party you are transacting for. If you create identities on behalf of third parties, as a payment service provider or a bank does, your jurisdiction still governs those identities, wherever those parties are based and whichever corridor they pay on."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Jurisdiction requirements add to the corridor requirements above rather than replacing them. A field your jurisdiction requires is required even on corridors that would otherwise treat it as optional."]},{"$$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":"20%","data-label":"Jurisdiction"},"children":["Jurisdiction "]},{"$$mdtype":"Tag","name":"th","attributes":{"width":"25%","data-label":"Field"},"children":["Field "]},{"$$mdtype":"Tag","name":"th","attributes":{"width":"25%","data-label":"Applies to"},"children":["Applies to "]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Effect"},"children":["Effect"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Brazil (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR"]},")"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityDocuments"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ORIGINATOR identities"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required on every corridor, including corridors that do not otherwise require it"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Creating or updating an originator identity without the field fails with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400 Bad Request"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USR_111"]},")."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Updates must resend `identityDocuments`"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An update validates the body you send, not the record already stored. If your organization is configured for the BR jurisdiction, any update to an originator identity that omits ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityDocuments"]}," fails, even when you are changing something unrelated such as a nickname or an address. Send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityDocuments"]}," on every update to an originator identity."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Identities created before this requirement took effect are affected the same way."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/v2026.03/api-docs/integration-resources/payload-schema-utility"},"children":["Payload schema utility"]}," has a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Jurisdiction"]}," selection. Set it to your organization's jurisdiction and the tool reports the fields it requires alongside the corridor's own."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To confirm how your organization is configured, contact your Ripple representative."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"accepted-document-types-by-corridor","__idx":36},"children":["Accepted document types by corridor"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Some corridors accept only a subset of the document-type enum, and the API rejects unsupported values with a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400 error"]},". Enforcement is based on the corridors in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]}," (at identity creation) or the financial instrument type (at instrument creation). Corridors and roles not listed below accept the full enum for the field."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Individual identities (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityDocuments.type"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idType"]},")"]}]},{"$$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":"Corridor"},"children":["Corridor"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Originator"},"children":["Originator"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Beneficiary"},"children":["Beneficiary"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AR_INTERBANKING"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["TAX_ID"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["NATIONAL_ID_NUMBER, SSN"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AU_NPP"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["PASSPORT"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["All"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_PIX"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["PASSPORT, TAX_ID"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["TAX_ID"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_TED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["PASSPORT, TAX_ID"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["TAX_ID"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CL_TEF"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["PASSPORT, TAX_ID"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["NATIONAL_ID_NUMBER, TAX_ID"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CO_PSE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["All"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ALIEN_REGISTRATION, NATIONAL_ID_NUMBER, TAX_ID"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IN_NEFT"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["PASSPORT"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["All"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["KR_KFTC"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["PASSPORT"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["All"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PE_LBTR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["PASSPORT, TAX_ID"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["NATIONAL_ID_NUMBER, TAX_ID"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TH_PROMPTPAY"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["PASSPORT"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ALIEN_REGISTRATION, DRIVERS_LICENSE, EMPLOYEE_ID, NATIONAL_ID_NUMBER, PASSPORT, SSN, TAX_ID"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Business identities (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["registration.type"]},")"]}]},{"$$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":"Corridor"},"children":["Corridor"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Originator"},"children":["Originator"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Beneficiary"},"children":["Beneficiary"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AR_INTERBANKING"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["TAX_ID"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["TAX_ID"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_PIX"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["TAX_ID"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["TAX_ID"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BR_TED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["TAX_ID"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["TAX_ID"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CL_TEF"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["TAX_ID"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["TAX_ID"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CO_PSE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["All"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["TAX_ID"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ETH_WALLET"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["All"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["INCORPORATION_CERTIFICATE"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PE_LBTR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["TAX_ID"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["TAX_ID"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SOL_WALLET"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["All"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["INCORPORATION_CERTIFICATE"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRON_WALLET"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["All"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["INCORPORATION_CERTIFICATE"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":37},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["To learn how to create, update, list, and deactivate identities via the API, including how to use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalId"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]},", see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/v2026.03/api-docs/developer-guides/create-and-manage-identities"},"children":["Create and manage identities"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["To understand how identities connect to payout account details, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/v2026.03/introduction/concepts/financial-instruments"},"children":["Financial instruments"]},"."]}]}]},"headings":[{"value":"Payment identities","id":"payment-identities","depth":1},{"value":"What you’ll learn","id":"what-youll-learn","depth":2},{"value":"Identity types and payment roles","id":"identity-types-and-payment-roles","depth":2},{"value":"Identity types","id":"identity-types","depth":3},{"value":"Payment roles","id":"payment-roles","depth":3},{"value":"Identity lifecycle and versioning","id":"identity-lifecycle-and-versioning","depth":2},{"value":"Identity states","id":"identity-states","depth":3},{"value":"Relationship to financial instruments","id":"relationship-to-financial-instruments","depth":2},{"value":"Identity object reference","id":"identity-object-reference","depth":2},{"value":"Identity metadata","id":"identity-metadata","depth":3},{"value":"Idempotency and deduplication with internalId","id":"idempotency-and-deduplication-with-internalid","depth":3},{"value":"How internalId is used","id":"how-internalid-is-used","depth":4},{"value":"Recommended patterns","id":"recommended-patterns","depth":4},{"value":"The originator's account number","id":"the-originators-account-number","depth":3},{"value":"How originatorAccountNumber behaves","id":"how-originatoraccountnumber-behaves","depth":4},{"value":"Validating identities for specific payment rails","id":"validating-identities-for-specific-payment-rails","depth":3},{"value":"What validatePayoutRails does","id":"what-validatepayoutrails-does","depth":4},{"value":"When to use validatePayoutRails","id":"when-to-use-validatepayoutrails","depth":4},{"value":"Supported values","id":"supported-values","depth":4},{"value":"How validation works","id":"how-validation-works","depth":4},{"value":"Example: Create an identity with payment rail validation","id":"example-create-an-identity-with-payment-rail-validation","depth":4},{"value":"Relationship to financial instruments","id":"relationship-to-financial-instruments-1","depth":4},{"value":"Updating validatePayoutRails","id":"updating-validatepayoutrails","depth":4},{"value":"Best practices","id":"best-practices","depth":4},{"value":"Individual identity properties (individual)","id":"individual-identity-properties-individual","depth":3},{"value":"Core personal details","id":"core-personal-details","depth":4},{"value":"Address structure","id":"address-structure","depth":4},{"value":"Contact details and identification","id":"contact-details-and-identification","depth":4},{"value":"Identity document structure","id":"identity-document-structure","depth":4},{"value":"Business identity properties (business)","id":"business-identity-properties-business","depth":3},{"value":"Core business details","id":"core-business-details","depth":4},{"value":"Address structure","id":"address-structure-1","depth":4},{"value":"Contact details and registration","id":"contact-details-and-registration","depth":4},{"value":"Business registration structure","id":"business-registration-structure","depth":4},{"value":"Corridor-specific and rail-specific requirements","id":"corridor-specific-and-rail-specific-requirements","depth":3},{"value":"Jurisdiction-based requirements","id":"jurisdiction-based-requirements","depth":3},{"value":"Accepted document types by corridor","id":"accepted-document-types-by-corridor","depth":3},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Payment identities","seo":{"title":"Payment identities"}},"lastModified":"2026-10-21T03:05:03.816Z","pagePropGetterError":{"message":"","name":""}},"slug":"/pt-br/products/payments-direct-2/v2026.03/introduction/concepts/payment-identities","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}