User Registration API #

Gateway Path: /User
Service: Authentication & Authorization
Method: POST
Auth: Bearer token in Authorization header (see Security)

1) Overview & Purpose #

The onboarding flow begins by creating a minimal but persistent record for a customer (a “User record”). This record becomes the foundation for subsequent steps such as KYC, address collection, payment method linking, and AML checks. The /User endpoint creates this initial record and returns a unique id that is used in all future services and flows.

Goals:

• Provide a consistent starting point for each customer profile.
• Require only minimal information at the beginning to avoid blocking UX.
• Allow extensibility with additionalData so metadata can be added incrementally without breaking changes.

2) Endpoint Definition #

HTTP: POST /User

Headers

• Authorization: Bearer <token> — valid access token.
• Content-Type: application/json

Request Body Example

{
"merchantId": 9101,
"email": "client.name@example.org"
}

Fields #

• merchantId (integer, required) — Identifier of the merchant initiating the request.
• email (string | null, required) — Customer email address. Can be null at creation time. Must not be an empty string and must be valid when provided.
• additionalData (object, optional) — Extensible container for metadata.
  • type (string | null) — Free label, e.g. onboarding, migration, import.
  • data (object | null) — Custom key/value metadata.

3) Responses #

3.1 Success — 201 Created #

{
"id": 2072
}

• id (int32) — Unique identifier assigned to the user.

3.2 Validation Errors — 400 Bad Request #

Invalid email format:

{
"errors": {
"Email": [
"Invalid email address"
]
},
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"traceId": "00-515d7188d11bc727bd3a370ee0cd1616-2be049b580ab15d0-00"
}

Empty string as email:

{
"errors": {
"Email": [
"The Email field is required.",
"Email address is required"
]
},
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"traceId": "00-fcbcb78b23ec3326237f26ce00531c90-4b3cd8492df8c02d-00"
}

3.3 Server Errors — 5xx Server Error #

Returned for unexpected failures or downtime.

4) Validation Rules #

• merchantId: Required, integer.
• email: Required. Either null or a valid RFC-compliant address. Must not be an empty string.
• additionalData: Must be a JSON object. Recommended keys: type (string|null), data (object|null).

5) Idempotency & Retries #

• Each valid call creates a new user record.
• To avoid duplicates during retries, include a client-generated requestId inside additionalData.data and handle deduplication client-side.

6) Security #

• Bearer token is mandatory: Authorization: Bearer <token>.
• HTTPS only.
• Do not log tokens in plaintext; mask sensitive data in diagnostics.

7) Examples #

7.1 cURL #

curl -X POST "https://api-test.10npay.com/User" \
-H "Authorization: Bearer <YOUR_SECRET_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"merchantId": 9101,
"email": "client.name@example.org"
}'

7.2 C# (.NET) #

using System.Net.Http.Headers;
var client = new HttpClient();
var request = new HttpRequestMessage
{
Method = HttpMethod.Post,
RequestUri = new Uri("https://api-test.10npay.com/User"),
Headers = { { "Authorization", "Bearer <YOUR_SECRET_TOKEN>" } },
Content = new StringContent(
"{\n \"merchantId\": 9101,\n \"email\": \"client.name@example.org\"\n}"
) { Headers = { ContentType = new MediaTypeHeaderValue("application/json") } }
};
using var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);

7.3 JavaScript (fetch) #

await fetch("https://api-test.10npay.com/User", {
method: "POST",
headers: {
"Authorization": "Bearer <YOUR_SECRET_TOKEN>",
"Content-Type": "application/json"
},
body: JSON.stringify({
merchantId: 9101,
email: "client.name@example.org"
})
});

8) Sequence #

Client → API Gateway: POST /User (Bearer, body)
API Gateway → Auth Service: Validate token
Auth Service → API Gateway: OK
API Gateway → User DB: Create user record
User DB → API Gateway: userId
API Gateway → Client: 201 { id }