Skip to main content
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.
cURL
curl --request POST \
  --url https://gp-auth-module.sandbox.gnosispay.in/email-verification \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "jsmith@example.com"
}'
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.
cURL
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>"
}'
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:
StatusDescriptionUser Action Required
action_accept_tosTerms of Service acceptance required - user registered but hasn’t accepted required termsReview and accept Terms of Service
waiting_kyc_setupKYC initialization in progress - all terms accepted, KYC process being set upWait for KYC setup completion
action_complete_kycKYC verification pending - KYC check created but pending user completionComplete KYC verification via Sumsub webSdkUrl
action_kyc_contact_supportKYC provider flagged the check as requiring manual review — this is a non-recoverable state from the user’s sideContact support
action_kyc_resubmission_requestedKYC provider has requested the user resubmit their KYC documents — a new Sumsub session URL is providedRe-complete KYC verification via Sumsub using the provided webSdkUrl
action_complete_sofSource of Funds questionnaire required - KYC approved, SOF answers neededAnswer Source of Funds questionnaire
action_create_accountReady for account creation - KYC approved and SOF completedProceed with account creation
waiting_account_setupAccount provisioning in progress - account is being set up in the systemWait for account setup completion
completedOnboarding complete - account is active with cardholder IDStart using the platform
rejectedOnboarding rejected - account is blocked, closed, or KYC verification failedContact support or retry if applicable
cURL
curl --request GET \
  --url https://gp-auth-module.sandbox.gnosispay.in/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.
cURL
curl --request GET \
  --url https://gp-auth-module.sandbox.gnosispay.in/terms
Submit the accepted Terms of Service via the POST /user/terms endpoint.
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>"
    }
  ]
}'
You can check the status of the user’s acceptance of the Terms of Service via the GET /user/terms endpoint.
cURL
curl --request GET \
  --url https://gp-auth-module.sandbox.gnosispay.in/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

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
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 action_kyc_contact_support, 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": "action_kyc_contact_support"
}
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.
cURL
curl --request GET \
  --url https://gp-auth-module.sandbox.gnosispay.in/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.
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>"
    }
  ]
}'

​
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.
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
    }
  }
}'
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.
cURL
curl --request GET \
  --url https://gp-auth-module.sandbox.gnosispay.in/user \
  --header 'Content-Type: application/json'