Skip to main content

​
Referral Codes

Partners can create and manage referral codes for tracking user acquisitions and providing referral bonuses.

​
Endpoints

MethodEndpointDescription
POST/v1/kyc/referral-codesCreate a new referral code
GET/v1/kyc/referral-codesList referral codes
GET/v1/kyc/referral-codes/{code}Validate a specific code

​
Create Referral Code

Create a new referral code for tracking.

​
Request

POST /v1/kyc/referral-codes

{
  "userId": "isv_user_123",
  "referralCode": "PARTNER2024",
  "category": "isv_premium"
}

​
Request Fields

FieldTypeRequiredDescription
userIdstringYesPartner user ID creating the code
referralCodestringYesThe referral code string
categorystringNoCategory for grouping codes

​
Response

{}
An empty response indicates successful creation.

​
List Referral Codes

Retrieve referral codes with optional filtering.

​
Request

GET /v1/kyc/referral-codes?userId=isv_user_123&limit=20

​
Query Parameters

ParameterTypeRequiredDescription
userIdstringNoFilter by partner user ID
categorystringNoFilter by category
codestringNoFilter by specific code
cursorstringNoPagination cursor
limitintegerNoResults per page (default: 20)

​
Response

{
  "referralCodes": [
    {
      "referralCode": "PARTNER2024",
      "userId": "isv_user_123",
      "isvId": "isv_001",
      "usedCount": "42",
      "category": "isv_premium"
    },
    {
      "referralCode": "SUMMER2024",
      "userId": "isv_user_123",
      "isvId": "isv_001",
      "usedCount": "15",
      "category": "seasonal"
    }
  ],
  "nextCursor": "eyJsYXN0X2lkIjogMTAwfQ==",
  "eof": false
}

​
Response Fields

FieldTypeDescription
referralCodesarrayList of referral code objects
nextCursorstringCursor for next page (if more results)
eofbooleanTrue if this is the last page

​
Referral Code Object

FieldTypeDescription
referralCodestringThe referral code
userIdstringPartner user who created the code
isvIdstringPartner organization ID
usedCountstringNumber of times code has been used
categorystringCode category (if set)

​
Validate Referral Code

Check if a referral code is valid and get associated information.

​
Request

GET /v1/kyc/referral-codes/PARTNER2024

​
Response

{
  "isValid": true,
  "userId": "isv_user_123",
  "amount": {
    "value": "50.00",
    "currency": "USD"
  }
}

​
Response Fields

FieldTypeDescription
isValidbooleanWhether the code is valid
userIdstringPartner user who owns the code (if valid)
amountobjectReferral bonus amount (if applicable)

​
Invalid Code Response

{
  "isValid": false,
  "userId": null,
  "amount": null
}

​
Using Referral Codes in KYC

Pass the referral code when starting KYC verification: 
POST /v1/kyc/start

{
  "userId": "new_user_456",
  "firstName": "Jane",
  "lastName": "Smith",
  "referralCode": "PARTNER2024",
  ...
}
When the user’s KYC is approved, the referral will be tracked and any associated bonuses will be processed.

​
Best Practices

  1. Use descriptive codes - Make codes easy to remember and associate with campaigns
  2. Track usage - Monitor usedCount to measure campaign effectiveness
  3. Use categories - Group codes by campaign, partner tier, or time period
  4. Validate before display - Check code validity before showing to users
  5. Handle pagination - Use cursor for large code lists