2. Building the secured card
Steps you perform to be able to issue a credit builder card.
To issue a credit builder card, perform the following steps:
- Create a customer
- Create a credit application
- Submit the credit application
- Issue a credit builder card
1. Creating a customer
On the Bond platform, every consumer who is issued a financial product must have an associated Customer object. This customer object stores important information on the consumer, including name, address, and other sensitive information that is required for regulatory purposes.
For the purposes of this guide, we are onboarding a fictional consumer named Eline Amista who lives at Bond HQ. An example of the customer creation request for Eline is shown below.
curl --request POST \
--url https://sandbox.bond.tech/api/v0.1/customers/ \
--header 'Accept: application/json' \
--header 'Authorization: YOUR-AUTHENTICATION' \
--header 'Content-Type: application/json' \
--header 'Identity: YOUR-IDENTITY' \
--data '
{
"addresses": [
{
"address_type": "PHYSICAL",
"street": "345 California Ave.",
"street2": "Suite 600",
"city": "San Francisco",
"state": "CA",
"zip_code": "12345-1234",
"country": "US",
"is_primary": true
}
],
"dob": "1997-12-25",
"first_name": "Eline",
"last_name": "Amista",
"ssn": "333-245-8546",
"phone": "555-111-2222",
"phone_country_code": "1",
"email": "[email protected]"
}
'
An example of a successful customer creation request is shown below.
{
"customer_id": "3a43b612-825c-48d4-b025-47083ab10755",
"brand_person_id": "ac6ee2d3-5a03-4043-a4aa-dda51836b9fd",
"bond_brand_id": "8c7e08c8-0320-444c-b834-007cd9e18c0e",
"business_id": "null",
"dob": "1997-12-25",
"first_name": "Eline",
"middle_name": "null",
"last_name": "Amista",
"ssn": "333-245-8546",
"phone": "555-111-2222",
"phone_country_code": "1",
"email": "[email protected]",
"addresses": [
{
"address_id": "9de0c172-dc43-4c80-9d2c-dc0e4687cdb5",
"address_type": "PHYSICAL",
"street": "345 California Ave.",
"street2": "Suite 600",
"city": "San Francisco",
"state": "CA",
"zip_code": "12345-1234",
"country": "US",
"is_primary": true,
"date_created": "2021-10-11T17:54:26.784367+00:00",
"deliverability": "deliverable"
}
],
"date_created": "2021-06-02T13:38:27.965404+00:00"
}
In the response, we want to pay particular attention to the customer_id UUID value 3a43b612-825c-48d4-b025-47083ab10755 which uniquely identifies the newly created customer object associated with Elina, and the address_id UUID value 9de0c172-dc43-4c80-9d2c-dc0e4687cdb5 which uniquely identifies Eline's address.
For more information, see Creating a customer in the API Guide.
2. Creating a credit application
In order to determine whether your user is eligible for a charge card, you need to create and submit a credit application on their behalf which contains personal details of the user. The following is an example of a credit application creation request.
curl --request POST \
--url https://sandbox.bond.tech/api/v0.1/credit/applications \
--header 'Accept: application/json' \
--header 'Authorization: YOUR-AUTHENTICATION' \
--header 'Content-Type: application/json' \
--header 'Identity: YOUR-IDENTITY' \
--data '
{
"applicant": {
"customer_id": "3a43b612-825c-48d4-b025-47083ab10755",
"total_annual_income": 6500000,
"monthly_housing_payment": 68500
},
"program_id": "92637aa9-2699-40cb-a492-dd0c8fadadc0"
}
'
Note that we are using the customer_id value 3a43b612-825c-48d4-b025-47083ab10755 that we received in the customer creation response payload.
For more information, see Creating a credit application in the API Guide.
An example of a successful response to the credit application creation request is shown below.
{
"application_id": "2629182a-3aeb-4834-846a-1688d4649bb9",
"program_id": "54f7882b-6b95-4cde-a7eb-775b9468bcb1",
"date_created": "2021-11-15T00:17:56.842105Z",
"date_updated": "2021-11-15T00:17:56.842105Z",
"application_status": "created",
"applicant": {
"customer_id": "05a8054f-8259-4e30-8d1d-d286081987bd",
"address_id": "bb5fa77d-fd66-4e31-81c0-eaf549b0c797",
"total_annual_income": 5000050,
"monthly_housing_payment": 1000,
"terms_accepted": true,
"currency": "USD",
"first_name": "James",
"middle_name": "Herbert",
"last_name": "Bond",
"date_of_birth": "1997-12-25",
"street": "45 California St.",
"street2": "Suite 600",
"city": "San Francisco",
"state": "CA",
"country": "US",
"zip_code": "94105",
"ssn": "tok_sandbox_xoZzhoxaCXHb823bZp3x2e",
"email": "[email protected]"
},
"accounts": {
"security_deposit_account_id": null
}
}
Note the application_id value 9b3dbb5c-97c1-4c18-97bc-e376e62cc2c9 which uniquely identifies the application associated with Eline.
Not all of the information needs to be provided when the application is created. The PATCH credit application API allows you to update the application information incrementally as you onboard your user.
3. Submitting the credit application
Submitting a credit application starts the following:
- KYC process to ensure that the customer information is genuine
- Creation of a secured deposit account once the KYC process is approved
Credit application submission
When the application is ready to be submitted, use the Submit credit application API.
The following is an example of a credit application submission request.
curl --request POST \
--url https://api.bond.tech/api/v0.1/credit/applications/9b3dbb5c-97c1-4c18-97bc-e376e62cc2c9/submit \
--header 'Accept: application/json' \
--header 'Authorization: YOUR-AUTHORIZATION' \
--header 'Identity: YOUR-IDENTITY'
Note that we used the application_id 9b3dbb5c-97c1-4c18-97bc-e376e62cc2c9 from the credit application creation as a path variable.
The following is an example of a successful submission response.
{
"application_id": "2629182a-3aeb-4834-846a-1688d4649bb9",
"program_id": "PROGRAM_ID",
"date_created": "2021-11-15T00:17:56.842105Z",
"date_updated": "2021-11-15T00:17:56.842105Z",
"application_status": "kyc_started",
"applicant": {
"customer_id": "05a8054f-8259-4e30-8d1d-d286081987bd",
"address_id": "bb5fa77d-fd66-4e31-81c0-eaf549b0c797",
"total_annual_income": 5000050,
"monthly_housing_payment": 1000,
"terms_accepted": true,
"currency": "USD",
"first_name": "Elise",
"middle_name": null,
"last_name": "Amista",
"date_of_birth": "1997-12-25",
"street": "45 California St.",
"street2": "Suite 600",
"city": "San Francisco",
"state": "CA",
"country": "US",
"zip_code": "94105",
"ssn": "tok_sandbox_xoZzhoxaCXHb823bZp3x2e",
"email": "[email protected]"
},
"accounts": {
"security_deposit_account_id": null
}
}
KYC process
As shown in the previous response, the application_status value of kyc_started indicates that the Bond platform has automatically initiated regulatory KYC checks on Eline. These KYC checks are the same as the KYC checks initiated by the Start KYC (Know-Your-Customer) endpoint and should be handled in the same way. In the majority of cases, these checks run automatically and are completed in a few seconds. However, in certain scenarios, additional information may be required to complete identity verification. For more information, see Running KYC.
There are a few cases that arise during KYC that may require additional intervention. The following table describes these cases.
| KYC Webhook | Notes |
|---|---|
kyc.verification.document_requiredresponse required | The documents required for the document required state are accessible via webhook or via the Retrieve KYC Status endpoint using the relevant customer_id and program_id. |
kyc.verification.reenter_informationresponse optional | To respond to the reenter_information webhook, information provided via the customer object can be patched directly via the Update a customer endpoint, while information provided via the credit application can be changed directly via the Patch credit application endpoint.After changing the relevant fields described by the kyc.verification.reenter_information webhook, the credit application can be resubmitted again using the Submit credit application endpoint. |
kyc.verification.failure | When the background KYC checks result in a failure, the application_status value is kyc_warning. However, an application can be resubmitted after a failed KYC up to a limit of three times using the Submit credit application endpoint. |
Approval
Pending a successful KYC, the credit application is moved to the approved state. This is accompanied by a credit.application.approved webhook event. The application state can also be viewed using the Get credit application endpoint.
The following is an example of a GET response for an approved application.
{
"program_id": "54f7882b-6b95-4cde-a7eb-775b9468bcb1",
"date_created": "2022-05-15T00:17:56.842105Z",
"date_updated": "2022-05-15T00:17:56.842105Z",
"application_id": "9b3dbb5c-97c1-4c18-97bc-e376e62cc2c9",
"application_status": "approved",
"applicant": {
"customer_id": "05a8054f-8259-4e30-8d1d-d286081987bd",
"address_id": "bb5fa77d-fd66-4e31-81c0-eaf549b0c797",
"total_annual_income": 8000000,
"monthly_housing_payment": 200000,
"terms_accepted": true,
"currency": "USD",
"first_name": "Elise",
"middle_name": "null",
"last_name": "Amista",
"date_of_birth": 1997-12-25",
"street": 45 California St.",
"street2": "Suite 600",
"city": San Francisco",
"state": ""CA,
"country": "USA",
"zip_code": ""94105,
"ssn": "333-245-7829",
"email": "[email protected]"
},
"accounts": {
"security_deposit_account_id": "173121d8-f05e-4bb6-b280-b5b761d2214f"
}
}
We take special note of the security_deposit_account_id field 173121d8-f05e-4bb6-b280-b5b761d2214f under the accounts key. This value uniquely identifies the security deposit account that has been created for Eline.
Adverse action notices
Not all credit applications are approved. When a credit application is rejected, an adverse action notice is generated. These notices need to be supplied to the end consumer (in this case, Eline), in an approved template via email.
The Get adverse actions can be used to get additional information on the reason for the rejection.
The following is an example of a request to retrieve the reason for rejection.
curl --request GET \
--url https://api.bond.tech/api/v0.1/credit/applications/9b3dbb5c-97c1-4c18-97bc-e376e62cc2c9/adverse-actions \
--header 'Accept: application/json' \
--header 'Authorization: YOUR-AUTHORIZATION' \
--header 'Identity: YOUR-IDENTITY'
For the majority of credit application we expect that the application will encounter no difficulties and we'd receive the 404 response shown below.
{
"status": "ERROR_CODE_CREDIT_APPLICATION_GENERIC",
"code": 3001,
"message": "Not found.",
"details": {}
}
The following is an example of a response for a different application_id that contains an adverse action.
{
"id": "585ffb6a-98f9-40f6-a2b9-81ab22fb169a",
"application_id": "8d3dbb5c-97c1-4c18-97bc-e376e62cc2c9",
"date_created": "2022-05-15T21:39:10.130756Z",
"date_updated": "2022-05-15T21:39:10.192226Z",
"service": "kyc",
"reasons": [
"Unable to verify identity"
]
}
The most common reason for adverse action notices is when the customer and the credit application fail three submission attempts at KYC. After three attempts an error is generated.
The following is an example of this error.
{
"status": "ERROR_CODE_CREDIT_APPLICATION_MAX_KYC_ATTEMPTS",
"code": 3010,
"message": "Customer has exceeded maximum number of KYC attempts.",
"details": {
"@type": "type.googleapis.com/bond.credit.v1.CreditCustomerErrorDetail",
"application_id": "9b3dbb5c-97c1-4c18-97bc-e376e62cc2c9",
"customer_id": "3a43b612-825c-48d4-b025-47083ab10755"
}
}
4. Issuing a secured charge card
The status of an application can be actively monitored using the Get credit application API or it can be passively received using the credit.application.approved webhook event. Once Eline's application_status is approved, we can issue a secured charge card which are issued using our Create a card API.
Creation of a card not only creates the card, but also creates an associated credit account.
Note
To be able to make purchases on a credit builder card you need to fund the security deposit account. This can be done before or after the card is issued. Until there are funds in the secured deposit account, the credit limit on the card is zero.
The following is an example of a secured charge card creation request.
curl --request POST \
--url https://api.bond.tech/api/v0.1/cards \
--header 'Accept: application/json' \
--header 'Authorization: YOUR-AUTHORIZATION' \
--header 'Content-Type: application/json' \
--header 'Identity: YOUR-IDENTITY' \
--data '
{
"account_id": "173121d8-f05e-4bb6-b280-b5b761d2214f"
}
'
Note that we pass the security_deposit_account_id value in the request account_id field. This allows us to link the card with the security deposit account.
The following is an example of a successful card creation request.
{
"card_id": "057c6074-a02d-4a5a-bad9-bbc64b047df7",
"customer_id": "3a43b612-825c-48d4-b025-47083ab10755",
"account_id": "e913d434-bda9-494e-b6df-adf46a52c1cc",
"card_number": "tok_live_283734",
"cvv": "tok_live_p923u34",
"expiry_date": "0331",
"last_four": "6270",
"status": "active",
"card_design_id": null
}
We take note of the card_id value 057c6074-a02d-4a5a-bad9-bbc64b047df7 and the credit account_id value e913d434-bda9-494e-b6df-adf46a52c1cc for future use.
Updated 11 months ago