Guides

Creating a secured charge card

How to create a secured charge card, from getting your API keys to making payments.

Suggest Edits

Overview

This guide covers the following elements of Bond's secured charge card experience:

What is a secured charge card?

A secured charge card pairs a charge card with a security deposit account. The balance in the security deposit account is effectively the credit limit of the charge card, and repayments on the charge card can be made from either the security deposit account or another bank account.

Since the balance of the account starts at zero, users can't spend on their charge cards without funding the security deposit account. The security deposit account can be funded by various methods, including ACH and direct deposit.

Prerequisites

Before you can create a secured charge card, you need to successfully complete the following steps:

  1. Get your API keys
  2. Get your Program ID
  3. Register webhooks

1. Getting your API keys

To interact with the API endpoints on Bond's platform, a pair of identity and authorization API keys must be supplied in the request headers. For more information, see Getting your API key.

2. Finding your Program ID

A Program ID is a UUID value provided by Bond that represents a relationship between you and a bank and is often associated one-to-one with a financial product. For the puposes of this guide, the program ID is associated with consumer secured credit accounts. You can find your program_id in the Bond Portal under the Developers tab. For more information, see Getting your Program ID.

3. Registering webhooks

We use webhooks to signal asynchronously that work has been done in response to certain API requests. These webhooks are for convenience and any information provided asynchronously by the webhooks can also be queried using synchronous API requests. For this guide we are interested in webhooks specifically in the following categories:

  • credit
  • kyc
  • transactions
  • cards

Webhook registration can be done through Bond Portal or via API. For more information, see Webhook events and subscriptions.

Creating the secured charge card

The status of an application can be actively monitored using the Get credit application API or passively received using the credit.application.approved webhook event. Once Eline's application_status is approved, we can issue a secured charge card. Secured charge cards are issued using our Create a card API.

Creation of a card not only creates the card, but also creates an associated credit account.

An example of a secured charge card creation request is shown below.

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.

An example of a successful card creation request is shown below.

{
  "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_1dJbCBY9ucg8MohvYy7HyA",
  "cvv": "tok_live_6dSxybBYBXbFq6KLzc2kW9",
  "expiry_date": "tok_live_1dJbCXY1tcg4MohvYy7SyZ",
  "last_four": "6270",
  "status": "active",
  "card_design_id": null
}

We want to note the card_id value 057c6074-a02d-4a5a-bad9-bbc64b047df7 and the credit account_id value e913d434-bda9-494e-b6df-adf46a52c1cc for future use.

📘

Card Expiry Dates

The expiry dates for cards are configurable for your live program, but the recommended Bond default for expiry is 36 months from card issue.

Making a repayment

  1. Generate a statement
  2. Initialize payment

Generating a statement

Statements contain information, such as transaction history, outstanding balance, and payment due date, and must be provided to your users during the repayment cycle. For more information, see Statements guide.

Initializing a payment

You can initialize a payment from either the security deposit account or from an externally linked bank account. Both options must be presented to your user, though one may be encouraged based on your product flow.

Paying from a security deposit account

To initialize a transfer from our example security deposit account to our card, use the Create a transfer API.

An example of a transfer initialization request is shown below.

curl --request POST \
     --url https://api.bond.tech/api/v0.1/transfers \
     --header 'Accept: application/json' \
     --header 'Authorization: YOUR-AUTHORIZATION' \
     --header 'Content-Type: application/json' \
     --header 'Identity: YOUR-IDENTITY' \
     --data '{
     	"origination_account_id": "173121d8-f05e-4bb6-b280-b5b761d2214f",
     	"destination_account_id": "e913d434-bda9-494e-b6df-adf46a52c1cc",
     	"description": "eline repayment",
    	"amount": 25600
		}'

Note that we use the security_deposit_account_id value 173121d8-f05e-4bb6-b280-b5b761d2214f as our origination_account_id, and the credit_account_id value e913d434-bda9-494e-b6df-adf46a52c1cc as our destination_account_id to indicate that the funds should move from security_deposit_account_id to the credit_account_id.

An example of a successful response is shown below.

{
  "date_created": "2022-05-19T17:14:09.686688",
  "date_updated": "2022-05-19T17:14:09.686688",
  "date_settled": "2022-05-19T17:14:09.686688",
  "transfer_id": "4ead6cdc-77eb-45fa-9959-3f166385a60a",
  "transaction_id": "0fec1e58-b197-4052-99cf-2218496c5482",
  "origination_account_id": "173121d8-f05e-4bb6-b280-b5b761d2214f",
  "destination_account_id": "e913d434-bda9-494e-b6df-adf46a52c1cc",
  "description": "eline repayment",
  "amount": 25600
}

Paying from an external account

To initialize a transfer from an external bank account, use the Create a transfer API in the same way that we funded the security deposit account.

An example of a transfer initialization request is shown below.

curl --request POST \
     --url https://api.bond.tech/api/v0.1/transfers \
     --header 'Accept: application/json' \
     --header 'Authorization: YOUR-AUTHORIZATION' \
     --header 'Content-Type: application/json' \
     --header 'Identity: YOUR-IDENTITY' \
     --data '
{
     "ach": {
          "class_code": "WEB",
          "same_day": false
     },
     "origination_account_id": "f64eadeb-5398-46f7-b1a1-9a0a709039a9",
     "destination_account_id": "e913d434-bda9-494e-b6df-adf46a52c1cc",
     "description": "eline repayment",
     "amount": 25600
}
'

Note again that we use the external_account_id value f64eadeb-5398-46f7-b1a1-9a0a709039a9 as our origination_account_id, and the credit_account_id value e913d434-bda9-494e-b6df-adf46a52c1cc as our destination_account_id in order to indicate that the funds should move from the external_account_id to the credit_account_id.

An example of a successful response is shown below.

{
  "date_created": "2022-05-19T17:14:09.686688",
  "date_updated": "2022-05-19T17:14:09.686688",
  "date_settled": null,
  "transfer_id": "e19472da-86c7-404c-8737-b64d9d120ece",
  "transaction_id": "cedc0221-9de6-4735-86d7-1ea89e0cc591",
  "origination_account_id": "f64eadeb-5398-46f7-b1a1-9a0a709039a9",
  "destination_account_id": "e913d434-bda9-494e-b6df-adf46a52c1cc",
  "description": "eline repayment",
  "amount": 25600,
  "ach": {
    "ach_class_code": "WEB",
    "same_day": false,
    "ach_return_code": "R73",
    "failure_reason": null
  }
}

Closing a secured charge card

To be able to close a secured charge card you need to perform the following operations:

  1. Change the card to inactive status
  2. Execute final repayment cycle
  3. Close credit account
  4. Refund security deposit account balance
  5. Close security deposit account

Changing the card to Inactive status

To close Eline's card, we need to ensure that no further transactions occur on the card. This is done by changing the card status to inactive using our Update Card endpoint.

An example of a card status update request is shown below.

curl --request PATCH \
     --url https://api.bond.tech/api/v0.1/cards/057c6074-a02d-4a5a-bad9-bbc64b047df7 \
     --header 'Accept: application/json' \
     --header 'Authorization: YOUR-AUTHORIZATION' \
     --header 'Content-Type: application/json' \
     --header 'Identity: YOUR-IDENTITY' \
     --data '{"status": "inactive"}'

Note that we pass the card_Id value 057c6074-a02d-4a5a-bad9-bbc64b047df7 as a path variable in the request.

An example of a successful response is shown below.

{
  "card_id": "057c6074-a02d-4a5a-bad9-bbc64b047df7",
  "customer_id": "3a43b612-825c-48d4-b025-47083ab10755",
  "account_id": "173121d8-f05e-4bb6-b280-b5b761d2214f",
  "card_number": "tok_live_283734",
  "cvv": "tok_live_p923u34",
  "expiry_date": "0331",
  "last_four": "6270",
  "status": "inactive",
  "card_design_id": null
}

Executing the final repayment cycle

🚧

The credit account balance must be zero

If the credit account balance is not zero, attempts to close the account will be unsuccessful.

Now that the card has been made inactive, one final repayment cycle must be executed to bring the balance of the secured charge card to zero. This includes issuing a statement and making a cardholder payment, either through the security deposit account or through an externally linked bank account.

Closing the credit account

After the last repayment cycle has settled successfully, the secured charge card credit account is now ready to be closed. This is done using our Close an account endpoint.

An example of a request to close Eline's credit account is provided below.

curl --request POST \
     --url https://api.bond.tech/api/v0.1/accounts/e913d434-bda9-494e-b6df-adf46a52c1cc/close \
     --header 'Accept: application/json' \
     --header 'Authorization: YOUR-AUTHORIZATION' \
     --header 'Identity: YOUR-IDENTITY'

Note that we provided Eline's credit_account_id value e913d434-bda9-494e-b6df-adf46a52c1cc as a path variable in this request.

🚧

Credit account balance must be zero

If the credit account balance is not zero, attempts to close the account will be unsuccessful.

Refunding a security deposit account balance

Refunding the security deposit account balance is done in a similar way to funding the security deposit account. The key difference is that the security_deposit_account_id is now the origination_account_id and the external_account_id is now the destination_account_id.

Again, ACH timelines typically include time both for transactions to be processed and to be considered settled before the funds are made available.

For more information, see ACH transfers.

Closing the security deposit account

After the refunding of the security deposit account has settled successfully, we can close the security deposit account. This is done using our Close an account endpoint.

An example of a request to close Eline's security deposit account is shown below.

curl --request POST \
     --url https://api.bond.tech/api/v0.1/accounts/173121d8-f05e-4bb6-b280-b5b761d2214f/close \
     --header 'Accept: application/json' \
     --header 'Authorization: YOUR-AUTHORIZATION' \
     --header 'Identity: YOUR-IDENTITY'

Note that we provide Eline's security_deposit_account_id value 173121d8-f05e-4bb6-b280-b5b761d2214f as a path variable.

Updated almost 2 years ago

Next Steps