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 business or individual originator 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 to create an identity of the type BENEFICIARY and usecase type BUSINESS.

The piiData object

To create an identity of the type BENEFICIARY and usecase type BUSINESS, 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.

{
    "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. The property of this object may either be OrgId or PrvId depending on the useCaseType parameter in the request body:
  • If you're adding a beneficiary with useCaseType set to BUSINESS , then specify the OrgId property. In this example we're adding a business beneficiary, so we'll specify OrgId .
  • If you're adding a beneficiary with useCaseType set to INDIVIDUAL , then specify the PrvtId property.
• PstlAdr : The creditor's physical address.

{
    "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.

{
    "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.

{
    "CdtrAcct": {
        "Ccy": "USD",
        "Id": {
            "IBAN": "1234123412341234",
            "Othr": {
                "SchmeNm": {
                    "Cd": "BBAN"
                }
            }
        }
    }
}

For the full object schema, see CdtrAcct.