;
};
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.
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. |
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:
1. A running Blnk Core instance (e.g. at `http://localhost:5001`).
2. [An API key](/advanced/secure-blnk) for Blnk (replace `YOUR_API_KEY` in the code examples). Required for authenticated requests.
3. Optionally, you can connect your Blnk Core to your [Blnk Cloud](https://cloud.blnkfinance.com/?utm_source=blnk_docs\&utm_medium=documentation\&utm_campaign=tutorials%2Fdigital-banking%2Fcards) workspace to view your ledger data.
Okay, let's dive in!
***
## 1: Create card account
Each card account will be represented with [a ledger](/ledgers/introduction.mdx). The card balance will be created under this ledger.
[Create a ledger](/reference/create-ledger) for the card account. This groups all of the balances for that customer in one place:
```bash cURL wrap theme={"system"}
curl -X POST "http://localhost:5001/ledgers" \
-H "X-Blnk-Key: " \
-H "Content-Type: application/json" \
-d '{
"name": "Customers Card Ledger"
}'
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Ledgers.create({
name: 'Customers Card Ledger',
});
```
```go Go wrap theme={"system"}
ledger, resp, err := client.Ledger.Create(blnkgo.CreateLedgerRequest{
Name: "Customers Card Ledger",
})
```
```python Python wrap theme={"system"}
response = blnk.ledgers.create({
"name": "Customers Card Ledger",
})
```
```java Java wrap theme={"system"}
ApiResponse response = blnk.ledgers().create(
CreateLedger.create()
.name("Customers Card Ledger"));
```
```bash Blnk CLI wrap theme={"system"}
blnk ledgers create
```
Save the `ledger_id` from the response. You'll need it to create balances for the card account.
[Create a customer identity](/reference/create-identity) to link all balances to the same customer identity:
```bash cURL wrap theme={"system"}
curl -X POST "http://localhost:5001/identities" \
-H "X-Blnk-Key: " \
-H "Content-Type: application/json" \
-d '{
"first_name": "Xavier",
"last_name": "Woods"
}'
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Identity.create({
first_name: 'Xavier',
last_name: 'Woods',
});
```
```go Go wrap theme={"system"}
identity, resp, err := client.Identity.Create(blnkgo.Identity{
FirstName: "Xavier",
LastName: "Woods",
})
```
```python Python wrap theme={"system"}
response = blnk.identity.create({
"first_name": "Xavier",
"last_name": "Woods",
})
```
```java Java wrap theme={"system"}
ApiResponse response = blnk.identity().create(
IdentityData.create()
.firstName("Xavier")
.lastName("Woods"));
```
```bash Blnk CLI wrap theme={"system"}
blnk identities create
```
Save the `identity_id` from the response. You'll use this ID to link all balances to this customer.
[Create a balance](/reference/create-balance) for the card account. This balance will track all card transactions:
```bash cURL wrap expandable theme={"system"}
curl -X POST "http://localhost:5001/balances" \
-H "X-Blnk-Key: " \
-H "Content-Type: application/json" \
-d '{
"ledger_id": "",
"identity_id": "",
"currency": "USD",
"meta_data": {
"last_4_digits": "1234",
"card_scheme": "visa",
"type": "virtual",
"card-id": "card-id-1234"
}
}'
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.LedgerBalances.create({
ledger_id: '',
identity_id: '',
currency: 'USD',
meta_data: {
last_4_digits: '1234',
card_scheme: 'visa',
type: 'virtual',
'card-id': 'card-id-1234',
},
});
```
```go Go wrap theme={"system"}
balance, resp, err := client.LedgerBalance.Create(blnkgo.CreateLedgerBalanceRequest{
LedgerID: "",
IdentityID: "",
Currency: "USD",
MetaData: blnkgo.MetaData{
"last_4_digits": "1234",
"card_scheme": "visa",
"type": "virtual",
"card-id": "card-id-1234",
},
})
```
```python Python wrap theme={"system"}
response = blnk.ledger_balances.create({
"ledger_id": "",
"identity_id": "",
"currency": "USD",
"meta_data": {
"last_4_digits": "1234",
"card_scheme": "visa",
"type": "virtual",
"card-id": "card-id-1234",
},
})
```
```java Java wrap theme={"system"}
ApiResponse response = blnk.ledgerBalances().create(
CreateLedgerBalance.create()
.ledgerId("")
.identityId("")
.currency("USD")
.metaData(Map.of(
"last_4_digits", "1234",
"card_scheme", "visa",
"type", "virtual",
"card-id", "card-id-1234"
)));
```
```bash Blnk CLI wrap theme={"system"}
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](/transactions/inflight/creating-inflight).
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 here](https://map.blnkfinance.xyz/FwsQD41GqU)
The 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 to authorize the payment. Setting `inflight = true` puts the transaction in a pending state until it's settled or voided.
```bash cURL wrap theme={"system"}
curl -X POST "http://localhost:5001/transactions" \
-H "X-Blnk-Key: " \
-H "Content-Type: application/json" \
-d '{
"precise_amount": 200000,
"precision": 100,
"currency": "USD",
"reference": "",
"source": "",
"destination": "@World-USD",
"description": "Card transaction",
"inflight": true
}'
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Transactions.create({
precise_amount: 200000,
precision: 100,
currency: 'USD',
reference: '',
source: '',
destination: '@World-USD',
description: 'Card transaction',
inflight: true,
});
```
```go Go wrap theme={"system"}
transaction, resp, err := client.Transaction.Create(blnkgo.CreateTransactionRequest{
ParentTransaction: blnkgo.ParentTransaction{
PreciseAmount: big.NewInt(200000),
Precision: 100,
Currency: "USD",
Reference: "",
Source: "",
Destination: "@World-USD",
Description: "Card transaction",
},
Inflight: true,
})
```
```python Python wrap theme={"system"}
response = blnk.transactions.create({
"precise_amount": 200000,
"precision": 100,
"currency": "USD",
"reference": "",
"source": "",
"destination": "@World-USD",
"description": "Card transaction",
"inflight": True,
})
```
```java Java wrap theme={"system"}
ApiResponse response = blnk.transactions().create(
CreateTransactions.create()
.preciseAmount(200000)
.precision(100)
.currency("USD")
.reference("")
.source("")
.destination("@World-USD")
.description("Card transaction")
.inflight(true));
```
```bash Blnk CLI wrap theme={"system"}
blnk transactions create
```
`@World-USD` is an [internal balance](/balances/internal-balances) 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.
If you use the [queue](/guides/concurrency#queueing-transactions), 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](/guides/hot-balances).
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.
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](/transactions/transaction-lifecycle) from `INFLIGHT` (pending) to `APPLIED` (completed).
If it was rejected or cancelled, you can void the transaction instead.
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.
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.
Commit the inflight transaction. This turns the transaction from `INFLIGHT` (pending) to `APPLIED` (completed).
```bash cURL wrap theme={"system"}
curl -X PUT "http://localhost:5001/transactions/inflight/" \
-H "X-Blnk-Key: " \
-H "Content-Type: application/json" \
-d '{
"status": "commit"
}'
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Transactions.updateStatus('', {
status: 'commit',
});
```
```go Go wrap theme={"system"}
txn, resp, err := client.Transaction.Update("", blnkgo.UpdateStatus{
Status: blnkgo.InflightStatusCommit,
})
```
```python Python wrap theme={"system"}
response = blnk.transactions.update_status("", {
"status": "commit",
})
```
```java Java wrap theme={"system"}
ApiResponse response = blnk.transactions().updateStatus(
"",
UpdateTransactionStatus.create()
.status("commit"));
```
```bash Blnk CLI wrap theme={"system"}
blnk transactions update --commit
```
Void the inflight transaction instead of committing it, and release the reserved amount back to the customer.
```bash cURL wrap theme={"system"}
curl -X PUT "http://localhost:5001/transactions/inflight/" \
-H "X-Blnk-Key: " \
-H "Content-Type: application/json" \
-d '{
"status": "void"
}'
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Transactions.updateStatus('', {
status: 'void',
});
```
```go Go wrap theme={"system"}
txn, resp, err := client.Transaction.Update("", blnkgo.UpdateStatus{
Status: blnkgo.InflightStatusVoid,
})
```
```python Python wrap theme={"system"}
response = blnk.transactions.update_status("", {
"status": "void",
})
```
```java Java wrap theme={"system"}
ApiResponse response = blnk.transactions().updateStatus(
"",
UpdateTransactionStatus.create()
.status("void"));
```
```bash Blnk CLI wrap theme={"system"}
blnk transactions update --void
```
***
## 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
***
Get dedicated support for architecture reviews, integration planning, ledger workflows, and production deployment.
***
[Explore the map yourself here](https://map.blnkfinance.xyz/FwsQD41GqU)
The transaction is created with `inflight: true`, so it remains pending until the payment processor clears it (or the transaction is voided).
The transaction status changes from `INFLIGHT` to `APPLIED`, completing the transfer.