Recurring Payments
With Ntropy Recurring Payments, you can extract all recurring payments from your customers' bank transactions.
Getting Started​
The first step is to add the entire transaction history of an account holder using Ntropy enrichment. If you have previously added these transactions, you do not need to add them again.
Once transactions have been added, the recurring payments can be retrieved:
- cURL
- Python SDK
$ curl \
-H "X-API-KEY: <YOUR-API-KEY>" \
-H "Content-Type: application/json" \
-X POST \
https://api.ntropy.com/v2/account-holder/<account_holder_id>/recurring-payments
from ntropy_sdk import SDK
sdk = SDK("<YOUR-API-KEY>")
recurring_payments = sdk.get_recurring_payments(<account_holder_id>)
You will get back a list of recurring payment groups:
- Table
- JSON
latest_payment_amount | merchant | website | periodicity | first_payment_date | latest_payment_date | next_expected_payment_date | type | is_essential | is_active | logo | transaction_ids | latest_payment_description | total_amount | iso_currency_code | |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
0 | 17.99 | Netflix | netflix.com | monthly | 2022-01-01 | 2022-04-01 | 2022-05-01 | subscription | False | True | https://logos.ntropy.com/netflix.com | tx-4, tx-3, tx-2, tx-1 | Recurring Debit Purchase Card 1350 #6063924 netflix.com Netflix.com CA | 71.96 | USD |
1 | 11.99 | Dropbox | dropbox.com | monthly | 2022-03-15 | 2022-03-15 | 2022-04-15 | subscription | False | True | https://logos.ntropy.com/dropbox.com | tx-8 | DROPBOX*RJXZ4L113B58 DROPBOX.COM CA 03/15 | 11.99 | USD |
2 | 9.99 | Spotify | spotify.com | monthly | 2022-01-15 | 2022-03-15 | 2022-04-15 | subscription | False | True | https://logos.ntropy.com/spotify.com | tx-7, tx-6, tx-5 | SPOTIFY 877-778-1161 NY S582210783453432 CARD 3373 | 29.97 | USD |
3 | 100 | Consolidated Edison | coned.com | monthly | 2022-01-01 | 2022-03-01 | 2022-04-01 | bill | True | True | https://logos.ntropy.com/coned.com | tx-14, tx-13, tx-12 | Consolidated Edison | 300.0 | USD |
4 | 1000 | Avesta Housing | avestahousing.org | monthly | 2022-01-01 | 2022-03-01 | 2022-04-01 | bill | True | True | https://logos.ntropy.com/consumer_icons-housing-rent | tx-11, tx-10, tx-9 | Payment from Avesta Housing | 3000.0 | USD |
[
{
"latest_payment_amount": 17.99,
"first_payment_date": "2022-01-01",
"iso_currency_code": "USD",
"is_active": true,
"is_essential": false,
"labels": ["entertainment", "television", "subscriptions"],
"latest_payment_date": "2022-04-01",
"latest_payment_description": "Recurring Debit Purchase Card 1350 #6063924 netflix.com Netflix.com CA",
"logo": "https://logos.ntropy.com/netflix.com",
"merchant": "Netflix",
"next_expected_payment_date": "2022-05-01",
"periodicity": "monthly",
"total_amount": 71.96,
"transaction_ids": ["tx-4", "tx-3", "tx-2", "tx-1"],
"type": "subscription",
"website": "netflix.com"
},
{
"latest_payment_amount": 11.99,
"first_payment_date": "2022-03-15",
"iso_currency_code": "USD",
"is_active": true,
"is_essential": false,
"labels": ["goods", "software", "subscriptions"],
"latest_payment_date": "2022-03-15",
"latest_payment_description": "DROPBOX*RJXZ4L113B58 DROPBOX.COM CA 03/15",
"logo": "https://logos.ntropy.com/dropbox.com",
"merchant": "Dropbox",
"next_expected_payment_date": "2022-04-15",
"periodicity": "monthly",
"total_amount": 11.99,
"transaction_ids": ["tx-8"],
"type": "subscription",
"website": "dropbox.com"
},
{
"latest_payment_amount": 9.99,
"first_payment_date": "2022-01-15",
"iso_currency_code": "USD",
"is_active": true,
"is_essential": false,
"labels": ["entertainment", "music", "subscriptions"],
"latest_payment_date": "2022-03-15",
"latest_payment_description": "SPOTIFY 877-778-1161 NY S582210783453432 CARD 3373",
"logo": "https://logos.ntropy.com/spotify.com",
"merchant": "Spotify",
"next_expected_payment_date": "2022-04-15",
"periodicity": "monthly",
"total_amount": 29.97,
"transaction_ids": ["tx-7", "tx-6", "tx-5"],
"type": "subscription",
"website": "spotify.com"
},
{
"latest_payment_amount": 100.0,
"first_payment_date": "2022-01-01",
"iso_currency_code": "USD",
"is_active": true,
"is_essential": true,
"labels": ["utilities", "electric"],
"latest_payment_date": "2022-03-01",
"latest_payment_description": "Consolidated Edison",
"logo": "https://logos.ntropy.com/coned.com",
"merchant": "Consolidated Edison",
"next_expected_payment_date": "2022-04-01",
"periodicity": "monthly",
"total_amount": 300.0,
"transaction_ids": ["tx-14", "tx-13", "tx-12"],
"type": "bill",
"website": "coned.com"
},
{
"latest_payment_amount": 1000.0,
"first_payment_date": "2022-01-01",
"iso_currency_code": "USD",
"is_active": true,
"is_essential": true,
"labels": ["housing", "rent"],
"latest_payment_date": "2022-03-01",
"latest_payment_description": "Payment from Avesta Housing",
"logo": "https://logos.ntropy.com/consumer_icons-housing-rent",
"merchant": "Avesta Housing",
"next_expected_payment_date": "2022-04-01",
"periodicity": "monthly",
"total_amount": 3000.0,
"transaction_ids": ["tx-11", "tx-10", "tx-9"],
"type": "bill",
"website": "avestahousing.org"
}
]
Each output field within the response is explained below.
attribute | type | summary |
---|---|---|
latest_payment_amount | float | Amount of the latest recurring payment in this group. |
merchant | string | Normalized merchant name (if a merchant is present). |
website | string | Website of the merchant (if a merchant is present). |
logo | url | Logo of the merchant (if a merchant is present). |
labels | list(string) | Label from our live hierarchy (consumer). |
periodicity | enum | Time between payments in the recurring payments group; weekly , bi-weekly , monthly , bi-monthly , quarterly , semi-yearly , yearly , other (based on the mode interval between two sequential payments). |
first_payment_date | date | Date of the first recurring payment for this group. |
latest_payment_date | date | Date of the most recent recurring payment for this group. |
next_expected_payment_date | date | Date of the next expected recurring payment for this group. This is determined by adding up the periodicity to the latest latestpayment_date. (null _ if group is inactive). |
latest_payment_description | string | Description of the most recent recurring payment for this group. |
type | string | Type of recurring payments. Can be one of: subscription - subscriptions like Netflix, DropBox, Spotify etc. bill - recurring bills such as electricity bills or rent bills. |
is_essential | boolean | Indicates whether the recurring payments are essential (e.g. rent, tax payments, transportation subscription), or non-essential (discretionary spending e.g. music streaming, gym subscription). |
is_active | boolean | Indicates whether the recurring payments group is still active. This is determined by checking whether the next_expected_payment_date is in the future compared to the latest payment date of the account holder. |
transaction_ids | list(string) | Ids of transactions that belong to this recurring payments group. |
transactions | list(Transaction) | Returns a list of the transactions that belong to this recurring payments group (SDK only). |
total_amount | float | Total amount of the recurring payments during the period between first_payment_date and latest_payment_date. |
iso_currency_code | string | Currency of the recurring payments in ISO-4217 format. See supported options. |
Example Code​
from ntropy_sdk import SDK, Transaction
import uuid
sdk = SDK("<YOUR-API-KEY>")
account_holder_id = str(uuid.uuid4())
transactions = [
("2021-01-01", 17.99, "Recurring Debit Purchase Card 1350 #3233432 netflix.com Netflix.com CA",),
("2021-02-01", 17.99, "Recurring Debit Purchase Card 1350 #4248423 netflix.com Netflix.com CA"),
("2021-03-01", 17.99, "Recurring Debit Purchase Card 1350 #5364213 netflix.com Netflix.com CA"),
("2021-04-01", 17.99, "Recurring Debit Purchase Card 1350 #6063924 netflix.com Netflix.com CA"),
("2021-01-15", 17.24, "SPOTIFY 877-778-1161 NY S582210763326751 CARD 3373"),
("2021-02-15", 17.24, "SPOTIFY 877-778-1161 NY S582210773412353 CARD 3373"),
("2021-03-15", 17.24, "SPOTIFY 877-778-1161 NY S582210783453432 CARD 3373"),
("2021-03-15", 11.99, "DROPBOX*RJXZ4L113B58 DROPBOX.COM CA 03/15"),
("2021-01-01", 100.0, "Consolidated Edison"),
("2021-02-01", 100.0, "Consolidated Edison"),
("2021-03-01", 100.0, "Consolidated Edison"),
("2021-01-01", 1000.0, 'Payment from Avesta Housing'),
("2021-02-01", 1000.0, 'Payment from Avesta Housing'),
("2021-03-01", 1000.0, 'Payment from Avesta Housing'),
]
transactions = [
Transaction(
date=tx[0],
amount=tx[1],
description=tx[2],
entry_type="debit",
iso_currency_code="USD",
transaction_id=f"tx-{i}",
account_holder_type="consumer",
account_holder_id=account_holder_id,
)
for i, tx in enumerate(transactions)
]
enriched_transactions = sdk.add_transactions(transactions)
recurring_payments = sdk.get_recurring_payments(account_holder_id)
print(recurring_payments)
Utility functions
The SDK provides a few utility functions that can be used to help with filtering the recurring payments.
# returns a list of subscriptions
recurring_payments.subscriptions()
# returns a list of active subscriptions
recurring_payments.subscriptions().active()
# returns a list of past subscriptions which are not active anymore
recurring_payments.subscriptions().inactive()
# returns a list of bills
recurring_payments.recurring_bills()
# returns a list of essential recurring payments
recurring_payments.essential()
# returns a list of non-essential recurring payments
recurring_payments.non_essential()