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 beneficiary or originator 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.

Types of identities

Ripple Payments Direct supports the Originator and Beneficiary identity types. Depending on the type of identity you want to create, the contents of the piiData object you specify in the POST /identities operation are different.

The following sections show the piiData object schema for each identity type.

piiData object schema for a Beneficiary-type identity

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

{
    "piiData": {
        "Cdtr": {
            "key": "value"
        },
        "CdtrAgt": {
            "key": "value"
        },
        "CdtrAcct": {
            "key": "value"
        }
    }
}

Cdtr, CdtrAgt, and CdtrAcct schema

The list of properties you need to include in the Cdtr, CdtrAgt, and CdtrAcct objects depends on the payout currency and payout country. For more information about specific data requirements, see the GET /data-requirements operation and the Create an identity tutorial.

For object schemas, see PII data object reference.

piiData object schema for an Originator-type identity

If you want to make payments on behalf of your customer, you must create an ORIGINATOR identity with their information. To create an identity of this type, the piiData object must contain these two nested objects - Dbtr and DbtrAcct. Each of these nested object contains more granular information about the originator identity you want to create.

{
    "piiData": {
        "Dbtr": {
            "key": "value"
        },
        "DbtrAcct": {
            "key": "value"
        }
    }
}

Dbtr and DbtrAcct schema

The list of properties you need to include in the Dbtr and DbtrAcct objects depends on the payout currency and the payout country. For more information about specific data requirements, see the GET /data-requirements operation and the Create an identity tutorial.

For object schemas, see PII data object reference.