Entities Overview

Entities lets you register the people (INDIVIDUAL) and companies (COMPANY) you work with, declare their identity and supporting documents, upload the files that prove them, and follow the result of the KYC/KYB review performed by Localpayment. Entities is shared by payins and payouts: the same entity can be used across Localpayment products.

This guide is for developers who onboard customers, beneficiaries, or business partners through the API.

Objects

%%{init: {'theme': 'base', 'themeVariables': {'background': '#ffffff', 'primaryColor': '#31467c', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#0c1a29', 'secondaryColor': '#31467c', 'tertiaryColor': '#ffffff', 'lineColor': '#0c1a29', 'textColor': '#0c1a29', 'edgeLabelBackground': '#ffffff', 'fontFamily': 'Manrope'}, 'fontFamily': 'Manrope', 'htmlLabels': false, 'flowchart': {'htmlLabels': false, 'wrappingWidth': 400, 'padding': 20}}}%%
flowchart LR
    M["Your merchant account"] --> S["Custom-fields schema"]
    M --> P["Entity: INDIVIDUAL"]
    M --> C["Entity: COMPANY"]
    P --> D1["Document: CPF (primary)<br/>proofs: FRONT, BACK, SELFIE"]
    P --> D2["Document: PROOF_OF_ADDRESS<br/>proof: DOCUMENT"]
    C --> D3["Document: CNPJ (primary)<br/>proof: DOCUMENT"]
    C --> D4["Document: ARTICLES_OF_INCORPORATION<br/>proof: DOCUMENT"]
    C -.- L1(["UBO link: 60%, CEO"]):::lbl -.-> P
    classDef default fill:#31467c,stroke:#0c1a29,stroke-width:1px,color:#ffffff,font-family:Manrope
    classDef lp fill:#0c1a29,stroke:#0c1a29,color:#ffffff
    classDef terminal fill:#0c1a29,stroke:#0c1a29,color:#ffffff
    classDef lbl fill:#0c1a29,stroke:#0c1a29,color:#ffffff,font-size:13px

How it works

Your integration has five steps. The last one, verify, tells Localpayment that the upload is complete and starts the review. With verify your part of the upload ends: you don't need to poll the entity's status afterwards. You only act again on the entity if Localpayment asks for a correction.

%%{init: {'theme': 'base', 'themeVariables': {'background': '#ffffff', 'primaryColor': '#31467c', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#0c1a29', 'secondaryColor': '#31467c', 'tertiaryColor': '#ffffff', 'lineColor': '#0c1a29', 'textColor': '#0c1a29', 'edgeLabelBackground': '#ffffff', 'fontFamily': 'Manrope'}, 'fontFamily': 'Manrope', 'htmlLabels': false, 'flowchart': {'htmlLabels': false, 'wrappingWidth': 400, 'padding': 20}}}%%
flowchart TD
    A["1. Create the entity with its primary document<br/>POST /api/entity/v1/entities"] --> B["2. Add the other documents<br/>POST /api/entity/v1/entities/{entityId}/documents"]
    B --> C["3. Upload the files of each document<br/>POST /api/entity/v1/documents/{docId}/proofs"]
    C --> Q{"Is it a company?"}
    Q --- L1(["yes"]):::lbl --> D["4. Link the owners<br/>POST /api/entity/v1/entities/{companyId}/ubos"]
    Q --- L2(["no"]):::lbl --> V
    D --> V["5. Request verification<br/>POST /api/entity/v1/entities/{entityId}/verify<br/>on the company, once everything is loaded"]
    V --> E[/"Localpayment reviews the entity"/]:::lp
    classDef default fill:#31467c,stroke:#0c1a29,stroke-width:1px,color:#ffffff,font-family:Manrope
    classDef lp fill:#0c1a29,stroke:#0c1a29,color:#ffffff
    classDef terminal fill:#0c1a29,stroke:#0c1a29,color:#ffffff
    classDef lbl fill:#0c1a29,stroke:#0c1a29,color:#ffffff,font-size:13px

If Localpayment needs a correction, it tells you what to fix: each rejected file carries its verificationReason. Upload a replacement with the same proofType or correct the data, then call Request Verification again. See Track the Review and Fix Rejections.

Entity statuses

%%{init: {'theme': 'base', 'themeVariables': {'background': '#ffffff', 'primaryColor': '#31467c', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#0c1a29', 'secondaryColor': '#31467c', 'tertiaryColor': '#ffffff', 'lineColor': '#0c1a29', 'textColor': '#0c1a29', 'edgeLabelBackground': '#ffffff', 'fontFamily': 'Manrope'}, 'fontFamily': 'Manrope', 'htmlLabels': false, 'flowchart': {'htmlLabels': false, 'wrappingWidth': 400, 'padding': 20}}}%%
flowchart TD
    S((Start)) --- L1(["Create an Entity"]):::lbl --> PK[PENDING_KYC]
    PK --- L2(["Request Verification, by you"]):::lbl --> IR[IN_REVIEW]
    IR --- L3(["correction requested, with reason"]):::lbl --> PK
    IR --- L4(["approved"]):::lbl --> AC[ACTIVE]
    IR --- L5(["rejected, with reason"]):::lbl --> RJ[REJECTED]
    AC --- L6(["blocked, with reason"]):::lbl --> BL[BLOCKED]
    BL --- L7(["unblocked"]):::lbl --> AC
    PK --- L8(["Close an Entity"]):::lbl --> CL[CLOSED]
    IR --> CL
    AC --> CL
    BL --> CL
    RJ --> CL
    CL --> E((End))
    class S,E terminal
    classDef default fill:#31467c,stroke:#0c1a29,stroke-width:1px,color:#ffffff,font-family:Manrope
    classDef lp fill:#0c1a29,stroke:#0c1a29,color:#ffffff
    classDef terminal fill:#0c1a29,stroke:#0c1a29,color:#ffffff
    classDef lbl fill:#0c1a29,stroke:#0c1a29,color:#ffffff,font-size:13px

"Editable" means the KYC data, documents, and files can still be changed. Editing a document resets its approved files to PENDING. Editing other entity data does not change a review already recorded.

Document and proof statuses

Localpayment Compliance sets the status of each proof. The status of a document is derived from its proofs and its validity.

documentationStatus on the entity summarizes file coverage: NO_FILES (no document has a file), PARTIAL (some do), or COMPLETE (all do). It does not express approval.

Conventions

Next steps