Submit KYC for a Team
POST
/api/v2/account_kycs
const url = 'https://api.payhero.africa/api/v2/account_kycs';const options = { method: 'POST', headers: {Authorization: 'Basic <credentials>', 'Content-Type': 'application/json'}, body: '{"account_id":63,"entity_type":"business","country_code":"KE","country":"Kenya","kyc_tier":3,"contact_information":{"first_name":"Jane","last_name":"Doe","identification_number":12345678,"identification_type":"national_id","phone_number":"+254712345678","upload_information":{"identification_front_document":"https://cdn.acme.co/kyc/id-front.jpg","identification_back_document":"https://cdn.acme.co/kyc/id-back.jpg","selfie_image":"https://cdn.acme.co/kyc/selfie.jpg"}},"entity_information":{"entity_name":"Vendor A Ltd","nature_of_business":"Internet Service Provider","business_type":"limited_company","entity_address":"Westlands, Nairobi"},"account_information":{"currency":"KES","organization_id":"9","account_name":"Vendor A","email":"vendor-a@acme.co","phone_number":"+254711000111"}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.payhero.africa/api/v2/account_kycs \ --header 'Authorization: Basic <credentials>' \ --header 'Content-Type: application/json' \ --data '{ "account_id": 63, "entity_type": "business", "country_code": "KE", "country": "Kenya", "kyc_tier": 3, "contact_information": { "first_name": "Jane", "last_name": "Doe", "identification_number": 12345678, "identification_type": "national_id", "phone_number": "+254712345678", "upload_information": { "identification_front_document": "https://cdn.acme.co/kyc/id-front.jpg", "identification_back_document": "https://cdn.acme.co/kyc/id-back.jpg", "selfie_image": "https://cdn.acme.co/kyc/selfie.jpg" } }, "entity_information": { "entity_name": "Vendor A Ltd", "nature_of_business": "Internet Service Provider", "business_type": "limited_company", "entity_address": "Westlands, Nairobi" }, "account_information": { "currency": "KES", "organization_id": "9", "account_name": "Vendor A", "email": "vendor-a@acme.co", "phone_number": "+254711000111" } }'Attaches identity and (for businesses) entity information to a Team. A
fresh submission returns status: "pending"; PayHero reviews it
asynchronously. See KYC tiers & limits.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”Media typeapplication/json
object
account_id
required
integer
entity_type
individual or business.
string
country_code
string
country
string
kyc_tier
integer
notes
string
contact_information
object
first_name
string
last_name
string
surname
string
entity_type
string
identification_number
integer
identification_type
string
secondary_identification_number
integer
secondary_identification_type
string
status
string
phone_number
string
upload_information
References to uploaded KYC document files.
object
identification_front_document
string
identification_back_document
string
secondary_identification_front_document
string
secondary_identification_back_document
string
selfie_image
string
tax_document
string
proof_of_address_document
string
entity_certificate_document
string
entity_shareholding_document
string
entity_information
object
entity_name
string
entity_directors
string
nature_of_business
string
business_type
string
entity_address
string
tax_document_number
integer
entity_certificate_number
integer
upload_information
References to uploaded KYC document files.
object
identification_front_document
string
identification_back_document
string
secondary_identification_front_document
string
secondary_identification_back_document
string
selfie_image
string
tax_document
string
proof_of_address_document
string
entity_certificate_document
string
entity_shareholding_document
string
account_information
object
currency
string
organization_id
string
account_name
string
email
string
phone_number
string
kyc_status
string
account_status
string
is_phone_verified
boolean
is_email_verified
boolean
Examples
ExampleBusiness KYC
{ "account_id": 63, "entity_type": "business", "country_code": "KE", "country": "Kenya", "kyc_tier": 3, "contact_information": { "first_name": "Jane", "last_name": "Doe", "identification_number": 12345678, "identification_type": "national_id", "phone_number": "+254712345678", "upload_information": { "identification_front_document": "https://cdn.acme.co/kyc/id-front.jpg", "identification_back_document": "https://cdn.acme.co/kyc/id-back.jpg", "selfie_image": "https://cdn.acme.co/kyc/selfie.jpg" } }, "entity_information": { "entity_name": "Vendor A Ltd", "nature_of_business": "Internet Service Provider", "business_type": "limited_company", "entity_address": "Westlands, Nairobi" }, "account_information": { "currency": "KES", "organization_id": "9", "account_name": "Vendor A", "email": "vendor-a@acme.co", "phone_number": "+254711000111" }}Responses
Section titled “Responses”The KYC submission.
Media typeapplication/json
object
account_kyc
object
id
integer
account_id
integer
entity_type
string
status
string
country_code
string
country
string
kyc_tier
integer
notes
string
contact_information
object
first_name
string
last_name
string
surname
string
entity_type
string
identification_number
integer
identification_type
string
secondary_identification_number
integer
secondary_identification_type
string
status
string
phone_number
string
upload_information
References to uploaded KYC document files.
object
identification_front_document
string
identification_back_document
string
secondary_identification_front_document
string
secondary_identification_back_document
string
selfie_image
string
tax_document
string
proof_of_address_document
string
entity_certificate_document
string
entity_shareholding_document
string
entity_information
object
entity_name
string
entity_directors
string
nature_of_business
string
business_type
string
entity_address
string
tax_document_number
integer
entity_certificate_number
integer
upload_information
References to uploaded KYC document files.
object
identification_front_document
string
identification_back_document
string
secondary_identification_front_document
string
secondary_identification_back_document
string
selfie_image
string
tax_document
string
proof_of_address_document
string
entity_certificate_document
string
entity_shareholding_document
string
account_information
object
currency
string
organization_id
string
account_name
string
email
string
phone_number
string
kyc_status
string
account_status
string
is_phone_verified
boolean
is_email_verified
boolean
created_at
string format: date-time
updated_at
string format: date-time
Example
{ "account_kyc": { "id": 501, "account_id": 63, "entity_type": "business", "status": "pending", "country_code": "KE", "country": "Kenya", "kyc_tier": 3, "contact_information": { "first_name": "Jane", "last_name": "Doe", "identification_number": 12345678, "identification_type": "national_id", "phone_number": "+254712345678" }, "entity_information": { "entity_name": "Vendor A Ltd", "nature_of_business": "Internet Service Provider", "business_type": "limited_company", "entity_address": "Westlands" }, "account_information": { "currency": "KES", "organization_id": "9", "account_name": "Vendor A", "email": "vendor-a@acme.co", "phone_number": "+254711000111" } }}The request was rejected (validation or business-rule failure).
Media typeapplication/json
object
error_code
string
error_message
string
status_code
integer
Examples
{ "error_code": "invalid_argument", "error_message": "the transaction amount is insufficient as it wont cater for cost: (4.62)", "status_code": 400}{ "error_code": "invalid_argument", "error_message": "The passed channel is not active", "status_code": 400}Missing or invalid Basic auth credentials.
Media typeapplication/json
object
error_code
string
error_message
string
status_code
integer
Example
{ "error_code": "invalid_argument", "error_message": "the transaction amount is insufficient as it wont cater for cost: (4.62)", "status_code": 400}