> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blnkfinance.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Building an Online Card Payment System
> Learn how to implement online card payments with authorization and settlement phases using inflight transactions.
## Overview
In this tutorial, you’ll learn how to model online card payments using Blnk.
We cover the full 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 when 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 a customer makes a purchase with a card, the following happens:
1. **Authorization:** When your customer tries to pay, the card network asks your system if the customer has enough balance. If yes, you reserve that amount and create an inflight transaction. The money is not taken yet, only held.
2. **Settlement:** A few hours or days later, the payment processor sends the final confirmation.
* If the transaction is approved, you deduct the money from the customer’s balance and commit the transaction in your ledger.
* If it is declined or reversed, you release the reserved amount 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) 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 theme={"system"}
curl --request POST \
--url http://localhost:5001/ledgers \
--header 'X-blnk-key: ' \
--header 'Content-Type: application/json' \
--data '{
"name": "Customers Card Ledger"
}'
```
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 theme={"system"}
curl --request POST \
--url http://localhost:5001/identities \
--header 'X-blnk-key: ' \
--header 'Content-Type: application/json' \
--data '{
"first_name": "Xavier",
"last_name": "Woods"
}'
```
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 theme={"system"}
curl --request POST \
--url http://localhost:5001/balances \
--header 'X-blnk-key: ' \
--header 'Content-Type: application/json' \
--data '{
"ledger_id": "",
"identity_id": "",
"currency": "USD",
"meta_data": {
"last_4_digits": "1234",
"card_scheme": "visa",
"type": "virtual",
"card-id": "card-id-1234"
}
}'
```
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-transactions).
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`, which means it's pending until the payment processor clears it.
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 theme={"system"}
curl --request POST \
--url http://localhost:5001/transactions \
--header 'X-blnk-key: ' \
--header 'Content-Type: application/json' \
--data '{
"amount": 2000,
"precision": 100,
"currency": "USD",
"reference": "",
"source": "",
"destination": "@World-USD",
"description": "Card transaction",
"inflight": true
}'
```
`@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.
Your transaction will be recorded successfully and it will be in `INFLIGHT` status (pending a commit or void action).
When a transaction is inflight, the amount is reserved and cannot be used for anything else until it’s settled or voided.
Blnk handles this automatically. Every inflight transaction reduces the customer’s available balance. If the available balance isn’t enough to cover a new transaction, the new one is rejected.
For example:
* Customer balance: \$5,000
* One inflight transaction: \$2,000
* Available balance: \$3,000
Any new transaction above \$3,000 will fail. This ensures you never spend money that has already been 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.
Commit the inflight transaction from the authorization step once clearing is received. This turns the transaction from `INFLIGHT` (pending) to `APPLIED` (completed):
```bash cURL theme={"system"}
curl --request PUT \
--url http://localhost:5001/transactions/inflight/ \
--header 'X-blnk-key: ' \
--header 'Content-Type: application/json' \
--data '{
"status": "commit"
}'
```
If a transaction is rejected or cancelled, you can void it instead of committing it:
```bash cURL theme={"system"}
curl --request PUT \
--url http://localhost:5001/transactions/inflight/ \
--header 'X-blnk-key: ' \
--header 'Content-Type: application/json' \
--data '{
"status": "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
***
## Can't find your use case?
If you’re searching for a specific tutorial that isn’t included here, you’re welcome to [contribute to our documentation](https://github.com/blnkfinance/blnk-docs/tree/main/tutorials) by sharing your expertise or requesting a new tutorial in [our Discord community](https://discord.gg/7WNv94zPpx).
We’re always thrilled to expand our resources with the help of our developer community!