Proof of Income Verification for High-Risk Users

1. Overview

During onboarding, each customer is assessed from an AML/CFT perspective.

A red-scored user is a customer assessed as presenting an increased AML/CFT risk. A customer assessed as High risk is considered Red scored for this flow.

In that case, a Proof of Income (PoI) document is requested as part of enhanced due diligence.

The Proof of Income requirement is represented by an Income Demand, with its own lifecycle, statuses, documents and callbacks.

The Income Demand is independent from the KYC demand, but the KYC demand must already have been created and the identity document must have been provided and validated before the Proof of Income flow can be triggered.

If the user's risk level remains below High, no Proof of Income document is required.

Once the Proof of Income requirement has been triggered, a subsequent decrease in the user's risk level does not cancel it. The Income Demand must reach a final outcome.

2. When the Proof of Income requirement is triggered

The Proof of Income requirement is a separate demand from the KYC demand.

It can be triggered once:

• the KYC demand has been created;
• the identity document has been provided and validated;
• the information required for the AML/CFT risk assessment is available;
• the customer is assessed as High / Red.

The Proof of Income flow is therefore related to the onboarding KYC journey, but it has its own lifecycle and does not replace or restart the KYC demand.

Relationship with KYC and QES

The Proof of Income is not a prerequisite for completing the KYC provider journey or performing the signature / QES.

The KYC journey can continue end to end, including signature, even if the Proof of Income document has not yet been provided.

However, if the required Proof of Income is still missing or unresolved, the onboarding remains blocked and cannot reach its final completed state.

In other words:

• KYC processing may continue;
• QES / signature may be performed;
• the Proof of Income demand remains open independently;
• onboarding completion remains blocked until the Proof of Income requirement is resolved.

3. Country-specific processing

Accepted Proof of Income document types are:

• INCOME_TAX
• TAX_NOTICE
• PAYSLIP

The review mode is determined by the user's tax residence:

• one tax residence in France → automated review;
• tax residence outside France → manual review;
• multiple tax residences → manual review automatically.

For users with more than one tax residence, only one Proof of Income document is requested. The back office decides whether the submitted document is sufficient.

4. High-level lifecycle

flowchart TD
    A[User is onboarding] --> B[KYC demand created]
    B --> C[Identity document provided and validated]
    C --> D{Risk level High?}
    D -- No --> E[No Proof of Income required]
    E --> F[Onboarding continues]
    D -- Yes --> G[Create Income Demand]
    G --> H[Request Proof of Income]

    H --> I[User submits document]
    I --> J[Document review]
    J --> K{Review result}

    K -- Validated --> L[Income Demand Complete]
    K -- Refused --> M{Reopening available?}
    M -- Yes --> N[Income Demand Incomplete]
    N --> H
    M -- No --> O[Income Demand Rejected]

    H --> P{90 days elapsed?}
    P -- Yes --> Q[Income Demand Expired]

    C --> R[KYC journey may continue]
    R --> S[QES / signature may be completed]

    L --> T[PoI requirement resolved]
    T --> U[Onboarding can reach final completion]

    O --> V[User becomes Inactive]
    Q --> V

    S --> W{PoI resolved?}
    W -- No --> X[Onboarding remains blocked]
    W -- Yes --> U

5. Sequence diagrams

5.1 Risk level below High

sequenceDiagram
    participant Partner
    participant Xpollens

    Xpollens-->>Partner: User remains below High risk
    Note over Partner,Xpollens: No Proof of Income demand is required
    Note over Partner,Xpollens: Onboarding continues normally

5.2 High-risk user — successful Proof of Income

sequenceDiagram
    participant User
    participant Partner
    participant Xpollens

    Xpollens-->>Partner: IncomeDemandChanged - Initialized
    Partner-->>User: Proof of Income expected
    User->>Partner: Submit Proof of Income
    Partner->>Xpollens: Upload Proof of Income document

    Xpollens-->>Partner: IncomeDemandChanged - Pending
    Note over Xpollens: Document is reviewed

    Xpollens-->>Partner: IncomeDemandChanged - Complete
    Note over Partner,Xpollens: PoI requirement completed

5.3 Refused document and reopening

sequenceDiagram
    participant User
    participant Partner
    participant Xpollens

    User->>Partner: Submit Proof of Income
    Partner->>Xpollens: Upload Proof of Income document
    Note over Xpollens: Document is refused

    Xpollens-->>Partner: IncomeDemandChanged - Incomplete
    Partner-->>User: Request another document

    User->>Partner: Submit another Proof of Income
    Partner->>Xpollens: Upload replacement document

    alt Document is validated
        Xpollens-->>Partner: IncomeDemandChanged - Complete
    else Reopening limit reached
        Xpollens-->>Partner: IncomeDemandChanged - Rejected
        Note over Partner,Xpollens: relationState moves to AwaitingInactivation
    end

5.4 Demand timeout

sequenceDiagram
    participant User
    participant Partner
    participant Xpollens

    Xpollens-->>Partner: IncomeDemandChanged - Pending
    Note over Partner: User has not completed the PoI requirement

    Note over Xpollens: 90 days elapse without successful validation

    Xpollens-->>Partner: IncomeDemandChanged - Expired
    Note over Partner,Xpollens: reason = IncomeTimedOut
    Note over Partner,Xpollens: relationState = AwaitingInactivation

5.5 Non-French user — manual review

sequenceDiagram
    participant User
    participant Partner
    participant Xpollens

    Xpollens-->>Partner: IncomeDemandChanged - Pending
    User->>Partner: Submit Proof of Income
    Partner->>Xpollens: Upload Proof of Income document

    Note over Xpollens: Document is routed to manual review
    Xpollens-->>Partner: IncomeDemandChanged - updated demand

    alt Document is validated
        Xpollens-->>Partner: IncomeDemandChanged - Complete
    else Document is refused
        Xpollens-->>Partner: IncomeDemandChanged - Incomplete or Rejected
    end

During manual review, the partner receives To_Review_Manually in receivedDiligences.status.

6. Income Demand statuses

The main field to monitor is the status carried by the IncomeDemandChanged callback and returned by the Income Demand API.

Status calculation

1. documentary fraud detected → FraudSuspicion;
2. all expected documents satisfied → Complete;
3. an expected document is refused:
   • reopening available → Incomplete;
   • reopening limit reached → Rejected;
4. 90 days reached without successful validation → Expired;
5. otherwise → Pending.

7. Supporting-document statuses

Processing time

The processing time depends on the country and review mode:

• France: automated review is performed in real time;
• Other countries: manual review follows standard banking-production service hours, 5 days a week from 09:00 to 18:00.

The 09:00–18:00 service window is expressed in CET/CEST (France time).

7.1 Common refusal reason codes

When a Proof of Income diligence is refused, the reason field provides the corresponding refusal reason code.

8. Reopening after a refusal

When a Proof of Income document is refused and reopening is still available, the user can submit another accepted document.

After three refused attempts, the Proof of Income flow is definitively refused and the user becomes Inactive.

The associated reason is IncomeReopeningLimitReached.

9. IncomeDemandChanged callback

The partner is notified through the HTTP callback IncomeDemandChanged.

Correlation

Use:

• appUserId to correlate the callback with the partner user;

Emission rule

Acceptance testing validates that IncomeDemandChanged is sent to the partner on each update of the Income Demand.

Partners should therefore treat the callback as an updated snapshot of the demand and should not assume that every callback means that the top-level status changed.

Example payload

{
  "type": "IncomeDemandChanged",
  "status": "Incomplete",
  "appUserId": "partner-user-id",
  "receivedDiligences": [
    {
      "reason": "Expired document",
      "reasonCodes": [
        "DOCUMENT_EXPIRED"
      ],
      "diligenceType": "PAYSLIP",
      "status": "Refused",
      "comment": "Expired document",
      "attachments": [
        {
          "fileName": "xp_document_expired.png",
          "attachmentKey": "8ce4c4cc-0e91-48ff-9f40-0289c2bb0696"
        }
      ]
    }
  ]
}

10. APIs

10.1 Retrieve the current Income Demand

GET /v3.0/users/{appUserId}/income/demand

10.2 Upload a Proof of Income document

POST /v3.0/users/{appUserId}/income/attachments

Partners do not need to restrict uploads to PDF or enforce a specific file format for this flow.

Maximum upload size:

• 20 MB per file

10.3 Download an uploaded document

GET /v3.0/users/{appUserId}/income/attachment/{attachmentKey}

11. Accepted Proof of Income documents

Accepted document types are:

• INCOME_TAX
• TAX_NOTICE
• PAYSLIP

For users declaring tax residency in France, an Avis d'imposition is therefore not the only accepted document.

Users who do not yet have an Avis d'imposition can provide a PAYSLIP.

For users with tax residency in France and another country, only one document is requested. The back office decides whether the submitted document is sufficient for the user's situation.

A work contract is not currently listed among the accepted document types.

12. Recommended partner integration

Partners should:

1. handle the IncomeDemandChanged callback;
2. correlate notifications using appUserId;
3. when the demand is Initialized or Pending, prompt the user to provide the expected Proof of Income documents;
4. upload the document through the income attachment endpoint;
5. keep the user onboarding open while the demand is non-terminal;
6. if the demand becomes Incomplete, explain that the submitted document was not accepted and allow the user to submit another document;
7. when the demand becomes Complete, continue/finalize onboarding subject to all other onboarding requirements;
8. when the demand becomes Rejected or FraudSuspicion, stop the normal onboarding completion flow and apply the corresponding refusal user experience;
9. make callback handling idempotent and tolerate duplicate notifications.

13. How to test

The Proof of Income flow can be tested end to end in Xpollens test environments.

13.1 Prepare the onboarding prerequisites

For the Proof of Income flow to be triggered:

1. create the user and initialize onboarding;
2. create the KYC demand;
3. provide and validate the identity document (ID + Selfie in the reference test flow);
4. complete the information required for risk assessment, including FATCA and declarative information where applicable;
5. wait for the relevant PEP / sanctions checks to complete;
6. obtain a High / Red risk result.

At that point, the Income Demand can be created.

The QES / signature does not have to wait for the Income document. The KYC journey may continue and the signature may be completed while the Income Demand is still open.

13.2 Test data for a high-risk scenario

High-risk test scenarios can be exercised with suitable test data.

The following residence countries have been used in testing because of their very-high-risk classification:

An IR residence scenario has been successfully used to validate Red Score triggering.

A French-address scenario has also been validated with the following declarative values:

{
  "economicActivity": "21",
  "asset": "6",
  "income": "5"
}

The test datasets above are approved for partner use in Sandbox.

13.3 Retrieve the Income Demand

GET /v3.0/users/{appUserId}/income/demand

Example:

{
  "status": "Pending",
  "decision": "Pending",
  "diligences": [],
  "expectedDiligences": [
    {
      "type": "Income",
      "expectedCount": 1,
      "possibleDiligenceSubTypes": [
        "PAYSLIP",
        "TAX_NOTICE",
        "INCOME_TAX"
      ]
    }
  ]
}

13.4 Upload a Proof of Income document

POST /v3.0/users/{appUserId}/income/attachments

13.5 Force a result using the filename mock

Examples:

13.6 Verify the result

For a successful scenario:

{
  "status": "Complete",
  "decision": "Ok",
  "diligences": [
    {
      "type": "PAYSLIP",
      "status": "Validated"
    }
  ],
  "expectedDiligences": []
}

The partner should also receive an IncomeDemandChanged callback.

13.7 Test refusal and reopening

Use a mock filename such as:

xp_document_expired.pdf

If reopening is still available, another document can be uploaded.

After three refused attempts, the Proof of Income flow is definitively refused and the user becomes Inactive.

13.8 Complete the onboarding

The QES / signature may already have been completed before the Proof of Income document is provided.

The onboarding can reach its final completed state only once all required onboarding controls, including the Proof of Income requirement, are resolved.

The expected final result is a validated onboarding and an active user relationship.

13.9 Troubleshooting information

If a test is blocked, provide at least:

• appUserId;
• blocked onboarding step;
• KYC, FATCA, PEP/sanctions and Income statuses;
• received callback payload, if any;
• approximate date and time;
• API request payload when relevant.

14. FAQ

1. At which step of the registration process is the risk calculated? Is it after KYC? After QES?

The Proof of Income requirement is a separate demand from KYC.

Before it can be triggered, the KYC demand must already exist and the identity document must have been provided and validated.

It is not dependent on QES. The KYC journey and signature / QES may continue even while the Proof of Income demand is still open.

2. If the user has not submitted the Proof of Income yet, does this block some registration steps? Only account activation?

The missing Proof of Income blocks final onboarding completion, but it does not prevent all other onboarding steps from continuing.

In particular, the KYC journey and the QES / signature can be completed before the Proof of Income document is provided.

The user cannot reach the final completed onboarding state until the Proof of Income requirement is resolved.

3. What happens if the Proof of Income demand expires after 90 days? Is the user account permanently closed?

After 90 days without successful validation, the demand expires and the user becomes Inactive.

4. Will the user account be permanently closed after 3 refused Proof of Income attempts?

Yes. After three refused attempts, the flow is definitively refused and the user becomes Inactive.

5. How long can a document with a Received status take to move to Validated or Refused?

• France: automated review is performed in real time.
• Other countries: manual review follows standard banking-production service hours, 5 days a week from 09:00 to 18:00.

The service window is 09:00–18:00 CET/CEST (France time).

6. For users declaring tax residency in France, is the Avis d'imposition the only document accepted?

No. Accepted document types are:

• INCOME_TAX
• TAX_NOTICE
• PAYSLIP

7. For users declaring tax residency in France but who do not yet have an Avis d'imposition, can they provide another document such as a work contract?

A PAYSLIP is accepted as an alternative.

A work contract is not currently listed among the accepted document types.

8. For users declaring tax residency in France and another country, is only one Avis d'imposition sufficient, or are multiple documents needed?

Only one Proof of Income document is requested. The back office decides whether it is sufficient.

9. Should partners control the format or maximum upload size?

No specific file format control is required.

Maximum upload size: 20 MB per file.