KYC & Identity

intent

use this skill when a user needs to complete identity verification, upload KYC documents, or check verification status against MasterPay Global. the skill handles the full flow from profile setup through document upload to approval polling. use it for onboarding workflows, wallet activation, or regulatory compliance checks.

inputs

environment variables

• AIOT_API_BASE_URL: api base url. defaults to https://payment-api-dev.aiotnetwork.io if unset. override with export AIOT_API_BASE_URL="http://localhost:8080" for local dev.

authentication

• valid bearer token (required for all endpoints). token must have scope covering profile, KYC, and MasterPay operations. if token expires during workflow, caller must re-authenticate and resume from the failed step.

external connection: MasterPay Global

• integration point for KYC submission and approval tracking. MasterPay reviews submitted data and documents asynchronously. no direct API key needed; uses bearer token auth to this system.

user profile data (required before KYC submission)

• english_first_name, english_last_name: user's full name in english
• dob: date of birth in YYYY-MM-DD format (e.g., "1990-03-15")
• gender: user's gender
• nationality: ISO alpha-3 or country name, validated against metadata endpoint
• occupation: must match a value from get_kyc_metadata (e.g., PrivateBusinessOwnersAndExecutives, Freelancer, Students). invalid values cause 400 error.
• source_of_fund: source of wealth or income
• phone_number: user's phone number (digits only or with common separators)
• phone_country_code: country code with '+' prefix (e.g., "+65", "+1"). MasterPay requires the prefix.
• country: ISO alpha-2 code (e.g., "SG", "MY") or full country name (e.g., "ARGENTINA"). backend resolves to MasterPay country name.
• address1: primary address line
• address2: optional secondary address line
• address3: optional tertiary address line
• city: city or suburb
• state: state or province
• zip: postal or zip code
• billing_same_as_home: boolean, typically true

identity document data (required before wallet KYC, optional for personal KYC)

• identity_type: "passport" or "identity_card"
• id_number: passport number, NRIC, driver license number, etc. required for wallet-level KYC submission.

document files (for upload_kyc_document step)

• file format: JPEG, PNG, or PDF. max 15MB per file.
• document_type: one of PassportFront, PassportBack, NationalIdFront, NationalIdBack, DrivingLicenseFront, DrivingLicenseBack, Selfie, ProofOfAddress. must match at least one required type in approval workflow (passport/ID + proof of address recommended).
• submission method: JSON with base64 encoding OR multipart/form-data. JSON requires {document_type, file_data (base64), file_name, mime_type}. multipart requires 'file' field and 'document_type' form field.

procedure

1. create MasterPay user (one-time setup)

   • input: bearer token
   • call: POST /api/v1/masterpay/users
   • output: MasterPay user ID (uuid). save this for reference; other endpoints may auto-create if missing, but explicit creation is best practice.
   • edge case: if user already exists, endpoint returns 409 Conflict. safe to ignore and proceed.

2. fetch KYC metadata

   • input: bearer token
   • call: GET /api/v1/masterpay/kyc/metadata
   • output: json object containing:
     • valid_nationalities: array of nationality strings
     • valid_occupations: array of occupation enum values (e.g., "PrivateBusinessOwnersAndExecutives", "Freelancer")
     • valid_document_types: array of acceptable document_type values
     • valid_countries: array of country names and ISO codes
   • use this to validate user inputs before profile update and occupation selection.

3. get current profile

   • input: bearer token
   • call: GET /api/v1/profile
   • output: current profile object. fields may be null or empty. inspect to see what's already populated.

4. update profile with personal and address data

   • input: bearer token, profile object with all required fields (see inputs section)
   • call: PUT /api/v1/profile with json body containing english_first_name, english_last_name, dob, gender, nationality, occupation (from metadata), source_of_fund, phone_number, phone_country_code (with '+'), country (ISO-2 or name), address1, city, state, zip, billing_same_as_home
   • output: updated profile object
   • validation: backend enforces all address fields (country, address1, city, state, zip) are present. missing fields cause 400 Bad Request. occupation value must match metadata list or returns 400.
   • edge case: phone_country_code without '+' prefix is rejected by MasterPay during KYC submit. always prefix with '+'.

5. update identity document info

   • input: bearer token, identity_type ("passport" or "identity_card"), id_number (passport/NRIC/DL number)
   • call: PUT /api/v1/profile/document with json body {identity_type, id_number}
   • output: updated document object
   • note: id_number is mandatory for wallet-level KYC but optional for personal KYC. set it now to avoid later failures.

6. upload KYC documents

   • input: bearer token, document files (JPEG/PNG/PDF, max 15MB), document_type labels
   • call: POST /api/v1/masterpay/kyc/documents with either:
     • json body: {document_type, file_data (base64-encoded), file_name, mime_type}
     • multipart/form-data: 'file' field + 'document_type' form field
   • output: document record with upload timestamp and status
   • recommended sequence: upload PassportFront, PassportBack (or NationalIdFront/Back), Selfie, ProofOfAddress. at minimum MasterPay expects passport/ID and proof of address, but our backend does not enforce this; submission succeeds even without all docs.
   • edge case: file encoding errors or corrupt base64 cause 400. ensure base64 is properly formatted and file is readable.
   • edge case: network timeout during large file upload. implement retry with exponential backoff (3 retries, 2s / 5s / 10s delay).

7. submit KYC for review

   • input: bearer token (profile and documents already set up)
   • call: POST /api/v1/masterpay/kyc/submit
   • output: submission acknowledgment (e.g., {status: "pending", submission_id: uuid}). KYC review is async.
   • validation: backend checks that profile has all required fields (name, dob, address, phone, nationality, occupation). missing fields cause 400. documents are not strictly required but MasterPay may request additional docs after submission.
   • side effect: profile country code and occupation are resolved to MasterPay canonical names and sent to MasterPay API.

8. poll KYC status

   • input: bearer token
   • call: GET /api/v1/masterpay/kyc/status
   • output: status object with fields: {status: "pending" | "approved" | "rejected" | "needs_info", rejection_reason: string (if rejected), documents_needed: array (if needs_info), submission_time: iso timestamp, last_update: iso timestamp}
   • polling strategy: poll every 30 seconds initially; after 5 minutes of "pending", increase to 1-minute intervals. review typically takes minutes to days.
   • edge case: rate limiting. if API returns 429, backoff to exponential delay (2s, 4s, 8s, etc.) up to 60s max.
   • edge case: empty response or missing status field. log and retry.

9. submit wallet-level KYC (optional, for card wallet activation)

   • input: bearer token (profile with phone_number + phone_country_code already set, identity document with id_number already set)
   • call: POST /api/v1/masterpay/wallets/kyc
   • output: wallet KYC submission confirmation
   • prerequisite: personal KYC must be approved (or at least submitted). wallet KYC is a secondary verification step.
   • validation: endpoint returns 400 INCOMPLETE_PROFILE if id_number is missing from identity document. ensure step 5 (update identity document) is complete first.

10. retrieve stored document info (optional, for audit or retry)

    • input: bearer token
    • call: GET /api/v1/profile/document
    • output: current identity document object with identity_type and id_number
    • use this to verify id_number is set before wallet KYC submission.

decision points

if MasterPay user creation fails (409 Conflict)

• user already exists. log and proceed to step 2. no action needed.

if occupation value is not in metadata list

• reject the value and ask user to select from valid_occupations returned by step 2. return 400 if user insists on invalid value.

if profile update fails (400 Bad Request)

• check error message. if "missing field", ensure all address fields (country, address1, city, state, zip) are populated. if "invalid occupation", fetch metadata again and retry with valid value. if "invalid phone country code", ensure '+' prefix is present.

if document upload fails (400 or 413 Payload Too Large)

• if 413, file exceeds 15MB. compress or split. if 400, check base64 encoding (if JSON) or file format (JPEG/PNG/PDF only).

if document upload times out (network error)

• retry up to 3 times with exponential backoff (2s, 5s, 10s). if all retries fail, log the failure and inform user; they can retry the upload later.

if KYC submission fails (400 Bad Request)

• backend validation failed. check error message:
  • "incomplete profile": missing required fields in profile. return to step 4 and fill gaps.
  • "invalid country code": country field is neither ISO-2 code nor recognized name. use step 2 metadata to select valid country.
  • other 400: log and ask user to contact support.

if KYC submission fails (500 or 502)

• backend or MasterPay service error. wait 30 seconds and retry submission. if persists, inform user and schedule retry.

if KYC status returns "rejected"

• read rejection_reason field. inform user of reason. if reason indicates missing documents, return to step 6 (upload_kyc_document) with new docs. if reason is insufficient funds or compliance issue, may not be recoverable; escalate to support.

if KYC status returns "needs_info"

• check documents_needed array. user must upload additional documents specified. return to step 6, upload requested docs, then re-submit KYC (step 7) or wait for auto-re-submission.

if wallet KYC submission fails (400 INCOMPLETE_PROFILE)

• identity_type or id_number is missing from identity document. return to step 5 (update identity document) and set id_number, then retry wallet KYC.

if wallet KYC submission fails (400 KYC_NOT_APPROVED)

• personal KYC has not been approved yet. wait for step 8 (poll KYC status) to return "approved", then retry wallet KYC.

output contract

successful KYC flow completion

• user profile fully populated with all required fields (english_first_name, english_last_name, dob, gender, nationality, occupation, source_of_fund, phone_number, phone_country_code, country, address1, city, state, zip, billing_same_as_home)
• identity document stored with identity_type and id_number
• at least one document uploaded (passport or ID + proof of address recommended)
• KYC submission sent to MasterPay (step 7 returned 200 with submission_id)
• final status polling (step 8) returns {status: "approved"}
• data format: all responses are json. dates in ISO 8601 (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ).

successful wallet KYC completion

• personal KYC status is "approved"
• wallet KYC submitted (step 9 returned 200)
• wallet is now eligible for card activation

failure states logged with detail

• step number, api endpoint, http status code, response body (scrubbed of sensitive data like full card numbers or tokens)
• timestamp of failure
• retry count and backoff duration (if retried)

outcome signal

user knows KYC succeeded when:

• step 8 polling returns {status: "approved"}
• caller receives explicit "KYC approved" message
• profile page or account settings show "verified" or "approved" badge
• user can proceed to wallet creation or card issuance without further identity verification prompts

user knows KYC is pending when:

• step 7 returns a submission confirmation
• step 8 returns {status: "pending"}
• caller informs user "your KYC is being reviewed, this typically takes X minutes to Y days" with expected timeline

user knows KYC failed when:

• step 8 returns {status: "rejected"} with rejection_reason
• caller displays reason to user (e.g., "document image was blurry", "occupation mismatch")
• next steps are presented (resubmit with new documents, contact support, etc.)

user knows KYC needs more info when:

• step 8 returns {status: "needs_info"} with documents_needed array
• caller lists required documents (e.g., "please upload proof of address")
• clear re-submission flow is presented

agent guidance on errors

• never expose, log, or persist secrets (passwords, bearer tokens, full card numbers, CVVs, PIN codes)
• if caller requests transaction PIN, ask fresh each time. never cache.
• if step fails with 401 Unauthorized, session token has expired or is invalid. ask user to re-authenticate.
• if step fails with 403 Forbidden, user does not have permission for this operation. escalate to account support.
• if step fails with 5xx (server error), issue is on backend. retry with backoff. if persists for >5 minutes, escalate to platform support.
• if caller requests an operation outside this skill (e.g., card issuance, transaction history), decline and refer to appropriate skill.
• always follow the documented flow order. skipping steps (e.g., creating MasterPay user, fetching metadata) can cause silent failures or confusing error messages downstream.