Skip to main content

​
Onboarding Lifecycle

Merchant onboarding on PayGlocal is a sequential, stateful process. Each API call enriches the merchant record, and PayGlocal validates completeness before allowing the final verification step.

​
Step-by-Step Breakdown

1

Create Onboarding Record

POST /gcc/v2/partner/merchant/onboardInitiate the onboarding with the merchant’s PAN and your internal externalOnboardingId. This is the entry point — all subsequent calls reference the onboardingId returned here.Key output: onboardingId (a PayGlocal-generated ID for this merchant’s onboarding session)
2

Submit Business Details

PUT /gcc/v2/partner/merchant/onboard/{onboardingId}/business-detailsProvide entity type, GST number, nature of business (from the Business Categories reference), website URL, expected monthly transaction volume, and registered/operating address.Use the State Codes reference for stateCode fields.
3

Add Beneficial Owners

PUT /gcc/v2/partner/merchant/onboard/{onboardingId}/beneficial-ownerSubmit all Ultimate Beneficial Owners (UBOs) holding ≥10% ownership. The array in the request completely replaces the existing beneficial owner list — always send all UBOs together.
4

Add Bank Details

PUT /gcc/v2/partner/merchant/onboard/{onboardingId}/bank-detailsSubmit the settlement bank account. PayGlocal performs a penny drop verification to confirm the account is active and the IFSC code is valid. The account must be either CURRENT or SAVINGS type.
5

Add Authorised Signatory

PUT /gcc/v2/partner/merchant/onboard/{onboardingId}/auth-signatorySubmit the details of the individual authorized to sign on behalf of the business. This person’s phone and email are used during VKYC and DigiLocker verification, so accuracy is critical.
6

Upload Documents

PUT /gcc/v2/partner/merchant/onboard/{onboardingId}/docsUpload each required compliance document as a separate API call. The merchantDocType field specifies the document category (e.g., PAN, COI_DOCUMENT, OPERATING_ADDRESS_PROOF). See the Upload Documents reference for the full list.
7

Configure Products and Fees

PUT /gcc/v2/partner/merchant/onboard/{onboardingId}/productsSpecify which payment products to enable for the merchant (GLOBAL_FUND_TRANSFER, INTERNATIONAL_CARDS_AND_ALT_PAYS, DOMESTIC_CARDS_UPI_AND_INB) and configure per-product fee structures.
8

Trigger Merchant Verification

PUT /gcc/v2/partner/merchant/verification/{onboardingId}/redirectGenerates a unique redirectLink for the merchant to complete VKYC, DigiLocker document verification, and T&C acknowledgement. Embed this URL in an iFrame — see the iFrame Integration guide.Authenticate with x-gl-auth and x-gl-digest (sign the request body). Call only after all pre-verification checklist steps are complete.
9

Confirm Final Status

GET /gcc/v2/partner/merchant/onboard/{onboardingId}/statusAfter the merchant completes the verification flow and is redirected to your callBackUrl, always perform a server-to-server status check to confirm the VKYC and DigiLocker checklist statuses are COMPLETE.Never rely solely on the callback URL redirect to determine completion.

​
State Transitions

​
Important Constraints

  • Business details and authorised signatory cannot be updated after the merchant has acknowledged the T&C.
  • Beneficial owner and bank details cannot be updated after the verification step is complete.
  • Attempting to call the verification redirect endpoint before all required steps are complete returns 400 Bad Request.
  • The externalOnboardingId must be unique per merchant in your system — it cannot be reused.