Skip to content

Ripple PII-Service Api (1.0.0)

This is the PII Service Api

Overview
E-mail

rn-architecture@ripple.com

License

Apache 2.0

Terms of Service

Languages
Servers
Mock server

https://docs.ripple.com/_mock/products/payments-direct/api-docs/pii-service/reference/pii-service-external/

Identities

Operations

Get a list of identities

Request

Get a list of identities that match the query parameters.

Note: Depending on the number of identities in your account, not all of them may be returned even if they match your query parameters.

Security
Bearer
Query
identityTypestring

The type of identities you want to retrieve

Enum ValueDescription
BENEFICIARY

Identity associated with the beneficiary.

ORIGINATOR

Identity associated with the party originating the payment.

Example: identityType=BENEFICIARY
nickNamestring

The nickname of the identity provided at the time of identity creation.

Example: nickName=Successful Beneficiary
curl -i -X GET \
  'https://docs.ripple.com/_mock/products/payments-direct/api-docs/pii-service/reference/pii-service-external/identities?identityType=BENEFICIARY&nickName=Successful+Beneficiary' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Requested identity info in JSON format

Bodyapplication/json
dataArray of objects

The list of the identities that match the query parameters

identityIdstring(uuid)required

The unique ID of the identity

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

The nickname of the identity provided at the time of identity creation.

Example: "MyCompany"
createdAtstring(date-time)required

The time at which the identity was created

Example: "2023-11-02T18:26:00.000Z"
identityTypestringrequired

The type of the identity

Enum ValueDescription
BENEFICIARY

Identity associated with the beneficiary.

ORIGINATOR

Identity associated with the party originating the payment.

Example: "BENEFICIARY"
useCaseTypestringrequired

The use case type for the identity

Enum ValueDescription
INDIVIDUAL

Identity associated with an individual

BUSINESS

Identity associated with an institution or business

Example: "BUSINESS"
Response
application/json
{
  "data": [
    { … }
  ]
}

Create a new identity

Request

Create a new identity.

Tutorials

Security
Bearer
Bodyapplication/jsonrequired
One of:

Create a new business or institutional beneficiary identity.

piiDataobjectrequired

PII data for a business or institutional benficiary in JSON format.

The specific properties you need to specify within the Cdtr, CdtrAgt, and CdtrAcct objects depend on the type of payment you plan to make to this beneficiary and the payout country and currency. To get the required properties for your use case, call the GET /data-requirements operation. For more information about the piiData object, see Working with the piiData object.

Note: The piiData.Cdtr.Id.OrgId.Othr.Id value must be unique for every identity you create in your account.

Cdtrobject

Party to which an amount of money is due.

Nmstring[ 1 .. 140 ] characters^[a-zA-Z0-9 \t]+$

Allows the name of the Creditor to be held as a single value.
Requirements

  • Must include one (1) name string.
  • Allowable characters: Alphanumeric and space.
  • Names with multiple words must be separated by a space.
  • For example, specify "Widgets Org", as Widgets Org.
  • Provide a truncated name if longer than 140 characters.

CtryOfResstring^[A-Z]{2}$

Allows the Country of Residence of the Creditor to be held. Use Alpha-2 Code as defined in the ISO CountryCode ISO 3166-1 list.

PstlAdrobject

Allows the address of the Creditor to be held.

AdrLineArray of arrays<= 70 characters

Information that locates and identifies the address for the party.

PstCdstring<= 16 characters

Information that locates and identifies postal code for the party, as defined by postal services.

TwnNmstring<= 35 characters

Information that locates and identifies the city / town for the party, as defined by postal services.

CtctDtlsobject

Allows the contact of the Creditor to be held.

MobNbstring<= 15 characters^\+?[1-9]\d{1,14}$

Mobile Phone Number

EmailAdrstring(email)<= 2048 characters

Address for electronic mail (e-mail).

Idobject

Unique and unambiguous way to identify the Creditor.

OrgIdobject

Unique and unambiguous way to identify a business or organization.

CdtrAgtobject

Financial institution servicing an account for the creditor.

FinInstnIdobject

Allows the details of the Creditor Agent to be held

Nmstring[ 1 .. 140 ] characters^[a-zA-Z0-9 \t]+$

Name by which the party is known and which is usually used to identify the party.

  • Must include one (1) name string.
  • Allowable characters: Alphanumeric and space.
  • Names with multiple words must be separated by a space.
  • For example, specify "Widgets Org", as Widgets Org.
  • Provide a truncated name if longer than 140 characters.

Othrobject

Unique identification of an agent, as assigned by an institution, using an identification scheme.

BrnchIdobject

Allows the details of the Creditor Agent Branch to be held

PstlAdrobject

Address for the Branch

CdtrAcctobject

Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction.

Ccystring^[A-Z]{3,3}$

Currency for the Creditor Account

Idobjectrequired

Identifier for the Creditor account.

IBANstring^([a-zA-Z0-9_-]){15,35}$

Holds the Creditor account number in International Bank Account Number (IBAN) format.

Usage Guidelines:

  • If you specify IBAN, do not specify Othr.Id.
  • This field is used in conjunction with CdtrAgt.FinInstnId.BICFI.
  • Example IBAN: GB29NWBK60161331926819.

    • Othrobject
    identityTypestringrequired

    The type of the identity

    Enum ValueDescription
    BENEFICIARY

    Identity associated with the beneficiary.

    ORIGINATOR

    Identity associated with the party originating the payment.

    Example: "BENEFICIARY"
    nickNamestring

    The nickname for the new identity.

    Note: Don't include any personally identifiable information in this field.

    Example: "MyCompany"
    useCaseTypestringrequired

    The use case type for the identity

    Enum ValueDescription
    INDIVIDUAL

    Identity associated with an individual

    BUSINESS

    Identity associated with an institution or business

    Example: "BUSINESS"
    curl -i -X POST \
  https://docs.ripple.com/_mock/products/payments-direct/api-docs/pii-service/reference/pii-service-external/identities \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "identityType": "BENEFICIARY",
    "nickName": "Successful Business Beneficiary",
    "useCaseType": "BUSINESS",
    "piiData": {
      "Cdtr": {
        "Nm": "Success Co.",
        "CtctDtls": {
          "MobNb": "+11234567890",
          "EmailAdr": "test@test.com"
        },
        "CtryOfRes": "AT",
        "Id": {
          "OrgId": {
            "Othr": {
              "Id": "1234567890",
              "SchmeNm": {
                "Cd": "CINC"
              }
            },
            "RelShipToDbtr": "CUST"
          }
        },
        "PstlAdr": {
          "AdrLine": [
            "1234 Business Beneficiary Ave"
          ],
          "PstCd": "02125",
          "TwnNm": "Boston"
        }
      },
      "CdtrAcct": {
        "Ccy": "US",
        "Id": {
          "IBAN": "1234123412341234",
          "Othr": {
            "SchmeNm": {
              "Cd": "BBAN"
            }
          }
        }
      },
      "CdtrAgt": {
        "BrnchId": {
          "PstlAdr": {
            "Ctry": "US"
          }
        },
        "FinInstnId": {
          "Nm": "Bank of Massachusetts",
          "Othr": {
            "Id": "123456"
          }
        }
      }
    }
  }'

    Responses

    successful operation

    Bodyapplication/json
    identityIdstring(uuid)required

    The unique ID of the identity

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

    The version number of the identity

    Example: 2
    Response
    application/json
    {
  "identityId": "2f4ac57f-c5ba-4051-b51f-b3565778717b",
  "version": 2
}

    Get an identity by ID

    Request

    Get an identity by its unique ID

    Security
    Bearer
    Path
    identity-idstring(uuid)required

    The ID of the identity to get.

    Example: 2f4ac57f-c5ba-4051-b51f-b3565778717b
    Query
    versioninteger>= 1

    Version of the identity you want to retrieve.

    Note: If you don't specify a version, the latest version of the identity is returned.

    Example: version=2
    curl -i -X GET \
  'https://docs.ripple.com/_mock/products/payments-direct/api-docs/pii-service/reference/pii-service-external/identities/2f4ac57f-c5ba-4051-b51f-b3565778717b?version=2' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

    Responses

    Requested identity info in JSON format

    Bodyapplication/json
    identityIdstringrequired

    The unique ID of the identity

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

    The type of the identity

    Enum ValueDescription
    BENEFICIARY

    Identity associated with the beneficiary.

    ORIGINATOR

    Identity associated with the party originating the payment.

    Example: "BENEFICIARY"
    createdAtstring(date-time)required

    The time at which the identity was created

    Example: "2023-11-02T18:26:00.000Z"
    identityStatestringrequired

    The state of the identity

    Enum ValueDescription
    ACTIVE

    The identity requested exists and is active.

    BLOCKED

    The identity requested exists, but is blocked.

    DELETED

    The identity requested has been deleted.

    Example: "ACTIVE"
    nickNamestring

    The nickname of the identity provided at the time of identity creation.

    Example: "MyCompany"
    piiDataobjectrequired

    PII data in JSON format

    property name*anyadditional property
    versionintegerrequired

    The version number of the identity

    Example: 2
    Response
    application/json
    {
  "identityId": "2f4ac57f-c5ba-4051-b51f-b3565778717b",
  "identityType": "BENEFICIARY",
  "createdAt": "2023-11-02T18:26:00.000Z",
  "identityState": "ACTIVE",
  "nickName": "MyCompany",
  "piiData": {},
  "version": 2
}

    Delete an identity

    Request

    Delete an identity

    Security
    Bearer
    Path
    identity-idstringrequired

    Unique UUID string that maps to the identity to be deleted.

    Example: 2f4ac57f-c5ba-4051-b51f-b3565778717b
    curl -i -X DELETE \
  https://docs.ripple.com/_mock/products/payments-direct/api-docs/pii-service/reference/pii-service-external/identities/2f4ac57f-c5ba-4051-b51f-b3565778717b \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

    Responses

    The identity was deleted successfully

    Response
    No content