Skip to main content

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 \
-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

You will get back a list of recurring payment groups:

latest_payment_amountmerchantwebsiteperiodicityfirst_payment_datelatest_payment_datenext_expected_payment_datetypeis_essentialis_activelogotransaction_idslatest_payment_descriptiontotal_amountiso_currency_code
017.99Netflixnetflix.commonthly2022-01-012022-04-012022-05-01subscriptionFalseTruehttps://logos.ntropy.com/netflix.comtx-4, tx-3, tx-2, tx-1Recurring Debit Purchase Card 1350 #6063924 netflix.com Netflix.com CA71.96USD
111.99Dropboxdropbox.commonthly2022-03-152022-03-152022-04-15subscriptionFalseTruehttps://logos.ntropy.com/dropbox.comtx-8DROPBOX*RJXZ4L113B58 DROPBOX.COM CA 03/1511.99USD
29.99Spotifyspotify.commonthly2022-01-152022-03-152022-04-15subscriptionFalseTruehttps://logos.ntropy.com/spotify.comtx-7, tx-6, tx-5SPOTIFY 877-778-1161 NY S582210783453432 CARD 337329.97USD
3100Consolidated Edisonconed.commonthly2022-01-012022-03-012022-04-01billTrueTruehttps://logos.ntropy.com/coned.comtx-14, tx-13, tx-12Consolidated Edison300.0USD
41000Avesta Housingavestahousing.orgmonthly2022-01-012022-03-012022-04-01billTrueTruehttps://logos.ntropy.com/consumer_icons-housing-renttx-11, tx-10, tx-9Payment from Avesta Housing3000.0USD

Each output field within the response is explained below.

attributetypesummary
latest_payment_amountfloatAmount of the latest recurring payment in this group.
merchantstringNormalized merchant name (if a merchant is present).
websitestringWebsite of the merchant (if a merchant is present).
logourlLogo of the merchant (if a merchant is present).
labelslist(string)Label from our live hierarchy (consumer).
periodicityenumTime 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_datedateDate of the first recurring payment for this group.
latest_payment_datedateDate of the most recent recurring payment for this group.
next_expected_payment_datedateDate 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_descriptionstringDescription of the most recent recurring payment for this group.
typestringType 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_essentialbooleanIndicates 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_activebooleanIndicates 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_idslist(string)Ids of transactions that belong to this recurring payments group.
transactionslist(Transaction)Returns a list of the transactions that belong to this recurring payments group (SDK only).
total_amountfloatTotal amount of the recurring payments during the period between first_payment_date and latest_payment_date.
iso_currency_codestringCurrency 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()