Referral Codes

BETA - SUBJECT TO CHANGE - This API is in beta and may change without notice.

Endpoints

Method	Endpoint	Description
`POST`	`/v1/kyc/referral-codes`	Create a new referral code
`GET`	`/v1/kyc/referral-codes`	List 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

Field	Type	Required	Description
`userId`	string	Yes	Partner user ID creating the code
`referralCode`	string	Yes	The referral code string
`category`	string	No	Category 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

Parameter	Type	Required	Description
`userId`	string	No	Filter by partner user ID
`category`	string	No	Filter by category
`code`	string	No	Filter by specific code
`cursor`	string	No	Pagination cursor
`limit`	integer	No	Results 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

Field	Type	Description
`referralCodes`	array	List of referral code objects
`nextCursor`	string	Cursor for next page (if more results)
`eof`	boolean	True if this is the last page

Referral Code Object

Field	Type	Description
`referralCode`	string	The referral code
`userId`	string	Partner user who created the code
`isvId`	string	Partner organization ID
`usedCount`	string	Number of times code has been used
`category`	string	Code 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

Field	Type	Description
`isValid`	boolean	Whether the code is valid
`userId`	string	Partner user who owns the code (if valid)
`amount`	object	Referral 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

{
  "external_id": "new_user_456",
  "first_name": "Jane",
  "last_name": "Smith",
  "referral_code": "PARTNER2024",
  ...
}

When the user’s KYC is approved, the referral will be tracked and any associated bonuses will be processed.

Best Practices

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

Start Here

Partner Types & Eligibility

Get Connected

Onboard Participants

Funding & Transfers

Submitting Orders

Monitor & Reconcile

Endpoints

Create Referral Code

Request

Request Fields

Response

List Referral Codes

Request

Query Parameters

Response

Response Fields

Referral Code Object

Validate Referral Code

Request

Response

Response Fields

Invalid Code Response

Using Referral Codes in KYC

Best Practices

​Endpoints

​Create Referral Code

​Request

​Request Fields

​Response

​List Referral Codes

​Request

​Query Parameters

​Response

​Response Fields

​Referral Code Object

​Validate Referral Code

​Request

​Response

​Response Fields

​Invalid Code Response

​Using Referral Codes in KYC

​Best Practices

Endpoints

Create Referral Code

Request

Request Fields

Response

List Referral Codes

Request

Query Parameters

Response

Response Fields

Referral Code Object

Validate Referral Code

Request

Response

Response Fields

Invalid Code Response

Using Referral Codes in KYC

Best Practices