Create an identity

You need to create an identity for the beneficiary or originating party so they can be identified in the payment request.

Identities in Ripple Payments are objects that correspond to payment participants, such as payment originators and beneficiaries of payments. They contain all of the personally identifiable information (PII) connected to a specific individual or business to ensure proper compliance and proper routing.

Note
While this tutorial focuses on creating a BENEFICIARY, the process is similar for an ORIGINATOR.

This guide walks you through the API calls required to create an identity.

  1. Get data requirements used to create an identity based on your workflow.
  2. Examine the response and transform them into a compatible JSON format.
  3. Create a new identity to serve as an originator or beneficiary.

Prerequisite

You should have the following items before you continue:

  • An access token to access secured API endpoints.
  • The value for partner-name provided by your Ripple Liaison.
Note
The partner-name defines which payout partner is used to complete your transaction.

Get data requirements

Use the get data requirements operation to retrieve the data requirements based on your use case.

Your requirements will be different

You should get the latest data requirements each time a new identity is created as they differ depending on the destination country and currencies.

Example requirements request

In this example, we'll go through the process of creating a BENEFICIARY in Austria configured for a BANK payout in EUR.

To achieve this we'll assign the following example values:

Field nameExample valueDescription
payout-countryATThe destination country for the payment, in this case, Austria.
use-caseB2BThe type of use-case, in this case, B2B (a business originator paying a business beneficiary).
payout-currencyEURThe payout currency, in this case, euro.
payout-categoryBANKThe payout category, Ripple Payments uses the bank payout.
partner-nameSamplePartnerSpecifies the payout partner, this tutorial uses SamplePartner.
field-categoryBENEFICIARYSpecifies the type of identity, in this case, a beneficiary.
flowRPDSpecifies the type of payment flow, currently RPD.

Example requirements response

The get data-requirements response contains a list of field names and values. You use these fields to create a JSON payload compatible with the piiData object.

Example response : This example is truncated for brevity.

{
  • "supportedUseCase": "B2B",
  • "payoutCountry": "AT",
  • "payoutCurrency": "EUR",
  • "dataRequirements": [
    • {
      • "fieldCategory": "BENEFICIARY",
      • "fieldName": "Cdtr.Nm",
      • "fieldType": "REQUIRED",
      • "fieldDataType": "STRING",
      • "fieldMinLength": 0,
      • "fieldMaxLength": 100,
      • "fieldDescription": "Beneficiary Business Legal Name",
      • "fieldHelpText": "The legal name of the beneficiary business"
      },
    • {
      • "fieldCategory": "BENEFICIARY",
      • "fieldName": "CdtrAcct.Ccy",
      • "fieldType": "REQUIRED",
      • "fieldDataType": "STRING",
      • "fieldMinLength": 0,
      • "fieldMaxLength": 6,
      • "fieldDescription": "Business Account Currency",
      • "fieldHelpText": "The beneficiary business' account's currency associated with the Account Identification Scheme"
      },
    • {
      • "fieldCategory": "BENEFICIARY",
      • "fieldName": "CdtrAgt.FinInstnId.Nm",
      • "fieldType": "REQUIRED",
      • "fieldDataType": "STRING",
      • "fieldMinLength": 0,
      • "fieldMaxLength": 50,
      • "fieldDescription": "Beneficiary's Bank name.",
      • "fieldHelpText": "Name by which the party is known and which is usually used to identify the party."
      }
    ]
}

Example transformed object

You need to transform the response by following the guidelines within the response, into a piiData-compatible JSON object.
{
  • "identityType": "BENEFICIARY",
  • "nickName": "Successful Business Beneficiary",
  • "useCaseType": "BUSINESS",
  • "piiData": {
    • "Cdtr": {
      },
    • "CdtrAcct": {
      },
    • "CdtrAgt": {
      }
    }
}

Create a new identity

Now it's time to take piiData JSON object schema we transformed from the response to our get data requirements request to create an identity token that we'll use for accepting a payment quote.


This example uses the create a new identity operation to create a new identity of the type BENEFICIARY.
  • identityType : This example uses BENEFICIARY to create a beneficiary identity.
  • nickName : This example uses a recognizable name such as Successful Business Beneficiary.
  • piiData : Populate this object with the required PII information for the chosen identityType.
application/json
{
  • "identityType": "BENEFICIARY",
  • "nickName": "Successful Business Beneficiary",
  • "useCaseType": "BUSINESS",
  • "piiData": {
    • "Cdtr": {
      },
    • "CdtrAcct": {
      },
    • "CdtrAgt": {
      }
    }
}

Identity response

Store the identityId value for use later with the accept quote operation. The accept quote operation's request body requires a user_info object containing this value as the beneficiary_token property.
{
  • "identityId": "22222222-aaaa-2222-bbbb-222222222222",
  • "version": 2
}
Tip
You can use the identityId with the get an identity by ID operation to view the newly created identity.