Update to Individual Customer Verification: Source of Funds Now Required

Starting October 19, individual customers created through Sphere will need to provide source of funds information before verification can proceed.

This change aligns our onboarding requirements with our banking partners' compliance standards. Their reviews routinely include source of funds checks. Without that information on file, each check becomes a request to your customer, pausing activation and payments while they respond. Collecting the information at onboarding removes that friction for the large majority of customers.

These fields are live today. Start submitting them now so your integration is ready before the change takes effect.

What's Changing

Individuals (KYC)

The following become required items in the customer's verification profile. All are sent under personalInformation on POST /v2/customer except the document, which is uploaded separately.

• Source of funds: personalInformation.sourceOfFunds
• Occupation: personalInformation.occupationSocCode
• Employment status: personalInformation.employmentStatus
• Expected monthly payment volume: personalInformation.expectedMonthlyPayments
• Acting on behalf of someone else: personalInformation.actingAsIntermediary
• Account purpose: personalInformation.accountPurpose (already required for EEA customers today; becomes required for all)
• Supporting document, such as a bank statement: source_of_funds_document via POST /v2/document

Businesses (KYB)

• No change. primarySourceOfFunds and primarySourceOfFundsDescription are already required at creation; no document requirement is added.

Who's Affected

• From October 19, customers created without these fields are still created. POST /v2/customer does not reject. The missing items appear in verificationProfiles[].criteria.required on GET /v2/customer/{id}, the profile stays incomplete, and verification is not submitted until they are supplied.
• Existing customers are not affected at the switch-over. Customers without this information on file may still receive a request from our banking partner as they transact; those requests continue to be handled through your Sphere contact as they are today.

Timeline‍

• Now: all fields and the document type are accepted and optional. Start submitting them today.
• October 19, 2026: enforcement begins for new customer creation.

What You Need to Implement

1. Update your onboarding flow to collect, for individuals: source of funds, occupation (SOC code), employment status, expected monthly payments, account purpose, and whether the customer is acting as an intermediary. For businesses: source of funds selection plus description (already required).
2. Collect a supporting document (bank statement or equivalent) and upload it via the document endpoint with documentType: "source_of_funds_document".
3. If you validate enum values client-side, update to the lists in the API section below.
4. Check field names carefully: POST /v2/customer silently ignores unknown property names (no error), so a misspelled field will not be flagged.

Questions about the change or your integration? Email support@spherepay.co or reach out to your Sphere account manager.

API Impact

Customer creation (POST /v2/customer): requests missing the new fields are accepted (200/201) before and after Oct 19 - the fields are optional on the request schema. Requests with an invalid value (e.g. sourceOfFunds: "other") return 422 with RFC 9457 field-level errors, today and after Oct 19. Unknown property names are stripped silently, not rejected.

Verification profile: on GET /v2/customer/{id}, each entry in verificationProfiles[] has name, status (incomplete | pending | approved | rejected | resubmission_required) and criteria with four arrays: required, pending, complete, errors. Until submitted, the new items appear in criteria.required. An uploaded source_of_funds_document shows in criteria.pending until reviewed by our verification provider, then criteria.complete.

Document upload (POST /v2/document): documentType: "source_of_funds_document", target: "customer". Accepted formats PDF, JPEG, PNG. File size 10 KB to 8 MB.

Hosted onboarding: If you use Sphere's hosted onboarding, no changes are required. Customers are prompted for the new information automatically.

Example - Create an Individual Customer (After Oct 19)

Name and date of birth are top-level; all source-of-funds fields are under personalInformation.

{
 "type": "individual",
 "email": "jane.smith@example.com",
 "phone": "+14155550123",
 "firstName": "Jane",
 "lastName": "Smith",
 "dateOfBirth": "1990-01-15",
 "address": { "line1": "123 Main St", "city": "Chicago", "state": "IL", "postalCode": "60601", "country": "USA" },
 "personalInformation": {
   "sourceOfFunds": "salary",
   "occupationSocCode": "151252",
   "employmentStatus": "employed",
   "expectedMonthlyPayments": "5000_9999",
   "actingAsIntermediary": false,
   "accountPurpose": "receive_salary"
 }
}


Example - Upload the Document

curl -X POST "https://api.spherepay.co/v2/document" \
 -H "Authorization: Bearer <API_KEY>" \
 -F "target=customer" \
 -F "targetId=customer_abc123" \
 -F "documentType=source_of_funds_document" \
 -F "file=@bank_statement.pdf" \
 -F "description=Bank statement, last 3 months"

Accepted formats PDF, JPEG, PNG, 10 KB to 8 MB. description is optional.

Example - Verification Profile Before and After Submission

Verification field names are snake_case and differ from the request field names.

Before submission (Oct 19+):

"verificationProfiles": [{
 "name": "kyc_profile_a",
 "status": "incomplete",
 "criteria": {
   "required": ["source_of_funds", "occupation_soc_code", "employment_status", "expected_monthly_payments", "acting_as_intermediary", "account_purpose", "source_of_funds_document"],
   "pending": [],
   "complete": ["identity_document"],
   "errors": []
 }
}]


After fields submitted and document uploaded:

"verificationProfiles": [{
 "name": "kyc_profile_a",
 "status": "pending",
 "criteria": {
   "required": [],
   "pending": ["source_of_funds_document"],
   "complete": ["identity_document", "source_of_funds", "occupation_soc_code", "employment_status", "expected_monthly_payments", "acting_as_intermediary", "account_purpose"],
   "errors": []
 }
}]


Accepted Values

Individual sourceOfFunds (12 values):

company_funds, ecommerce_reseller, gambling_proceeds, gifts, government_benefits, inheritance, investments_loans, pension_retirement, salary, sale_of_assets_real_estate, savings, someone_elses_funds

Three legacy values are still accepted and rewritten on receipt: gift → gifts, business_income → company_funds, investment_returns → investments_loans. other is rejected with 422 (sourceOfFunds must be a supported source of funds).

Business primarySourceOfFunds

business_loans, grants, inter_company_funds, investment_proceeds, legal_settlement, owners_capital, pension_retirement, sale_of_assets, sales_of_goods_and_services, third_party_funds, treasury_reserves