1 of 5

Card counting and summing groups

In this set of examples, you can learn how to create a counting and summing group to set up tiered pricing in card price lists. You will find the excerpt of transaction group parameters to know when managing the counting and summing groups, followed by links to associated example API calls.

Transaction group parameters

transactionGroupingCode: Unique transaction grouping code. Note: Must contain only upper case letters, numbers and underscores. Must start with a letter and not end with underscore. Double underscores are not allowed.

groupingType: Possible values SUM, COUNT
- SUM - transaction amounts are aggregated
- COUNT - transactions are counted
aggregationLevel: Defines the length of the aggregation period. Possible values MONTHLY, YEARLY
- MONTHLY - Aggregation is restarted when the first transaction is received at the beginning of the new calendar month.
- YEARLY - Aggregation is restarted when the first transaction is received at the beginning of the new calendar year.
aggregationScope: Possible values ACCOUNT, CARD
- ACCOUNT - aggregated amount is calculated based on all cards related to one and the same account
- CARD - Aggregated amount per card. Calculation is reset when card is replaced or renewed.
includeReservations: Flag indicating whether transaction is counted already when authorisation message is received or not.
- true - Transactions are aggregated when authorisation is approved.
- false - Transactions are aggregated when clearing data is processed.
enabled: A flag indicating whether this transaction grouping rule is currently active or not.
transactionTypeCodes: A list of transactions types that needs to be aggregated.

Create counting group

You need to create a counting group to set up price tiers for:

count range-based pricing, or
amount range-based pricing with a count threshold.

In card price lists, you can select the created counting group as a reference for tiered pricing.

Use case

In this example, we will set up a counting group that counts ATM cash withdrawal transactions during the authorisation stage.

Use case data

API parameters with values

Unique name for transaction grouping.

The number of transactions is counted.

Aggregation restarts at the beginning of each month.

Transactions made with different cards using the same account are aggregated.

Transactions are aggregated at the authorisation stage, when authorisation request or advice is approved (and account reservation or account transaction is created).

Transaction grouping is enabled.

List of transaction types that are aggregated.

Sample API call

To create a new counting group, make the following API call:

Sample request

The sample request body is as follows:

{
      "transactionGroupingCode": "MONTHLY_WITHDRAWAL_COUNT_V",
      "groupingType": "COUNT",
      "aggregationLevel": "MONTHLY",
      "aggregationScope": "ACCOUNT",
      "includeReservations": true,
      "enabled": true,
      "transactionTypeCodes": [
        "ATM_WITHDRAWAL"
      ]

curl --location 'https://card-api.sandbox.tuumplatform.com/api/v1/transaction-grouping' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiTGlpdmEgS2FzdCIsImVtcGxveWVlSWQiOiJJRC0xMjU4IiwidGVuYW50Q29kZSI6Ik1CLkVVIiwiZXhwaXJ5RFRpbWUiOiIyMDI1LTAzLTA1VDE0OjMwOjEyIiwiZXhwIjoxNzQxMTg1MDEyLCJyb2xlcyI6WyJGVUxMX0NBUkRfTUFOQUdFTUVOVCIsIlNZU1RFTSJdfQ.ZVincGpeLedTc1UtbjFefr-V7n8G3QVOn63FimgVPhM' \
--header 'Content-Type: application/json' \
--data '{
      "transactionGroupingCode": "MONTHLY_WITHDRAWAL_COUNT_V",
      "groupingType": "COUNT",
      "aggregationLevel": "MONTHLY",
      "aggregationScope": "ACCOUNT",
      "includeReservations": true,
      "enabled": true,
      "transactionTypeCodes": [
        "ATM_WITHDRAWAL"
      ]
}'

Sample response

Below you will find the response to the API request:

Response

{
    "errors": null,
    "validationErrors": null,
    "data": null
}

Result

We have created a new counting group, MONTHLY_WITHDRAWAL_COUNT_V, that counts ATM cash withdrawal transactions during the authorisation stage.

Create summing group

You need to create a summing group to set up price tiers for:

amount range-based pricing, or
amount range-based pricing with a count threshold.

In card price lists, you can select the created summing group as a reference for tiered pricing.

Use case

In this example, we will set up a summing group that counts ATM cash withdrawal transactions during the authorisation stage.

Use case data

API parameters with values

Unique name for transaction grouping.

The number of transactions is counted.

Aggregation restarts at the beginning of each month.

Transactions made with different cards using the same account are aggregated.

Transactions are aggregated at the authorisation stage, when authorisation request or advice is approved (and account reservation or account transaction is created).

Transaction grouping is enabled.

List of transaction types that are aggregated.

Sample API call

To create a new summing group, make the following API call:

{
      "transactionGroupingCode": "MONTHLY_WITHDRAWAL_SUM_V",
      "groupingType": "SUM",
      "aggregationLevel": "MONTHLY",
      "aggregationScope": "ACCOUNT",
      "includeReservations": true,
      "enabled": true,
      "transactionTypeCodes": [
        "ATM_WITHDRAWAL"
      ]
}

curl --location 'https://card-api.sandbox.tuumplatform.com/api/v1/transaction-grouping' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiT2ZmaWNlciBUZXN0IiwiZW1wbG95ZWVJZCI6IklELTEyMzgiLCJ0ZW5hbnRDb2RlIjoiTUIuRVUiLCJleHBpcnlEVGltZSI6IjIwMjUtMDMtMDVUMTU6MTI6MjAiLCJleHAiOjE3NDExODc1NDAsInJvbGVzIjpbIkFETUlOIl19.eYVmh9G6G55iOvmTUmDM0XBwQe5YT3UsCsyf0YQDFaw' \
--header 'Content-Type: application/json' \
--data '{
      "transactionGroupingCode": "MONTHLY_WITHDRAWAL_SUM_V",
      "groupingType": "SUM",
      "aggregationLevel": "MONTHLY",
      "aggregationScope": "ACCOUNT",
      "includeReservations": true,
      "enabled": true,
      "transactionTypeCodes": [
        "ATM_WITHDRAWAL"
      ]
}'

Sample response

Below you will find the response to the API request:

Response

{
    "errors": null,
    "validationErrors": null,
    "data": null
}

Result

We have created a new summing group, MONTHLY_WITHDRAWAL_SUM_V, to summarise ATM cash withdrawal transactions during the authorisation stage.

Find counting values for card

Suppose you want to know the number of cash withdrawals in the current period, use the get-aggregated-data API endpoint.

Use case

In this example, we will get the current counting value of an assigned counting group for a particular card.

Use case data

API parameters with values

Search for aggregation data of

...get-aggregation-data?

transaction grouping MONTHLY_WITHDRAWAL_COUNT and

transactionGroupingCode=MONTHLY_WITHDRAWAL_COUNT

related to card C001692281754

&cardId=C001692281754

Aggregation data is related to the card if aggregationScope for transaction grouping is CARD.

Sample API call

To retrieve the current counting value of an assigned counting group for a particular card, make the following API call.

Sample request

Below is an example request of the API call to retrieve the current counting value of an assigned counting group for a particular card.

No request body.

curl --location 'https://card-api.sandbox.tuumplatform.com/api/v1/get-aggregation-data?transactionGroupingCode=MONTHLY_WITHDRAWAL_COUNT&cardId=C001692281754' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiTGlpdmEgS2FzdCIsImVtcGxveWVlSWQiOiJJRC0xMjU4IiwidGVuYW50Q29kZSI6Ik1CLkVVIiwiZXhwaXJ5RFRpbWUiOiIyMDI1LTAzLTA2VDEwOjI3OjMzIiwiZXhwIjoxNzQxMjU2ODUzLCJyb2xlcyI6WyJGVUxMX0NBUkRfTUFOQUdFTUVOVCIsIlNZU1RFTSJdfQ.RcQOv2L6IwWbOQ4EJ7n_we68x0JQz0nLFHinCjV-hwU'

Sample response

Below you find an example response body to the API call above.

Response

{
  "errors": null,
  "validationErrors": null,
  "data": {
    "accountId": null,
    "cardId": "C001692281754",
    "transactionGroupingCode": "MONTHLY_WITHDRAWAL_COUNT",
    "currentTransactionAmount": {
      "amount": 0,
      "currencyCode": "EUR"
    },
    "currentTransactionCount": 3,
    "lastActualDate": "2030-10-19",
    "aggregationEvents": [
      {
        "directionCode": "IN",
        "transactionAmount": {
          "amount": 50,
          "currencyCode": "EUR"
        },
        "source": {
          "sourceName": "CARD.CARD_TRANSACTION",
          "sourceRef": "C001692280512"
        },
        "postingDate": "2030-10-17"
      },
      {
        "directionCode": "IN",
        "transactionAmount": {
          "amount": 150,
          "currencyCode": "EUR"
        },
        "source": {
          "sourceName": "CARD.CARD_TRANSACTION",
          "sourceRef": "C001692280513"
        },
        "postingDate": "2030-10-17"
      },
      {
        "directionCode": "IN",
        "transactionAmount": {
          "amount": 50,
          "currencyCode": "EUR"
        },
        "source": {
          "sourceName": "CARD.CARD_TRANSACTION",
          "sourceRef": "C001692280514"
        },
        "postingDate": "2030-10-17"
      },
      {
        "directionCode": "IN",
        "transactionAmount": {
          "amount": 150,
          "currencyCode": "EUR"
        },
        "source": {
          "sourceName": "CARD.CARD_TRANSACTION",
          "sourceRef": "C001692280515"
        },
        "postingDate": "2030-10-17"
      },
      {
        "directionCode": "OUT",
        "transactionAmount": {
          "amount": 50,
          "currencyCode": "EUR"
        },
        "source": {
          "sourceName": "CARD.CARD_TRANSACTION",
          "sourceRef": "C001692280512"
        },
        "postingDate": "2030-10-17"
      },
      {
        "directionCode": "IN",
        "transactionAmount": {
          "amount": 15,
          "currencyCode": "EUR"
        },
        "source": {
          "sourceName": "CARD.CARD_TRANSACTION",
          "sourceRef": "C001692280516"
        },
        "postingDate": "2030-10-17"
      },
      {
        "directionCode": "OUT",
        "transactionAmount": {
          "amount": 15,
          "currencyCode": "EUR"
        },
        "source": {
          "sourceName": "CARD.CARD_TRANSACTION",
          "sourceRef": "C001692280516"
        },
        "postingDate": "2030-10-19"
      }
    ]
  }
}

Result

The result of the API call is the dataset consisting of transactions count 3 and the related authorisation events.

The transaction count is calculated as the difference between received authorisation requests (IN) and authorisation reversals (OUT) for unsuccessful authorisations. In the current example, 5-2=3.

Find summing values for account

Suppose you want to know the total amount of cash withdrawals in the current period, use the get-aggregated-data API endpoint.

Use case

In this example, we will get the current summing value of an assigned summing group for a particular account.

Use case data

API parameters with values

Search for aggregation data of

...get-aggregation-data?

transaction grouping MONTHLY_ACCOUNT_WITHDRAWAL_SUM_Rand

transactionGroupingCode=MONTHLY_ACCOUNT_WITHDRAWAL_SUM_R

related to account C001718025430

&accountId=C001718025430

Aggregation data is related to the account if aggregationScope for transaction grouping is ACCOUNT.

Sample API call

To retrieve the current the current summing value of an assigned summing group for a particular account, make the following API call.

Sample request

Below is an example request of the API call to retrieve the current summing value of an assigned summing group for a particular account.

No request body.

curl --location 'https://card-api.sandbox.tuumplatform.com/api/v1/get-aggregation-data?transactionGroupingCode=MONTHLY_ACCOUNT_WITHDRAWAL_SUM_R&accountId=C001718025430' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiTGlpdmEgS2FzdCIsImVtcGxveWVlSWQiOiJJRC0xMjU4IiwidGVuYW50Q29kZSI6Ik1CLkVVIiwiZXhwaXJ5RFRpbWUiOiIyMDI1LTAzLTA3VDA4OjQxOjIyIiwiZXhwIjoxNzQxMzM2ODgyLCJyb2xlcyI6WyJGVUxMX0NBUkRfTUFOQUdFTUVOVCIsIlNZU1RFTSJdfQ.0HCEeLryRK5fPTCX11ieLY5C4YrSRg69946Af8Hsz4o'

Sample response

Below you find an example response body to the API call above.

Response

{
  "errors": null,
  "validationErrors": null,
  "data": {
    "accountId": "C001718025430",
    "cardId": null,
    "transactionGroupingCode": "MONTHLY_ACCOUNT_WITHDRAWAL_SUM_R",
    "currentTransactionAmount": {
      "amount": 50,
      "currencyCode": "EUR"
    },
    "currentTransactionCount": 0,
    "lastActualDate": "2028-12-25",
    "aggregationEvents": [
      {
        "directionCode": "IN",
        "transactionAmount": {
          "amount": 50,
          "currencyCode": "EUR"
        },
        "source": {
          "sourceName": "CARD.ACCOUNT_TRANSACTION",
          "sourceRef": "C001718027803"
        },
        "postingDate": "2028-12-25"
      },
      {
        "directionCode": "IN",
        "transactionAmount": {
          "amount": 10,
          "currencyCode": "EUR"
        },
        "source": {
          "sourceName": "CARD.CARD_TRANSACTION",
          "sourceRef": "C001718026304"
        },
        "postingDate": "2028-12-25"
      },
      {
        "directionCode": "OUT",
        "transactionAmount": {
          "amount": 10,
          "currencyCode": "EUR"
        },
        "source": {
          "sourceName": "CARD.CARD_TRANSACTION",
          "sourceRef": "C001718026304"
        },
        "postingDate": "2028-12-25"
      }
    ]
  }
}

Result

The result of the API call is the dataset consisting of transactions summing amount of 50 and the related authorisation events.

The transaction summing amount is calculated as the difference between received authorisation requests (IN) and authorisation reversals (OUT) for unsuccessful authorisations. In the current example, 50+10-10=50.

Create summing group

You need to create a summing group to set up price tiers for:

amount range-based pricing, or
amount range-based pricing with a count threshold.

In card price lists, you can select the created summing group as a reference for tiered pricing.

Use case

In this example, we will set up a summing group that counts ATM cash withdrawal transactions during the authorisation stage.

Use case data

API parameters with values

Unique name for transaction grouping.

"transactionGroupingCode": "MONTHLY_WITHDRAWAL_SUM_V"

The number of transactions is counted.

"groupingType": "SUM"

Aggregation restarts at the beginning of each month.

"aggregationLevel": "MONTHLY"

Transactions made with different cards using the same account are aggregated.

"aggregationScope": "ACCOUNT"

Transactions are aggregated at the authorisation stage, when authorisation request or advice is approved (and account reservation or account transaction is created).

"includeReservations": true

Transaction grouping is enabled.

"enabled": true

List of transaction types that are aggregated.

"transactionTypeCodes": [
        "ATM_WITHDRAWAL"
      ]

Sample API call

To create a new summing group, make the following API call:

https://card-api.sandbox.tuumplatform.com/api/v1/transaction-grouping

Learn more about endpoint in the Tuum developer portal.

{
      "transactionGroupingCode": "MONTHLY_WITHDRAWAL_SUM_V",
      "groupingType": "SUM",
      "aggregationLevel": "MONTHLY",
      "aggregationScope": "ACCOUNT",
      "includeReservations": true,
      "enabled": true,
      "transactionTypeCodes": [
        "ATM_WITHDRAWAL"
      ]
}

curl --location 'https://card-api.sandbox.tuumplatform.com/api/v1/transaction-grouping' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiT2ZmaWNlciBUZXN0IiwiZW1wbG95ZWVJZCI6IklELTEyMzgiLCJ0ZW5hbnRDb2RlIjoiTUIuRVUiLCJleHBpcnlEVGltZSI6IjIwMjUtMDMtMDVUMTU6MTI6MjAiLCJleHAiOjE3NDExODc1NDAsInJvbGVzIjpbIkFETUlOIl19.eYVmh9G6G55iOvmTUmDM0XBwQe5YT3UsCsyf0YQDFaw' \
--header 'Content-Type: application/json' \
--data '{
      "transactionGroupingCode": "MONTHLY_WITHDRAWAL_SUM_V",
      "groupingType": "SUM",
      "aggregationLevel": "MONTHLY",
      "aggregationScope": "ACCOUNT",
      "includeReservations": true,
      "enabled": true,
      "transactionTypeCodes": [
        "ATM_WITHDRAWAL"
      ]
}'

Sample response

Below you will find the response to the API request:

Response

{
    "errors": null,
    "validationErrors": null,
    "data": null
}

Result

We have created a new summing group, MONTHLY_WITHDRAWAL_SUM_V, to summarise ATM cash withdrawal transactions during the authorisation stage.

Find counting values for card

Suppose you want to know the number of cash withdrawals in the current period, use the get-aggregated-data API endpoint.

Use case

In this example, we will get the current counting value of an assigned counting group for a particular card.

Use case data

API parameters with values

Search for aggregation data of

...get-aggregation-data?

transaction grouping MONTHLY_WITHDRAWAL_COUNT and

transactionGroupingCode=MONTHLY_WITHDRAWAL_COUNT

related to card C001692281754

&cardId=C001692281754

Aggregation data is related to the card if aggregationScope for transaction grouping is CARD.

Sample API call

To retrieve the current counting value of an assigned counting group for a particular card, make the following API call.

https://card-api.sandbox.tuumplatform.com/api/v1/get-aggregation-data?transactionGroupingCode=MONTHLY_WITHDRAWAL_COUNT&cardId=C001692281754

Learn more about endpoint in the Tuum developer portal.

Sample request

Below is an example request of the API call to retrieve the current counting value of an assigned counting group for a particular card.

No request body.

curl --location 'https://card-api.sandbox.tuumplatform.com/api/v1/get-aggregation-data?transactionGroupingCode=MONTHLY_WITHDRAWAL_COUNT&cardId=C001692281754' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiTGlpdmEgS2FzdCIsImVtcGxveWVlSWQiOiJJRC0xMjU4IiwidGVuYW50Q29kZSI6Ik1CLkVVIiwiZXhwaXJ5RFRpbWUiOiIyMDI1LTAzLTA2VDEwOjI3OjMzIiwiZXhwIjoxNzQxMjU2ODUzLCJyb2xlcyI6WyJGVUxMX0NBUkRfTUFOQUdFTUVOVCIsIlNZU1RFTSJdfQ.RcQOv2L6IwWbOQ4EJ7n_we68x0JQz0nLFHinCjV-hwU'

Sample response

Below you find an example response body to the API call above.

Response

{
  "errors": null,
  "validationErrors": null,
  "data": {
    "accountId": null,
    "cardId": "C001692281754",
    "transactionGroupingCode": "MONTHLY_WITHDRAWAL_COUNT",
    "currentTransactionAmount": {
      "amount": 0,
      "currencyCode": "EUR"
    },
    "currentTransactionCount": 3,
    "lastActualDate": "2030-10-19",
    "aggregationEvents": [
      {
        "directionCode": "IN",
        "transactionAmount": {
          "amount": 50,
          "currencyCode": "EUR"
        },
        "source": {
          "sourceName": "CARD.CARD_TRANSACTION",
          "sourceRef": "C001692280512"
        },
        "postingDate": "2030-10-17"
      },
      {
        "directionCode": "IN",
        "transactionAmount": {
          "amount": 150,
          "currencyCode": "EUR"
        },
        "source": {
          "sourceName": "CARD.CARD_TRANSACTION",
          "sourceRef": "C001692280513"
        },
        "postingDate": "2030-10-17"
      },
      {
        "directionCode": "IN",
        "transactionAmount": {
          "amount": 50,
          "currencyCode": "EUR"
        },
        "source": {
          "sourceName": "CARD.CARD_TRANSACTION",
          "sourceRef": "C001692280514"
        },
        "postingDate": "2030-10-17"
      },
      {
        "directionCode": "IN",
        "transactionAmount": {
          "amount": 150,
          "currencyCode": "EUR"
        },
        "source": {
          "sourceName": "CARD.CARD_TRANSACTION",
          "sourceRef": "C001692280515"
        },
        "postingDate": "2030-10-17"
      },
      {
        "directionCode": "OUT",
        "transactionAmount": {
          "amount": 50,
          "currencyCode": "EUR"
        },
        "source": {
          "sourceName": "CARD.CARD_TRANSACTION",
          "sourceRef": "C001692280512"
        },
        "postingDate": "2030-10-17"
      },
      {
        "directionCode": "IN",
        "transactionAmount": {
          "amount": 15,
          "currencyCode": "EUR"
        },
        "source": {
          "sourceName": "CARD.CARD_TRANSACTION",
          "sourceRef": "C001692280516"
        },
        "postingDate": "2030-10-17"
      },
      {
        "directionCode": "OUT",
        "transactionAmount": {
          "amount": 15,
          "currencyCode": "EUR"
        },
        "source": {
          "sourceName": "CARD.CARD_TRANSACTION",
          "sourceRef": "C001692280516"
        },
        "postingDate": "2030-10-19"
      }
    ]
  }
}

Result

The result of the API call is the dataset consisting of transactions count 3 and the related authorisation events.

The transaction count is calculated as the difference between received authorisation requests (IN) and authorisation reversals (OUT) for unsuccessful authorisations. In the current example, 5-2=3.

Find summing values for account

Suppose you want to know the total amount of cash withdrawals in the current period, use the get-aggregated-data API endpoint.

Use case

In this example, we will get the current summing value of an assigned summing group for a particular account.

Use case data

API parameters with values

Search for aggregation data of

...get-aggregation-data?

transaction grouping MONTHLY_ACCOUNT_WITHDRAWAL_SUM_Rand

transactionGroupingCode=MONTHLY_ACCOUNT_WITHDRAWAL_SUM_R

related to account C001718025430

&accountId=C001718025430

Aggregation data is related to the account if aggregationScope for transaction grouping is ACCOUNT.

Sample API call

To retrieve the current the current summing value of an assigned summing group for a particular account, make the following API call.

https://card-api.sandbox.tuumplatform.com/api/v1/get-aggregation-data?transactionGroupingCode=MONTHLY_ACCOUNT_WITHDRAWAL_SUM_R&accountId=C001718025430

Learn more about endpoint in the Tuum developer portal.

Sample request

Below is an example request of the API call to retrieve the current summing value of an assigned summing group for a particular account.

No request body.

curl --location 'https://card-api.sandbox.tuumplatform.com/api/v1/get-aggregation-data?transactionGroupingCode=MONTHLY_ACCOUNT_WITHDRAWAL_SUM_R&accountId=C001718025430' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiTGlpdmEgS2FzdCIsImVtcGxveWVlSWQiOiJJRC0xMjU4IiwidGVuYW50Q29kZSI6Ik1CLkVVIiwiZXhwaXJ5RFRpbWUiOiIyMDI1LTAzLTA3VDA4OjQxOjIyIiwiZXhwIjoxNzQxMzM2ODgyLCJyb2xlcyI6WyJGVUxMX0NBUkRfTUFOQUdFTUVOVCIsIlNZU1RFTSJdfQ.0HCEeLryRK5fPTCX11ieLY5C4YrSRg69946Af8Hsz4o'

Sample response

Below you find an example response body to the API call above.

Response

{
  "errors": null,
  "validationErrors": null,
  "data": {
    "accountId": "C001718025430",
    "cardId": null,
    "transactionGroupingCode": "MONTHLY_ACCOUNT_WITHDRAWAL_SUM_R",
    "currentTransactionAmount": {
      "amount": 50,
      "currencyCode": "EUR"
    },
    "currentTransactionCount": 0,
    "lastActualDate": "2028-12-25",
    "aggregationEvents": [
      {
        "directionCode": "IN",
        "transactionAmount": {
          "amount": 50,
          "currencyCode": "EUR"
        },
        "source": {
          "sourceName": "CARD.ACCOUNT_TRANSACTION",
          "sourceRef": "C001718027803"
        },
        "postingDate": "2028-12-25"
      },
      {
        "directionCode": "IN",
        "transactionAmount": {
          "amount": 10,
          "currencyCode": "EUR"
        },
        "source": {
          "sourceName": "CARD.CARD_TRANSACTION",
          "sourceRef": "C001718026304"
        },
        "postingDate": "2028-12-25"
      },
      {
        "directionCode": "OUT",
        "transactionAmount": {
          "amount": 10,
          "currencyCode": "EUR"
        },
        "source": {
          "sourceName": "CARD.CARD_TRANSACTION",
          "sourceRef": "C001718026304"
        },
        "postingDate": "2028-12-25"
      }
    ]
  }
}

Result

The result of the API call is the dataset consisting of transactions summing amount of 50 and the related authorisation events.

Create counting group

You need to create a counting group to set up price tiers for:

count range-based pricing, or
amount range-based pricing with a count threshold.

In card price lists, you can select the created counting group as a reference for tiered pricing.

Use case

In this example, we will set up a counting group that counts ATM cash withdrawal transactions during the authorisation stage.

Use case data

API parameters with values

Unique name for transaction grouping.

"transactionGroupingCode": "MONTHLY_WITHDRAWAL_COUNT_V"

The number of transactions is counted.

"groupingType": "COUNT"

Aggregation restarts at the beginning of each month.

"aggregationLevel": "MONTHLY"

Transactions made with different cards using the same account are aggregated.

"aggregationScope": "ACCOUNT"

Transactions are aggregated at the authorisation stage, when authorisation request or advice is approved (and account reservation or account transaction is created).

"includeReservations": true

Transaction grouping is enabled.

"enabled": true

List of transaction types that are aggregated.

"transactionTypeCodes": [
        "ATM_WITHDRAWAL"
      ]

Sample API call

To create a new counting group, make the following API call:

https://card-api.sandbox.tuumplatform.com/api/v1/transaction-grouping

Learn more about endpoint in the Tuum developer portal.

Sample request

The sample request body is as follows:

{
      "transactionGroupingCode": "MONTHLY_WITHDRAWAL_COUNT_V",
      "groupingType": "COUNT",
      "aggregationLevel": "MONTHLY",
      "aggregationScope": "ACCOUNT",
      "includeReservations": true,
      "enabled": true,
      "transactionTypeCodes": [
        "ATM_WITHDRAWAL"
      ]

curl --location 'https://card-api.sandbox.tuumplatform.com/api/v1/transaction-grouping' \
--header 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiTGlpdmEgS2FzdCIsImVtcGxveWVlSWQiOiJJRC0xMjU4IiwidGVuYW50Q29kZSI6Ik1CLkVVIiwiZXhwaXJ5RFRpbWUiOiIyMDI1LTAzLTA1VDE0OjMwOjEyIiwiZXhwIjoxNzQxMTg1MDEyLCJyb2xlcyI6WyJGVUxMX0NBUkRfTUFOQUdFTUVOVCIsIlNZU1RFTSJdfQ.ZVincGpeLedTc1UtbjFefr-V7n8G3QVOn63FimgVPhM' \
--header 'Content-Type: application/json' \
--data '{
      "transactionGroupingCode": "MONTHLY_WITHDRAWAL_COUNT_V",
      "groupingType": "COUNT",
      "aggregationLevel": "MONTHLY",
      "aggregationScope": "ACCOUNT",
      "includeReservations": true,
      "enabled": true,
      "transactionTypeCodes": [
        "ATM_WITHDRAWAL"
      ]
}'

Sample response

Below you will find the response to the API request:

Response

{
    "errors": null,
    "validationErrors": null,
    "data": null
}

Result

We have created a new counting group, MONTHLY_WITHDRAWAL_COUNT_V, that counts ATM cash withdrawal transactions during the authorisation stage.