> ## Documentation Index
> Fetch the complete documentation index at: https://gnosispay-feat-v2-auth-module.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboard to Gnosis Pay V2

> User onboarding using Gnosis Pay V2

This documentation provides a step-by-step guide on how to test the user onboarding experience for Gnosis Pay V2 in a sandbox environment.

## 1. Authentication

<Steps>
  <Step title="Get access token">
    To get access token, please go through the [authentication guide here](/v2/v2-siwe-auth#authentication-flow-2).
  </Step>
</Steps>

## 2. User Registration

<Steps titleSize="h3">
  <Step title="Sign up with email ">
    Send an email verification request to [`POST /email-verification`](/api-reference/auth/request-email-verification) with a One-Time Password (OTP) to the user's email address.

    <Tabs>
      <Tab title="Sandbox">
        ```bash cURL theme={null}
        curl --request POST \
          --url https://gp-auth-module.sandbox.gnosispay.in/email-verification \
          --header 'Content-Type: application/json' \
          --data '{
          "email": "jsmith@example.com"
        }'
        ```
      </Tab>

      <Tab title="Production">
        ```bash cURL theme={null}
        curl --request POST \
          --url https://gp-auth-module.prod.gnosispay.com/email-verification \
          --header 'Content-Type: application/json' \
          --data '{
          "email": "jsmith@example.com"
        }'
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Register user">
    Register a new user with email OTP and create a user profile. POST [`/user`](/api-reference/user/register-user) endpoint returns a new access token with userID that must be used as the bearer token for all subsequent API requests - otherwise the calls will fail.

    Optionally, provide a shareToken for Sumsub reusable KYC.

    <Note>
      If the access token lacks a `userID`, it indicates that user registration failed because the email was never properly submitted.
    </Note>

    <Tabs>
      <Tab title="Sandbox">
        ```bash cURL theme={null}
        curl --request POST \
          --url https://gp-auth-module.sandbox.gnosispay.in/user \
          --header 'Content-Type: application/json' \
          --data '{
          "email": "jsmith@example.com",
          "otp": "<string>",
          "shareToken": "<string>"
        }'
        ```
      </Tab>

      <Tab title="Production">
        ```bash cURL theme={null}
        curl --request POST \
          --url https://gp-auth-module.prod.gnosispay.com/user \
          --header 'Content-Type: application/json' \
          --data '{
          "email": "jsmith@example.com",
          "otp": "<string>",
          "shareToken": "<string>"
        }'
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Get onboarding status of user">
    After user registration, use the access token to retrieve the user's current onboarding status.[`GET /user/onboarding`](/api-reference/user/get-onboarding-status) will indicate the next required step in the onboarding process.

    #### User Onboarding States

    The onboarding status values to indicate the current step and required user actions:

    | Status                              | Description                                                                                             | User Action Required                                                                                           |
    | ----------------------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
    | `action_accept_tos`                 | Terms of Service acceptance required - user registered but hasn't accepted required terms               | Review and accept Terms of Service                                                                             |
    | `waiting_kyc_setup`                 | KYC initialization in progress - all terms accepted, KYC process being set up                           | Wait for KYC setup completion                                                                                  |
    | `action_complete_kyc`               | KYC verification pending - KYC check created but pending user completion                                | Complete KYC verification via Sumsub `webSdkUrl`                                                               |
    | `kyc_manual_review`                 | KYC provider flagged the check as requiring manual review                                               | This is a non-recoverable state from the user's side, requires internal review for updating application status |
    | `action_kyc_resubmission_requested` | KYC provider has requested the user resubmit their KYC documents — a new Sumsub session URL is provided | Re-complete KYC verification via Sumsub using the provided `webSdkUrl`                                         |
    | `action_complete_sof`               | Source of Funds questionnaire required - KYC approved, SOF answers needed                               | Answer Source of Funds questionnaire                                                                           |
    | `action_create_account`             | Ready for account creation - KYC approved and SOF completed                                             | Proceed with account creation                                                                                  |
    | `waiting_account_setup`             | Account provisioning in progress - account is being set up in the system                                | Wait for account setup completion                                                                              |
    | `completed`                         | Onboarding complete - account is active with cardholder ID                                              | Start using the platform                                                                                       |
    | `rejected`                          | Onboarding rejected - account is blocked, closed, or KYC verification failed                            | Contact support or retry if applicable                                                                         |

    <Tabs>
      <Tab title="Sandbox">
        ```bash cURL theme={null}
        curl --request GET \
          --url https://gp-auth-module.sandbox.gnosispay.in/user/onboarding
        ```
      </Tab>

      <Tab title="Production">
        ```bash cURL theme={null}
        curl --request GET \
          --url https://gp-auth-module.prod.gnosispay.com/user/onboarding
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Accept Terms of Service (ToS)">
    At this point, the user is registered in the Gnosis Pay system and has an associated `userID`. Call the endpoint [`GET /user/onboarding`](/api-reference/user/get-onboarding-status). The response from JSON will be following returned with status of `action_accept_tos`.

    ```json theme={null}
    {
      "status": "action_accept_tos",
      "terms": [
        {
          "type": "string",
          "currentVersion": "string",
          "name": "string",
          "url": null,
          "accepted": true,
          "acceptedVersion": null,
          "acceptedAt": null
        }
      ]
    }
    ```

    <Note>
      UX tip: Handle ToS acceptance within the email registration flow to avoid introducing an additional screen in the onboarding process. In the same screen, render the Terms (or link to them) and include a mandatory “I agree to the Terms of Service” checkbox. Disable form submission until the checkbox is selected. After successful registration and token issuance, automatically trigger the SoF acceptance call with the new token.
    </Note>

    #### Request Terms of Service

    Fetch the current `Terms of Service` that users must agree to before continuing with the onboarding process via the endpoint [`GET /terms`](/api-reference/terms/list-available-terms).

    <Tabs>
      <Tab title="Sandbox">
        ```bash cURL theme={null}
        curl --request GET \
          --url https://gp-auth-module.sandbox.gnosispay.in/terms
        ```
      </Tab>

      <Tab title="Production">
        ```bash cURL theme={null}
        curl --request GET \
          --url https://gp-auth-module.prod.gnosispay.com/terms
        ```
      </Tab>
    </Tabs>

    Submit the accepted Terms of Service via the [`POST /user/terms`](/api-reference/terms/accept-terms) endpoint.

    <Tabs>
      <Tab title="Sandbox">
        ```bash cURL theme={null}
        curl --request POST \
          --url https://gp-auth-module.sandbox.gnosispay.in/user/terms \
          --header 'Content-Type: application/json' \
          --data '{
          "terms": [
            {
              "type": "<string>",
              "version": "<string>"
            }
          ]
        }'
        ```
      </Tab>

      <Tab title="Production">
        ```bash cURL theme={null}
        curl --request POST \
          --url https://gp-auth-module.prod.gnosispay.com/user/terms \
          --header 'Content-Type: application/json' \
          --data '{
          "terms": [
            {
              "type": "<string>",
              "version": "<string>"
            }
          ]
        }'
        ```
      </Tab>
    </Tabs>

    You can check the status of the user's acceptance of the Terms of Service via the [`GET /user/terms`](api-reference/terms/get-user-terms-status) endpoint.

    <Tabs>
      <Tab title="Sandbox">
        ```bash cURL theme={null}
        curl --request GET \
          --url https://gp-auth-module.sandbox.gnosispay.in/user/terms

        ```
      </Tab>

      <Tab title="Production">
        ```bash cURL theme={null}
        curl --request GET \
          --url https://gp-auth-module.prod.gnosispay.com/user/terms

        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

## 3. KYC Process

<Steps>
  <Step title="Get onboarding status">
    Call the [`GET /user/onboarding`](/api-reference/user/get-onboarding-status) API to retrieve the current status of the user's onboarding process. If the status is `action_complete_kyc`, you can proceed with the KYC process. The response will include the status and a `webSdkURL` for completing KYC verification.

    ```json theme={null}
    {
        "status": "action_complete_kyc",
        "webSdkUrl": "https://in.sumsub.com/websdk/p/sbx_yeuhsxyuhkio"
    }
    ```
  </Step>

  <Step title="Complete KYC">
    <Tabs>
      <Tab title="Sandbox">
        Access the Sumsub URL provided in the response to begin the KYC verification process. In the sandbox environment, you can use Sumsub's predefined templates for testing purposes.

        <Note>
          As you are in the sandbox environment, you can use fake documents or use one provided by Sumsub.
        </Note>

        To complete the verification process:

        1. Open an iframe with the provided `webSdkUrl`
        2. Use the [verification document templates](https://docs.sumsub.com/docs/verification-document-templates) for Proof of Identity (POI) and Proof of Address (POA)
        3. Complete the liveness check as prompted
      </Tab>

      <Tab title="Production">
        Access the Sumsub URL provided in the response to begin the KYC verification process.

        To complete the verification process:

        1. Open an iframe with the provided `webSdkUrl`
        2. Upload valid Proof of Identity (POI) and Proof of Address (POA) documents
        3. Complete the liveness check as prompted
      </Tab>
    </Tabs>
  </Step>

  <Step title="Handle KYC resubmission request">
    If [`GET /user/onboarding`](/api-reference/user/get-onboarding-status) returns `action_kyc_resubmission_requested`, the KYC provider has reviewed the submission and is requesting the user resubmit their documents. The response shape is identical to `action_complete_kyc` and includes a fresh `webSdkUrl`:

    ```json theme={null}
    {
        "status": "action_kyc_resubmission_requested",
        "webSdkUrl": "https://in.sumsub.com/websdk/p/sbx_yeuhsxyuhkio"
    }
    ```

    Open the Sumsub iframe again with the provided `webSdkUrl` and have the user resubmit their documents, following the same steps as the initial KYC completion.
  </Step>

  <Step title="Handle KYC manual review (contact support)">
    If [`GET /user/onboarding`](/api-reference/user/get-onboarding-status) returns `kyc_manual_review`, the KYC provider has flagged the check for manual review. This is a non-recoverable state from the user's side — no `webSdkUrl` is provided and the user cannot self-resolve it.

    ```json theme={null}
    {
        "status": "kyc_manual_review"
    }
    ```

    <Warning>
      Display a clear message directing the user to contact the customer support. No further onboarding actions are available until the manual review is resolved.
    </Warning>
  </Step>

  <Step title="Complete SOF">
    After completing the KYC process, the next steps is to proceed to the Source of Funds (SOF) verification step. Call the [`GET /user/onboarding`](/api-reference/user/get-onboarding-status), which will return the next required action to complete SOF verification along with the questions that need to be answered. Alternatively, retrieve the SOF questions directly using the [`GET /
            source-of-funds`](/api-reference/source-of-funds/get-sof-questions) endpoint.

    <Tabs>
      <Tab title="Sandbox">
        ```bash cURL theme={null}
        curl --request GET \
          --url https://gp-auth-module.sandbox.gnosispay.in/source-of-funds
        ```
      </Tab>

      <Tab title="Production">
        ```bash cURL theme={null}
        curl --request GET \
          --url https://gp-auth-module.prod.gnosispay.com/source-of-funds
        ```
      </Tab>
    </Tabs>

    Once all SOF questions have been reviewed and answered by user, submit the responses through the [`POST /source-of-funds`](/api-reference/source-of-funds/submit-sof-answers) endpoint to complete this step of the onboarding process.

    <Tabs>
      <Tab title="Sandbox">
        ```bash cURL theme={null}
        curl --request POST \
          --url https://gp-auth-module.sandbox.gnosispay.in/source-of-funds \
          --header 'Content-Type: application/json' \
          --data '{
          "answers": [
            {
              "question": "<string>",
              "answer": "<string>"
            }
          ]
        }'
        ```
      </Tab>

      <Tab title="Production">
        ```bash cURL theme={null}
        curl --request POST \
          --url https://gp-auth-module.prod.gnosispay.com/source-of-funds \
          --header 'Content-Type: application/json' \
          --data '{
          "answers": [
            {
              "question": "<string>",
              "answer": "<string>"
            }
          ]
        }'
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

## 4. Account Setup

<Steps>
  <Step title="Check onboarding status">
    Check the user's onboarding status using the [`GET /user/onboarding`](/api-reference/user/get-onboarding-status) endpoint to determine if their KYC verification has been accepted. If the KYC is approved, the user status will transition to the following:

    ```json theme={null}
    {
        "status": "action_create_account"
    }
    ```

    In next step, we will create GP spending safe wallet address.
  </Step>

  <Step title="Create GP Account">
    In this step, you will initiate the Gnosis Pay account provisioning and creation process. Call [`POST /user/account`](/api-reference/user/create-account) endpoint to create an account for the authenticated user.

    <Tabs>
      <Tab title="Sandbox">
        ```bash cURL theme={null}
        curl --request POST \
          --url https://gp-auth-module.sandbox.gnosispay.in/user/account \
          --header 'Content-Type: application/json' \
          --data '{
          "celoConfig": {
            "dailyLimits": {
              "usdt": 1,
              "usdc": 1
            }
          }
        }'
        ```
      </Tab>

      <Tab title="Production">
        ```bash cURL theme={null}
        curl --request POST \
          --url https://gp-auth-module.prod.gnosispay.com/user/account \
          --header 'Content-Type: application/json' \
          --data '{
          "celoConfig": {
            "dailyLimits": {
              "usdt": 1,
              "usdc": 1
            }
          }
        }'
        ```
      </Tab>
    </Tabs>

    Once the account provisioning begins, the onboarding status will be updated to `waiting_account_setup` state, indicating that the account is being set up in the system.

    ```json theme={null}
    {
        "status": "waiting_account_setup"
    }
    ```
  </Step>

  <Step title="Retrieve Authenticated User">
    Call the [`GET /user`](/api-reference/user/get-current-user) endpoint to retrieve the full user profile, including their GP spending wallet address.

    <Tabs>
      <Tab title="Sandbox">
        ```bash cURL theme={null}
        curl --request GET \
          --url https://gp-auth-module.sandbox.gnosispay.in/user \
          --header 'Content-Type: application/json'
        ```
      </Tab>

      <Tab title="Production">
        ```bash cURL theme={null}
        curl --request GET \
          --url https://gp-auth-module.prod.gnosispay.com/user \
          --header 'Content-Type: application/json'
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>