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 --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"}
}'

import requests
import json

url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/register_cardholder_synchronously"

payload = json.dumps({
  "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"}
)
headers = {
  'token': 'Bearer xxxxx',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/register_cardholder_synchronously',
  'headers': {
    'token': 'Bearer xxxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "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"}  
  )
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/register_cardholder_synchronously');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'token' => 'Bearer xxxxx',
  'Content-Type' => 'application/json'
));
$request->setBody('{\n  "first_name": "John",\n  "last_name": "Doe",\n \n  "address": {\n    "address": "9 Jibowu Street",\n   "city": "Aba North",\n    "state": "Abia",\n    "country": "Nigeria",\n    "postal_code": "1000242",\n    "house_no": "13"\n  },\n  "phone": "08122277789",\n  "email_address": "[email protected]",\n "meta_data":{ \n "any_key": "any_value"}, \n "identity": {\n    "id_type": "NIGERIAN_BVN",\n    "bvn": "32747711121",\n    "selfie_image": "https://id_image"\n},\n}');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/register_cardholder_synchronously"
  method := "POST"

  payload := strings.NewReader(`{
  "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"}
  }`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("token", "Bearer xxxxx")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

Body

first_name : String *required
last_name : String *required

address : CardHolderAdress *requiredCardHolderAdress 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 --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"}
}'

import requests
import json

url = "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/register_cardholder"

payload = json.dumps({
  "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"}
)
headers = {
  'token': 'Bearer xxxxx',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/register_cardholder',
  'headers': {
    'token': 'Bearer xxxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "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"}  
  )
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/register_cardholder');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'token' => 'Bearer xxxxx',
  'Content-Type' => 'application/json'
));
$request->setBody('{\n  "first_name": "John",\n  "last_name": "Doe",\n \n  "address": {\n    "address": "9 Jibowu Street",\n   "city": "Aba North",\n    "state": "Abia",\n    "country": "Nigeria",\n    "postal_code": "1000242",\n    "house_no": "13"\n  },\n  "phone": "08122277789",\n  "email_address": "[email protected]",\n "meta_data":{ \n "any_key": "any_value"}, \n "identity": {\n    "id_type": "NIGERIAN_BVN",\n    "bvn": "32747711121",\n    "selfie_image": "https://id_image",\n},\n}');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://issuecards.api.bridgecard.co/v1/issuing/sandbox/cardholder/register_cardholder"
  method := "POST"

  payload := strings.NewReader(`{
  "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_NIN" or "NIGERIAN_INTERNATIONAL_PASSPORT" or "NIGERIAN_PVC" or "NIGERIAN_DRIVERS_LICENSE"
      "id_no": "11111111111",
      "id_image": "",
      "bvn": "2222222222"
  },
  "meta_data":{"any_key": "any_value"}
  }`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("token", "Bearer xxxxx")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}