Building with transaction data
Not every line is a purchase: transfers, refunds, fees and declines
A spending chart that counts a salary, a refund or a declined payment is wrong in a way users notice. How to tell those lines apart, and what to do with each.
Written for: Developers 3 min read Updated
The quickest way to lose a user's trust in a spending chart is to count something that is not spending. A salary transfer shown as "income from Ahmed", a refund counted as a second purchase, a declined payment in this month's total, a card repayment as a huge "shopping" bill. Each of these comes from treating every line as a purchase. This guide covers the line types to separate, how to recognise them, and what to do with each.
Five kinds of line
| Kind | What it is | In a spending total |
|---|---|---|
purchase | A payment to a merchant, even one nobody can identify. | Count it. |
refund | Money back from a merchant: a return, a cancelled order. | Subtract it from that merchant. |
declined | A payment that did not go through. No money moved. | Never count it. |
transfer | Money between people or accounts: transfers, wallet top-ups, salary. | Leave it out of spending; show it separately. |
bank | A line the bank wrote itself: fees, interest, cashback, cash withdrawals, card repayments. | Fees and interest are costs; repayments are not spending. |
Transfers
Transfer lines are the most sensitive. They often contain a person's name, a phone number or an account number, and they look superficially like merchant lines. A system that tries to identify a merchant in "TRANSFER TO MOHAMED HASSAN" will, sooner or later, match a person to a business with a similar name, and show it to your user.
INSTAPAY TRANSFER TO 01xxxxxxxx9
- INSTAPAY TRANSFER
- Egypt's instant payment network: money to another person or account.
- TO 01xxxxxxxx9
- The recipient's mobile number. Personal data, not a merchant.
Wallet top-ups (moving card money into Vodafone Cash, PayPal or a prepaid card) are transfers to yourself. The spending happens later, from the wallet, and often never reaches the card statement at all.
Lines the bank writes
Fees, interest, cashback, cash withdrawals and card repayments are written by the bank, in its own wording, and usually have no merchant. Two are worth special care:
- Cashback and rewards often mention the merchant they relate to: "CASHBACK FOR YOUR TALABAT ORDER". That merchant is related to the line, but it is not the merchant of the line. Link them; do not count the cashback as a Talabat purchase.
- Instalment and loan repayments name the lender or plan. They are repayments of earlier spending, so counting them as new spending doubles it.
Refunds and reversals
A refund usually carries the merchant's name and a word such as REFUND, REVERSAL or CREDIT, or simply appears with the opposite sign. Pair it with the original purchase where you can, and net the two in category totals. Refunds can arrive weeks later and in a different month; showing them against the original month's spending is clearer for users than a "negative shopping" month.
Declined payments
Some statements and most banking apps show declined attempts, with words like DECLINED, FAILED or INSUFFICIENT. They are useful to show (they explain a failed checkout) and must never be in totals. They also tend to repeat: a user trying three times does not mean three purchases.
Field note
In the statements we read, the lines that most often distort a spending summary are not exotic. They are card repayments counted as purchases and cashback counted as spending at the merchant it mentions. Both are bank-written lines that happen to contain a familiar word.
How DescriptorAPI marks them
Every result has a kind: purchase, refund, declined, transfer or bank. We do not guess a merchant for transfers and bank lines, so a person's name in a transfer is not turned into a business. A bank line that mentions a merchant, like the cashback example, carries it in related, so you can link it without counting it. The enrich reference lists the fields.
A sensible default for a spending view: count purchases, subtract refunds, ignore declines, list transfers separately, and show fees and interest as their own costs.