Get Onboarding Requirements

Retrieve the UBO identity requirements and document requirements for business onboarding in a specific country. Use this before creating UBOs and uploading documents to know exactly what data is required.

Endpoint

GET https://prod.rynopay.io/partner/v1/onboarding-requirements?countryIso3Code={code}&businessTypeCode={type}

Query parameters

Parameter	Type	Required	Description
countryIso3Code	string	Yes	Country code (ISO 3166-1 alpha-3, e.g. NGA, GBR, USA)
businessTypeCode	string	No	Business type code to filter document requirements (e.g. LLC, SOLE_PROPRIETOR)

Example request

curl -X GET "https://prod.rynopay.io/partner/v1/onboarding-requirements?countryIso3Code=NGA&businessTypeCode=LLC" \
  -H "Authorization: Bearer <access_token>"

Response

200 OK

{
  "isSuccess": true,
  "value": {
    "countryId": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "countryName": "Nigeria",
    "countryIso3": "NGA",
    "customerType": "Business",
    "requiredDocuments": [
      {
        "documentTypeCategory": "RegistryDocuments",
        "label": "Certificate of Incorporation",
        "isRequired": true,
        "minimumDocuments": 1,
        "maximumDocuments": 3,
        "allowedFormats": ["pdf", "jpg", "png"],
        "maxFileSizeMB": 10,
        "displayOrder": 1,
        "description": "Official certificate of business registration"
      },
      {
        "documentTypeCategory": "ProofOfAddress",
        "label": "Utility Bill or Bank Statement",
        "isRequired": true,
        "minimumDocuments": 1,
        "maximumDocuments": 2,
        "allowedFormats": ["pdf", "jpg", "png"],
        "maxFileSizeMB": 10,
        "displayOrder": 2,
        "description": "Must be dated within the last 3 months"
      }
    ],
    "requiredIdentityFields": [
      {
        "identityType": "PASSPORT",
        "identityTypeCode": "PASSPORT",
        "fieldName": "passport_number",
        "inputType": "Input",
        "isRequired": true,
        "label": "Passport Number",
        "placeholder": "Enter passport number",
        "requiresIssueDate": true,
        "requiresExpiryDate": true,
        "requiresIdNumber": true,
        "validationRules": {
          "regex": "^[A-Z0-9]{6,12}$",
          "minLength": 6,
          "maxLength": 12,
          "errorMessage": "Passport number must be 6-12 alphanumeric characters"
        },
        "displayOrder": 1
      },
      {
        "identityType": "BVN",
        "identityTypeCode": "BVN",
        "fieldName": "bvn_number",
        "inputType": "Input",
        "isRequired": true,
        "label": "Bank Verification Number",
        "placeholder": "Enter 11-digit BVN",
        "requiresIssueDate": false,
        "requiresExpiryDate": false,
        "requiresIdNumber": true,
        "validationRules": {
          "regex": "^[0-9]{11}$",
          "minLength": 11,
          "maxLength": 11,
          "errorMessage": "BVN must be exactly 11 digits"
        },
        "displayOrder": 2
      }
    ],
    "configurationVersion": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
    "effectiveDate": "2026-01-01T00:00:00Z",
    "isDefaultConfiguration": false
  }
}

Response fields

Field	Type	Description
countryId	string (UUID)	Internal country identifier
countryName	string	Country display name
countryIso3	string	ISO 3166-1 alpha-3 code
customerType	string	Always Business for this endpoint
requiredDocuments	array	List of required documents
requiredIdentityFields	array	List of required identity fields
configurationVersion	string (UUID)	Configuration snapshot ID (store this for UBO submissions)
effectiveDate	string	When this configuration became active (ISO 8601)
isDefaultConfiguration	boolean	Whether this is a fallback configuration

Required document

Field	Type	Description
documentTypeCategory	string	Category (e.g. RegistryDocuments, ProofOfAddress, TaxRegistration)
label	string	Display label
isRequired	boolean	Whether this document is mandatory
minimumDocuments	integer	Minimum number of documents required
maximumDocuments	integer	Maximum number of documents allowed
allowedFormats	string[]	Accepted file formats (e.g. pdf, jpg, png)
maxFileSizeMB	integer	Maximum file size in MB
displayOrder	integer	Suggested display order
description	string	Additional instructions

Required identity field

Field	Type	Description
identityType	string	Identity type enum value
identityTypeCode	string	Identity type as string (use this when creating UBOs)
fieldName	string	Form field key
inputType	string	Document, Input, or Select
isRequired	boolean	Whether this identity is mandatory
label	string	Display label
placeholder	string	Input placeholder text
requiresIssueDate	boolean	Whether issue date must be provided
requiresExpiryDate	boolean	Whether expiry date must be provided
requiresIdNumber	boolean	Whether ID number must be entered
validationRules	object	Validation constraints (regex, min/max length, error message)
displayOrder	integer	Suggested display order

400 Bad Request

{
  "isSuccess": false,
  "error": {
    "code": "Country.NotFound",
    "message": "No country found with code 'XYZ'"
  }
}

Possible error codes:

Code	Description
Country.NotFound	No country matches the provided ISO3 code
BusinessType.NotFound	No business type matches the provided code
OnboardingConfig.NotFound	No active onboarding configuration for this country