Working with the piiData object

When you call the POST /identities operation to create an identity, you must include the piiData object in the request body. Use the piiData object to specify Personally Identifiable Information (PII) about the sender or beneficiary identity you want to add to your account.

The Ripple Payments Direct API itself doesn't validate the contents of the piiData object, however, the guidelines on this page can help you to ensure that the identities you create include the information needed to create payment requests.

The following sections walk you through an example piiData object that's part of the POST /identities operation's request body. This example uses the piiData object to provide data for an identity of the type BENEFICIARY.

The piiData object

To create an identity of the type BENEFICIARY, the piiData object must contain these three nested objects - Cdtr, CdtrAgt, CdtrAcct. Each nested object contains more granular information about the beneficiary identity you want to create.

Copy
Copied!
{
    "piiData": {
        "Cdtr": {
            "key": "value"
        },
        "CdtrAgt": {
            "key": "value"
        },
        "CdtrAcct": {
            "key": "value"
        }
    }
}

The following sections examine each of these objects in detail.

The Cdtr object

The Cdtr object contains information about the creditor (also known as the beneficiary) such as the (company) name, contact information, and address. This information is provided using objects nested within the Cdtr object:

  • CtctDtls : The creditor's contact details.
  • Id : The creditor's unique ID.
  • PstlAdr : The creditor's physical address.
Important

The Cdtr.Id.OrgId.Othr.Id value must be unique for every identity you create in your account. If more than one identity has the same Cdtr.Id.OrgId.Othr.Id value but different information in other fields, the identity you created first will be overwritten with the information that is different.

Expand to see an example Cdtr object
Copy
Copied!
{
    "Cdtr": {
        "Nm": "companyname",
        "CtctDtls": {
            "MobNb": "+1234567890",
            "EmailAdr": "test@test.com"
        },
        "CtryOfRes": "GB",
        "Id": {
            "OrgId": {
                "Othr": {
                    "Id": "1234567890",
                    "SchmeNm": {
                        "Cd": "CINC"
                    }
                },
                "RelShipToDbtr": "CUST"
            }
        },
        "PstlAdr": {
            "AdrLine": [
                "1234 Commonwealth Ave"
            ],
            "PstCd": "02125",
            "TwnNm": "Boston"
        }
    }
}

For the full object schema, see Cdtr.

The CdtrAgt object

The CdtrAgt object contains information about the financial institution servicing the account for the Cdtr. This object contains details about the financial institution's branch where the account is held and the name and unique identification of the bank account.

Expand to see an example CdtrAgt object
Copy
Copied!
{
    "CdtrAgt": {
        "BrnchId": {
            "PstlAdr": {
                "Ctry": "US"
            }
        },
        "FinInstnId": {
            "Nm": "Bank of Massachusetts",
            "Othr": {
                "Id": "123456"
            }
        }
    }
}

For the full object schema, see CdtrAgt.

The CdtrAcct object

The CdtrAcct object contains information that identifies the Cdtr's account where the payment sent to the Cdtr will be posted when the transaction is successful. This object contains details such as the currency of the account and the account number in the applicable format.

Expand to see an example CdtrAcct object
Copy
Copied!
{
    "CdtrAcct": {
        "Ccy": "USD",
        "Id": {
            "IBAN": "1234123412341234",
            "Othr": {
                "SchmeNm": {
                    "Cd": "BBAN"
                }
            }
        }
    }
}

For the full object schema, see CdtrAcct.