Cardholder

All the APIs to manage cardholder

Register a cardholder synchronously

Use this endpoint to register your user as a cardholder on our platform. The cardholder's Identity verification is done on the fly, so the response might take about 45 seconds and you might want to increase the seconds it takes for your requests to timeout.

This endpoint is rate limited per minute which means a cardholder can only retry his KYC once every minute(register_cardholder)

cURL

curl --location --request POST 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/register_cardholder_synchronously' \
--header 'token: Bearer xxxxx' \
--header 'Content-Type: application/json' \
--data-raw '{
  "first_name": "John",
  "last_name": "Doe",
  "address": {
    "address": "9 Jibowu Street",
    "city": "Aba North",
    "state": "Abia",
    "country": "Nigeria",
    "postal_code": "1000242",
    "house_no": "13"
  },
  "phone": "08122277789",
  "email_address": "[email protected]",
  "identity": {
    "id_type": "NIGERIAN_BVN_VERIFICATION",
    "bvn": "22222222222222",
    "selfie_image": "https://image.com" 
  },
  "meta_data":{"any_key": "any_value"}
}'

Python

Nodejs

PHP

Go

Body

• first_name : String *required

• last_name : String *required

• address : CardHolderAdress *required CardHolderAdress Object

  {
          "address": "9 Jibowu Street",
          "city": "Aba North",
          "state": "Abia",
          "country": "Nigeria",
          "postal_code": "1000242",
          "house_no": "13"
    }

You can use these endpoints to get a list of all the states

• phone : String *required

• identity: There are 4 types of identity objects depending on the country of the user you're onboarding.

If you need to onboard users outside these countries please check this link for the KYC requirements.

Nigerian Cardholder Identity Request Object

{
    "id_type": "NIGERIAN_BVN_VERIFICATION",
    "bvn": "22222222222222",
    "selfie_image": "https://image.com"
}
  
OR USE ANY OTHER GOVERNMENT ISSUED ID

{    
    "id_type": "NIGERIAN_NIN" or "NIGERIAN_INTERNATIONAL_PASSPORT" or "NIGERIAN_PVC" or "NIGERIAN_DRIVERS_LICENSE",
    "id_no": "32747711121",
    "id_image": "https://id_image",
    "bvn": "2222222222222"
 }
 

Ghanian Cardholder Identity Request Object

{    
    "id_type": "GHANIAN_SSNIT" or "GHANIAN_VOTERS_ID" or "GHANIAN_DRIVERS_LICENSE" or "GHANIAN_INTERNATIONAL_PASSPORT" or "GHANIAN_GHANA_CARD", 
    "id_no": "32747711121",
    "id_image": "https://immage.com",
    "selfie_image": "https://image.com"
 }

Ugandan Cardholder Identity Request Object

{    
   "id_type": "UGANDA_VOTERS_ID" or "UGANDA_PASSPORT" or "UGANDA_NATIONAL_ID" or "UGANDA_DRIVERS_LICENSE",
    "id_no": "32747711121",
    "first_name": "John",
    "last_name": "Doe",
    "middle_name": "Moe",
    "date_of_birth": "1990-12-02", #yyyy-mm-dd
    "gender": "male" or "female",
    "selfie_image": "https://image.com"
 }

Kenyan Cardholder Identity Request Object

{    
   "id_type": "KENYAN_VOTERS_ID"
    "id_no": "32747711121"
    "first_name": "John"
    "last_name": "Doe"
    "middle_name": "Moe"
    "date_of_birth": "1990-12-02" #yyyy-mm-dd
    "gender": "male" or "female"
    "selfie_image": "https://image.com"
 }

• meta_data: Use this to store any other data you want to use to recognise this cardholder from your system *optional

Responses

🟢 201: cardholder successfully created

{
  "status": "success",
  "message": "cardholder created successfully.",
  "data": {
    "cardholder_id": "e416a9a188af40b78b8afd740e835d699"
  }
}

🔴 400: Invalid Firstname Error

{
   "message": "Invalid firstname, a valid name should have a minimum of 3 letters"
}

🔴 400: Invalid Lastname Error

{
    "message":"Invalid lastname, a valid name should have a minimum of 3 letters"
}

🔴 400: Invalid BVN Error

{
  "message": "Invalid BVN, a valid BVN is 12 digits long"
}

🔴 400: BVN already exists error

{
    "message": "A cardholder already exists with this BVN"
}

🔴 400: Issuing not supported in Country Error

{
    "message":"Our card Issuing doesn't support this country, we only support ["Nigeria", "Ghana", "Uganda", "Kenya"]"
}

🔴 400: Invalid Address Error

{
    "message": "Invalid address, a valid address should have a minimum of 3 letters"
}

🔴 400: Invalid Postal code

{
    "message": "Invalid postalcode, please check the get_all_lga API to see the list of valid postalcodes and LGAs"
}

🔴 400: Invalid House Number Error

{
    "message": "Invalid house no, please enter a house or apartment number"
}

🔴 400: Invalid Local Government Error

{
    "message": "Invalid LGA, please check the get_all_lga API to see the list of valid LGAs"
}

🔴 400: Invalid Phone Number

{
     "message": "Invalid phoneno."
}

🔴 400: Phone Number already exists

{
    "message": "A cardholder already exists with this phoneno"
}

🔴 400: Invalid ID url

{
    "message": "Invalid ID url"
}

🔴 400: Invalid ID Number

{
    "message": "Invalid ID number"
}

🔴 403: Client account missing Address

{
    "message": "Your issuing account wasn't setup properly, we don't have your company's official address or utility bill, please contact support"
}

🔴 400: invalid DOB

{
    "message": "Invalid Date of Birth format, please send in yyyy-mm-dd e.g 2021-12-31"
}

🔴 400: Unable to verify BVN Error

{
    "message": "Oops.. we couldn't verify your BVN, please confirm the BVN and try again.",
}

🔴 400: Blacklisted BVN Profile

{
    "message": "Oops.. your BVN might have been associated with some fraud or bad record recently so we couldn't enroll you. please contact your bank."
}

🔴 400: ID number does not match the uploaded ID

{
    "message": "Oops.. The uploaded ID number doesn't match the ID uploaded, please try again."
}

🔴 400: Invalid State Error

{
    "message": "Invalid state, please check the get_all_states API to see the list of valid states"
}

🔴 400: BVN Name does not match ID

{
    "message": "Oops.. The uploaded ID name doesn't match the name on his BVN, please try again."
}

🔴 400: Could not verify ID error

{
    "message": "Oops.. we couldn't verify your ID, please try again."
}

🔴 400: Cardholder's name does not match name on BVN

{
    "message": "The cardholders name doesn't match the name on the BVN provided"
}

🔴 400: Could not send OTP

{
    "message": "We ran into an error sending you an OTP, please contact support."
}

🔴 400: BVN Phone number Fraud Suspected

{
    "message": "Oops.. we suspect fraud, this phone no is tied to multiple BVNs."
}

🔴 451: Customer has been blacklisted due to fraud

{
    "message": "This individual has been blacklisted on our platform due to fraudulent activities, please contact support."
}

Register a cardholder asynchronously (Recommended)

Use this endpoint to register your user as a cardholder on our platform. If the user passes the KYC verification we will send you a success webhook. However, we have a human-in-the-loop process where if a user fails a KYC verification we might pass it to a human being to do a manual verification just to double check that the automated KYC verification system didn't flag the user's KYC unnecessarily. In the case that a users KYC is being sent for manual review you will be sent a manual review webhook. The manual review process by our compliance team usually takes between 1 - 24hrs and after this, we will send you either the cardholder success or failure webhook verification response depending on the final decision.

cURL

curl --location --request POST 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/register_cardholder' \
--header 'token: Bearer xxxxx' \
--header 'Content-Type: application/json' \
--data-raw '{
  "first_name": "John",
  "last_name": "Doe",
  "address": {
    "address": "9 Jibowu Street",
    "city": "Aba North",
    "state": "Abia",
    "country": "Nigeria",
    "postal_code": "1000242",
    "house_no": "13"
  },
  "phone": "08122277789",
  "email_address": "[email protected]",
  "identity": {
    "id_type": "NIGERIAN_BVN_VERIFICATION",
    "bvn": "22222222222222",
    "selfie_image": "https://image.com" 
  },
  "meta_data":{"any_key": "any_value"}
}'

Python

Nodejs

PHP

Go

Body

• first_name : String *required

• last_name : String *required

• address : CardHolderAdress *required CardHolderAdress Object

  {
          "address": "9 Jibowu Street",
          "city": "Aba North",
          "state": "Abia",
          "country": "Nigeria",
          "postal_code": "1000242",
          "house_no": "13"
    }

You can use these endpoints to get a list of all the states and their lgas & postalcodes

• phone : String *required

• identity: There are 4 types of identity objects depending on the country of the user you're onboarding. If you need to onboard users outside these countries please check this link for the KYC requirements.

Nigerian Cardholder Identity Request Object

{
    "id_type": "NIGERIAN_BVN_VERIFICATION",
    "bvn": "22222222222222",
    "selfie_image": "https://image.com"
}
  
OR USE ANY OTHER GOVERNMENT ISSUED ID

{    
    "id_type": "NIGERIAN_NIN" or "NIGERIAN_INTERNATIONAL_PASSPORT" or "NIGERIAN_PVC" or "NIGERIAN_DRIVERS_LICENSE",
    "id_no": "32747711121",
    "id_image": "https://id_image",
    "bvn": "2222222222222"
 }
 

Ghanian Cardholder Identity Request Object

{    
    "id_type": "GHANIAN_SSNIT" or "GHANIAN_VOTERS_ID" or "GHANIAN_DRIVERS_LICENSE" or "GHANIAN_INTERNATIONAL_PASSPORT" or "GHANIAN_GHANA_CARD", 
    "id_no": "32747711121",
    "id_image": "https://immage.com",
    "selfie_image": "https://image.com"
 }

Ugandan Cardholder Identity Request Object

{    
   "id_type": "UGANDA_VOTERS_ID" or "UGANDA_PASSPORT" or "UGANDA_NATIONAL_ID" or "UGANDA_DRIVERS_LICENSE",
    "id_no": "32747711121",
    "first_name": "John",
    "last_name": "Doe",
    "middle_name": "Moe",
    "date_of_birth": "1990-12-02", #yyyy-mm-dd
    "gender": "male" or "female",
    "selfie_image": "https://image.com"
 }

Kenyan Cardholder Identity Request Object

{    
   "id_type": "KENYAN_VOTERS_ID"
    "id_no": "32747711121"
    "first_name": "John"
    "last_name": "Doe"
    "middle_name": "Moe"
    "date_of_birth": "1990-12-02" #yyyy-mm-dd
    "gender": "male" or "female"
    "selfie_image": "https://image.com"
 }

• meta_data: Use this to store any other data you want to use to recognise this cardholder from your system *optional

Responses

🟢 201: cardholder successfully created

{
  "status": "success",
  "message": "cardholder created successfully, you\'ll recieve a webhook event when this user\'s identity has been verified.",
  "data": {
    "cardholder_id": "e416a9a188af40b78b8afd740e835d699"
  }
}

🔴 400: Invalid Firstname Error

{
   "message": "Invalid firstname, a valid name should have a minimum of 3 letters"
}

🔴 400: Invalid Lastname Error

{
    "message":"Invalid lastname, a valid name should have a minimum of 3 letters"
}

🔴 400: Invalid BVN Error

{
  "message": "Invalid BVN, a valid BVN is 12 digits long"
}

🔴 400: BVN already exists error

{
    "message": "A cardholder already exists with this BVN"
}

🔴 400: Issuing not supported in Country Error

{
    "message":"Our card Issuing doesn't support this country, we only support ["Nigeria", "Ghana", "Uganda", "Kenya"]"
}

🔴 400: Invalid Address Error

{
    "message": "Invalid address, a valid address should have a minimum of 3 letters"
}

🔴 400: Invalid Postal code

{
    "message": "Invalid postalcode, please check the get_all_lga API to see the list of valid postalcodes and LGAs"
}

🔴 400: Invalid House Number Error

{
    "message": "Invalid house no, please enter a house or apartment number"
}

🔴 400: Invalid Local Government Error

{
    "message": "Invalid LGA, please check the get_all_lga API to see the list of valid LGAs"
}

🔴 400: Invalid Phone Number

{
     "message": "Invalid phoneno."
}

🔴 400: Phone Number already exists

{
    "message": "A cardholder already exists with this phoneno"
}

🔴 400: Invalid ID url

{
    "message": "Invalid ID url"
}

🔴 400: Invalid ID Number

{
    "message": "Invalid ID number"
}

🔴 403: Client account missing Address

{
    "message": "Your issuing account wasn't setup properly, we don't have your company's official address or utility bill, please contact support"
}

🔴 400: Invalid Utility Bill URL

{
    "message": "Invalid utility bill url"
}

🔴 400: invalid DOB

{
    "message": "Invalid Date of Birth format, please send in yyyy-mm-dd e.g 2021-12-31"
}

🔴 400: Unable to verify BVN Error

{
    "message": "Oops.. we couldn't verify your BVN, please confirm the BVN and try again.",
}

🔴 400: Blacklisted BVN Profile

{
    "message": "Oops.. your BVN might have been associated with some fraud or bad record recently so we couldn't enroll you. please contact your bank."
}

🔴 400: ID number does not match the uploaded ID

{
    "message": "Oops.. The uploaded ID number doesn't match the ID uploaded, please try again."
}

🔴 400: Invalid State Error

{
    "message": "Invalid state, please check the get_all_states API to see the list of valid states"
}

🔴 400: BVN Name does not match ID

{
    "message": "Oops.. The uploaded ID name doesn't match the name on his BVN, please try again."
}

🔴 400: Could not verify ID error

{
    "message": "Oops.. we couldn't verify your ID, please try again."
}

🔴 400: Cardholder's name does not match name on BVN

{
    "message": "The cardholders name doesn't match the name on the BVN provided"
}

🔴 400: Could not send OTP

{
    "message": "We ran into an error sending you an OTP, please contact support."
}

🔴 400: BVN Phone number Fraud Suspected

{
    "message": "Oops.. we suspect fraud, this phone no is tied to multiple BVNs."
}

🔴 451: Customer has been blacklisted due to fraud

{
    "message": "This individual has been blacklisted on our platform due to fraudulent activities, please contact support."
}

Get cardholder details.

Use this API to view a cardholder's profile.

cURL

curl --location --request GET 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/get_cardholder?cardholder_id=e416a9a188af40b78b8afd740e835d68' \
--header 'token: Bearer xxxxx'

Python

Nodejs

PHP

Go

Response

🟢 200: cardholder details fetched successfully.

{
  "status": "success",
  "message": "cardholder details fecthed successfully.",
  "data": {
    "address": {
      "address": "9 Jibowu Street",
      "city": "Aba North",
      "country": "nigeria",
      "house_no": "13",
      "lga": "Aba North",
      "postal_code": "1000242",
      "state": "Abia"
    },
    "cardholder_id": "d0658fedf8284207866d961e83fa",
    "created_at": 1659726281,
    "email_address": "[email protected]",
    "first_name": "John",
    "identity_details": {
      "blacklisted": false,
      "date_of_birth": "1999-02-04",
      "first_name": "John",
      "gender": "Male",
      "id_no": "22222222222",
      "id_type": "NIGERIAN_NIN",
      "last_name": "Doe",
      "phone": "08123456789"
    },
    "is_active": true,
    "is_id_verified": true,
    "issuing_app_id": "842352f4-8a6f-4a19-89c6-",
    "last_name": "Doe",
    "phone": "2348189691071"
  },
  "meta_data":{"user_id" : "zzz001658fedf8284207866d961e83fa"}
}

• is_active (bool) : When this value is True this means the cardholder can be issued a card.

• is_id_verified (bool) : Shows you whether the user has passed ID verification

if the user failed the ID verification step, is_active and is_id_verified will be set to False and you cannot issue the user a card.

🔴 400: Invalid Cardholder ID

{
    "message": "Invalid cardholder ID, there's no cardholder with this ID."
}

Delete cardholder

Use this API to delete a cardholder

cURL

curl --location --request DELETE 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/delete_cardholder/e416a9a188af40b78b8afd740e835d68' \
--header 'token: Bearer xxxxx'

Python

Nodejs

PHP

Go

Response

🟢 200: cardholder details deleted successfully.

{  
  "status": "success",
  "message": "cardholder has been deleted successfully.",
  "data": {}
}

🔴 400: Invalid Cardholder ID

{
    "message": "Invalid cardholder ID, there's no cardholder with this ID."
}