Skip to main content

Apply Referral Code API

Overview​

Apply a referral code to earn rewards and benefits. This API handles the actual application of referral codes by users, performing comprehensive validation including code existence, duplicate prevention, and referral limit enforcement. Upon successful application, it triggers asynchronous reward processing through the reward system.

API Details​

Endpoint​

POST https://api.gafapay.com:8443/gafapay/v3/reward_promotion/apply_referral_code

Headers​

authorization: Token eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIzYzM5OWVjOTNmMmI0YzM3OTA3NjUyODRlNTYyNGJjYSIsInJvbGVzIjpbIlJPTEVfQ1VTVE9NRVIiXSwiZXhwIjoxNzYwMTU2NDQ1fQ.Q252AoCQf5IPn9-BMMT4tnZWpDWkJTZRMnINNW3k8fM
companyid: 59388167894b4d10a04fe5da3b8a2104
requestid: 5bb30135-1815-41d5-827f-baed3daba4ae

Request Body​

Required Parameters​

  • company_id (String): Company identifier (passed in header)

Request Body Fields​

  • user_id (String): User applying the referral code
    • Example: "3c399ec93f2b4c3790765284e5624bca"
    • Description: The user who wants to apply the referral code
  • user_type (Integer): Type of user applying the code
    • 2 = Customer
    • 3 = Merchant
    • 5 = Agent
    • Example: 2
    • Description: The user type of the person applying the referral code
  • referral_code (String): Referral code to apply
    • Example: "C273551489XA"
    • Description: The referral code that the user wants to apply

Request Body Example​

{
    "user_type": 2,
    "user_id": "3c399ec93f2b4c3790765284e5624bca",
    "referral_code": "C273551489XA"
}

Response​

Success Response​

{
    "success": 1,
    "error": [],
    "data": {
        "message": "REWARD_PROMOTION_APPLY_REFERRAL_CODE_SUCCESS"
    }
}

Response Fields​

  • success (integer): Response status indicator
    • 1 = Success
    • 0 = Failure
  • error (array): Array of error messages (empty on success)
  • data (object): Response data object
    • message (string): Success message indicating referral code was applied successfully

Error Responses​

Bad Request​

{
    "success": 0,
    "error": ["BAD_REQUEST"],
    "data": {}
}

Invalid Referral Code​

{
    "success": 0,
    "error": ["REWARD_PROMOTION_INVALID_REFERRAL_CODE"],
    "data": {}
}

Already Applied​

{
    "success": 0,
    "error": ["REWARD_PROMOTION_REFERRAL_CODE_ALREADY_APPLIED"],
    "data": {}
}

Referral Limit Reached​

{
    "success": 0,
    "error": ["REWARD_PROMOTION_REFERRAL_REACHED_AT_MAX_LIMIT"],
    "data": {}
}

Example Usage​

Basic Application Request​

curl --location 'https://api.gafapay.com:8443/gafapay/v3/reward_promotion/apply_referral_code' \
--header 'authorization: Token YOUR_TOKEN_HERE' \
--header 'companyid: YOUR_COMPANY_ID' \
--header 'requestid: YOUR_REQUEST_ID' \
--header 'Content-Type: application/json' \
--data '{
    "user_type": 2,
    "user_id": "3c399ec93f2b4c3790765284e5624bca",
    "referral_code": "C273551489XA"
}'

Customer User Application​

curl --location 'https://api.gafapay.com:8443/gafapay/v3/reward_promotion/apply_referral_code' \
--header 'authorization: Token YOUR_TOKEN_HERE' \
--header 'companyid: YOUR_COMPANY_ID' \
--header 'requestid: YOUR_REQUEST_ID' \
--header 'Content-Type: application/json' \
--data '{
    "user_type": 2,
    "user_id": "customer_user_id_here",
    "referral_code": "CUSTOMER123ABC"
}'

Merchant User Application​

curl --location 'https://api.gafapay.com:8443/gafapay/v3/reward_promotion/apply_referral_code' \
--header 'authorization: Token YOUR_TOKEN_HERE' \
--header 'companyid: YOUR_COMPANY_ID' \
--header 'requestid: YOUR_REQUEST_ID' \
--header 'Content-Type: application/json' \
--data '{
    "user_type": 3,
    "user_id": "merchant_user_id_here",
    "referral_code": "MERCHANT456DEF"
}'

Agent User Application​

curl --location 'https://api.gafapay.com:8443/gafapay/v3/reward_promotion/apply_referral_code' \
--header 'authorization: Token YOUR_TOKEN_HERE' \
--header 'companyid: YOUR_COMPANY_ID' \
--header 'requestid: YOUR_REQUEST_ID' \
--header 'Content-Type: application/json' \
--data '{
    "user_type": 5,
    "user_id": "agent_user_id_here",
    "referral_code": "AGENT789GHI"
}'

Response Messages​

  • REWARD_PROMOTION_APPLY_REFERRAL_CODE_SUCCESS: Successful application
  • BAD_REQUEST: Invalid or missing required parameters
  • REWARD_PROMOTION_INVALID_REFERRAL_CODE: Referral code doesn't exist
  • REWARD_PROMOTION_REFERRAL_CODE_ALREADY_APPLIED: User already applied a code
  • REWARD_PROMOTION_REFERRAL_REACHED_AT_MAX_LIMIT: Referrer reached limits

Notes​

  • One-Time Application: Each user can apply only one referral code
  • Asynchronous Processing: Rewards are processed in the background via Kafka
  • Company Scoped: All applications are scoped to the company_id