Skip to content

Profile Completion & Role Activation

When should I use this?

  • Run immediately after the user authenticates via wallet signature (nonce login) and before granting access to any agreement workflow.
  • Use for every wallet-authenticated user whenever you must capture legal/business details (name, address, arbitrator info) to participate in PAYCIFI agreements.

Purpose

Attach off-chain identity (email, name, business metadata) to the wallet that was already authenticated so PAYCIFI can route invitations, identify participants, and register arbitrators. Wallet authentication may have already created a user record implicitly; POST /users/register completes or updates the authenticated user profile by attaching identity and business metadata to the wallet already verified during authentication. Email captured here is required for agreement invitations, notifications, and participant identification—not for authentication.

Preconditions

  • Client session already carries valid tokens from the completed wallet signature authentication flow.
  • Wallet ownership has been verified and the wallet address is available from the token; this endpoint does not create or provision wallets.
  • Client has collected required identity fields (firstname, lastname, email) plus any optional business metadata.

Client Responsibilities

  • MUST include the Authorization header with the current accessToken.
  • MUST normalize emails to lowercase before sending them to the API.
  • SHOULD validate arbitrator-specific requirements (e.g., website) before submitting.
  • SHOULD set accountType to arbitrator only when the user meets the extra data requirements listed below.

API Flow

  1. (Optional but recommended) Verify email availability via GET /auth/check-email-available/:email. Abort if available: false.
  2. Submit user data to POST /users/register (requires Authorization header). Payload must include firstname, lastname, normalized email, phone/address fields as collected, and accountType. Arbitrators must also provide website.
  3. Backend completes or updates the authenticated user profile, ensures wallet linkage, registers arbitrators when requested, and sends a welcome email.
  4. Backend returns the inserted user payload (and wallet metadata if applicable).

Arbitrator requirements

  • Set accountType to arbitrator.
  • Provide website (mandatory) and phone if available.
  • Include additionalInfo with context that will be shown to agreement participants.

Example request (POST /users/register)

POST /users/register
Authorization: Bearer <accessToken>
Content-Type: application/json

{
  "firstname": "Paula",
  "lastname": "Integrator",
  "email": "ops@partner.com",
  "phone": "+32470001122",
  "country": "BE",
  "region": "Brussels",
  "city": "Brussels",
  "address1": "123 Rue Royale",
  "postalCode": "1000",
  "accountType": "arbitrator",
  "website": "https://arbitrators.paycifi.com"
}

Example response

{
  "userId": "f3f4d6f2-8f1e-4a08-9b90-2ec2d0b6f001",
  "firstname": "Paula",
  "lastname": "Integrator",
  "email": "ops@partner.com",
  "accountType": "standard",
  "walletAddress": "0x1234...abcd",
  "additionalInfo": null
}

Response Handling

  • On success, client should refresh local profile cache (e.g., store firstname/lastname/email/accountType from response or follow-up /auth/me).
  • On failure, inspect errorCode to decide whether to prompt for corrections (e.g., duplicate email, missing website for arbitrators) or show a generic error.

Role activation & routing

  • The accountType field returned by /users/register dictates post-login routing:
  • arbitrator accounts should be redirected to arbitrator dashboards / agreement-review flows.
  • All other accounts should be routed to the standard agreement workspace.
  • Persist this value so subsequent logins can immediately direct users to the correct feature set.

Error Codes

  • wrong-user-id – Authorization missing or userId absent from token.
  • missing-data – firstname, lastname, email, or walletAddress not supplied.
  • email-already-exists – result from /auth/check-email-available.
  • user-insert-error – database failure while inserting user profile.
  • wallet-insert-error – internal data inconsistency while ensuring wallet linkage (not expected in normal use).
  • register-arbitrator-error – arbitrator-specific persistence failure.
  • registration-tx-error – generic transaction failure (rolled back).
  • GET /auth/check-email-available/:email
  • POST /users/register