Overview
Roma KYC APIs empower merchants to perform KYC for their individual customers.
Onboarding flows
Customer KYC runs through one of two onboarding flows. Both use the same endpoint and the same JSON body, but they make different fields mandatory. Roma assigns your client to one flow during onboarding; it is not selectable per request. Confirm which flow applies to you with your Roma representative.
| Standard flow | US flow | |
|---|---|---|
| Request variant | SubmitKycStandardRequest | SubmitKycUsRequest |
| Identity documents | Sent inline, in documents[] and selfie on the KYC submission | Sent separately, through Submit KYC Documents |
| Economic profile | nature_of_employment, nature_of_business, source_of_funds and employer details | The profile block — occupation, employment_status, source_of_funds[], purpose_of_account[], anticipated_monthly_fiat_activity |
| Tax and ID details | Not required | tax_info and identification are mandatory |
| Duplicate email | Returns the existing record with a kyc_link | Rejected with USER_ALREADY_EXISTS |
The per-field mandatory lists for both flows are documented on Submit Customer KYC.
APIs
- Submit Customer KYC: This API allows merchants to onboard the end customer. The mandatory fields depend on your onboarding flow.
- Submit KYC Documents: Uploads identity and supporting documents against a submitted KYC. US flow only — on the Standard flow, documents are sent inline on the KYC submission.
- Get KYC Details: Returns the whole record for a submitted KYC — its status, the field values on record, the documents already received, and the document types still outstanding.
- Get Customer KYC Status: This API allows merchants to check the KYC status.
- Get Terms and Conditions: This API allows the merchant to see which Terms and Conditions they are accepting while submitting the KYC.
- Get RFI: For customers whose KYC status is in
rfi_requestedstate, the pending RFI requirements can be fetched from this API. - Submit RFI: The requested RFI details can be submitted using the Submit RFI API. Once submitted, the status of the customer KYC is updated to
in_review.
Checking what has been received
Get KYC Details returns everything held against a KYC in one call, so use it when you need to reconcile a submission — for example, to show a customer which documents are still outstanding. Get Customer KYC Status returns the status alone and is the cheaper choice for polling.
pending_documents is populated on the US flow only, where documents are uploaded separately.
On the Standard flow documents arrive inline with the submission, so the array is always empty. An
empty array means nothing is known to be outstanding; it does not mean verification has finished —
read status for that.
No file content is returned. Documents come back as metadata only, and the fields in details that
hold a stored document reference are redacted.
KYC statuses
A successful submission returns initiated. The customer can only transact once the KYC reaches
active.
| Status | Meaning |
|---|---|
initiated | Submitted for verification. |
in_review | Under review. |
rfi_requested | More information is needed. Fetch the requirements with Get RFI and answer with Submit RFI. |
edd_initiated | Enhanced due diligence has started. |
edd_in_review | Enhanced due diligence is under review. |
active | Verified. The customer's accounts can be used. |
failed | Rejected. The customer cannot be onboarded. |
failed is terminal. An active KYC can return to rfi_requested when an identity document on
file expires, so keep handling KYC webhooks after activation. Documents can only be submitted while
the KYC is in initiated, in_review, rfi_requested, edd_initiated or edd_in_review.