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

1. Get access token

   To get access token, please go through the authentication guide here.

2. User Registration

1. Sign up with email

   Send an email verification request to POST /email-verification with a One-Time Password (OTP) to the user’s email address.

   Sandbox

   cURL

   curl --request POST \
     --url https://gp-auth-module.sandbox.gnosispay.in/email-verification \
     --header 'Content-Type: application/json' \
     --data '{
     "email": "[e-mail]"
   }'
   

   Production

   cURL

   curl --request POST \
     --url https://gp-auth-module.prod.gnosispay.com/email-verification \
     --header 'Content-Type: application/json' \
     --data '{
     "email": "[e-mail]"
   }'
   
2. Register user

   Register a new user with email OTP and create a user profile. POST /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.

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

   Sandbox

   cURL

   curl --request POST \
     --url https://gp-auth-module.sandbox.gnosispay.in/user \
     --header 'Content-Type: application/json' \
     --data '{
     "email": "[e-mail]",
     "otp": "<string>",
     "shareToken": "<string>"
   }'
   

   Production

   cURL

   curl --request POST \
     --url https://gp-auth-module.prod.gnosispay.com/user \
     --header 'Content-Type: application/json' \
     --data '{
     "email": "[e-mail]",
     "otp": "<string>",
     "shareToken": "<string>"
   }'
   
3. Get onboarding status of user

   After user registration, use the access token to retrieve the user’s current onboarding status.GET /user/onboarding 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

   Sandbox

   cURL

   curl --request GET \
     --url https://gp-auth-module.sandbox.gnosispay.in/user/onboarding
   

   Production

   cURL

   curl --request GET \
     --url https://gp-auth-module.prod.gnosispay.com/user/onboarding
   
4. 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. The response from JSON will be following returned with status of action_accept_tos.

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

   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.

   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.

   Sandbox

   cURL

   curl --request GET \
     --url https://gp-auth-module.sandbox.gnosispay.in/terms
   

   Production

   cURL

   curl --request GET \
     --url https://gp-auth-module.prod.gnosispay.com/terms
   

   Submit the accepted Terms of Service via the POST /user/terms endpoint.

   Sandbox

   cURL

   curl --request POST \
     --url https://gp-auth-module.sandbox.gnosispay.in/user/terms \
     --header 'Content-Type: application/json' \
     --data '{
     "terms": [
       {
         "type": "<string>",
         "version": "<string>"
       }
     ]
   }'
   

   Production

   cURL

   curl --request POST \
     --url https://gp-auth-module.prod.gnosispay.com/user/terms \
     --header 'Content-Type: application/json' \
     --data '{
     "terms": [
       {
         "type": "<string>",
         "version": "<string>"
       }
     ]
   }'
   

   You can check the status of the user’s acceptance of the Terms of Service via the GET /user/terms endpoint.

   Sandbox

   cURL

   curl --request GET \
     --url https://gp-auth-module.sandbox.gnosispay.in/user/terms
   
   

   Production

   cURL

   curl --request GET \
     --url https://gp-auth-module.prod.gnosispay.com/user/terms
   
   

3. KYC Process

1. Get onboarding status

   Call the GET /user/onboarding 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.

   {
       "status": "action_complete_kyc",
       "webSdkUrl": "https://in.sumsub.com/websdk/p/sbx_yeuhsxyuhkio"
   }
   
2. Complete KYC

   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.

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

   To complete the verification process:

   1. Open an iframe with the provided webSdkUrl
   2. Use the verification document templates for Proof of Identity (POI) and Proof of Address (POA)
   3. Complete the liveness check as prompted

   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
3. Handle KYC resubmission request

   If GET /user/onboarding 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:

   {
       "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.

4. Handle KYC manual review (contact support)

   If GET /user/onboarding 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.

   {
       "status": "kyc_manual_review"
   }
   

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

5. 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, 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 endpoint.

   Sandbox

   cURL

   curl --request GET \
     --url https://gp-auth-module.sandbox.gnosispay.in/source-of-funds
   

   Production

   cURL

   curl --request GET \
     --url https://gp-auth-module.prod.gnosispay.com/source-of-funds
   

   Once all SOF questions have been reviewed and answered by user, submit the responses through the POST /source-of-funds endpoint to complete this step of the onboarding process.

   Sandbox

   cURL

   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>"
       }
     ]
   }'
   

   Production

   cURL

   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>"
       }
     ]
   }'
   

4. Account Setup

1. Check onboarding status

   Check the user’s onboarding status using the GET /user/onboarding endpoint to determine if their KYC verification has been accepted. If the KYC is approved, the user status will transition to the following:

   {
       "status": "action_create_account"
   }
   

   In next step, we will create GP spending safe wallet address.

2. Create GP Account

   In this step, you will initiate the Gnosis Pay account provisioning and creation process. Call POST /user/account endpoint to create an account for the authenticated user.

   Sandbox

   cURL

   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
       }
     }
   }'
   

   Production

   cURL

   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
       }
     }
   }'
   

   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.

   {
       "status": "waiting_account_setup"
   }
   
3. Retrieve Authenticated User

   Call the GET /user endpoint to retrieve the full user profile, including their GP spending wallet address.

   Sandbox

   cURL

   curl --request GET \
     --url https://gp-auth-module.sandbox.gnosispay.in/user \
     --header 'Content-Type: application/json'
   

   Production

   cURL

   curl --request GET \
     --url https://gp-auth-module.prod.gnosispay.com/user \
     --header 'Content-Type: application/json'