Kyc Identity

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, passport (passport number, e.g. 'E1234567A' — required for wallet KYC), 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, passport (passport number — required for wallet KYC).

• 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 passport (passport number) AND address fields (country, address1, city, state, zip, billing_same_as_home) before calling submit_kyc. The passport field is also required for wallet 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.).

• submit_wallet_kyc requires: (1) profile with phone_number + phone_country_code and passport set, (2) identity document with id_number set. It will fail with INCOMPLETE_PROFILE if either 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").