Paymoja Verification

Create a new KYC or KYB verification case in draft status.

Request Body

Field	Type		Description
organization_id	UUID	required	Organization to verify
case_type	string	required	kyc or kyb
subject_type	string	optional	individual (default), company, trust, ngo
metadata	object	optional	Subject data — see metadata fields below
directors	array	optional	Directors/UBOs for KYB cases

KYC Metadata Fields

Field	Description
identity_number	South African ID number or passport number
first_name	Subject's first name
last_name	Subject's last name
account_number	Bank account number (for AVS checks)
account_type	Bank account type
branch_code	Bank branch code

KYB Metadata Fields

Field	Description
registration_number	CIPC company registration number
vat_number	VAT registration number
account_number	Company bank account
account_type	Account type
branch_code	Branch code

Example Request

curl -X POST /api/v1/verification/cases/ \
  -H "Authorization: Api-Key cen_xxxx_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "org-uuid",
    "case_type": "kyc",
    "subject_type": "individual",
    "metadata": {
      "identity_number": "9001015009087",
      "first_name": "John",
      "last_name": "Doe"
    }
  }'

Response 201 Created

{
  "id": "a1b2c3d4-e5f6-...",
  "case_type": "kyc",
  "status": "draft",
  "subject_type": "individual",
  "risk_level": "unknown",
  "metadata": { ... },
  "checks": [],
  "documents": [],
  "directors": [],
  "created_at": "2026-02-11T10:00:00Z"
}

Retrieve full details of a verification case including all checks, documents, and directors.

Response

{
  "id": "a1b2c3d4-...",
  "organization": "org-uuid",
  "organization_name": "Acme Corp",
  "case_type": "kyc",
  "status": "in_progress",
  "risk_level": "unknown",
  "submitted_by": "user-uuid",
  "submitted_by_name": "John Doe",
  "expires_at": null,
  "metadata": { ... },
  "checks": [
    {
      "id": "check-uuid",
      "check_type": "id_check",
      "status": "completed",
      "result": "pass",
      "result_details": { ... }
    }
  ],
  "documents": [ ... ],
  "directors": [ ... ]
}

Submit a draft case. This initiates all required checks with the verification provider automatically. Upload documents before submitting.

Response

{
  "case": {
    "id": "a1b2c3d4-...",
    "status": "in_progress",
    "checks": [
      {
        "check_type": "id_check",
        "status": "processing",
        "result": "pending"
      }
    ]
  },
  "checks_initiated": 3
}

Manually approve or reject a case after review.

Request Body

Field	Type		Description
action	string	required	approve or reject
notes	string	optional	Review notes
validity_days	integer	optional	Days until expiry (default: 365, approve only)

Example

{
  "action": "approve",
  "notes": "All checks passed",
  "validity_days": 365
}

Upload a supporting document to a case. Use multipart/form-data.

Form Fields

Field	Type		Description
document_type	string	required	See document types
file	file	required	The document file
check_id	UUID	optional	Link to a specific check

Example

curl -X POST /api/v1/verification/cases/{id}/documents/ \
  -H "Authorization: Api-Key cen_xxxx_xxxxx" \
  -F "document_type=national_id" \
  -F "file=@id_document.pdf"

Response 201 Created

{
  "id": "doc-uuid",
  "document_type": "national_id",
  "document_type_display": "National ID",
  "file_name": "id_document.pdf",
  "content_type": "application/pdf",
  "created_at": "2026-02-11T10:15:00Z"
}

Add a director or Ultimate Beneficial Owner to a KYB case.

Request Body

Field	Type		Description
first_name	string	required	Director's first name
last_name	string	required	Director's last name
identity_number	string	optional	ID number (encrypted, write-only)
role	string	optional	director, ubo, shareholder, secretary
ownership_percentage	decimal	optional	Ownership stake (e.g. 25.50)

Example

{
  "first_name": "Jane",
  "last_name": "Smith",
  "identity_number": "8505025009083",
  "role": "director",
  "ownership_percentage": 51.00
}

Response

{
  "id": "check-uuid",
  "check_type": "id_check",
  "check_type_display": "ID Check",
  "status": "completed",
  "status_display": "Completed",
  "provider": "thisisme",
  "result": "pass",
  "result_display": "Pass",
  "result_details": {
    "first_names": "JOHN",
    "last_name": "DOE",
    "id_number_valid": true,
    "deceased": false
  },
  "error_message": "",
  "started_at": "2026-02-11T10:30:00Z",
  "completed_at": "2026-02-11T10:30:45Z"
}

Retry a check that failed due to a provider error. Only checks in failed status can be retried.

No request body required.

Retrieve per-organization verification configuration.

Response

{
  "id": "config-uuid",
  "organization": "org-uuid",
  "provider": "thisisme",
  "is_active": true,
  "required_kyc_checks": ["id_check", "selfie", "address_lookup"],
  "required_kyb_checks": ["company_lookup", "director_lookup"],
  "auto_approve_threshold": "none",
  "verification_validity_days": 365
}

Update organization verification settings including required checks and auto-approve policy.

Request Body

{
  "organization": "org-uuid",
  "required_kyc_checks": ["id_check", "selfie", "aml_risk"],
  "required_kyb_checks": ["company_lookup", "director_lookup", "company_aml"],
  "auto_approve_threshold": "low",
  "verification_validity_days": 180
}