API Reference

Know Your Client - Cardholder Scenarios

Know Your Client (KYC) is a step when creating a cardholder on a general purpose reloadable program. In order to issue a card to a client their identity needs to be confirmed during the Create Cardholder call.

Cases

KYC Check Success

The automated KYC check passed and the cardholder has been created. No further action is necessary.

POST {{domain}}/api/v1/card_issuing/cardholders

{
	"program_id": 101,
	"external_tag": "Demo",
    "first_name": "OLIVIA",
    "last_name": "DEPONTENUF",
    "middle_name": "LITA",
    "address1": "541 MCKERCHER DR",
    "address2": "",
    "city": "SASKATOON",
    "state": "SK",
    "postal_code": "S7H4G3",
    "date_of_birth": "12-08-1994",
	"phone": "2895215466",
	"email": "[email protected]",
	"country": "124",
	"shipping_method": "3"
}

{
    "data": {
        "company_id": "35",
        "created_at": "2021-04-09T19:44:43Z",
        "external_tag": "Demo",
        "id": 475,
        "primary_processor_reference": "1900000661",
        "username": null,
        "value_load_result": {
            "code": "success",
            "message": ""
        }
    }
}

KYC Check Review

The automated KYC check failed. This usually means:

  • There is insufficient credit history available to make a match
  • Failure to match a key field such as address or date of birth
  • There is a potential risk of fraud
  • The client triggered a sanction screening warning.

The Berkeley compliance team will reach out to the cardholder and verify their identity. If their identity can be verified the cardholder will automatically be created. Otherwise the request will be rejected.

POST {{domain}}/api/v1/card_issuing/cardholders

{
	"program_id": 101,
	"external_tag": "Demo",
    "first_name": "WELLS",
    "last_name": "LAPORTE",
    "middle_name": "ZONTA",
    "address1": "49 ENGLEMANN DR",
    "address2": "",
    "city": "WHITEHORSE",
    "state": "ON",
    "postal_code": "Y1A5S5",
    "date_of_birth": "09-11-1988",
	"phone": "2895214433",
	"email": "[email protected]",
	"country": "124",
	"shipping_method": "3"
}

{
    "error": {
        "code": "kyc_verification_review",
        "kyc_result_codes": [
            {
                "code": "street_mismatch",
                "description": "Street does not match records",
                "found": "ENGELMANN DR",
                "match_type": "partial_match",
                "value": "49 ENGLEMANN DR"
            },
            {
                "code": "state_mismatch",
                "description": "State/Province does not match records",
                "found": "YT",
                "match_type": "no_match",
                "value": "ON"
            },
            {
                "code": "insufficient_credit_record",
                "description": "Insufficient credit history for a match"
            }
        ],
        "kyc_transaction_id": "074efdb04a574f1683eeab57",
        "message": "The cardholder is under manual review due to KYC verification failure"
    }
}

KYC Check Rejected

The automated KYC check failed. This usually means that there is either no record of this cardholder can be found or there is insufficient credit history available to make a match. This failure will not be reviewed by the Berkeley compliance team.

POST {{domain}}/api/v1/card_issuing/cardholders

{
	"program_id": 101,
	"external_tag": "Demo",
    "first_name": "CRAMSFORD",
    "last_name": "WILLIAM",
    "middle_name": "MARY",
	"email": "[email protected]",
	"postal_code": "B2H1V6",
    "date_of_birth": "03-10-1984",
	"phone": "2895214459",
	"city": "MARLO",
	"state": "NB",
	"address1": "222 Limson Cres",
    "address2": "Apt 200",
	"country": "124",
	"shipping_method": "3"
}

{
    "error": {
        "code": "kyc_verification_rejected",
        "kyc_result_codes": [
            {
                "code": "public_record_not_found",
                "description": "No matching public record found"
            }
        ],
        "kyc_transaction_id": "ca826d514d55444bafaba511",
        "message": "The cardholder was rejected due to KYC verification failure"
    }
}

Result Status

Changes in result status can be found by using the following endpoint:

POST {{get_domain}}/api/v1/card_issuing/kyc_results?kyc_transaction_id=074efdb04a574f1683eeab57

{
    "data": {
        "cardholder": null,
        "code": "kyc_verification_review",
        "company_id": "35",
        "created_at": "2021-04-09T19:44:01Z",
        "id": 57,
        "kyc_transaction_id": "074efdb04a574f1683eeab57",
        "result": {
            "code": "kyc_verification_review",
            "kyc_result_codes": [
                {
                    "code": "street_mismatch",
                    "description": "Street does not match records",
                    "found": "ENGELMANN DR",
                    "match_type": "partial_match",
                    "value": "49 ENGLEMANN DR"
                },
                {
                    "code": "state_mismatch",
                    "description": "State/Province does not match records",
                    "found": "YT",
                    "match_type": "no_match",
                    "value": "ON"
                },
                {
                    "code": "insufficient_credit_record",
                    "description": "Insufficient credit history for a match"
                }
            ],
            "kyc_transaction_id": "074efdb04a574f1683eeab57",
            "message": "The cardholder is under manual review due to KYC verification failure"
        },
        "updated_at": "2021-04-09T19:44:01Z"
    }
}

Please note that the result field is always the original KYC response. code is the current status.

📘

Related pages:

KYC Test Cases
Card Issuing API Quickstart Guide
API Flows