Skip to content

Identities

Use these API operations to manage your identities with Identity Management v3 (recommended for all new integrations). For more information about identity management, see Payment identities and Financial instruments.

OperationMethodDescription
Create an identityPOSTCreate a new identity (INDIVIDUAL/BUSINESS; ORIGINATOR/BENEFICIARY).
Get a list of identitiesGETRetrieve a list of identities with optional filters (e.g., paymentRole, identityType).
Get an identity by IDGETRetrieve a specific identity by identityId (latest version by default).
Get an identity by internal IDGETRetrieve an active identity by client-provided internalId.
Update an identityPUTUpdate one or more fields; creates a new version.
Deactivate an identityDELETESet the identity state to DEACTIVATED (cannot be used for new payments).
Add a financial instrumentPOSTAdd a financial instrument to an identity.
Get a list of financial instrumentsGETGet a list of financial instruments for an identity.
Get a financial instrument by IDGETGet a specific financial instrument by financialInstrumentId.
Update a financial instrumentPUTUpdate a financial instrument by financialInstrumentId.
Deactivate a financial instrumentDELETEDeactivate a financial instrument by financialInstrumentId.
Operations

Create an identity

Request

Create a new payment identity as an ORIGINATOR or BENEFICIARY for either an INDIVIDUAL or BUSINESS.

The request body must follow the v3 identity schema and will be validated against corridor rules where applicable.

On success, the API returns the new identityId and its initial version.

Security
Bearer
Bodyapplication/jsonrequired
identityTypestringrequired

The type of the identity

Enum ValueDescription
BUSINESS

Identity associated with an institution or business

INDIVIDUAL

Identity associated with an individual

Example:"BUSINESS"
paymentRolestringrequired

The payment role of the identity

Enum ValueDescription
ORIGINATOR

Refers to originator identity

BENEFICIARY

Refers to beneficiary identity

Example:"BENEFICIARY"
internalIdstring

Client-provided unique identifier for idempotency and deduplication. Required for ORIGINATOR identities; optional for BENEFICIARY identities. Must be unique across all active identities in your organization. Duplicate values will result in a 409 Conflict error.

This is your own reference key, not the originator's account number. Use originatorAccountNumber for that.

Example:"customer-12345-uuid"
originatorAccountNumberstring

The originator's account number, or your customer identifier for the originator. Required for ORIGINATOR identities on USD payments to China (CN_CFXPS); optional elsewhere. Only sent to payout partners for ORIGINATOR identities.

Must be unique across all active identities in your organization, including BENEFICIARY identities. Duplicate values return a 409 Conflict error.

Corridor length and character limits apply to this value but are not enforced on this field. See the corridor's Integration resources page.

Example:"6222021001125874"
businessobject

PII data to support business and institutional identities

individualobject

Data for an individual

nickNamestring, <= 256 characters

The nickname for the identity

Example:"nickName"
validatePayoutRailsArray of strings

The payment rails to validate the identity against

tagsArray of strings, <= 25 items

Tags are used to categorize the identity.

curl -i -X POST \
  https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v3/identities \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "identityType": "INDIVIDUAL",
    "paymentRole": "ORIGINATOR",
    "internalId": "customer-12345-uuid",
    "nickName": "Alice Sender USD",
    "tags": [
      "sender",
      "priority"
    ],
    "validatePayoutRails": [
      "CO_PSE"
    ],
    "individual": {
      "firstName": "Alice",
      "lastName": "Chen",
      "dateOfBirth": "1990-05-14",
      "citizenship": "US",
      "address": {
        "streetAddress": [
          "123 Main Street"
        ],
        "city": "San Francisco",
        "stateOrProvince": "CA",
        "postalCode": "94105",
        "country": "US"
      }
    }
  }'

Responses

Identity created.

Bodyapplication/json
identityIdstringrequired

The unique ID of the identity

Example:"2f4ac57f-c5ba-4051-b51f-b3565778717b"
versionstringrequired

The version number of the identity

Example:"2"
Response
{
  "identityId": "99254c4f-f207-4792-a846-06928825018c",
  "version": "1"
}