In this example, you’ll learn how to implement a virtual card issuance service and all of its transaction workflows with the Blnk Ledger.

We’ll learn about:

  1. Defining and creating your ledger structure
  2. Balance (virtual card) creation
  3. Authorizing transactions
  4. Approving transactions
  5. Declining transactions
  6. Best Practices

​
1. Ledger structure

The entry point of the Blnk ledger system is ledger folders. These folders serve as a way to group and manage assets, accounts, and balances that fit your product or organization’s structure.

In this guide, we’ll use a simple structure:

  • USD Ledger: Contains all USD virtual cards (wallets)

The ledger structure is flexible and can be customized based on your specific needs. For instance, you could group by users instead of currencies, or use a combination of both.

See also:

​
Creating a USD ledger

View your ledgers in your terminal:

bash
blnk ledgers list

Always store the ledger_id in your database. You’ll need it for future operations related to this ledger.

​
2. Balance (virtual cards) creation

Blnk uses the concept of ledger balances to manage accounts/balances in a ledger. In this example, we’ll create virtual cards for a customer named Jerry. Each card will be represented as a balance in the ledger.

Assume that card details (e.g., card number, expiry date, CVV) are generated and provided by your card issuing partner. Store these details securely and ensure they are masked or encrypted when stored or displayed.

See also:

​
Creating a USD virtual card for Jerry

View your balances in your terminal:

bash
blnk balances list

The card’s state and details are stored in the meta_data field. Always update this metadata as the state of the card changes.

​
3. Authorizing transactions

When a transaction is initiated using the virtual card, it must first be authorized. We use the Inflight feature for this purpose.

See also:

View your transactions in your terminal:

bash
blnk transactions list

​
4. Approving transactions

After the authorization, if the transaction is verified, it can be approved and committed.

​
Approving a transaction

​
5. Declining transactions

If the transaction cannot be verified, it should be declined.

​
Declining a transaction

Use the inflight status to handle transaction authorizations, approvals, and declines. Always ensure that sensitive card details are securely managed and stored.

​
Best practices

  1. Available Balance Calculation: In your application, calculate the available balance to prevent users from accessing funds that are held in Inflight transactions. This can be done as follows:
    JavaScript
    const availableBalance = balance - inflight_debit_balance;
  2. Error Handling: Implement robust error handling in your Inflight process. If a commit or void operation fails, you may need to retry or escalate to manual intervention.
  3. Customer Communication: Implement a system to notify customers about the status of their transactions, especially when they are held in Inflight. Clear communication can enhance customer trust and satisfaction.
  4. Reconciliation: Regularly reconcile your internal records with Blnk’s transaction logs to ensure accuracy. Pay special attention to Inflight transactions. Blnk v1 will support reconciliation features built into the ledger, which can aid in this process.
  5. Webhook Authentication: In a production environment, implement a mechanism to verify that webhooks are genuinely from your payment provider. This helps in maintaining the integrity and security of your transaction processing.
  6. Idempotency: Ensure your webhook handler is idempotent. Providers may send the same webhook multiple times, so your system should handle duplicate notifications gracefully. This prevents double-processing of transactions.
  7. Monitoring: Set up monitoring and alerting for your webhook endpoint and Inflight transactions. This can help you quickly identify and respond to any issues in the payment verification process.
  8. Data Security: Always ensure that sensitive card details are securely managed and stored. Mask or encrypt card numbers, CVVs, and other sensitive information when storing or displaying them.
  9. Transaction State Management: Use metadata to manage the state of virtual cards and transactions effectively. For example, track the card state (e.g., ACTIVE, BLOCKED) and transaction verification status (e.g., VERIFIED, DECLINED) in the metadata.
  10. Compliance: Ensure that your virtual card issuance and transaction processing comply with relevant regulations and standards, such as PCI-DSS for handling card data securely.
  11. Testing: Thoroughly test your virtual card issuance and transaction processing flows, including Inflight handling, to identify and resolve any issues before going live.

​
Need help?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool.

To ask questions or discuss issues, please join our Discord community.

Was this page helpful?

Managing transfersLoyalty points system