This topic describes the v3 identity model. Identity Management v3 is recommended for new integrations.
A payment identity is a structured record that represents either the originator or beneficiary of a payment. Identities hold personally identifiable information (PII) such as names, addresses, nationality, contact details, and identifying documents.
With Identity Management v3, identities are first-class resources that you create once and reuse across payments. They sit alongside financial instruments (bank accounts, local payout rails, wallets) and are referenced by ID from the Payments Direct API, instead of sending raw PII in every payment request.
Identity Management v3 lets you:
- Create reusable identities instead of of embedding PII in each payment.
- Maintain a clear separation between who is involved in a payment (identities) and how funds move (financial instruments).
- Track identity history through immutable versions for audit and compliance.
- Enforce a one-to-one mapping between your customer records and ACTIVE identities via
internalId.
This topic focuses on the v3 identity model. The v3 API can also read legacy v2 identities, but v3 is the recommended model for new integrations.
In this topic, you’ll learn:
- How identities are classified by identityType (
INDIVIDUAL,BUSINESS) and paymentRole (ORIGINATOR,BENEFICIARY). - Which PII fields are available on INDIVIDUAL and BUSINESS identities, and how corridor rules affect which fields are required.
- How identity versioning and lifecycle states (
ACTIVE,BLOCKED,DEACTIVATED) work. - How
internalIdprovides idempotency and deduplication, so that at most one ACTIVE identity in your tenant uses a given upstream customer ID. - How identities relate to financial instruments, which hold bank account and payout details.
Every identity is defined by two key properties:
identityType– whether the identity is an individual or a businesspaymentRole– whether the identity acts as an originator or a beneficiary in payments
| Identity type | Description |
|---|---|
| INDIVIDUAL | Used for natural persons. Includes personal details such as name, date of birth, address, contact information, and government ID data. |
| BUSINESS | Used for companies, institutions, or other organizations. Includes legal name, registered address, business identifiers (such as incorporation certificate or tax ID), and contact information. |
The identity type determines which section of the identity object is populated:
- individual – for INDIVIDUAL identities
- business – for BUSINESS identities
Only one of these sections is populated for a given identity.
| Payment role | Description |
|---|---|
| ORIGINATOR | The party that initiates the payment and ultimately pays for it. Often the customer or corporate client using Ripple Payments Direct. |
| BENEFICIARY | The party that receives the funds. This may be an individual or business in a different country, subject to local KYC and payout-partner requirements. |
Identities are immutable and versioned:
- Each identity has a stable
identityId. - Each update creates a new version, leaving previous versions intact for audit.
- The service tracks a schema version and timestamps for creation and updates.
The identityState field describes where an identity is in its lifecycle:
| State | Description |
|---|---|
| ACTIVE | Identity exists and can be used for payments. |
| BLOCKED | Identity exists but cannot be used until unblocked (for example, due to compliance review). |
| DEACTIVATED | Identity has been deactivated and should no longer be used for new payments. |
State changes are tracked per version; callers typically use the latest version when building new payments.
A payment identity represents the party, not the account.
- Identities hold who the party is (PII).
- Financial instruments hold where money is sent or received (for example, bank account details or wallet addresses).
An identity can be associated with one or more financial instruments. This lets you keep a single KYC record for a party while managing multiple payout accounts (for example, a vendor with both a local MX SPEI account and a EUR SEPA account).
For details, see Financial instruments.
The sections below describe the core identity object returned by Identity Management v3 responses.
These fields apply to every identity, regardless of type or role.
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
| identityId | string | Yes | Server-generated unique identifier for the identity. Stable across all versions. | "2f4ac57f-c5ba-4051-b51f-b3565778717b" |
| identityType | string | Yes | Identity category. Allowed values: INDIVIDUAL, BUSINESS. | "INDIVIDUAL" |
| paymentRole | string | Yes | Payment role for this identity. Allowed values: ORIGINATOR, BENEFICIARY. | "BENEFICIARY" |
| internalId | string | Conditional | Client-defined identifier that links this identity to your customer or account record. Required for ORIGINATOR identities; optional for BENEFICIARY identities. Must be unique across all ACTIVE identities in your tenant. If you try to create or update an identity with an internalId that is already used by a different ACTIVE identity, the request fails with HTTP 409 Conflict. | "customer-12345" |
| nickName | string | No | Human-readable alias to simplify management in your systems. | "primary-gbp-sender" |
| tags | array | No | Free-form labels (strings) for categorizing or filtering identities (for example by segment, region, or customer tier). | ["vip", "gb-smb"] |
| version | integer | Yes | Sequential version number for this identity. Increments with each successful update. | 2 |
| schemaVersion | string | Yes | Schema version used to validate this identity’s PII payload. | "1.0.0" |
| identityState | string | Yes | Lifecycle state of the identity: ACTIVE, BLOCKED, or DEACTIVATED. | "ACTIVE" |
| createdAt | string | Yes | RFC 3339 timestamp when the identity was first created. | "2025-11-02T18:26:00.000Z" |
| updatedAt | string | Yes | RFC 3339 timestamp when the identity was last updated (latest version created). | "2025-11-03T18:26:00.000Z" |
Each identity can carry a client-defined internalId that links it back to your own customer or account record. This allows Identity Management v3 to help you avoid duplicate identities for the same real-world party and makes it easier to reconcile identities across systems.
At a high level:
internalIdis required for ORIGINATOR identities and optional for BENEFICIARY identities.internalIdmust be unique across all ACTIVE identities within your environment.- If you try to create or update an identity so that its
internalIdmatches a different ACTIVE identity, the request fails with HTTP 409 Conflict.
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 Identity Management v3.
Identity Management v3 uses internalId in three main places:
- Create identity (v3): When you call
POST /v3/identities, you can (and for ORIGINATORs, must) provideinternalIdin the request body. If another ACTIVE identity in your tenant already uses the same value, the request fails with 409 Conflict. - Update identity (v3) When you call
PUT /v3/identities/{identity-id}, you can changeinternalId. If the new value is already assigned to a different ACTIVE identity, the update fails with 409 Conflict. - Identity responses: Identity responses include the current
internalId, so you can easily map anidentityIdback to your own customer record.
The uniqueness check is scoped to your tenant. Different tenants can reuse the same internalId values without conflict.
When choosing and using internalId, we recommend that you:
- Use a stable upstream key, such as a CRM customer ID, core-banking customer ID, or KYC master record ID.
- Avoid embedding PII (for example, emails, phone numbers, national IDs) directly in
internalId. - Treat
internalIdas effectively immutable for the life of an identity whenever possible. - Handle 409 Conflict responses as “duplicate identity” signals:
- Look up and reuse the existing identity instead of creating a new one.
- Investigate your upstream systems if multiple records are attempting to reuse the same
internalId.
For step-by-step examples of how to send internalId in create and update calls, and how to handle 409 conflicts, see Create and manage identities.
When identityType is INDIVIDUAL, the individual object contains the person’s PII data.
Many of these fields are 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.
| Field | Type | Required | Description | Conditional requirements (examples) | Example |
|---|---|---|---|---|---|
| firstName | string | Yes | First name of the individual. | — | "John" |
| lastName | string | Yes | Last name of the individual. | — | "Smith" |
| address | object | Yes | Postal address for the individual, including street, city, postal code, state/province, and country. | 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. | — |
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
| streetAddress | string[] | Yes | One or more free-form address lines (for example, street, building, apartment). | ["123 Example St. Apt 4B"] |
| city | string | Yes | City or locality. | "Boston" |
| stateOrProvince | string | Yes | State, province, or region, as defined by local postal services. | "Massachusetts" |
| postalCode | string | Yes | Postal or ZIP code. | "02125" |
| country | string | Yes | Country of residence, using ISO 3166-1 alpha-2 code. | "US" |
| Field | Type | Required | Description | Conditional requirements (examples) | Example |
|---|---|---|---|---|---|
| string | Conditional | Email address of the individual. | 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. | "fake@example.com" | |
| phone | string | Conditional | Mobile or contact phone number in international format (+ and country code). | Required for some payout rails (for example, BR_PIX, BR_TED, AFRICA_BANK_PAYOUT) for either the originator, beneficiary, or both, depending on corridor-specific regulations. | "+1234567890" |
| identityDocuments | array | Conditional | One or more identification documents used to verify the individual (for example, passport, national ID, tax ID). | Required for certain rails and roles, such as BENEFICIARY on US_ACH, BR_PIX, BR_TED, CO_PSE, AFRICA_BANK_PAYOUT, and ORIGINATOR on BR_PIX, depending on corridor requirements. | — |
| dateOfBirth | string | Conditional | Date of birth in YYYY-MM-DD format. | Commonly required for BENEFICIARY on rails like US_ACH, EU_SEPA, GB_FPS, BR_PIX, BR_TED, CA_EFT, and for ORIGINATOR on some corridors (for example, EU_SEPA, BR_PIX`). | "2001-01-24" |
| countryOfBirth | string | Conditional | Country of birth, ISO 3166-1 alpha-2 code. | Required for ORIGINATOR on some payout rails (for example, portions of AFRICA_BANK_PAYOUT, BR_PIX) where local regulations mandate this data. | "US" |
| citizenship | string | Conditional | Country of citizenship, ISO 3166-1 alpha-2 code. | Required for BENEFICIARY on some rails (for example, BR_PIX, BR_TED, AFRICA_BANK_PAYOUT), and sometimes for ORIGINATOR depending on corridor rules. | "US" |
| gender | string | Conditional | Gender of the individual. Allowed values include MALE, FEMALE, OTHER. | Required for BENEFICIARY on certain payout rails (for example, some AFRICA_BANK_PAYOUT corridors) where local clearing systems require it. | "FEMALE" |
Each element of individual.identityDocuments has the following structure:
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
| idNumber | string | Yes | Identification number printed on the document (for example, passport number, national ID). | "123ABC" |
| idType | string | Yes | Type of identification document. Supported values include ALIEN_REGISTRATION, CUSTOMER_ID, DRIVERS_LICENSE, PASSPORT, EMPLOYEE_ID, NATIONAL_ID_NUMBER, SSN, TAX_ID. | "PASSPORT" |
When identityType is BUSINESS, the business object contains the organization’s PII data.
| Field | Type | Required | Description | Conditional requirements (examples) | Example |
|---|---|---|---|---|---|
| businessName | string | Yes | Legal name of the business or institution. | — | "Widgets Org" |
| address | object | Yes | Registered or primary operating address of the business, including street, city, postal code, state, and country. | 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. | — |
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
| streetAddress | string[] | Yes | One or more free-form address lines for the business. | ["123 Example St. Boston, MA"] |
| city | string | Yes | City or locality. | "Boston" |
| stateOrProvince | string | Yes | State, province, or region, as defined by local postal services. | "Massachusetts" |
| postalCode | string | Yes | Postal or ZIP code. | "02125" |
| country | string | Yes | Country of the business address, using ISO 3166-1 alpha-2 code. | "US" |
| Field | Type | Required | Description | Conditional requirements (examples) | Example |
|---|---|---|---|---|---|
| string | Conditional | General contact email address for the business. | Required for some rails for ORIGINATOR and/or BENEFICIARY (for example, BR_PIX, BR_TED, CO_PSE, AFRICA_BANK_PAYOUT) where payout partners require email contact details. | "fake@example.com" | |
| phone | string | Conditional | Primary business phone number in international format (+ and country code). | Required on selected rails such as BR_PIX, BR_TED, AFRICA_BANK_PAYOUT for originators and beneficiaries, depending on corridor. | "+1234567890" |
| registration | array | Conditional | One or more business registration identifiers (for example, incorporation certificate, tax ID). | Required for specific rails where local regulations require a business registration number (for example, combinations of US_ACH, CA_EFT, BR_PIX, BR_TED, CO_PSE, AFRICA_BANK_PAYOUT, sometimes EU_SEPA). | — |
| incorporationCountry | string | Conditional | Country where the business is incorporated, using ISO 3166-1 alpha-2 code. | Required for BENEFICIARY on some payout rails (for example, BR_PIX, BR_TED, AFRICA_BANK_PAYOUT) and for ORIGINATOR on selected rails (for example, BR_PIX, BR_TED) where local rules mandate incorporation country. | "US" |
Each element of business.registration has the following structure:
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
| number | string | Yes | Unique registration identifier issued to the business (for example, company registration number). | "123ABC" |
| type | string | Yes | Type of registration identifier. Typical values include INCORPORATION_CERTIFICATE, TAX_ID. | "TAX_ID" |
PII requirements vary depending on:
- Payment role: originator vs beneficiary
- Payment rail / financial instrument type: for example,
US_ACH,MX_SPEI,BR_PIX,AFRICA_BANK_PAYOUT - Destination country and local regulations
The x-requiredByOriginatorFor and x-requiredByBeneficiaryFor annotations in the API schema capture these conditions for each field. In practice:
- Identity Management v3 and related tooling validate identities against the appropriate rules for the selected payout rails.
- 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.
For corridor-level schema details and validation rules, refer to the Financial instruments topic.
- To learn how to create, update, list, and deactivate identities via the API, see Create and manage identities.
- To understand how identities connect to payout account details, see Financial instruments.