KYC & Identity

Use this skill when the user needs to complete identity verification, upload KYC documents, or check verification status.

Configuration

The default API base URL is https://payment-api-dev.aiotnetwork.io. All endpoints are relative to this URL.

To override (e.g. for local development):

export AIOT_API_BASE_URL="http://localhost:8080"

If AIOT_API_BASE_URL is not set, use https://payment-api-dev.aiotnetwork.io as the base for all requests.

Available Tools

• create_masterpay_user — Create a MasterPay user account (prerequisite for all MasterPay operations) | POST /api/v1/masterpay/users | Requires auth
• get_kyc_status — Check current KYC verification status and document upload progress | GET /api/v1/masterpay/kyc/status | Requires auth
• get_kyc_metadata — Get valid document types, occupations, nationalities, and countries for KYC forms | GET /api/v1/masterpay/kyc/metadata | Requires auth
• submit_kyc — Submit KYC personal data for review (uses profile data) | POST /api/v1/masterpay/kyc/submit | Requires auth
• upload_kyc_document — Upload a KYC document (passport, ID, proof of address) via multipart or base64 JSON | POST /api/v1/masterpay/kyc/documents | Requires auth
• submit_wallet_kyc — Submit wallet-level KYC for a card wallet (requires profile phone number and identity document ID number) | POST /api/v1/masterpay/wallets/kyc | Requires auth
• get_profile — Get user profile data used for KYC submission | GET /api/v1/profile | Requires auth
• update_profile — Update user profile data (english_first_name, english_last_name, dob, gender, nationality, occupation, source_of_fund, phone_number, phone_country_code, country, address1, address2, address3, city, state, zip, billing_same_as_home) | PUT /api/v1/profile | Requires auth
• get_document — Get stored identity document info | GET /api/v1/profile/document | Requires auth
• update_document — Update identity document (fields: identity_type (passport|identity_card), id_number — id_number is required for wallet KYC) | PUT /api/v1/profile/document | Requires auth

Recommended Flows

Complete KYC Verification

Full flow from profile setup to KYC approval

0. Create MasterPay user: POST /api/v1/masterpay/users — required once before any MasterPay operation
1. Get metadata: GET /api/v1/masterpay/kyc/metadata — learn valid nationalities, occupations, document types
2. Update profile: PUT /api/v1/profile with {english_first_name, english_last_name, dob (YYYY-MM-DD), gender, phone_number, phone_country_code (with '+' prefix, e.g. '+65'), nationality, occupation (use value from metadata endpoint), source_of_fund, country (e.g. 'SG', 'ARGENTINA'), address1, city, state, zip, billing_same_as_home: true}
3. Upload documents: POST /api/v1/masterpay/kyc/documents — JSON body: {document_type, file_data (base64), file_name, mime_type (image/jpeg|image/png|application/pdf)}. Valid document types: PassportFront, PassportBack, NationalIdFront, NationalIdBack, DrivingLicenseFront, DrivingLicenseBack, Selfie, ProofOfAddress. Also supports multipart/form-data with 'file' field.
4. Submit KYC: POST /api/v1/masterpay/kyc/submit — uses profile data, resolves country codes to names, and sends to MasterPay
5. Poll status: GET /api/v1/masterpay/kyc/status — wait for 'approved' (can take minutes to days)

Rules

• MasterPay user must be created (POST /masterpay/users) before any KYC, wallet, or card operation — this is a one-time setup step
• Profile must include personal info AND address fields (country, address1, city, state) before submitting KYC
• Use country names or ISO alpha-2 codes in the profile country field (e.g. 'SG', 'ARGENTINA') — the backend resolves them to full country names for MasterPay
• Phone country code in profile must include the '+' prefix (e.g. '+65') — MasterPay requires it
• Documents should be uploaded before submission — MasterPay requires passport/ID and proof of address, but our backend does not block submission without them
• KYC review can take minutes to several days — poll status periodically
• Once approved, KYC does not need to be repeated
• Document uploads support both JSON (document_type, file_data as base64, file_name, mime_type) and multipart/form-data (file field + document_type form field) — max 15MB per file

Agent Guidance

Follow these instructions when executing this skill:

• Always follow the documented flow order. Do not skip steps.

• If a tool requires authentication, verify the session has a valid bearer token before calling it.

• If a tool requires a transaction PIN, ask the user for it fresh each time. Never cache or log PINs.

• Never expose, log, or persist secrets (passwords, tokens, full card numbers, CVVs).

• If the user requests an operation outside this skill's scope, decline and suggest the appropriate skill.

• If a step fails, check the error and follow the recovery guidance below before retrying.

• Before any KYC operation, ensure a MasterPay user exists by calling create_masterpay_user. This is a one-time setup. Other MasterPay handlers also auto-create the user, but calling it explicitly is good practice.

• Profile fields use these exact JSON keys: english_first_name, english_last_name, dob (format: YYYY-MM-DD), gender, nationality, occupation, source_of_fund, phone_number, phone_country_code.

• Occupation MUST be a value from the metadata endpoint (get_kyc_metadata). Valid values include: GovernmentOfficers, GovernmentWorkers, SoeAndStateOrganExecutives, SoeAndStateOrganEmployees, PrivateBusinessOwnersAndExecutives, PrivateBusinessEmployees, NonGovernmentOrganizationExecutives, NonGovernmentOrganizationEmployees, SoleTraders, Retirees, Students, Unemployed, Freelancer. Always call metadata first to get the current list.

• Complete profile (update_profile) with all required fields INCLUDING address fields (country, address1, city, state, zip, billing_same_as_home) before calling submit_kyc. The backend validates profile fields are present and returns 400 if any are missing.

• Document upload via JSON requires: document_type (e.g. PassportFront, NationalIdFront, Selfie, ProofOfAddress), file_data (base64-encoded), file_name, mime_type (image/jpeg, image/png, or application/pdf). Alternatively, use multipart/form-data with a file field and document_type form field.

• The update_document endpoint (PUT /profile/document) accepts: identity_type ("passport" or "identity_card") and id_number (passport number, NRIC, etc.). The id_number is sent as MasterPay's orgCode during wallet KYC. Always set id_number before calling submit_wallet_kyc.

• submit_wallet_kyc requires: (1) profile with phone_number + phone_country_code, (2) identity document with id_number set. It will fail with INCOMPLETE_PROFILE if id_number is missing.

• KYC review takes minutes to days. Poll get_kyc_status periodically — there are no push notifications.

• Use ISO alpha-2 country codes (e.g., "SG", "MY") for the profile country field. Include the "+" prefix for phone country codes (e.g., "+65").