Create business profile

POST/partner/v1/business-profiles

Auth Bearer tokenScope partner.write

Creates a business customer under your partner account, together with its beneficial owners, directors and shareholders.

The call is idempotent on partnerCustomerId. Sending an id you already used returns the existing customer with 200 OK and created: false. People in a replayed businessPersonList are ignored, so retrying a timed-out request never duplicates an owner.

info

Everything is written in one transaction. If any person is rejected, nothing is created, so an error always means it is safe to fix and retry.

Body

partnerCustomerIdstringrequired

Your own id for this customer, 1 to 128 characters, no control characters. Used for idempotency and for lookup by reference.

emailstringrequired

Valid email, up to 255 characters.

phoneNumberstringrequired

E.164: a leading + then 7 to 15 digits, for example +2348012345678. Without the + it is rejected with PhoneNumber.Invalid.

companyNamestringrequired

2 to 255 characters.

tradingNamestring

businessTypeCodestringrequired

One of the business type codes, for example Corporate.

incorporationCountryCodestringrequired

ISO 3166-1 alpha-3 code in upper case, for example NGA.

industrystringrequired

One of the industry codes.

descriptionstring

websitestringrequired

Absolute https:// URL, up to 255 characters.

registrationNumberstringrequired

Up to 50 characters. Must not already be registered for a business in the same country.

registrationDatedate

YYYY-MM-DD.

addressesAddress[]

Every entry is validated when present.

Show Address propertiesHide Address properties

streetLine1stringrequired

Up to 255 characters.

streetLine2string

Up to 255 characters.

citystringrequired

Up to 100 characters.

statestringrequired

Up to 100 characters.

postalCodestringrequired

Up to 20 characters.

countryCodestringrequired

ISO 3166-1 alpha-3.

financialsobject

Optional. estimatedMonthlyVolume and monthlyTransactionFrequency take fixed values, the same ones the business app offers; the other two fields are free text.

Show Financials propertiesHide Financials properties

estimatedMonthlyVolumestring

The business's monthly volume in USD: UpTo15k, UpTo50k, UpTo100k, UpTo500k or Above500k. See monthly volume bands. Any case is accepted and stored as written there; anything else, including an amount such as 450000, is 400 ValidationControl.Error.

monthlyTransactionFrequencystring

How often the business expects to transact: Daily, SeveralTimesAWeek, Weekly, BiWeekly or Occasionally. See transaction frequencies. Any case is accepted and stored as written there; anything else, including a number, is 400 ValidationControl.Error.

sourceOfFundsstring

Free text.

purposeOfAccountstring

Free text.

businessPersonListBusinessPerson[]

Beneficial owners, directors and shareholders. This is the only call that creates people at creation time. Add more later with Update business profile.

Across the array, percentageShare must total 100 or less and every email must be distinct.

Show BusinessPerson propertiesHide BusinessPerson properties

firstNamestringrequired

Up to 100 characters.

lastNamestringrequired

Up to 100 characters.

nationalitystringrequired

ISO 3166-1 alpha-3, for example NGA.

emailstringrequired

Valid email, up to 255 characters, unique within the request.

ownershipTypeinteger[]required

At least one ownership type. A person can hold several roles.

addressAddressrequired

Same shape as addresses. countryCode is the person's country of residence, which decides the identity documents accepted. See Accepted identity documents.

identitiesIdentity[]required

At least one entry, each accepted for the person's country of residence.

Show Identity propertiesHide Identity properties

idTypeCodestringrequired

An identity type code accepted for the person's country of residence, not the business's.

idIssuingCountrystringrequired

ISO 3166-1 alpha-3.

idNumberstringrequired

Required for every identity, whatever its type. Not blank. Up to 255 characters, in the type's format for the country. Nigerian BVN and NIN are 11 digits.

idFrontDocumentUploadIduuiddeprecated

Accepted but ignored. Identity documents are no longer uploaded through the API.

idBackDocumentUploadIduuiddeprecated

Accepted but ignored.

idIssueDatedate

Not in the future. Required for PASSPORT, DRIVING_LICENCE, NATIONAL_ID, IDENTITY_CARD and RESIDENCE_CARD by default.

idExpiryDatedate

In the future, and after idIssueDate. Required for the same types as idIssueDate.

birthDatedate

In the past.

taxResidenceCountrystring

ISO 3166-1 alpha-3.

phonestring

E.164, for example +2348011112222.

percentageShareinteger

1 to 100.

Accepted identity documents

The identity documents accepted from a person depend on where they live, address.countryCode, not where the business is incorporated. Look them up first. This endpoint needs no token.

GET /customer/v1/onboarding/ubo-identity-requirements?countryCode=NGA

Each entry gives identityTypeCode, whether it isRequired, and whether it requiresIssueDate and requiresExpiryDate. idNumber is required for every identity, whatever the entry says. Compliance manages the list. Changes apply to new submissions only.

A person who fails these rules is refused with 400 ValidationControl.Error, and error.name names the reason.

Reason	Fix
`UboIdentity.CountryNotSupported`	No identity documents are accepted from that country, so the person cannot be onboarded.
`UboIdentity.TypeNotAccepted`	Use a type accepted for the person's country.
`UboIdentity.RequiredTypeMissing`	Add the type the country requires.
`UboIdentity.IdNumberRequired`	`idNumber` is missing. Send it.
`UboIdentity.IdNumberInvalid`	Fix the number's format or length.
`UboIdentity.IssueDateRequired`	Send `idIssueDate`.
`UboIdentity.ExpiryDateRequired`	Send `idExpiryDate`.

Response

201 Created with a Location header on first creation, 200 OK on an idempotent repeat.

customerIduuid

The business customer. Use it on every other business profile route.

partnerCustomerIdstring

Your id, as sent.

createdboolean

true when this call created the customer, false on a repeat.

ubosobject[]

The people on the customer. On a repeat this lists the people that already exist.

Show propertiesHide properties

uboIduuid

The person's id.

firstNamestring

lastNamestring

emailstring

percentageShareinteger | null

Errors

Besides the common errors:

Show endpoint errors

Code	HTTP	When
`Customer.PartnerCustomerIdRequired`	400	`partnerCustomerId` is empty.
`Customer.PartnerCustomerIdInvalid`	400	Longer than 128 characters or contains control characters.
`BusinessType.NotFound`	400	Unknown `businessTypeCode`.
`BusinessType.NotOffered`	400	`businessTypeCode` is a retired code, e.g. `Llc`. Use `Corporate`, `SoleTrader` or `PaymentMto`.
`Country.NotFound`	400	Unknown `incorporationCountryCode`.
`OnboardingConfig.NotFound`	400	The country is not yet enabled for business onboarding. Contact support.
`PhoneNumber.Invalid`	400	`phoneNumber` is not E.164.
`ValidationControl.Error`	400	A field failed validation, including shares above 100, duplicate emails, or identities not accepted for a person's country.
`Customer.DuplicateBusiness`	409	This registration number is already registered in this country.
`OwnershipDetails.DuplicateEmail`	409	Two people share an email. Nothing was created.
`Customer.InvalidStage`	409	The customer cannot accept owners at its stage. Should not occur on create.

Request

curl -X POST https://gateway.sandbox.rynopay.io/api/partner/v1/business-profiles \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "partnerCustomerId": "cust-001",
    "email": "ops@acme.test",
    "phoneNumber": "+2348012345678",
    "companyName": "Acme Ltd",
    "businessTypeCode": "Corporate",
    "incorporationCountryCode": "NGA",
    "industry": "FinancialServices",
    "website": "https://acme.test",
    "registrationNumber": "RC123456",
    "addresses": [{
      "streetLine1": "1 Marina Road",
      "city": "Lagos",
      "state": "Lagos",
      "postalCode": "100001",
      "countryCode": "NGA"
    }],
    "businessPersonList": [{
      "firstName": "Jane",
      "lastName": "Doe",
      "nationality": "NGA",
      "email": "jane@acme.test",
      "ownershipType": [1, 2],
      "percentageShare": 60,
      "address": {
        "streetLine1": "1 Marina Road",
        "city": "Lagos",
        "state": "Lagos",
        "postalCode": "100001",
        "countryCode": "NGA"
      },
      "identities": [{
        "idTypeCode": "PASSPORT",
        "idIssuingCountry": "NGA",
        "idNumber": "A12345678",
        "idExpiryDate": "2030-01-10"
      }]
    }]
  }'

Response

{
  "isSuccess": true,
  "isFailure": false,
  "error": { "code": "", "name": "" },
  "title": null,
  "traceId": "0HN...",
  "value": {
    "customerId": "b3f1c2d4-...",
    "partnerCustomerId": "cust-001",
    "created": true,
    "ubos": [{
      "uboId": "7c2a9e10-...",
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane@acme.test",
      "percentageShare": 60
    }]
  }
}

{
  "value": null,
  "isSuccess": false,
  "isFailure": true,
  "error": {
    "code": "Customer.DuplicateBusiness",
    "name": "A business with registration number 'RC123456' already exists in country 'NGA'"
  },
  "title": "Conflict",
  "traceId": "0HN..."
}

Body​

Accepted identity documents​

Response​

Errors​

Body

Accepted identity documents

Response

Errors