Skip to main content
Embedded Payments

Onboard to sub-products and multiple products

This guide explains how to onboard clients to sub-products and multiple products, retrieve onboarding status, and manage onboarding changes before and after submission.

Onboard to one sub-product

Use this workflow when onboarding a client to a single sub-product within a product.

How it works

  1. Create the client using POST /clients.
  2. Specify the product in productDetails.Product and sub-product in productDetails.subProduct.
  3. Additionally, include the product in products for backward compatibility.
  4. Clear all outstanding requirements returned in the outstanding object.
  5. Submit the onboarding request using POST /verifications.
  6. Retrieve onboarding status from productDetails.onboardingStatus.
    Note: Do not use status for tracking onboarding progress. It is maintained for backward compatibility.

Sample request:

Json
{
  "parties": [
    {
      "partyType": "ORGANIZATION",
      "roles": [
        "CLIENT"
      ],
      "email": "monica@cpgetaways.com",
      "organizationDetails": {
        "organizationType": "LIMITED_LIABILITY_COMPANY",
        "organizationName": "Central Park Getaways",
        "countryOfFormation": "US",
        "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",
        "addresses": [
          {
            "addressType": "BUSINESS_ADDRESS",
            "addressLines": [
              "90 Bedford Street",
              "Apt 2E"
            ],
            "city": "New York",
            "state": "NY",
            "postalCode": "10014",
            "country": "US"
          }
        ],
        "phone": {
          "phoneType": "BUSINESS_PHONE",
          "phoneNumber": "6316215110",
          "countryCode": "+1"
        },
        "organizationIds": [
          {
            "idType": "EIN",
            "value": "421870602",
            "issuer": "US"
          }
        ],
        "yearOfFormation": "2023"
      }
    },
    {
      "partyType": "INDIVIDUAL",
      "externalId": "TCU12344",
      "roles": [
        "CONTROLLER",
        "BENEFICIAL_OWNER"
      ],
      "email": "foobar@example.com",
      "individualDetails": {
        "firstName": "Monica",
        "lastName": "Gellar",
        "countryOfResidence": "US",
        "natureOfOwnership": "Direct",
        "jobTitle": "Other",
        "jobTitleDescription": "Senior Manager",
        "birthDate": "1987-01-01",
        "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": "621256154"
          }
        ]
      }
    }
  ],
  "products": [
    "EMBEDDED_PAYMENTS"
  ],
  "productDetails": [
    {
      "product": "EMBEDDED_PAYMENTS",
      "subProduct": "LIMITED_DDA"
    }
  ]
}

Sample response:

Json
{
  "attestations": [],
  "createdAt": "2026-08-04T14:45:05.782Z",
  "id": "3100011587",
  "parties": [
    {
      "access": [],
      "id": "2100551430",
      "createdAt": "2026-08-04T14:45:05.241Z",
      "email": "monica@cpgetaways.com",
      "partyType": "ORGANIZATION",
      "preferences": {
        "defaultLanguage": "en-US"
      },
      "profileStatus": "NEW",
      "roles": [
        "CLIENT"
      ],
      "status": "ACTIVE",
      "active": true,
      "validationResponse": [],
      "organizationDetails": {
        "addresses": [
          {
            "addressType": "BUSINESS_ADDRESS",
            "addressLines": [
              "90 Bedford Street",
              "Apt 2E"
            ],
            "city": "New York",
            "state": "NY",
            "postalCode": "10014",
            "country": "US"
          }
        ],
        "associatedCountries": [],
        "countryOfFormation": "US",
        "dbaName": "CP Getaways",
        "industryCategory": "Accommodation and Food Services",
        "industryType": "All Other Traveler Accommodation",
        "industry": {
          "codeType": "NAICS",
          "code": "721199"
        },
        "secondaryMccList": [],
        "socialMedia": [],
        "organizationName": "Central Park Getaways",
        "organizationDescription": "Relax, unwind and experience the comforting charm of our apartment while exploring New York",
        "organizationType": "LIMITED_LIABILITY_COMPANY",
        "organizationIds": [
          {
            "idType": "EIN",
            "value": "421870602",
            "issuer": "US"
          }
        ],
        "phone": {
          "phoneType": "BUSINESS_PHONE",
          "countryCode": "+1",
          "phoneNumber": "6316215110"
        },
        "websiteAvailable": false,
        "yearOfFormation": "2023"
      },
      "metadata": []
    },
    {
      "access": [],
      "id": "2100551431",
      "createdAt": "2026-08-04T14:45:05.391Z",
      "email": "foobar@example.com",
      "externalId": "TCU12344",
      "partyType": "INDIVIDUAL",
      "parentPartyId": "2100551430",
      "preferences": {
        "defaultLanguage": "en-US"
      },
      "profileStatus": "NEW",
      "roles": [
        "CONTROLLER",
        "BENEFICIAL_OWNER"
      ],
      "status": "ACTIVE",
      "active": true,
      "validationResponse": [],
      "individualDetails": {
        "addresses": [
          {
            "addressType": "RESIDENTIAL_ADDRESS",
            "addressLines": [
              "90 Bedford Street",
              "Apt 2E"
            ],
            "city": "New York",
            "state": "NY",
            "postalCode": "10014",
            "country": "US"
          }
        ],
        "birthDate": "1987-01-01",
        "countryOfResidence": "US",
        "firstName": "Monica",
        "lastName": "Gellar",
        "individualIds": [
          {
            "idType": "SSN",
            "issuer": "US",
            "value": "621256154"
          }
        ],
        "jobTitle": "Other",
        "jobTitleDescription": "Senior Manager",
        "natureOfOwnership": "Direct",
        "socialMedia": []
      },
      "metadata": []
    }
  ],
  "partyId": "2100551430",
  "products": [
    "EMBEDDED_PAYMENTS"
  ],
  "outstanding": {
    "attestationDocumentIds": [
      "a3db2849-5e58-4d8a-89d6-ef77ad809c49"
    ],
    "documentRequestIds": [],
    "questionIds": [
      "30195",
      "30198",
      "30109",
      "30194"
    ],
    "partyIds": [],
    "partyRoles": []
  },
  "questionResponses": [],
  "results": {
    "customerIdentityStatus": "NOT_STARTED"
  },
  "status": "NEW",
  "productDetails": [
    {
      "product": "EMBEDDED_PAYMENTS",
      "subProduct": "LIMITED_DDA",
      "onboardingStatus": "NEW"
    }
  ]
}

Onboard to multiple sub-products

Use this workflow when onboarding a client to more than one sub-product.

How it works

  1. Create the client using POST /clients.
  2. Specify the product in productDetails.Product and required sub-products in productDetails.subProduct.
  3. Additionally, include the product in products for backward compatibility.
  4. Clear all outstanding requirements returned in the outstanding object.
  5. Submit the onboarding request using POST /verifications.
  6. Retrieve the onboarding status for each sub-product from productDetails.onboardingStatus.
    Note: Do not use status for tracking onboarding progress. It is maintained for backward compatibility.

Sample request:

Json
{
  "parties": [
    {
      "partyType": "ORGANIZATION",
      "roles": [
        "CLIENT"
      ],
      "email": "monica@cpgetaways.com",
      "organizationDetails": {
        "organizationType": "LIMITED_LIABILITY_COMPANY",
        "organizationName": "Central Park Getaways",
        "countryOfFormation": "US",
        "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",
        "addresses": [
          {
            "addressType": "BUSINESS_ADDRESS",
            "addressLines": [
              "90 Bedford Street",
              "Apt 2E"
            ],
            "city": "New York",
            "state": "NY",
            "postalCode": "10014",
            "country": "US"
          }
        ],
        "phone": {
          "phoneType": "BUSINESS_PHONE",
          "phoneNumber": "6316215110",
          "countryCode": "+1"
        },
        "organizationIds": [
          {
            "idType": "EIN",
            "value": "421870602",
            "issuer": "US"
          }
        ],
        "yearOfFormation": "2023"
      }
    },
    {
      "partyType": "INDIVIDUAL",
      "externalId": "TCU12344",
      "roles": [
        "CONTROLLER",
        "BENEFICIAL_OWNER"
      ],
      "email": "foobar@example.com",
      "individualDetails": {
        "firstName": "Monica",
        "lastName": "Gellar",
        "countryOfResidence": "US",
        "natureOfOwnership": "Direct",
        "jobTitle": "Other",
        "jobTitleDescription": "Senior Manager",
        "birthDate": "1987-01-01",
        "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": "621256154"
          }
        ]
      }
    }
  ],
  "products": [
    "EMBEDDED_PAYMENTS"
  ],
  "productDetails": [
    {
      "product": "EMBEDDED_PAYMENTS",
      "subProduct": "LIMITED_DDA"
    },
    {
      "product": "EMBEDDED_PAYMENTS",
      "subProduct": "LIMITED_DDA_PAYMENTS"
    }
  ]
}

Sample response:

Json
{
  "attestations": [
    {
      "attesterFullName": "Monica Gellar",
      "attestationTime": "2023-08-28T12:00:00Z",
      "documentId": "a3db2849-5e58-4d8a-89d6-ef77ad809c49",
      "ipAddress": "1.1.1.1"
    }
  ],
  "createdAt": "2026-08-04T14:46:11.642Z",
  "id": "3100011588",
  "parties": [
    {
      "access": [],
      "id": "2100551432",
      "createdAt": "2026-08-04T14:46:11.174Z",
      "email": "monica@cpgetaways.com",
      "partyType": "ORGANIZATION",
      "preferences": {
        "defaultLanguage": "en-US"
      },
      "profileStatus": "REVIEW_IN_PROGRESS",
      "roles": [
        "CLIENT"
      ],
      "status": "ACTIVE",
      "active": true,
      "validationResponse": [],
      "organizationDetails": {
        "addresses": [
          {
            "addressType": "BUSINESS_ADDRESS",
            "addressLines": [
              "90 Bedford Street",
              "Apt 2E"
            ],
            "city": "New York",
            "state": "NY",
            "postalCode": "10014",
            "country": "US"
          }
        ],
        "associatedCountries": [],
        "countryOfFormation": "US",
        "dbaName": "CP Getaways",
        "industryCategory": "Accommodation and Food Services",
        "industryType": "All Other Traveler Accommodation",
        "industry": {
          "codeType": "NAICS",
          "code": "721199"
        },
        "secondaryMccList": [],
        "socialMedia": [],
        "organizationName": "Central Park Getaways",
        "organizationDescription": "Relax, unwind and experience the comforting charm of our apartment while exploring New York",
        "organizationType": "LIMITED_LIABILITY_COMPANY",
        "organizationIds": [
          {
            "idType": "EIN",
            "value": "421870602",
            "issuer": "US"
          }
        ],
        "phone": {
          "phoneType": "BUSINESS_PHONE",
          "countryCode": "+1",
          "phoneNumber": "6316215110"
        },
        "websiteAvailable": false,
        "yearOfFormation": "2023"
      },
      "metadata": []
    },
    {
      "access": [],
      "id": "2100551433",
      "createdAt": "2026-08-04T14:46:11.306Z",
      "email": "foobar@example.com",
      "externalId": "TCU12344",
      "partyType": "INDIVIDUAL",
      "parentPartyId": "2100551432",
      "preferences": {
        "defaultLanguage": "en-US"
      },
      "profileStatus": "REVIEW_IN_PROGRESS",
      "roles": [
        "CONTROLLER",
        "BENEFICIAL_OWNER"
      ],
      "status": "ACTIVE",
      "active": true,
      "validationResponse": [],
      "individualDetails": {
        "addresses": [
          {
            "addressType": "RESIDENTIAL_ADDRESS",
            "addressLines": [
              "90 Bedford Street",
              "Apt 2E"
            ],
            "city": "New York",
            "state": "NY",
            "postalCode": "10014",
            "country": "US"
          }
        ],
        "birthDate": "1987-01-01",
        "countryOfResidence": "US",
        "firstName": "Monica",
        "lastName": "Gellar",
        "individualIds": [
          {
            "idType": "SSN",
            "issuer": "US",
            "value": "621256154"
          }
        ],
        "jobTitle": "Other",
        "jobTitleDescription": "Senior Manager",
        "natureOfOwnership": "Direct",
        "socialMedia": []
      },
      "metadata": []
    }
  ],
  "partyId": "2100551432",
  "products": [
    "EMBEDDED_PAYMENTS"
  ],
  "outstanding": {
    "attestationDocumentIds": [],
    "documentRequestIds": [],
    "questionIds": [],
    "partyIds": [],
    "partyRoles": []
  },
  "questionResponses": [
    {
      "questionId": "30194",
      "values": [
        "100"
      ]
    },
    {
      "questionId": "30195",
      "values": [
        "false"
      ]
    },
    {
      "questionId": "30020",
      "values": [
        "false"
      ]
    },
    {
      "questionId": "30005",
      "values": [
        "1000"
      ]
    },
    {
      "questionId": "30198",
      "values": [
        "false"
      ]
    },
    {
      "questionId": "30023",
      "values": [
        "false"
      ]
    },
    {
      "questionId": "30024",
      "values": [
        "false"
      ]
    },
    {
      "questionId": "30109",
      "values": [
        "false"
      ]
    }
  ],
  "results": {
    "customerIdentityStatus": "REVIEW_IN_PROGRESS"
  },
  "status": "REVIEW_IN_PROGRESS",
  "productDetails": [
    {
      "product": "EMBEDDED_PAYMENTS",
      "subProduct": "LIMITED_DDA",
      "onboardingStatus": "REVIEW_IN_PROGRESS"
    },
    {
      "product": "EMBEDDED_PAYMENTS",
      "subProduct": "LIMITED_DDA_PAYMENTS",
      "onboardingStatus": "REVIEW_IN_PROGRESS"
    }
  ]
}

Onboard an existing client to a new sub-product

Use this workflow to add a new sub-product to an existing client.

Before starting, determine whether the client's beneficial owner or controller information has changed.

No changes to ownership or controller information

How it works

  1. Add the sub-product using PATCH /clients. Specify the product in productDetails.Product, sub-product in productDetails.subProduct, and "ADD" in productDetails.action.
  2. Additionally, include the product in products for backward compatibility.
  3. Clear all outstanding requirements returned in the outstanding object.
  4. Submit the onboarding request using POST /verifications.
  5. Retrieve onboarding status for both existing and newly requested products from productDetails.onboardingStatus.
    Note: Do not use status for tracking onboarding progress. It is maintained for backward compatibility.

Sample request:

Json
{
  "productDetails": [
    {
      "product": "EMBEDDED_PAYMENTS",
      "action": "ADD",
      "subProduct": "LIMITED_DDA_PAYMENTS"
    }
  ]
}

Sample response:

Json
{
  "attestations": [
    {
      "attesterFullName": "Monica Gellar",
      "attestationTime": "2023-08-28T12:00:00Z",
      "documentId": "a3db2849-5e58-4d8a-89d6-ef77ad809c49",
      "ipAddress": "1.1.1.1"
    }
  ],
  "createdAt": "2026-08-04T14:48:47.153Z",
  "id": "3100011590",
  "parties": [
    {
      "access": [],
      "id": "2100551436",
      "createdAt": "2026-08-04T14:48:46.713Z",
      "email": "monica@cpgetaways.com",
      "partyType": "ORGANIZATION",
      "preferences": {
        "defaultLanguage": "en-US"
      },
      "profileStatus": "APPROVED",
      "roles": [
        "CLIENT"
      ],
      "status": "ACTIVE",
      "active": true,
      "validationResponse": [
        {
          "validationStatus": "APPROVED",
          "validationType": "ENTITY_VALIDATION",
          "fields": [],
          "identities": [],
          "documentRequestIds": [],
          "roleSubType": []
        }
      ],
      "organizationDetails": {
        "addresses": [
          {
            "addressType": "BUSINESS_ADDRESS",
            "addressLines": [
              "90 Bedford Street",
              "Apt 2E"
            ],
            "city": "New York",
            "state": "NY",
            "postalCode": "10014",
            "country": "US"
          }
        ],
        "associatedCountries": [],
        "countryOfFormation": "US",
        "dbaName": "CP Getaways",
        "industryCategory": "Accommodation and Food Services",
        "industryType": "All Other Traveler Accommodation",
        "industry": {
          "codeType": "NAICS",
          "code": "721199"
        },
        "secondaryMccList": [],
        "socialMedia": [],
        "organizationName": "Central Park Getaways",
        "organizationDescription": "Relax, unwind and experience the comforting charm of our apartment while exploring New York",
        "organizationType": "LIMITED_LIABILITY_COMPANY",
        "organizationIds": [
          {
            "idType": "EIN",
            "value": "421870602",
            "issuer": "US"
          }
        ],
        "phone": {
          "phoneType": "BUSINESS_PHONE",
          "countryCode": "+1",
          "phoneNumber": "6316215110"
        },
        "websiteAvailable": false,
        "yearOfFormation": "2023"
      },
      "metadata": []
    },
    {
      "access": [],
      "id": "2100551437",
      "createdAt": "2026-08-04T14:48:46.843Z",
      "email": "foobar@example.com",
      "externalId": "TCU12344",
      "partyType": "INDIVIDUAL",
      "parentPartyId": "2100551436",
      "preferences": {
        "defaultLanguage": "en-US"
      },
      "profileStatus": "APPROVED",
      "roles": [
        "CONTROLLER",
        "BENEFICIAL_OWNER"
      ],
      "status": "ACTIVE",
      "active": true,
      "validationResponse": [
        {
          "validationStatus": "APPROVED",
          "validationType": "ENTITY_VALIDATION",
          "fields": [],
          "identities": [],
          "documentRequestIds": [
            "17858553286702100551437"
          ],
          "roleSubType": []
        }
      ],
      "individualDetails": {
        "addresses": [
          {
            "addressType": "RESIDENTIAL_ADDRESS",
            "addressLines": [
              "90 Bedford Street",
              "Apt 2E"
            ],
            "city": "New York",
            "state": "NY",
            "postalCode": "10014",
            "country": "US"
          }
        ],
        "birthDate": "1987-01-01",
        "countryOfResidence": "US",
        "firstName": "Monica",
        "lastName": "Gellar",
        "individualIds": [
          {
            "idType": "SSN",
            "issuer": "US",
            "value": "621256154"
          }
        ],
        "jobTitle": "Other",
        "jobTitleDescription": "Senior Manager",
        "natureOfOwnership": "Direct",
        "socialMedia": []
      },
      "metadata": []
    }
  ],
  "partyId": "2100551436",
  "products": [
    "EMBEDDED_PAYMENTS"
  ],
  "outstanding": {
    "attestationDocumentIds": [],
    "documentRequestIds": [],
    "questionIds": [
      "30024",
      "30023",
      "30020",
      "30005"
    ],
    "partyIds": [],
    "partyRoles": []
  },
  "questionResponses": [
    {
      "questionId": "30195",
      "values": [
        "false"
      ]
    },
    {
      "questionId": "30198",
      "values": [
        "false"
      ]
    },
    {
      "questionId": "30109",
      "values": [
        "false"
      ]
    },
    {
      "questionId": "30194",
      "values": [
        "100"
      ]
    }
  ],
  "results": {
    "customerIdentityStatus": "APPROVED"
  },
  "status": "APPROVED",
  "productDetails": [
    {
      "product": "EMBEDDED_PAYMENTS",
      "subProduct": "LIMITED_DDA",
      "onboardingStatus": "APPROVED"
    },
    {
      "product": "EMBEDDED_PAYMENTS",
      "subProduct": "LIMITED_DDA_PAYMENTS",
      "onboardingStatus": "NEW"
    }
  ]
}

Changes to ownership or controller information

How it works

  1. Add the sub-product using PATCH /clients. Specify the product in productDetails.Product, sub-product in productDetails.subProduct, and "ADD" in productDetails.action.
  2. Update existing party information using PATCH /parties. 
    Note: You cannot update the country of residence or formation, and individual or organization IDs. Any changes are reflected after onboarding is complete.
  3. Remove existing party, if required, using PATCH /parties with active as "false".
    Note: The party is removed after onboarding is complete.
  4. Add a new party using POST /parties. Populate the immediate parent's party ID in the parentPartyId.
    • Remove the newly added party using DELETE /maintenance-requests/{partyId} or {requestId}.
  5. Clear all outstanding requirements returned in the outstanding object.
  6. Submit the onboarding request using POST /verifications.
  7. Retrieve onboarding status for both existing and newly requested products from productDetails.onboardingStatus.
  8. Review submitted updates using GET /maintenance-requests/{requestId}.
    Note: Do not use status for tracking onboarding progress. It is maintained for backward compatibility.

Add a sub product

Add the new sub-product to the existing client using PATCH /clients with action set to "ADD" within productDetails.

Sample request:

Json
{
  "productDetails": [
    {
      "product": "EMBEDDED_PAYMENTS",
      "action": "ADD",
      "subProduct": "LIMITED_DDA_PAYMENTS"
    }
  ]
}

Sample response:

Json
{
  "attestations": [
    {
      "attesterFullName": "Monica Gellar",
      "attestationTime": "2023-08-28T12:00:00Z",
      "documentId": "a3db2849-5e58-4d8a-89d6-ef77ad809c49",
      "ipAddress": "1.1.1.1"
    }
  ],
  "createdAt": "2026-08-04T14:58:51.012Z",
  "id": "3100011591",
  "parties": [
    {
      "access": [],
      "id": "2100551438",
      "createdAt": "2026-08-04T14:58:50.467Z",
      "email": "monica@cpgetaways.com",
      "partyType": "ORGANIZATION",
      "preferences": {
        "defaultLanguage": "en-US"
      },
      "profileStatus": "APPROVED",
      "roles": [
        "CLIENT"
      ],
      "status": "ACTIVE",
      "active": true,
      "validationResponse": [],
      "organizationDetails": {
        "addresses": [
          {
            "addressType": "BUSINESS_ADDRESS",
            "addressLines": [
              "90 Bedford Street",
              "Apt 2E"
            ],
            "city": "New York",
            "state": "NY",
            "postalCode": "10014",
            "country": "US"
          }
        ],
        "associatedCountries": [],
        "countryOfFormation": "US",
        "dbaName": "CP Getaways",
        "industryCategory": "Accommodation and Food Services",
        "industryType": "All Other Traveler Accommodation",
        "industry": {
          "codeType": "NAICS",
          "code": "721199"
        },
        "secondaryMccList": [],
        "socialMedia": [],
        "organizationName": "Central Park Getaways",
        "organizationDescription": "Relax, unwind and experience the comforting charm of our apartment while exploring New York",
        "organizationType": "LIMITED_LIABILITY_COMPANY",
        "organizationIds": [
          {
            "idType": "EIN",
            "value": "421870602",
            "issuer": "US"
          }
        ],
        "phone": {
          "phoneType": "BUSINESS_PHONE",
          "countryCode": "+1",
          "phoneNumber": "6316215110"
        },
        "websiteAvailable": false,
        "yearOfFormation": "2023"
      },
      "metadata": []
    },
    {
      "access": [],
      "id": "2100551446",
      "createdAt": "2026-08-04T15:14:30.095Z",
      "email": "controller_party@example.com",
      "externalId": "TCU12344",
      "partyType": "INDIVIDUAL",
      "parentPartyId": "2100551438",
      "preferences": {
        "defaultLanguage": "en-US"
      },
      "profileStatus": "APPROVED",
      "roles": [
        "CONTROLLER"
      ],
      "status": "ACTIVE",
      "active": true,
      "validationResponse": [],
      "individualDetails": {
        "addresses": [
          {
            "addressType": "RESIDENTIAL_ADDRESS",
            "addressLines": [
              "90 Bedford Street",
              "Apt 2E"
            ],
            "city": "New York",
            "state": "NY",
            "postalCode": "10014",
            "country": "US"
          }
        ],
        "birthDate": "1987-01-01",
        "countryOfResidence": "US",
        "firstName": "Jack",
        "lastName": "Gellar",
        "individualIds": [
          {
            "idType": "SSN",
            "issuer": "US",
            "value": "521256154"
          }
        ],
        "jobTitle": "Other",
        "jobTitleDescription": "Senior Manager",
        "natureOfOwnership": "Direct",
        "socialMedia": []
      },
      "metadata": []
    }
  ],
  "partyId": "2100551438",
  "products": [
    "EMBEDDED_PAYMENTS"
  ],
  "outstanding": {
    "attestationDocumentIds": [],
    "documentRequestIds": [],
    "questionIds": [],
    "partyIds": [],
    "partyRoles": []
  },
  "questionResponses": [
    {
      "questionId": "30194",
      "values": [
        "100"
      ]
    },
    {
      "questionId": "30195",
      "values": [
        "false"
      ]
    },
    {
      "questionId": "30020",
      "values": [
        "false"
      ]
    },
    {
      "questionId": "30005",
      "values": [
        "1000"
      ]
    },
    {
      "questionId": "30198",
      "values": [
        "false"
      ]
    },
    {
      "questionId": "30023",
      "values": [
        "false"
      ]
    },
    {
      "questionId": "30024",
      "values": [
        "false"
      ]
    },
    {
      "questionId": "30109",
      "values": [
        "false"
      ]
    }
  ],
  "results": {
    "customerIdentityStatus": "APPROVED"
  },
  "status": "APPROVED",
  "updateRequest": {
    "status": "APPROVED",
    "action": "ADD",
    "requestId": "400000092"
  } 
  "productDetails": [
    {
      "product": "EMBEDDED_PAYMENTS",
      "subProduct": "LIMITED_DDA",
      "onboardingStatus": "APPROVED"
    },
    {
      "product": "EMBEDDED_PAYMENTS",
      "subProduct": "LIMITED_DDA_PAYMENTS",
      "onboardingStatus": "REVIEW_IN_PROGRESS"
    }
  ]
}

Remove exisiting party

Remove an existing party using PATCH /parties/{partyId} with active set to "false". The party is removed after onboarding is complete.

Sample request:

Json
{
  "active": false
}

Sample response:

Json
{
  "attestations": [
    {
      "attesterFullName": "Monica Gellar",
      "attestationTime": "2023-08-28T12:00:00Z",
      "documentId": "a3db2849-5e58-4d8a-89d6-ef77ad809c49",
      "ipAddress": "1.1.1.1"
    }
  ],
  "createdAt": "2026-08-04T14:58:51.012Z",
  "id": "3100011591",
  "parties": [
    {
      "access": [],
      "id": "2100551438",
      "createdAt": "2026-08-04T14:58:50.467Z",
      "email": "monica@cpgetaways.com",
      "partyType": "ORGANIZATION",
      "preferences": {
        "defaultLanguage": "en-US"
      },
      "profileStatus": "APPROVED",
      "roles": [
        "CLIENT"
      ],
      "status": "ACTIVE",
      "active": true,
      "validationResponse": [],
      "organizationDetails": {
        "addresses": [
          {
            "addressType": "BUSINESS_ADDRESS",
            "addressLines": [
              "90 Bedford Street",
              "Apt 2E"
            ],
            "city": "New York",
            "state": "NY",
            "postalCode": "10014",
            "country": "US"
          }
        ],
        "associatedCountries": [],
        "countryOfFormation": "US",
        "dbaName": "CP Getaways",
        "industryCategory": "Accommodation and Food Services",
        "industryType": "All Other Traveler Accommodation",
        "industry": {
          "codeType": "NAICS",
          "code": "721199"
        },
        "secondaryMccList": [],
        "socialMedia": [],
        "organizationName": "Central Park Getaways",
        "organizationDescription": "Relax, unwind and experience the comforting charm of our apartment while exploring New York",
        "organizationType": "LIMITED_LIABILITY_COMPANY",
        "organizationIds": [
          {
            "idType": "EIN",
            "value": "421870602",
            "issuer": "US"
          }
        ],
        "phone": {
          "phoneType": "BUSINESS_PHONE",
          "countryCode": "+1",
          "phoneNumber": "6316215110"
        },
        "websiteAvailable": false,
        "yearOfFormation": "2023"
      },
      "metadata": []
    }
  ],
  "partyId": "2100551438",
  "products": [
    "EMBEDDED_PAYMENTS"
  ],
  "outstanding": {
    "attestationDocumentIds": [],
    "documentRequestIds": [],
    "questionIds": [],
    "partyIds": [],
    "partyRoles": [
      "CONTROLLER"
    ]
  },
  "questionResponses": [
    {
      "questionId": "30194",
      "values": [
        "100"
      ]
    },
    {
      "questionId": "30195",
      "values": [
        "false"
      ]
    },
    {
      "questionId": "30020",
      "values": [
        "false"
      ]
    },
    {
      "questionId": "30005",
      "values": [
        "1000"
      ]
    },
    {
      "questionId": "30198",
      "values": [
        "false"
      ]
    },
    {
      "questionId": "30023",
      "values": [
        "false"
      ]
    },
    {
      "questionId": "30024",
      "values": [
        "false"
      ]
    },
    {
      "questionId": "30109",
      "values": [
        "false"
      ]
    }
  ],
  "results": {
    "customerIdentityStatus": "APPROVED"
  },
  "status": "APPROVED",
  "updateRequest": {
    "status": "NEW",
    "action": "DELETE",
    "requestId": "400000091"
  },
  "productDetails": [
    {
      "product": "EMBEDDED_PAYMENTS",
      "subProduct": "LIMITED_DDA",
      "onboardingStatus": "APPROVED"
    },
    {
      "product": "EMBEDDED_PAYMENTS",
      "subProduct": "LIMITED_DDA_PAYMENTS",
      "onboardingStatus": "NEW"
    }
  ]
}

Add a new party

Add a new party using POST /parties. Populate the immediate parent's party ID in parentPartyId.

Sample request:

Json
{
  "partyType": "INDIVIDUAL",
  "email": "controller_party@example.com",
  "externalId": "TCU12344",
  "partyType": "INDIVIDUAL",
  "parentPartyId": "2100551438",
  "preferences": {
    "defaultLanguage": "en-US"
  },
  "roles": [
    "CONTROLLER"
  ],
  "individualDetails": {
    "addresses": [
      {
        "addressType": "RESIDENTIAL_ADDRESS",
        "addressLines": [
          "90 Bedford Street",
          "Apt 2E"
        ],
        "city": "New York",
        "state": "NY",
        "postalCode": "10014",
        "country": "US"
      }
    ],
    "birthDate": "1987-01-01",
    "countryOfResidence": "US",
    "firstName": "Jack",
    "lastName": "Gellar",
    "individualIds": [
      {
        "idType": "SSN",
        "issuer": "US",
        "value": "521256154"
      }
    ],
    "jobTitle": "Other",
    "jobTitleDescription": "Senior Manager"
  }
}

Sample response:

Json
{
  "attestations": [
    {
      "attesterFullName": "Monica Gellar",
      "attestationTime": "2023-08-28T12:00:00Z",
      "documentId": "a3db2849-5e58-4d8a-89d6-ef77ad809c49",
      "ipAddress": "1.1.1.1"
    }
  ],
  "createdAt": "2026-08-04T14:58:51.012Z",
  "id": "3100011591",
  "parties": [
    {
      "access": [],
      "id": "2100551438",
      "createdAt": "2026-08-04T14:58:50.467Z",
      "email": "monica@cpgetaways.com",
      "partyType": "ORGANIZATION",
      "preferences": {
        "defaultLanguage": "en-US"
      },
      "profileStatus": "APPROVED",
      "roles": [
        "CLIENT"
      ],
      "status": "ACTIVE",
      "active": true,
      "validationResponse": [],
      "organizationDetails": {
        "addresses": [
          {
            "addressType": "BUSINESS_ADDRESS",
            "addressLines": [
              "90 Bedford Street",
              "Apt 2E"
            ],
            "city": "New York",
            "state": "NY",
            "postalCode": "10014",
            "country": "US"
          }
        ],
        "associatedCountries": [],
        "countryOfFormation": "US",
        "dbaName": "CP Getaways",
        "industryCategory": "Accommodation and Food Services",
        "industryType": "All Other Traveler Accommodation",
        "industry": {
          "codeType": "NAICS",
          "code": "721199"
        },
        "secondaryMccList": [],
        "socialMedia": [],
        "organizationName": "Central Park Getaways",
        "organizationDescription": "Relax, unwind and experience the comforting charm of our apartment while exploring New York",
        "organizationType": "LIMITED_LIABILITY_COMPANY",
        "organizationIds": [
          {
            "idType": "EIN",
            "value": "421870602",
            "issuer": "US"
          }
        ],
        "phone": {
          "phoneType": "BUSINESS_PHONE",
          "countryCode": "+1",
          "phoneNumber": "6316215110"
        },
        "websiteAvailable": false,
        "yearOfFormation": "2023"
      },
      "metadata": []
    },
    {
      "access": [],
      "id": "2100551446",
      "createdAt": "2026-08-04T15:14:30.095Z",
      "email": "controller_party@example.com",
      "externalId": "TCU12344",
      "partyType": "INDIVIDUAL",
      "parentPartyId": "2100551438",
      "preferences": {
        "defaultLanguage": "en-US"
      },
      "profileStatus": "APPROVED",
      "roles": [
        "CONTROLLER"
      ],
      "status": "ACTIVE",
      "active": true,
      "validationResponse": [],
      "individualDetails": {
        "addresses": [
          {
            "addressType": "RESIDENTIAL_ADDRESS",
            "addressLines": [
              "90 Bedford Street",
              "Apt 2E"
            ],
            "city": "New York",
            "state": "NY",
            "postalCode": "10014",
            "country": "US"
          }
        ],
        "birthDate": "1987-01-01",
        "countryOfResidence": "US",
        "firstName": "Jack",
        "lastName": "Gellar",
        "individualIds": [
          {
            "idType": "SSN",
            "issuer": "US",
            "value": "521256154"
          }
        ],
        "jobTitle": "Other",
        "jobTitleDescription": "Senior Manager",
        "natureOfOwnership": "Direct",
        "socialMedia": []
      },
      "metadata": []
    }
  ],
  "partyId": "2100551438",
  "products": [
    "EMBEDDED_PAYMENTS"
  ],
  "outstanding": {
    "attestationDocumentIds": [],
    "documentRequestIds": [],
    "questionIds": [],
    "partyIds": [],
    "partyRoles": []
  },
  "questionResponses": [
    {
      "questionId": "30194",
      "values": [
        "100"
      ]
    },
    {
      "questionId": "30195",
      "values": [
        "false"
      ]
    },
    {
      "questionId": "30020",
      "values": [
        "false"
      ]
    },
    {
      "questionId": "30005",
      "values": [
        "1000"
      ]
    },
    {
      "questionId": "30198",
      "values": [
        "false"
      ]
    },
    {
      "questionId": "30023",
      "values": [
        "false"
      ]
    },
    {
      "questionId": "30024",
      "values": [
        "false"
      ]
    },
    {
      "questionId": "30109",
      "values": [
        "false"
      ]
    }
  ],
  "results": {
    "customerIdentityStatus": "APPROVED"
  },
  "status": "APPROVED",
  "updateRequest": {
    "status": "APPROVED",
    "action": "ADD",
    "requestId": "400000092"
  } 
  "productDetails": [
    {
      "product": "EMBEDDED_PAYMENTS",
      "subProduct": "LIMITED_DDA",
      "onboardingStatus": "APPROVED"
    },
    {
      "product": "EMBEDDED_PAYMENTS",
      "subProduct": "LIMITED_DDA_PAYMENTS",
      "onboardingStatus": "REVIEW_IN_PROGRESS"
    }
  ]
}

Remove an added sub-product before submission

Use this workflow when a sub-product has been added but the onboarding request has not yet been submitted.

How it works

  1. Remove the sub-product using PATCH /clients. Specify the product in productDetails.Product, sub-product in productDetails.subProduct, and "REMOVE" in productDetails.action.
  2. If applicable, terminate any associated update requests using DELETE /maintenance-requests/{requestId}.
  3. Verify the removal using GET /clients.

Sample request:

Json
{
  "productDetails": [
    {
      "product": "EMBEDDED_PAYMENTS",
      "action": "REMOVE",
      "subProduct": "LIMITED_DDA_PAYMENTS"
    }
  ]
}

Sample response:

Json
{
  "attestations": [],
  "createdAt": "2026-08-03T20:22:57.41Z",
  "id": "3100011515",
  "parties": [
    {
      "access": [],
      "id": "2100551181",
      "createdAt": "2026-08-03T20:22:56.766Z",
      "email": "monica@cpgetaways.com",
      "partyType": "ORGANIZATION",
      "preferences": {
        "defaultLanguage": "en-US"
      },
      "profileStatus": "NEW",
      "roles": [
        "CLIENT"
      ],
      "status": "ACTIVE",
      "active": true,
      "validationResponse": [],
      "organizationDetails": {
        "addresses": [
          {
            "addressType": "BUSINESS_ADDRESS",
            "addressLines": [
              "90 Bedford Street",
              "Apt 2E"
            ],
            "city": "New York",
            "state": "NY",
            "postalCode": "10014",
            "country": "US"
          }
        ],
        "associatedCountries": [],
        "countryOfFormation": "US",
        "dbaName": "CP Getaways",
        "industryCategory": "Accommodation and Food Services",
        "industryType": "All Other Traveler Accommodation",
        "industry": {
          "codeType": "NAICS",
          "code": "721199"
        },
        "secondaryMccList": [],
        "socialMedia": [],
        "organizationName": "Central Park Getaways",
        "organizationDescription": "Relax, unwind and experience the comforting charm of our apartment while exploring New York",
        "organizationType": "SOLE_PROPRIETORSHIP",
        "organizationIds": [
          {
            "idType": "EIN",
            "value": "000000001",
            "issuer": "US"
          }
        ],
        "phone": {
          "phoneType": "BUSINESS_PHONE",
          "countryCode": "+1",
          "phoneNumber": "6316215110"
        },
        "websiteAvailable": false,
        "yearOfFormation": "2023"
      },
      "metadata": []
    },
    {
      "access": [],
      "id": "2100551182",
      "createdAt": "2026-08-03T20:22:56.98Z",
      "email": "foobar@example.com",
      "externalId": "TCU12344",
      "partyType": "INDIVIDUAL",
      "parentPartyId": "2100551181",
      "preferences": {
        "defaultLanguage": "en-US"
      },
      "profileStatus": "NEW",
      "roles": [
        "CONTROLLER",
        "BENEFICIAL_OWNER"
      ],
      "status": "ACTIVE",
      "active": true,
      "validationResponse": [
        {
          "validationStatus": "NEEDS_INFO",
          "validationType": "ENTITY_VALIDATION",
          "fields": [
            {
              "name": "birthDate"
            }
          ],
          "identities": [],
          "documentRequestIds": [],
          "roleSubType": []
        }
      ],
      "individualDetails": {
        "addresses": [
          {
            "addressType": "RESIDENTIAL_ADDRESS",
            "addressLines": [
              "90 Bedford Street",
              "Apt 2E"
            ],
            "city": "New York",
            "state": "NY",
            "postalCode": "10014",
            "country": "US"
          }
        ],
        "countryOfResidence": "US",
        "firstName": "Monica",
        "lastName": "Gellar",
        "individualIds": [
          {
            "idType": "SSN",
            "issuer": "US",
            "value": "100010001"
          }
        ],
        "jobTitle": "Other",
        "jobTitleDescription": "CEO",
        "natureOfOwnership": "Direct",
        "socialMedia": [],
        "soleOwner": true
      },
      "metadata": []
    }
  ],
  "partyId": "2100551181",
  "products": [
    "EMBEDDED_PAYMENTS"
  ],
  "outstanding": {
    "attestationDocumentIds": [
      "a3db2849-5e58-4d8a-89d6-ef77ad809c49"
    ],
    "documentRequestIds": [],
    "questionIds": [
      "30195",
      "30198",
      "30109",
      "30194"
    ],
    "partyIds": [
      "2100551182"
    ],
    "partyRoles": []
  },
  "questionResponses": [],
  "results": {
    "customerIdentityStatus": "NOT_STARTED"
  },
  "status": "NEW",
  "productDetails": [
    {
      "product": "EMBEDDED_PAYMENTS",
      "subProduct": "LIMITED_DDA",
      "onboardingStatus": "NEW"
    }
  ]
}

Onboard to multiple products

Use this workflow when onboarding a client to multiple products.

How it works

  1. Create the client using POST /clients.
  2. Specify each product in productDetails.Product.
  3. Additionally, include any one product in products for backward compatibility.
  4. Clear all outstanding requirements returned in the outstanding object.
  5. Submit the onboarding request using POST /verifications.
  6. Retrieve onboarding status for each product from productDetails.onboardingStatus.
    Note: Do not use status for tracking onboarding progress. It is maintained for backward compatibility.

Sample request:

Json
{
  "parties": [
    {
      "partyType": "ORGANIZATION",
      "roles": [
        "CLIENT"
      ],
      "email": "monica@cpgetaways.com",
      "organizationDetails": {
        "organizationType": "LIMITED_LIABILITY_COMPANY",
        "organizationName": "Central Park Getaways",
        "countryOfFormation": "US",
        "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",
        "addresses": [
          {
            "addressType": "BUSINESS_ADDRESS",
            "addressLines": [
              "90 Bedford Street",
              "Apt 2E"
            ],
            "city": "New York",
            "state": "NY",
            "postalCode": "10014",
            "country": "US"
          }
        ],
        "phone": {
          "phoneType": "BUSINESS_PHONE",
          "phoneNumber": "6316215110",
          "countryCode": "+1"
        },
        "organizationIds": [
          {
            "idType": "EIN",
            "value": "421870602",
            "issuer": "US"
          }
        ],
        "yearOfFormation": "2023"
      }
    },
    {
      "partyType": "INDIVIDUAL",
      "externalId": "TCU12344",
      "roles": [
        "CONTROLLER",
        "BENEFICIAL_OWNER"
      ],
      "email": "foobar@example.com",
      "individualDetails": {
        "firstName": "Monica",
        "lastName": "Gellar",
        "countryOfResidence": "US",
        "natureOfOwnership": "Direct",
        "jobTitle": "Other",
        "jobTitleDescription": "Senior Manager",
        "birthDate": "1987-01-01",
        "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": "621256154"
          }
        ]
      }
    }
  ],
  "products": [
    "EMBEDDED_PAYMENTS"
  ],
  "productDetails": [
    {
      "product": "EMBEDDED_PAYMENTS",
      "subProduct": "LIMITED_DDA"
    },
    {
      "product": "MERCHANT_SERVICES"
    }
  ]
}

Sample response:

Json
{
  "attestations": [],
  "createdAt": "2026-08-04T15:53:17.523Z",
  "id": "3100011596",
  "parties": [
    {
      "access": [],
      "id": "2100551477",
      "createdAt": "2026-08-04T15:53:17.003Z",
      "email": "monica@cpgetaways.com",
      "partyType": "ORGANIZATION",
      "preferences": {
        "defaultLanguage": "en-US"
      },
      "profileStatus": "NEW",
      "roles": [
        "CLIENT"
      ],
      "status": "ACTIVE",
      "active": true,
      "validationResponse": [],
      "organizationDetails": {
        "addresses": [
          {
            "addressType": "BUSINESS_ADDRESS",
            "addressLines": [
              "90 Bedford Street",
              "Apt 2E"
            ],
            "city": "New York",
            "state": "NY",
            "postalCode": "10014",
            "country": "US"
          }
        ],
        "associatedCountries": [],
        "countryOfFormation": "US",
        "dbaName": "CP Getaways",
        "industryCategory": "Accommodation and Food Services",
        "industryType": "All Other Traveler Accommodation",
        "industry": {
          "codeType": "NAICS",
          "code": "721199"
        },
        "secondaryMccList": [],
        "socialMedia": [],
        "organizationName": "Central Park Getaways",
        "organizationDescription": "Relax, unwind and experience the comforting charm of our apartment while exploring New York",
        "organizationType": "LIMITED_LIABILITY_COMPANY",
        "organizationIds": [
          {
            "idType": "EIN",
            "value": "421870602",
            "issuer": "US"
          }
        ],
        "phone": {
          "phoneType": "BUSINESS_PHONE",
          "countryCode": "+1",
          "phoneNumber": "6316215110"
        },
        "websiteAvailable": false,
        "yearOfFormation": "2023"
      },
      "metadata": []
    },
    {
      "access": [],
      "id": "2100551478",
      "createdAt": "2026-08-04T15:53:17.161Z",
      "email": "foobar@example.com",
      "externalId": "TCU12344",
      "partyType": "INDIVIDUAL",
      "parentPartyId": "2100551477",
      "preferences": {
        "defaultLanguage": "en-US"
      },
      "profileStatus": "NEW",
      "roles": [
        "CONTROLLER",
        "BENEFICIAL_OWNER"
      ],
      "status": "ACTIVE",
      "active": true,
      "validationResponse": [],
      "individualDetails": {
        "addresses": [
          {
            "addressType": "RESIDENTIAL_ADDRESS",
            "addressLines": [
              "90 Bedford Street",
              "Apt 2E"
            ],
            "city": "New York",
            "state": "NY",
            "postalCode": "10014",
            "country": "US"
          }
        ],
        "birthDate": "1987-01-01",
        "countryOfResidence": "US",
        "firstName": "Monica",
        "lastName": "Gellar",
        "individualIds": [
          {
            "idType": "SSN",
            "issuer": "US",
            "value": "621256154"
          }
        ],
        "jobTitle": "Other",
        "jobTitleDescription": "Senior Manager",
        "natureOfOwnership": "Direct",
        "socialMedia": []
      },
      "metadata": []
    }
  ],
  "partyId": "2100551477",
  "products": [
    "EMBEDDED_PAYMENTS"
  ],
  "outstanding": {
    "attestationDocumentIds": [
      "a3db2849-5e58-4d8a-89d6-ef77ad809c49"
    ],
    "documentRequestIds": [],
    "questionIds": [
      "30024",
      "30023",
      "30020",
      "30195",
      "30198",
      "30109",
      "30194",
      "30005"
    ],
    "partyIds": [],
    "partyRoles": []
  },
  "questionResponses": [],
  "results": {
    "customerIdentityStatus": "NOT_STARTED"
  },
  "status": "NEW",
  "productDetails": [
    {
      "product": "EMBEDDED_PAYMENTS",
      "subProduct": "LIMITED_DDA",
      "onboardingStatus": "NEW"
    },
    {
      "product": "MERCHANT_SERVICES",
      "onboardingStatus": "NEW"
    }
  ]
}

Receive onboarding updates with webhooks

Subscribe to onboarding events to receive updates when verification status changes or additional information is required.

Webhook notifications with OAuth

Sample header:

Json
"correlation-id": "4e1d4e12-1d48-4548-961f-800ae3a84ef4", 
"signature": "<digital-signature>", 
"key-id": "fac1e103bf3343268fe1217211d08c39", 
"signingAlgorithm": "EC", 
"Authorization": "Bearer <token>", 
"Content-Type": "application/json"

Sample body:

Json
{
      "notificationId": "368aa7df-b5b7-45bf-9efa-b90c61e04e23",
      "platformId": "6019582220",
      "notificationType": "EntityOnboardingEventNotification",
      "notificationSubType": "EntityOnboardingV3",
      "messageCreateTimestamp": "2026-07-21T19:24:57.942124081Z",
      "subscriptionId": "01a2a8cd-266c-4439-acc8-9fb95acf0a9e",
      "callbackURL": "https://clienturl.com/api/v1/notification",
      "entityOnboardingEventNotification": {
        "entityOnboardingV3": {
          "status": "APPROVED",
          "id": "3000574379",
          "hasOutstandingInformation": false,
          "customerIdentityStatus": "APPROVED",
          "productDetails": [
            {
              "product": "EMBEDDED_PAYMENTS",
              "subProduct": "LIMITED_DDA",
              "onboardingStatus": "APPROVED"
            },
            {
              "product": "EMBEDDED_PAYMENTS",
              "subProduct": "LIMITED_DDA_PAYMENTS",
              "onboardingStatus": "REVIEW_IN_PROGRESS"
            }
          ]
        }
      }
    }