👥 Enrollment — Initiate External Identification API #

Gateway Path: /Enrollment/initiate-external-identification
Service: Customer Relationship Management (CRM)
Method: POST
Auth: Bearer token in Authorization header

1) 📖 Overview & Purpose #

Starts an external KYC identity verification session with Borica.
On success, the API returns a URL that, once opened by the user (browser/webview), launches Borica’s flow: ID scan → liveness/selfie → cloud QES signing of Borica’s documents.

✅ Redirects after completion: After signing and pressing Continue in Borica’s UI, Borica redirects the user back to your application:

• Success Redirect URL — used when the identification completes successfully.

• Fail Redirect URL — used when the process fails or is aborted.
  Both URLs are configured in the Merchant Portal (per tenant/project) and are not passed in this API request.

2) 🔗 Endpoint Definition #

HTTP: POST /Enrollment/initiate-external-identification

Headers #

• Authorization: Bearer <token> — valid access token

• Content-Type: application/json

Request Body (example) #

Fields #

• userId (integer, required, int32) — User identifier. Range: 1..2147483647.

• isRestartIdentification (boolean, optional, default: false) — Force a fresh session if one exists.

• localTimezone (string | null, optional) — IANA TZ, e.g., Europe/Sofia.

• userAgent (string | null, optional) — Client UA (for diagnostics).

• browserLanguage (string | null, optional) — e.g., bg, en-US.

• userLanguage (string | null, optional) — Preferred UI language.

• deviceName (string | null, optional) — Friendly device label.

• correlationType (integer, optional, enum: 0, 1) — Correlation flag for CRM tracking.

ℹ️ Redirect URLs are configured in the Merchant Portal and associated with the merchant/app; the CRM passes them to Borica when creating the session. They are not included in this request body.

3) 📡 Responses #

✅ 3.1 Success — 200 OK #

{
    "videoIdentificationUrl": "https://iduat.borica.bg/session/ea05298a-28fd-4dbe-9d05-fe294d08acda",
    "videoIdentificationStatus": "STARTED",
    "message": ""
}

• videoIdentificationUrl (string) — Open to begin Borica’s identification flow.

• videoIdentificationStatus (string) — Typically STARTED.

• message (string) — Optional informational text.

❌ 3.2 Server Error — 500 Internal Server Error #

Unexpected failure. Body usually empty (inspect logs/trace).

4) 🔁 Redirect Handling (VERY IMPORTANT) #

• After the user signs with cloud QES and clicks Continue, Borica redirects:

  • to your Success Redirect URL on successful identification;

  • to your Fail Redirect URL if the flow fails, times out, or the user aborts.

• These URLs are pre-configured in the Merchant Portal (per merchant/app).

• Your frontend should:

  • Trust only whitelisted domains you control;

  • Show a clear success/failure state to the user;

  • Optionally trigger a status check (if your system exposes a status endpoint) to confirm final state before proceeding.

🔒 Security tip: enforce strict allowlists for redirect domains and avoid reflecting arbitrary query parameters.

5) 🛡 Validation Rules #

• userId: required; integer 1..2147483647.

• correlationType: if provided, must be 0 or 1.

• localTimezone: valid IANA TZ if provided.

• Languages: ISO tags recommended (bg, en, bg-BG).

• Restart logic: isRestartIdentification=true may supersede incomplete sessions.

6) 💻 Examples #

6.1 cURL #

curl -X POST "https://api-test.10npay.com/Enrollment/initiate-external-identification" \
-H "Authorization: Bearer <YOUR_SECRET_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"userId": 2077,
"isRestartIdentification": false,
"localTimezone": "Europe/Sofia",
"userAgent": "Chrome/139.0",
"browserLanguage": "bg",
"userLanguage": "bg",
"deviceName": "MacBook Pro",
"correlationType": 0
}' -i

using System.Net.Http;
using System.Net.Http.Headers;

var http = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Post,
"https://api-test.10npay.com/Enrollment/initiate-external-identification");

req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", "<YOUR_SECRET_TOKEN>");
req.Content = new StringContent(@"{
""userId"": 2077,
""isRestartIdentification"": false,
""localTimezone"": ""Europe/Sofia"",
""userAgent"": ""Chrome/139.0"",
""browserLanguage"": ""bg"",
""userLanguage"": ""bg"",
""deviceName"": ""MacBook Pro"",
""correlationType"": 0
}");
req.Content.Headers.ContentType = new MediaTypeHeaderValue("application/json");

using var res = await http.SendAsync(req);
res.EnsureSuccessStatusCode(); // 200 OK

6.3 JavaScript (fetch) #

await fetch("https://api-test.10npay.com/Enrollment/initiate-external-identification", {
method: "POST",
headers: {
Authorization: "Bearer <YOUR_SECRET_TOKEN>",
"Content-Type": "application/json"
},
body: JSON.stringify({
userId: 2077,
isRestartIdentification: false,
localTimezone: "Europe/Sofia",
userAgent: "Chrome/139.0",
browserLanguage: "bg",
userLanguage: "bg",
deviceName: "MacBook Pro",
correlationType: 0
})
}); // Expect 200 OK with videoIdentificationUrl

7) 🔄 Sequence (with Redirects) #

1. Client → API Gateway: POST /Enrollment/initiate-external-identification (Bearer, JSON)

2. Gateway → CRM/Orchestrator: Create Borica session (includes merchant-configured Success/Fail redirect URLs)

3. Gateway → Client: 200 OK with videoIdentificationUrl

4. Client: Open videoIdentificationUrl (web/webview)

5. Borica Flow: ID scan → liveness → cloud QES signing

6. Borica → App: Redirect user to Success or Fail URL (from Merchant Portal)

7. App: Render final state and, if applicable, confirm status / continue KYC