Guides
Service statusPluggy.aiLogin

Recurring Payments Analysis

Suggest Edits

We offer a Recurring Payments API that allows you to identify a user's repeating expenses (like rent, service bills) and repeating incomes (like salary), useful for financial profiling. You can analyze an item's transactions and find out which ones repeat, how regular that repetition is, and the average amount of the repeating transaction.

📘

Categorization Feature required

To use this API you will need the Categorization feature enabled for your client. It is enabled by default during trial period. After that, it is an opt-in premium feature.

Please contact our Sales team if you want to enable it!

Using the Recurring Payments API

  1. Obtain an API key from our Auth endpoint.
  2. Use the recurring Payments endpoint with the obtained API key (as the X-API-Key header), and specify an Item ID in the request body:
{
  "itemId": "aaaaaaa1-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
}
  1. The response will look something like this:


{
    "recurringPayments": [
        {
            "description": "debito aut conta agua e esgoto sabesp",
            "averageAmount": -76.78,
            "occurrences": [
                "77777777-8888-9999-0000-111111111111",
                "88888888-9999-0000-1111-222222222222",
                "99999999-0000-1111-2222-333333333333"
            ],
            "regularityScore": 0.997773784382727
        },
        {
            "description": "ebn spotify",
            "averageAmount": 21.9,
            "occurrences": [
                "aaaaaaa1-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
                "bbbbbbb1-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
                "ccccccc1-cccc-cccc-cccc-cccccccccccc",
                "ddddddd1-dddd-dddd-dddd-dddddddddddd",
                "eeeeeee1-eeee-eeee-eeee-eeeeeeeeeeee",
                "fffffff1-ffff-ffff-ffff-ffffffffffff",
                "11111111-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
                "22222222-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
                "33333333-cccc-cccc-cccc-cccccccccccc",
                "44444444-dddd-dddd-dddd-dddddddddddd",
                "55555555-eeee-eeee-eeee-eeeeeeeeeeee",
                "66666666-ffff-ffff-ffff-ffffffffffff"
            ],
            "regularityScore": 0.9344445222642911
        },
        {
            "description": "mp camisetadepre",
            "averageAmount": 8.57,
            "occurrences": [
                "99999999-cccc-cccc-cccc-cccccccccccc",
                "00000000-dddd-dddd-dddd-dddddddddddd",
                "aaaaaaa3-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
                "bbbbbbb3-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
                "ccccccc3-cccc-cccc-cccc-cccccccccccc",
                "ddddddd3-dddd-dddd-dddd-dddddddddddd"
            ],
            "regularityScore": 0.9199999999999999
        },
        {
            "description": "niazi chohfi textil",
            "averageAmount": 20.12,
            "occurrences": [
                "eeeeeee3-eeee-eeee-eeee-eeeeeeeeeeee",
                "fffffff3-ffff-ffff-ffff-ffffffffffff",
                "11111113-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
                "22222222-bbbb-bbbb-bbbb-bbbbbbbbbbbb"
            ],
            "regularityScore": 0.9528595479208968
        }
    ]
}

regularityScore is a value between 0 and 1, indicating how consistent the payments are in terms of timing and amount. A higher score means more regular payments.

Considerations

  • Amount Significance: Negative amounts represent debits (expenses), and positive amounts represent credits (income). Ensure that transaction amounts are correctly signed to get accurate results.
  • Normalization: Transaction descriptions are normalized by converting to lowercase and removing special characters and extra whitespace.
  • Minimum Occurrences: A payment must occur at least three times to be considered recurring.
    Interval Consistency: Payments must occur at consistent intervals (approximately monthly, within a 30 ±5 day range).
  • Amount Variance: The variance in transaction amounts must be less than or equal to 10% to be considered consistent.

📘

Customized analysis

If you are interested in a more custom user analysis, please contact our Sales team so we can work on it together!

Updated 8 days ago