Create an identity

Requisição

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.

Segurança

Bearer

Corpoapplication/jsonobrigatório

identityTypestringobrigatório

The type of the identity

Enum Value	Description
BUSINESS	Identity associated with an institution or business
INDIVIDUAL	Identity associated with an individual

Exemplo:"BUSINESS"

paymentRolestringobrigatório

The payment role of the identity

Enum Value	Description
ORIGINATOR	Refers to originator identity
BENEFICIARY	Refers to beneficiary identity

Exemplo:"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.

Exemplo:"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.

Exemplo:"6222021001125874"

businessobject

PII data to support business and institutional identities

individualobject

Data for an individual

nickNamestring, <= 256 characters

The nickname for the identity

Exemplo:"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/pt-br/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"
      }
    }
  }'

Respostas

Identity created.

Corpoapplication/json

identityIdstringobrigatório

The unique ID of the identity

Exemplo:"2f4ac57f-c5ba-4051-b51f-b3565778717b"

versionstringobrigatório

The version number of the identity

Exemplo:"2"

Resposta

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