Gnosis Pay User API

openapi: 3.2.0
info:
  title: Service User API
  version: 0.0.0
servers:
- url: https://core.prod.gnosispay.com/user-api
  description: Production
  variables: {}
- url: https://core.sandbox.gnosispay.in/user-api
  description: Sandbox
  variables: {}
tags:
- name: User
paths:
  /user:
    post:
      operationId: User_registerUser
      summary: Register User
      description: 'Register a new user and create a profile. You receive a new JWT access

        token with user id that you can use to authenticate requests to the API.

        Optionally provide a shareToken for Sumsub reusable KYC.


        If you require users to verify their email, include `otp` from POST

        /email-verification. Otherwise `otp` is ignored and the email is stored

        without proof of ownership.


        A wallet address may hold at most one user across all partners.


        Failure codes carried in `error`: `EMAIL_VERIFICATION_REQUIRED` /

        `INVALID_OTP` / `OTP_EXPIRED` (400), `USER_ALREADY_EXISTS` /

        `USER_REGISTRATION_IN_PROGRESS` (409), `PROFILE_CREATION_FAILED` (502),

        and `INTERNAL_ERROR` (500, returned on the shared error response).'
      parameters: []
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterUserSuccess'
        '400':
          description: 'Discriminated 400 body shared with the auth POST routes: `validation`

            (decoder / request constraints) or `business` (`EMAIL_VERIFICATION_REQUIRED`

            / `INVALID_OTP` / `OTP_EXPIRED`).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthBadRequest'
        '401':
          description: Access is unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '409':
          description: 'Conflict on registration. `error` is one of:

            - `USER_ALREADY_EXISTS` - the wallet address is already registered. A wallet

            may hold at most one user across all partners, so this is also returned

            when the address belongs to another partner. Terminal: do not retry.

            - `USER_REGISTRATION_IN_PROGRESS` - another in-flight request is registering this

            same wallet. Retryable: retrying once it settles either succeeds or

            returns `USER_ALREADY_EXISTS`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterUserConflict'
        '502':
          description: 'Upstream failure creating the KYC profile. `error` is

            `PROFILE_CREATION_FAILED`. The OTP is not consumed, so the request can be

            retried with the same code.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterUserBadGateway'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - User
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterUserRequest'
      security:
      - BearerAuth: []
      x-ogen-operation-group: User
    get:
      operationId: User_getUser
      summary: Get Current User
      description: Get the current authenticated user from the database
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetUserResponse'
        '401':
          description: Access is unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - User
      security:
      - BearerAuth: []
      x-ogen-operation-group: User
  /user/onboarding:
    get:
      operationId: User_getUserOnboarding
      summary: Get Onboarding Status
      description: 'Get the current onboarding status for the authenticated user. Returns a

        tagged union indicating the current step and any required actions.'
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingStatus'
        '401':
          description: Access is unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '502':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetUserOnboardingBadGateway'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - User
      security:
      - BearerAuth: []
      x-ogen-operation-group: User
components:
  schemas:
    UserKycProfileStatus:
      type: string
      enum:
      - pending
      - approved
      - blocked
      - rejected
      - requires_action
      - resubmission_requested
    OnboardingStatusActionCompleteSof:
      type: object
      required:
      - status
      - questions
      - version
      properties:
        status:
          type: string
          enum:
          - action_complete_sof
        questions:
          type: array
          items:
            $ref: '#/components/schemas/OnboardingSofQuestion'
        version:
          type: number
    OnboardingSofQuestion:
      type: object
      required:
      - id
      - question
      - answers
      properties:
        id:
          type: string
        question:
          type: string
        answers:
          type: array
          items:
            type: string
    OnboardingStatusWaitingAccountSetup:
      type: object
      required:
      - status
      properties:
        status:
          type: string
          enum:
          - waiting_account_setup
    GetUserResponse:
      type: object
      required:
      - id
      - address
      - email
      - profileId
      - accountId
      - cardholderId
      - partnerId
      - createdAt
      - kycProfile
      properties:
        id:
          type: string
        address:
          type: string
        email:
          type: string
        profileId:
          $ref: '#/components/schemas/uuid'
        accountId:
          anyOf:
          - $ref: '#/components/schemas/uuid'
          - type: 'null'
        cardholderId:
          anyOf:
          - $ref: '#/components/schemas/uuid'
          - type: 'null'
        partnerId:
          type: string
        createdAt:
          type: string
          format: date-time
        kycProfile:
          $ref: '#/components/schemas/UserKycProfile'
    OnboardingStatusActionAcceptTos:
      type: object
      required:
      - status
      - terms
      properties:
        status:
          type: string
          enum:
          - action_accept_tos
        terms:
          type: array
          items:
            $ref: '#/components/schemas/UserTermsStatus'
    RegisterUserRequest:
      type: object
      required:
      - email
      properties:
        email:
          type: string
          format: email
        otp:
          type: string
          description: 6-digit code from POST /email-verification. Required, and must be 6 characters, if you require email verification for your users. Ignored otherwise; the email is stored without proof of ownership.
        shareToken:
          type: string
          description: Optional Sumsub share token for reusable KYC
    UserKycAddress:
      type: object
      required:
      - id
      - country
      - postalCode
      - city
      - state
      - address1
      - address2
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        country:
          type: string
        postalCode:
          type: string
        city:
          type: string
        state:
          type: string
        address1:
          type: string
        address2:
          anyOf:
          - type: string
          - type: 'null'
    RegisterUserConflict:
      type: object
      required:
      - success
      - error
      properties:
        success:
          type: boolean
          enum:
          - false
        error:
          type: string
      description: 'Conflict on registration. `error` is one of:

        - `USER_ALREADY_EXISTS` - the wallet address is already registered. A wallet

        may hold at most one user across all partners, so this is also returned

        when the address belongs to another partner. Terminal: do not retry.

        - `USER_REGISTRATION_IN_PROGRESS` - another in-flight request is registering this

        same wallet. Retryable: retrying once it settles either succeeds or

        returns `USER_ALREADY_EXISTS`.'
    OnboardingStatusRejected:
      type: object
      required:
      - status
      - reason
      properties:
        status:
          type: string
          enum:
          - rejected
        reason:
          type: string
        rejectLabels:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
        comments:
          anyOf:
          - type: string
          - type: 'null'
    UserKycProfile:
      type: object
      required:
      - id
      - reference
      - email
      - status
      - tenantId
      - details
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        reference:
          type: string
        email:
          type: string
        status:
          $ref: '#/components/schemas/UserKycProfileStatus'
        tenantId:
          type: string
        details:
          anyOf:
          - $ref: '#/components/schemas/UserKycProfileDetails'
          - type: 'null'
    Unauthorized:
      type: object
      required:
      - success
      - error
      properties:
        success:
          type: boolean
          enum:
          - false
        error:
          type: string
    OnboardingStatusWaitingKycSetup:
      type: object
      required:
      - status
      properties:
        status:
          type: string
          enum:
          - waiting_kyc_setup
    OnboardingStatusActionVerifyPhone:
      type: object
      required:
      - status
      properties:
        status:
          type: string
          enum:
          - action_verify_phone
    ValidationErrorDetail:
      type: object
      required:
      - name
      - message
      properties:
        name:
          type: string
          enum:
          - ValidationError
        message:
          type: string
    GetUserOnboardingBadGateway:
      type: object
      required:
      - success
      - error
      properties:
        success:
          type: boolean
          enum:
          - false
        error:
          type: string
    Error:
      type: object
      required:
      - success
      - error
      properties:
        success:
          type: boolean
          enum:
          - false
        error:
          type: string
    uuid:
      type: string
      format: uuid
    RegisterUserBadGateway:
      type: object
      required:
      - success
      - error
      properties:
        success:
          type: boolean
          enum:
          - false
        error:
          type: string
      description: 'Upstream failure creating the KYC profile. `error` is

        `PROFILE_CREATION_FAILED`. The OTP is not consumed, so the request can be

        retried with the same code.'
    OnboardingStatus:
      type: object
      oneOf:
      - $ref: '#/components/schemas/OnboardingStatusActionAcceptTos'
      - $ref: '#/components/schemas/OnboardingStatusWaitingKycSetup'
      - $ref: '#/components/schemas/OnboardingStatusActionCompleteKyc'
      - $ref: '#/components/schemas/OnboardingStatusKycManualReview'
      - $ref: '#/components/schemas/OnboardingStatusActionKycResubmissionRequested'
      - $ref: '#/components/schemas/OnboardingStatusActionCompleteSof'
      - $ref: '#/components/schemas/OnboardingStatusActionCreateAccount'
      - $ref: '#/components/schemas/OnboardingStatusWaitingAccountSetup'
      - $ref: '#/components/schemas/OnboardingStatusActionVerifyPhone'
      - $ref: '#/components/schemas/OnboardingStatusRejected'
      - $ref: '#/components/schemas/OnboardingStatusCompleted'
      discriminator:
        propertyName: status
        mapping:
          action_accept_tos: '#/components/schemas/OnboardingStatusActionAcceptTos'
          waiting_kyc_setup: '#/components/schemas/OnboardingStatusWaitingKycSetup'
          action_complete_kyc: '#/components/schemas/OnboardingStatusActionCompleteKyc'
          kyc_manual_review: '#/components/schemas/OnboardingStatusKycManualReview'
          action_kyc_resubmission_requested: '#/components/schemas/OnboardingStatusActionKycResubmissionRequested'
          action_complete_sof: '#/components/schemas/OnboardingStatusActionCompleteSof'
          action_create_account: '#/components/schemas/OnboardingStatusActionCreateAccount'
          waiting_account_setup: '#/components/schemas/OnboardingStatusWaitingAccountSetup'
          action_verify_phone: '#/components/schemas/OnboardingStatusActionVerifyPhone'
          rejected: '#/components/schemas/OnboardingStatusRejected'
          completed: '#/components/schemas/OnboardingStatusCompleted'
      description: Onboarding status tagged union (discriminated by `status`).
    OnboardingStatusActionKycResubmissionRequested:
      type: object
      required:
      - status
      - webSdkUrl
      - mobileSdkToken
      - comments
      properties:
        status:
          type: string
          enum:
          - action_kyc_resubmission_requested
        webSdkUrl:
          type: string
        mobileSdkToken:
          type: string
        comments:
          anyOf:
          - type: string
          - type: 'null'
    OnboardingStatusCompleted:
      type: object
      required:
      - status
      properties:
        status:
          type: string
          enum:
          - completed
    AuthBusinessError:
      type: object
      required:
      - kind
      - success
      - error
      properties:
        kind:
          type: string
          enum:
          - business
        success:
          type: boolean
          enum:
          - false
        error:
          type: string
      description: Domain/business failure on auth routes (returned by handlers).
    OnboardingStatusActionCompleteKyc:
      type: object
      required:
      - status
      - webSdkUrl
      - mobileSdkToken
      properties:
        status:
          type: string
          enum:
          - action_complete_kyc
        webSdkUrl:
          type: string
        mobileSdkToken:
          type: string
    AuthValidationError:
      type: object
      required:
      - kind
      - success
      - error
      properties:
        kind:
          type: string
          enum:
          - validation
        success:
          type: boolean
          enum:
          - false
        error:
          $ref: '#/components/schemas/ValidationErrorDetail'
      description: Validation failure on auth routes (decoder / request constraints).
    OnboardingStatusActionCreateAccount:
      type: object
      required:
      - status
      properties:
        status:
          type: string
          enum:
          - action_create_account
    NotFound:
      type: object
      required:
      - success
      - error
      properties:
        success:
          type: boolean
          enum:
          - false
        error:
          type: string
    AuthBadRequest:
      type: object
      oneOf:
      - $ref: '#/components/schemas/AuthValidationError'
      - $ref: '#/components/schemas/AuthBusinessError'
      discriminator:
        propertyName: kind
        mapping:
          validation: '#/components/schemas/AuthValidationError'
          business: '#/components/schemas/AuthBusinessError'
      description: 'Discriminated 400 body for auth POST routes. The `kind` field is additive

        and not a breaking change. Clients can keep reading `success` and `error`.'
    UserKycProfileDetails:
      type: object
      required:
      - fullName
      - phoneNumber
      - dateOfBirth
      - nationality
      - countryOfResidence
      - countryOfBirth
      - taxIdNumber
      - gender
      - addresses
      properties:
        fullName:
          type: string
        phoneNumber:
          type: string
        dateOfBirth:
          type: string
          format: date-time
        nationality:
          type: string
        countryOfResidence:
          type: string
        countryOfBirth:
          type: string
        taxIdNumber:
          type: string
        gender:
          type: string
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/UserKycAddress'
    RegisterUserSuccess:
      type: object
      required:
      - userId
      - accessToken
      properties:
        userId:
          type: string
        accessToken:
          type: string
    OnboardingStatusKycManualReview:
      type: object
      required:
      - status
      - comments
      properties:
        status:
          type: string
          enum:
          - kyc_manual_review
        comments:
          anyOf:
          - type: string
          - type: 'null'
    UserTermsStatus:
      type: object
      required:
      - type
      - currentVersion
      - name
      - url
      - accepted
      - acceptedVersion
      - acceptedAt
      properties:
        type:
          type: string
        currentVersion:
          type: string
        name:
          type: string
        url:
          anyOf:
          - type: string
          - type: 'null'
        accepted:
          type: boolean
        acceptedVersion:
          anyOf:
          - type: string
          - type: 'null'
        acceptedAt:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: Bearer