Building an Online Card Payment System with Blnk • Blnk Developer Documentation

In this tutorial, you’ll learn how to model online card payments using Blnk. We’ll cover the money movement flow a card issuer needs to handle: creating an authorization hold, tracking the pending transaction, settling it when the processor clears it, and voiding it if it’s cancelled. By the end, you’ll know the exact ledger steps needed to support basic card payments.

How online card payments work

When your customer makes a purchase with a card, the process unfolds in two stages: authorization and settlement.

Authorization

The card network requests confirmation that the customer has sufficient funds.

Outcome	Action
Approved	Confirm to the network and reserve the transaction amount. The funds remain held until settlement.
Declined	Notify the network to block the transaction.

Settlement

Hours or days later, the payment processor sends the final confirmation.

Outcome	Action
Approved	Deduct the reserved amount from the customer’s balance and commit the transaction to your ledger.
Declined or Reversed	Release the reserved funds by voiding the transaction.

Prerequisites

Before starting, ensure you have:

A running Blnk Core instance (e.g. at http://localhost:5001).
An API key for Blnk (replace YOUR_API_KEY in the code examples). Required for authenticated requests.
Optionally, you can connect your Blnk Core to your Blnk Cloud workspace to view your ledger data.

Okay, let’s dive in!

1: Create card account

Each card account will be represented with a ledger. The card balance will be created under this ledger.

Create a ledger

Create a ledger for the card account. This groups all of the balances for that customer in one place:

curl -X POST "http://localhost:5001/ledgers" \
  -H "X-Blnk-Key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customers Card Ledger"
  }'

const response = await blnk.Ledgers.create({
  name: 'Customers Card Ledger',
});

ledger, resp, err := client.Ledger.Create(blnkgo.CreateLedgerRequest{
  Name: "Customers Card Ledger",
})

response = blnk.ledgers.create({
  "name": "Customers Card Ledger",
})

blnk ledgers create

Save the ledger_id from the response. You’ll need it to create balances for the card account.

Create customer identity

Create a customer identity to link all balances to the same customer identity:

curl -X POST "http://localhost:5001/identities" \
  -H "X-Blnk-Key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Xavier",
    "last_name": "Woods"
  }'

const response = await blnk.Identity.create({
  first_name: 'Xavier',
  last_name: 'Woods',
});

identity, resp, err := client.Identity.Create(blnkgo.Identity{
  FirstName: "Xavier",
  LastName:  "Woods",
})

response = blnk.identity.create({
  "first_name": "Xavier",
  "last_name": "Woods",
})

blnk identities create

Save the identity_id from the response. You’ll use this ID to link all balances to this customer.

Create card balance

Create a balance for the card account. This balance will track all card transactions:

curl -X POST "http://localhost:5001/balances" \
  -H "X-Blnk-Key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "ledger_id": "<customer-ledger-id>",
    "identity_id": "<xavier-identity-id>",
    "currency": "USD",
    "meta_data": {
      "last_4_digits": "1234",
      "card_scheme": "visa",
      "type": "virtual",
      "card-id": "card-id-1234"
    }
  }'

const response = await blnk.LedgerBalances.create({
  ledger_id: '<customer-ledger-id>',
  identity_id: '<xavier-identity-id>',
  currency: 'USD',
  meta_data: {
    last_4_digits: '1234',
    card_scheme: 'visa',
    type: 'virtual',
    'card-id': 'card-id-1234',
  },
});

balance, resp, err := client.LedgerBalance.Create(blnkgo.CreateLedgerBalanceRequest{
  LedgerID:   "<customer-ledger-id>",
  IdentityID: "<xavier-identity-id>",
  Currency:   "USD",
  MetaData: blnkgo.MetaData{
    "last_4_digits": "1234",
    "card_scheme":   "visa",
    "type":          "virtual",
    "card-id":       "card-id-1234",
  },
})

response = blnk.ledger_balances.create({
  "ledger_id": "<customer-ledger-id>",
  "identity_id": "<xavier-identity-id>",
  "currency": "USD",
  "meta_data": {
    "last_4_digits": "1234",
    "card_scheme": "visa",
    "type": "virtual",
    "card-id": "card-id-1234",
  },
})

blnk balances create

Save the balance_id from the response. You’ll need it for creating transactions throughout this tutorial.

2: Authorization

Authorizing a card transaction means telling the processor that the customer has enough funds to cover the transaction, and they can proceed with the transaction. You can model this in Blnk with inflight transactions.

Money movement map

When a card transaction is authorized, money moves from the customer’s card balance to @World-USD (representing the external merchant):

Explore the map yourself hereThe transaction is created with inflight: true, so it remains pending until the payment processor clears it (or the transaction is voided).

Create an inflight transaction

Create an inflight transaction to authorize the payment. Setting inflight = true puts the transaction in a pending state until it’s settled or voided.

curl -X POST "http://localhost:5001/transactions" \
  -H "X-Blnk-Key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "precise_amount": 200000,
    "precision": 100,
    "currency": "USD",
    "reference": "<unique-reference>",
    "source": "<customer-card_balance_id>",
    "destination": "@World-USD",
    "description": "Card transaction",
    "inflight": true
  }'

const response = await blnk.Transactions.create({
  precise_amount: 200000,
  precision: 100,
  currency: 'USD',
  reference: '<unique-reference>',
  source: '<customer-card_balance_id>',
  destination: '@World-USD',
  description: 'Card transaction',
  inflight: true,
});

transaction, resp, err := client.Transaction.Create(blnkgo.CreateTransactionRequest{
  ParentTransaction: blnkgo.ParentTransaction{
    PreciseAmount: big.NewInt(200000),
    Precision:   100,
    Currency:    "USD",
    Reference:   "<unique-reference>",
    Source:      "<customer-card_balance_id>",
    Destination: "@World-USD",
    Description: "Card transaction",
  },
  Inflight: true,
})

response = blnk.transactions.create({
  "precise_amount": 200000,
  "precision": 100,
  "currency": "USD",
  "reference": "<unique-reference>",
  "source": "<customer-card_balance_id>",
  "destination": "@World-USD",
  "description": "Card transaction",
  "inflight": True,
})

blnk transactions create

@World-USD is an internal balance that represents money leaving and coming into your system (like payments to merchants or payments from customers). Internal balances use the @ prefix and don’t require a balance ID.

Confirm authorization

Using the queue
Skipping the queue

If you use the queue, Blnk returns a QUEUED status in the API response, processes the transaction asynchronously, and emits a webhook event when complete.To confirm authorization, listen for these events:

Event	Meaning
`transaction.inflight`	Customer has sufficient funds. The transaction is authorized and the amount is reserved.
`transaction.rejected`	Customer has insufficient funds. The transaction is rejected.

For high traffic scenarios, Blnk supports various strategies to improve performance and reliability in your ledger. Learn more.

If you skip the queue, Blnk returns the final status directly in the API response.

Status	Meaning
`INFLIGHT`	Customer has sufficient funds. The transaction is authorized and the amount is reserved.

If authorization fails, Blnk returns the error code TXN_INSUFFICIENT_FUNDS and rejects the transaction.

Handling fund reservation

When a transaction is INFLIGHT, the amount is reserved and unavailable until the transaction settles or is voided.Blnk handles this automatically. Each inflight transaction reduces the customer’s available balance. If the available balance is insufficient to cover a new transaction, that transaction is rejected.

	Amount
Customer balance	$5,000
Reserved card transaction	$2,000
Available balance	$3,000

Any new transaction over $3,000 will be rejected. This prevents spending funds already reserved for pending card payments.

3: Settlement

Once a transaction is settled by the payment processor, it means the money has finally been transferred to the recipient. Now, you can commit the inflight transaction. This moves the transaction from INFLIGHT (pending) to APPLIED (completed). If it was rejected or cancelled, you can void the transaction instead.

Money movement map

When you commit the inflight transaction, it finalizes the money movement that was authorized:

The transaction status changes from INFLIGHT to APPLIED, completing the transfer.

Update the inflight transaction

Once clearing is received, update the inflight transaction from the authorization step depending on the outcome.

This approach allows your ledger to cleanly track when the transaction was initiated, and when it was completed based on your business requirements.

Settlement successful
Payment reversed or cancelled

Commit the inflight transaction. This turns the transaction from INFLIGHT (pending) to APPLIED (completed).

curl -X PUT "http://localhost:5001/transactions/inflight/<transaction_id>" \
  -H "X-Blnk-Key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "commit"
  }'

const response = await blnk.Transactions.updateStatus('<transaction_id>', {
  status: 'commit',
});

txn, resp, err := client.Transaction.Update("<transaction_id>", blnkgo.UpdateStatus{
  Status: blnkgo.InflightStatusCommit,
})

response = blnk.transactions.update_status("<transaction_id>", {
  "status": "commit",
})

blnk transactions update --commit <transaction_id>

Void the inflight transaction instead of committing it, and release the reserved amount back to the customer.

curl -X PUT "http://localhost:5001/transactions/inflight/<transaction_id>" \
  -H "X-Blnk-Key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "void"
  }'

const response = await blnk.Transactions.updateStatus('<transaction_id>', {
  status: 'void',
});

txn, resp, err := client.Transaction.Update("<transaction_id>", blnkgo.UpdateStatus{
  Status: blnkgo.InflightStatusVoid,
})

response = blnk.transactions.update_status("<transaction_id>", {
  "status": "void",
})

blnk transactions update --void <transaction_id>

Conclusion

You now have a fully functional card payment system built with Blnk Finance. This system can:

Create and manage card accounts with a ledger and card balance
Authorize card transactions using inflight transactions to reserve funds
Commit or void inflight transactions when they’re settled or rejected

Start Here

Ledgers

Ledger balances

Transactions

Reconciliation

Identities

Metadata

Search

Webhooks

API keys

Guides

Configuration

Advanced

Migration guides

Building an Online Card Payment System

How online card payments work

Prerequisites

1: Create card account

Create a ledger

Create customer identity

Create card balance

2: Authorization

3: Settlement

Conclusion

​How online card payments work

​Prerequisites

​1: Create card account

Create a ledger

Create customer identity

Create card balance

​2: Authorization

​3: Settlement

​Conclusion

How online card payments work

Prerequisites

1: Create card account

2: Authorization

3: Settlement

Conclusion