Embedded Payments

Create a client profile

You can create a minimal client profile, using only the most basic information required first, and update over time. Once all of the information required is ready, you can send the final request for client background checks to begin.

Create a client profile with minimum data

To create a client, you must send a POST /do/v1/clients request with:

A parties list of objects.
A product with the value EMBEDDED_PAYMENTS.

The clients object represents the overall business and its related parties.

The parties object contains both information about the client as an organization, and an individual party who can act as the controller for the client business.

In your parties objects, include:

partyType: ORGANIZATION for the client organization.
partyType: INDIVIDUAL to represent controllers, beneficial owners and decision makers related to the organization or business
externalId: Your own unique identifier for this client organization, individual and subsequent individual party. This field is optional.
roles: Represents the role of the party as it relates to the client object. Values vary based on:
- partyType: ORGANIZATION – set to CLIENT for the party representing the client organization or business.
- partyType: INDIVIDUAL – For individuals that act as the client’s controller, assign the role CONTROLLER. For individuals that own more than a 25% ownership of the company, you must also assign the role BENEFICIAL_OWNER.
organizationDetails for the organization must include:
- organizationType
- organizationName
- countryOfFormation
- If the organization is a Publicly Traded Company (PTC) you may need to include additional information. Take a look at this PTC reference for more information.

individualDetails for the individual party must include:
- firstName
- lastName
- countryOfResidence

Sample of create a client request body with minimum data:

createClient

Json

{
  "parties": [
    {
      "partyType": "ORGANIZATION",
      "email": "monica@cpgetaways.com",
      "roles": [
        "CLIENT"
      ],
      "organizationDetails": {
        "organizationType": "SOLE_PROPRIETORSHIP",
        "organizationName": "Central Park Getaways",
        "countryOfFormation": "US"
      }
    },
    {
      "partyType": "INDIVIDUAL",
      "roles": [
        "CONTROLLER",
        "BENEFICIAL_OWNER"
      ],
      "individualDetails": {
        "firstName": "Monica",
        "lastName": "Gellar",
        "countryOfResidence": "US"
      }
    }
  ],
  "products": [
    "EMBEDDED_PAYMENTS"
  ]
}

Create a client profile with full data

Send a full payload with all the required information about your client and their organization.

Note on addresses

Include your principal place of business in at least one entry in organizationDetails.addresses. Organizations must use addresses.addressType of LEGAL_ADDRESS or BUSINESS_ADDRESS. Overall we allow the following values for addresses.addressType:

LEGAL_ADDRESS: The official registered address of the legal entity on file with government authorities or the entity's registered agent. P.O. Boxes and Private Mail Boxes (P.M.B.) are not accepted for onboarding.
MAILING_ADDRESS: The address where the organization receives postal correspondence, statements, and notices. This address may differ from the legal address or primary business location.
BUSINESS_ADDRESS: The primary physical location where the organization conducts business operations. This is the principal place of business or designated primary site. P.O. Boxes and Private Mail Boxes (P.M.B.) are not accepted.
RESIDENTIAL_ADDRESS: The physical home address used when the party is an individual or sole proprietor, or when required for key principals or beneficial owners associated with the organization. P.O. Boxes and Private Mail Boxes (P.M.B.) are not accepted.

Note

For addresses.addressType other than MAILING_ADDRESS, we do not permit the following address types:

Post Office (P.O.) boxes
Private Mail Boxes (P.M.B.)
Virtual office addresses
Registered agent addresses

Set addresses.addressType to BUSINESS_ADDRESS for your principal place of business.

Note on metadata for parties

The parties object includes a single metadata field per party, as a flexible array of key-value entries that you use to attach custom data to any party record. Metadata key-value pairs are passthrough data. The system stores them alongside the party record, returns them in responses, and does not use them for processing, evaluation, or onboarding decisions.

The metadata field is the following array of key-value pairs, where key is a string and value is any JSON type: string, number, boolean, or nested object.

Json

{
  "key1": "...",
  "value1": "...",
  "key2": "...",
  "value2": "..."
}

Tip

The metadata field supports a maximum of 20 key-value entries.

Send metadata through the Create party, Update party, Create client and Update client endpoints by including metadata in the parties object. When you include metadata in a request body, the entire metadata for the party is replaced by the metadata in the request. To modify existing metadata, send the complete metadata, including the existing entries with any edits.

If metadata is present, the Get party and Get client responses return the metadata in the parties object.

In the following example, you can see a complete request with all required fields populated for a sole proprietorship organization. This includes details about the organization's industry type and industry category. For the USA, you can find this reference information in the United States Census Bureau.

Refer to the following sample request to create a client profile with complete data:

Sample createClient request body with complete data:

Json

{
  "parties": [
    {
      "partyType": "ORGANIZATION",
      "externalId": "TC1234",
      "email": "monica@cpgetaways.com",
      "roles": [
        "CLIENT"
      ],
      "organizationDetails": {
        "organizationType": "SOLE_PROPRIETORSHIP",
        "organizationName": "Central Park Getaways",
        "dbaName": "CP Getaways",
        "organizationDescription": "Relax, unwind and experience the comforting charm of our apartment while exploring New York",
        "industryCategory": "Accommodation and Food Services",
        "industryType": "All Other Traveler Accommodation",
        "countryOfFormation": "US",
        "yearOfFormation": "2020",
        "significantOwnership": true,
        "entitiesInOwnership": false,
        "addresses": [
          {
            "addressType": "BUSINESS_ADDRESS",
            "addressLines": [
              "90 Bedford Street"
            ],
            "city": "New York",
            "state": "NY",
            "postalCode": "10014",
            "country": "US"
          }
        ],
        "phone": {
          "phoneType": "BUSINESS_PHONE",
          "countryCode": "+1",
          "phoneNumber": "6316215110"
        },
        "organizationIds": [
          {
            "idType": "EIN",
            "issuer": "US",
            "value": "000000001"
          }
        ],
        "websiteAvailable": true,
        "website": "https://topcookie.net"
      }
    },
    {
      "partyType": "INDIVIDUAL",
      "externalId": "TCU12344",
      "email": "monicagellar@gmail.com",
      "roles": [
        "CONTROLLER",
        "BENEFICIAL_OWNER"
      ],
      "individualDetails": {
        "firstName": "Monica",
        "lastName": "Gellar",
        "birthDate": "1990-10-09",
        "countryOfResidence": "US",
        "natureOfOwnership": "Direct",
        "jobTitle": "Other",
        "jobTitleDescription": "CEO",
        "soleOwner": true,
        "addresses": [
          {
            "addressType": "RESIDENTIAL_ADDRESS",
            "addressLines": [
              "90 Bedford Street",
              "Apt 2E"
            ],
            "city": "New York",
            "state": "NY",
            "postalCode": "10014",
            "country": "US"
          }
        ],
        "individualIds": [
          {
            "idType": "SSN",
            "issuer": "US",
            "value": "100010001"
          }
        ]
      }
    }
  ],
  "products": [
    "EMBEDDED_PAYMENTS"
  ]
}

When you have multiple individual parties related to a client, you can add them to your POST /clients request like this:

Create a client with multiple parties

Json

{
    "parties": [
        {
            "partyType": "ORGANIZATION",
            "externalId":"UDV23455"
            "roles": ["CLIENT"],
            "email": "phil@banksfamilyllc.com",
            "organizationDetails": {
                "organizationType": "LIMITED_LIABILITY_COMPANY",
                "organizationName": "Banks Family LLC",
                "addresses": [
                    {
                        "addressType": "BUSINESS_ADDRESS",
                        "addressLines": [
                            "251 N Bristol Ave"
                        ],
                        "city": "Los Angeles",
                        "state": "CA",
                        "postalCode": "90049",
                        "country": "US"
                    }
                ],
                "countryOfFormation": "US",
                "dbaName": "Banks Family Decor",
                "industryCategory": "Retail Trade",
                "industryType": "All Other Home Furnishings Retailers",
                "organizationDescription": "Step in to a world of sophistication with stylish home goods",
                "phone": {
                    "phoneType": "BUSINESS_PHONE",
                    "phoneNumber": "7606810558",
                    "countryCode": "+1"
                },
                "website": "https://banksfamilyllc.com",
                "yearOfFormation": "1984",
                "organizationIds": [
                    {
                        "idType": "EIN",
                        "value": "300030003",
                        "issuer": "US"
                    }
                ]
            }
        },
        {
            "partyType": "INDIVIDUAL",
            "roles": ["CONTROLLER"],
            "individualDetails": {
                "firstName": "Philip",
                "lastName": "Banks",
                "birthDate": "1945-01-30",
                "addresses": [
                    {
                        "addressType": "RESIDENTIAL_ADDRESS",
                        "addressLines": [
                            "251 N Bristol Ave"
                        ],
                        "city": "Los Angeles",
                        "state": "CA",
                        "postalCode": "90049",
                        "country": "US"
                    }
                ],
                "countryOfResidence": "US",
                "phone": {
                    "phoneType": "BUSINESS_PHONE",
                    "phoneNumber": "7606810553",
                    "countryCode": "+1"
                },
                "individualIds": [
                    {
                        "idType": "SSN",
                        "value": "300040004",
                        "issuer": "US"
                    }
                ],
                "jobTitle": "CEO"
            }
        },
        {
            "partyType": "INDIVIDUAL",
            "roles": ["BENEFICIAL_OWNER"],
            "individualDetails": {
                "firstName": "Dahlia",
                "lastName": "Banks",
                "birthDate": "1945-01-30",
                "addresses": [
                    {
                        "addressType": "RESIDENTIAL_ADDRESS",
                        "addressLines": [
                            "251 N Bristol Ave"
                        ],
                        "city": "Los Angeles",
                        "state": "CA",
                        "postalCode": "90049",
                        "country": "US"
                    }
                ],
                "countryOfResidence": "US",
                "phone": {
                    "phoneType": "BUSINESS_PHONE",
                    "phoneNumber": "7606810553",
                    "countryCode": "+1"
                },
                "individualIds": [
                    {
                        "idType": "SSN",
                        "value": "300050005",
                        "issuer": "US"
                    }
                ],
                "jobTitle": "CFO"
            }
        }
    ],
    "products": [
        "EMBEDDED_PAYMENTS"
    ]
}

Understand outstanding data

A successful 200 or 201 response to any POST /clients or GET /clients/{id} request includes an outstanding object. This object tells you what still needs to be added or completed before you can submit your client's profile and complete the onboarding process. The object may include:

questionId : An answers must be provided for each questionId listed. You can find out how to manage questions in this guide.
partyIds : A required attribute related to the partyId is missing.
partyRoles : A required party role has not been submitted with the client. For example, the role CONTROLLER has not been assigned to any party.
attestationDocumentIds : The document IDs in which the client must review and attest to. You can find out how to manage attestations in this guide.
documentRequestIds : The IDs for the documents that the client must submit for verification.

To update client and party details such as partyId and partyRoles, send a `POST clients/{id}` request with the updated details.

Update party data

In the response to a GET /do/v1/clients/{id}. The missing fields are described in the party’s validationResponse field.

Sample of missing fields in validationResponse object:

Json

{
    "id": "1000010400",
    "outstanding": {
        "attestationDocumentIds": [],
        "documentRequestIds": [],
        "questionIds": [],
        "partyRoles": [],
        "partyIds": [
            "2000000112"
        ]
    },
    "parties": [
        {
            "id": "2000000112",
            "createdAt": "2024-08-06T01:22:22.607Z",
            "partyType": "INDIVIDUAL",
            "parentPartyId": "2000000111",
            "profileStatus": "NEW",
            "roles": [
                "CONTROLLER"
            ],
            "active": true,
            "status": "ACTIVE",
            "individualDetails": {
                "countryOfResidence": "US",
                "firstName": "Philip",
                "lastName": "Banks"
            },
            "validationResponse": [
                {
                    "validationStatus": "NEEDS_INFO",
                    "validationType": "ENTITY_VALIDATION",
                    "fields": [
                        {
                            "name": "individualIds"
                        },
                        {
                            "name": "addresses"
                        },
                        {
                            "name": "birthDate"
                        }
                    ]
                }
            ]
        },
        ... other party objects
    ],
    "questionResponses": [],
    "createdAt": "2024-08-06T01:22:23.035Z",
    "partyId": "2000000111",
    "products": [
        "EMBEDDED_PAYMENTS"
    ],
    "status": "NEW",
    "results": {
        "customerIdentityStatus": "NOT_STARTED"
    }
}

Once you have collected the additional fields, send the fields using POST /do/v1/parties/{id} by specifying the party ID in the request URL path, along with the additional fields:

Example of updated party:

Json

{
    "individualDetails": {
        "birthDate": "1945-01-30",
        "addresses": [
            {
                "addressType": "RESIDENTIAL_ADDRESS",
                "addressLines": [
                    "251 N Bristol Ave"
                ],
                "city": "Los Angeles",
                "state": "CA",
                "postalCode": "90049",
                "country": "US"
            }
        ],
        "individualIds": [
            {
                "idType": "SSN",
                "value": "300050005",
                "issuer": "US"
            }
        ]
    }
}

Next steps

Once you have successfully created a client profile, you can present onboarding questions to your client.

Create a client profile

Create a client profile with minimum data

Create a client profile with full data

Note on addresses

Note on metadata for parties

Create a client with multiple related parties

Understand outstanding data

Update party data

Next steps