🧩 User — Add Additional Data (Risk/KYC) API #

Gateway Path: /User/add-additional-data
Service: Authentication & Authorization
Method: POST
Auth: Bearer token in Authorization header

1) 📖 Overview & Purpose #

Persists risk & KYC-related attributes for a user in a structured JSON payload.
All values in additionalData.data must be sourced from the KYC verification process (i.e., retrieved by calling the KYC-related endpoints in your flow) and then submitted here in one consolidated call.

🔎 Source of truth: “KYC verification process” endpoints (questionnaires, address capture, device/location capture, BTrust callback, etc.). This endpoint does not compute values; it only stores them.

2) 🔗 Endpoint Definition #

HTTP: POST /User/add-additional-data

Headers #

• Authorization: Bearer <token> — valid access token

• Content-Type: application/json

Request Body (structure) #

{
    "id": 2077,
    "additionalData": {
        "type": "EnrollAdditionalData",
        "data": {
            "userId": 2077,
            "BTrustAppCallBackId": "",
            "isCorrespondenceAddressSame": true,
            "sourceOfFundId": "8",
            "residenceAddressZipCode": "1000",
            "correspondenceAddress": {
                "addressType": "C",
                "addressLine": "",
                "city": "",
                "stateProvinceCounty": "",
                "zipCode": "",
                "countryId": "BG"
            },
            "secondaryLanguage": "BUL",
            "taxResidences": "BG",
            "gender": "M",
            "accountPurposeCode": "1",
            "mainActivityCode": "1",
            "financingMethodCode": "2",
            "enrollIP": "203.0.113.24",
            "enrollLatitude": 42.6975,
            "enrollLongitude": 23.3241,
            "enrollChannel": "M"
        }
    }
}

Fields #

• id (integer, required, int32) — User identifier, range 1..2147483647.

• additionalData (object, required)

  • type (string, required) — Fixed contract marker, e.g. "EnrollAdditionalData".

  • data (object, required) — KYC/risk attributes:

    • userId (integer, required) — Mirrors id.

    • BTrustAppCallBackId (string) — From BTrust callback step.

    • isCorrespondenceAddressSame (boolean, required) — Whether correspondence = residence.

    • sourceOfFundId (string, required) — Code from the SoF selection.

    • residenceAddressZipCode (string) — Residence ZIP/postal code.

    • correspondenceAddress (object, required if isCorrespondenceAddressSame=false)

      • addressType (string) — e.g., "C" (correspondence).

      • addressLine, city, stateProvinceCounty, zipCode, countryId (strings).

    • secondaryLanguage (string) — Language code; from profile/KYC.

    • taxResidences (string, required) — Country code(s), e.g., "BG".

    • gender (string) — "M", "F", or policy-defined values.

    • accountPurposeCode (string, required) — Purpose of account.

    • mainActivityCode (string, required) — Customer main activity.

    • financingMethodCode (string, required) — Funding method.

    • enrollIP (string, required) — IP captured at enrollment.

    • enrollLatitude, enrollLongitude (number) — Geo coordinates captured during KYC.

    • enrollChannel (string, required) — "M" (mobile), "W" (web), etc.

✅ Important: some field above must be fetched from KYC flow endpoints prior to calling this API.

3) 📡 Responses #

✅ 3.1 Success — 200 OK #

The additional data was stored successfully.
Body: none (or minimal confirmation, depending on gateway configuration).

❌ 3.2 Server Error — 500 Internal Server Error #

Unexpected failure.
Body: usually empty (use logs/trace IDs from gateway).

4) 🛡 Validation Rules #

• id: required; integer 1..2147483647.

• additionalData.type: required; must match contract ("EnrollAdditionalData" or as defined by your spec).

• additionalData.data: required; object must include all mandatory KYC fields per policy.

• Correspondence address: required only if isCorrespondenceAddressSame=false.

• Codes & country fields: must use valid enumerations/ISO codes (e.g., ISO-3166 alpha-2 for countries).

• IP & geo: if collected, provide canonical formats (IPv4/IPv6 string; decimal lat/long).

🧯 Apply server-side throttling and audit logging. Do not accept partially-populated data if policy requires a complete KYC dataset.

5) 🔌 Data Sourcing — KYC Verification Process (Guidance) #

Implement the KYC flow first, cache/collect results, then submit them via this endpoint.

6) 💻 Examples #

6.1 cURL #

curl -X POST "https://api-test.10npay.com/User/add-additional-data" \ -H "Authorization: Bearer <YOUR_SECRET_TOKEN>" \ -H "Content-Type: application/json" \ -d @payload.json -i

6.2 C# (.NET) #

using System.Net.Http; using System.Net.Http.Headers; var http = new HttpClient(); var req = new HttpRequestMessage(HttpMethod.Post, "https://api-test.10npay.com/User/add-additional-data"); req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", "<YOUR_SECRET_TOKEN>"); req.Content = new StringContent(System.IO.File.ReadAllText("payload.json")); req.Content.Headers.ContentType = new MediaTypeHeaderValue("application/json"); using var res = await http.SendAsync(req); res.EnsureSuccessStatusCode(); // Expect 200 OK

6.3 JavaScript (fetch) #

const body = {/* build from KYC endpoints */}; await fetch("https://api-test.10npay.com/User/add-additional-data", { method: "POST", headers: { Authorization: "Bearer <YOUR_SECRET_TOKEN>", "Content-Type": "application/json" }, body: JSON.stringify(body) }); // Expect 200 OK

7) 🔄 Sequence #

1. Client → KYC endpoints: Collect questionnaire, addresses, device/IP, BTrust callback ID, etc.

2. Client → API Gateway: POST /User/add-additional-data (Bearer, JSON body) with the consolidated payload.

3. Gateway → Auth Service: Validate token.

4. Gateway → User Service: Persist additionalData.

5. Gateway → Client: 200 OK (or 500 on error).