Fusion Docs

With the current capabilities of Fusion we can explore upon the use case where Fintechs onboard various real account holders, issue a card to them and provide them the flexibility to control the transactions on their card.

Pre-requisites:

Fintech is onboarded in Zeta’s system
Zeta offers various options to control the user’s transactions
All the policies to be applied by Fintech using Zeta’s Account Holder Transaction Policy API offering.

In this tutorial, you will be coming across the various use cases which can be used to control transactions at the card level:

Before you begin

Keep the following points in mind before making calls to Fusion APIs:

Endpoint URI: To ensure data privacy and security, all Fusion APIs are served over HTTPS and use the common URI https://fusion.preprod.zeta.in/
Authentication: Before testing any endpoint using the cURL sample provided, replace {{AUTH_TOKEN}} with the X-Zeta-AuthToken provided by Zeta.
A unique identifier (ifiID) 140793 is assigned to the fintech for this tutorial.

All request examples in the tutorial are provided as cURL samples, and response examples are provided in JSON format.

Fintech decides to offer their users to instantly turn on/ off their card transactions at various channels like ATM, ECOM, POS etc.

CHANNELS	ON OFF
ECOM	⚪ ⚫
ATM	⚪ ⚪
POS	⚪ ⚪

Fintech gets user’s input and creates a category (basis the user’s input) , in this case to block the ECOM transaction (refer Appendix to get more information on “attrKey” for other channels)

Request

cURL Sample

curl --location --request POST 'https://fusion.preprod.zeta.in/api/v1/ifi/140793/accountHolders/4902cc00-c984-4ee2-a5f2-2eefea271776/transactionCategories' \ --header 'Content-Type: application/json' \ --header 'X-Zeta-AuthToken: {{AUTH_TOKEN}}' \ --data-raw '{ "ifi": 140793, "accountHolderId": "4902cc00-c984-4ee2-a5f2-2eefea271776", "code": "ECOM_TXN_CODE_TEST_1776USER", "description": "Group to identify ECOM transactions", "transactionAttributes": [ { "attrKey": "super-card.txn-type", "attrVal": "ECOM", "txnCategoryComparator": "EQUALS" }, { "attrKey": "super-card.card-id", "attrVal": "c0905631-ac83-47d1-95f3-aadce0c21776", "txnCategoryComparator": "EQUALS" } <span style="color:#719e07">]</span>

}'

Code Copied

Response

JSON Sample

{
    "ifi": 140793,
    "code": "ECOM_TXN_CODE_TEST_1776USER",
    "description": "Group to identify ECOM transactions",
    "transactionAttributes": [
        {
            "id": 755398,
            "code": "ECOM_TXN_CODE_TEST_1776USER",
            "attrKey": "super-card.card-id",
            "attrVal": "c0905631-ac83-47d1-95f3-aadce0c21776",
            "txnCategoryComparator": "EQUALS"
        },
        {
            "id": 755397,
            "code": "ECOM_TXN_CODE_TEST_1776USER",
            "attrKey": "super-card.txn-type",
            "attrVal": "ECOM",
            "txnCategoryComparator": "EQUALS"
        }
    ]
}

Code Copied

Once the category is created, Fintech creates the policy for the user for the category code created above (ECOM_TXN_CODE_TEST_1776USER)

Request

cURL Sample

curl --location --request POST 'https://fusion.preprod.zeta.in/api/v1/ifi/140793/accountHolders/4902cc00-c984-4ee2-a5f2-2eefea271776/transactionPolicies' \
--header 'Content-Type: application/json' \
--header 'X-Zeta-AuthToken: {{AUTH_TOKEN}}' \
--d '{
   "code":"ECOM_POLICY_CODE_USER1776",
   "description":"Apply eCOM limits on account holder",
   "scope":"AGGREGATE_OF_ALL_ACCOUNTS_OF_ACCOUNT_HOLDER",
   "coaID":6221687368577586252,
   "transactionConstraints":[
      {
         "action":"DEBIT",
         "allowedTransactionCategoryCodes":[
     <span style="color:#719e07">],</span>
     <span style="color:#2aa198">&#34;disallowedTransactionCategoryCodes&#34;</span><span style="color:#719e07">:[</span>
        <span style="color:#2aa198">&#34;ECOM_TXN_CODE_TEST_1776USER&#34;</span>
     <span style="color:#719e07">],</span>
     <span style="color:#2aa198">&#34;allowedTimeSlices&#34;</span><span style="color:#719e07">:[</span>
        
     <span style="color:#719e07">],</span>
     <span style="color:#2aa198">&#34;disallowedTimeSlices&#34;</span><span style="color:#719e07">:[</span>
        
     <span style="color:#719e07">],</span>
     <span style="color:#2aa198">&#34;errorCode&#34;</span><span style="color:#719e07">:</span><span style="color:#2aa198">&#34;GENERIC_ERROR&#34;</span>
  <span style="color:#719e07">}</span>

],
"transactionRules":[
],
"balanceRules":[
],
"aggregateRules":[
],
"effectiveFrom":"2020-05-01T00:00:00.000Z",
"expiresAt":"2021-12-31T00:00:00.000Z",
"violationAction":"DECLINE_AND_NOTIFY",
"attributes":{
"dummy-attribute-key":"dummy-attribute-value"
},
"accountsApplicableTo":{
"account.pd-id":"6178734290235544095"
}
}'

Code Copied

Response

JSON Sample

{
    "ifiID": 140793,
    "accountHolderID": "4902cc00-c984-4ee2-a5f2-2eefea271776",
    "coaID": 6221687368577586252,
    "id": 7291909357796461906,
    "code": "ECOM_POLICY_CODE_USER1776",
    "description": "Apply eCOM limits on account holder",
    "scope": "AGGREGATE_OF_ALL_ACCOUNTS_OF_ACCOUNT_HOLDER",
    "transactionConstraints": [
        {
            "action": "DEBIT",
            "allowedTransactionCategoryCodes": [],
            "disallowedTransactionCategoryCodes": [
                "ECOM_TXN_CODE_TEST_1776USER"
            ],
            "allowedTimeSlices": [],
            "disallowedTimeSlices": []
        }
    ],
    "effectiveFrom": "2020-05-01T05:30:00.000+05:30",
    "expiresAt": "2021-12-31T05:30:00.000+05:30",
    "violationAction": "DECLINE_AND_NOTIFY",
    "attributes": {
        "dummy-attribute-key": "dummy-attribute-value"
    },
    "tags": [
        {
            "type": "vbo-id",
            "value": "96100856-8c1e-4735-bb62-97f56a829555",
            "attributes": {}
        }
    ]
}

Code Copied

In the above API, to fetch the account product ID, please use the GET Account Details by Account Holder API, refer “productID” attribute from the mentioned API response to pass it on to “account.pd-id”

COA ID will be provided to the Fintechs by Fusion Team

Fintech onboards a minor and decides to offer the parent to control the spends of the child’s card. Aggregation rules look at the historic state of the account over a period of discreet windows of time to determine if the transaction should be allowed. Currently we have support for these time windows :

Daily
Weekly
Monthly
Quarterly
Yearly

There are two types of aggregation rules

Volume - the aggregation is done on the amount in the transactions
Velocity - the aggregation is done on the count of the transactions

Aggregation rules are configured for actions(debit/credit) and transaction category code.

Fintech creates the Transaction Category by providing the user’s card ID
Fintech creates the Aggregation Transaction Policy

Request

cURL Sample

curl --location --request POST 'https://fusion.preprod.zeta.in/api/v1/ifi/140793/accountHolders/4902cc00-c984-4ee2-a5f2-2eefea271776/transactionPolicies' \
--header 'Content-Type: application/json' \
--header 'X-Zeta-AuthToken: {{AUTH_TOKEN}}' \
--d '{
   "code":"ECOM_POLICY_CODE_USER1776_2",
   "description":"Apply eCOM limits on account holder",
   "scope":"AGGREGATE_OF_ALL_ACCOUNTS_OF_ACCOUNT_HOLDER",
   "coaID":6221687368577586252,
   "transactionRules":[],
   "balanceRules":[],
   "aggregateRules":[
      {
         "action":"DEBIT",
         "transactionCategoryCode":"ECOM_TXN_CODE_TEST_1776USER",
         "aggExpressionCode":"1",
         "dailyLimit":15000,
         "weeklyLimit":70000,
         "monthlyLimit":300000,
         "quarterlyLimit":900000,
         "yearlyLimit":3600000,
         "errorCode":"GENERIC_ERROR",
         "type":"VOLUME"
      },
      {
         "action":"DEBIT",
         "categoryCode":"ECOM_TXN_CODE_TEST_1776USER",
         "aggExpressionCode":"3",
         "dailyLimit":5,
         "weeklyLimit":7,
         "monthlyLimit":20,
         "quarterlyLimit":90,
         "yearlyLimit":200,
         "errorCode":"GENERIC_ERROR",
         "type":"VELOCITY"
      }
   ]
   "effectiveFrom":"2020-05-01T00:00:00.000Z",
   "expiresAt":"2021-12-31T00:00:00.000Z",
   "violationAction":"DECLINE_AND_NOTIFY",
   "attributes":{
      "dummy-attribute-key":"dummy-attribute-value"
   },
   "accountsApplicableTo":{
      "account.pd-id":"6178734290235544095"
   }
}'

Code Copied

For more information on the VOLUME and VELOCITY, see Appendix

Fintech onboards a minor and provides flexibility to the parent to set the transaction constraints, so that the child never transacts beyond the specified maximum transaction amount or below the specified minimum transaction amount.

Fintech creates the Transaction Category by specifying the child’s card ID.
Fintech creates the Transaction Policy.

Request

cURL Sample

curl --location --request POST 'https://fusion.preprod.zeta.in/api/v1/ifi/140793/accountHolders/4902cc00-c984-4ee2-a5f2-2eefea271776/transactionPolicies' \
--header 'Content-Type: application/json' \
--header 'X-Zeta-AuthToken: {{AUTH_TOKEN}}' \
--d '{
   "code":"ECOM_POLICY_CODE_USER1776_2",
   "description":"Apply eCOM limits on account holder",
   "scope":"AGGREGATE_OF_ALL_ACCOUNTS_OF_ACCOUNT_HOLDER",
   "coaID":6221687368577586252,
   "transactionRules":[
        {
          "action": "DEBIT",
          "transactionCategoryCode": "ECOM_TXN_CODE_TEST_1776USER",
          "minRequiredAmount": 10000,
          "maxAllowedAmount": 200000,
          "errorCode": "GENERIC_ERROR"
        }
   ],
   "balanceRules":[],
   "aggregateRules":[],
   "effectiveFrom":"2020-05-01T00:00:00.000Z",
   "expiresAt":"2021-12-31T00:00:00.000Z",
   "violationAction":"DECLINE_AND_NOTIFY",
   "attributes":{
      "dummy-attribute-key":"dummy-attribute-value"
   },
   "accountsApplicableTo":{
      "account.pd-id":"6178734290235544095"
   }
}'

Code Copied

Fintech onboards a minor and provides flexibility to the parent to allow the child to make transactions at only Books, Periodicals and Newspapers merchants.

Fintech creates the Transaction Category to allow the child’s card at only the specified Merchant ID (MID) / Merchant Category Code (MCC).
Fintech creates the Transaction Policy to allow transactions at only specified merchants.

Creates Transaction Category for Merchant Category Code

Request

cURL Sample

curl --location --request POST 'https://fusion.preprod.zeta.in/api/v1/ifi/140793/accountHolders/4902cc00-c984-4ee2-a5f2-2eefea271776/transactionCategories' \ --header 'Content-Type: application/json' \ --header 'X-Zeta-AuthToken: {{AUTH_TOKEN}}' \ --data-raw '{ "ifi": 140793, "accountHolderId": "4902cc00-c984-4ee2-a5f2-2eefea271776", "code": "MCC_TXN_CAT_100001", "description": "Group to identify Merchant transactions", "transactionAttributes": [ { "attrKey": "super-card.mcc", "attrVal": "5411", "txnCategoryComparator": "EQUALS" }, { "attrKey": "super-card.card-id", "attrVal": "c0905631-ac83-47d1-95f3-aadce0c21776", "txnCategoryComparator": "EQUALS" } <span style="color:#719e07">]</span>

}'

Code Copied

Creates Transaction Policy to allow transaction only at a particular merchant

Request

cURL Sample

curl --location --request POST 'https://fusion.preprod.zeta.in/api/v1/ifi/140793/accountHolders/4902cc00-c984-4ee2-a5f2-2eefea271776/transactionPolicies' \
--header 'Content-Type: application/json' \
--header 'X-Zeta-AuthToken: {{AUTH_TOKEN}}' \
--d '{
   "code":"POLICY_CODE_MCC_001",
   "description":"Apply eCOM limits on account holder",
   "scope":"AGGREGATE_OF_ALL_ACCOUNTS_OF_ACCOUNT_HOLDER",
   "coaID":6221687368577586252,
   "transactionConstraints":[
      {
         "action":"DEBIT",
         "allowedTransactionCategoryCodes":[
            "MCC_TXN_CAT_100001"
         ],
         "disallowedTransactionCategoryCodes":[],
         "allowedTimeSlices":[],
         "disallowedTimeSlices":[],
         "errorCode":"GENERIC_ERROR"
      }
   ],
   "transactionRules":[],
   "balanceRules":[],
   "aggregateRules":[],
   "effectiveFrom":"2020-05-01T00:00:00.000Z",
   "expiresAt":"2021-12-31T00:00:00.000Z",
   "violationAction":"DECLINE_AND_NOTIFY",
   "attributes":{
      "dummy-attribute-key":"dummy-attribute-value"
   },
   "accountsApplicableTo":{
      "account.pd-id":"6178734290235544095"
   }
}'

Code Copied

Transaction Policy is composed of a set of rules. Each rule validates if a transaction should be permitted. A policy permits a transaction when all rules of the policy permit the transaction.
An account may have multiple policies applicable on it at any point in time.
All applicable policies for an account are validated for every credit or debit posted onto an account. If any of the policies disallow a transaction, the transaction will be rejected by the system with a specific error message as specified in the policy.

[P.S.: User defined error codes are supported in system, however if Fintech wants to set error codes as per their choice for better tracking and improving responses, please reach out to Fusion team by providing a set of error codes and once done, the same could be used while creating policies]

Aggregate Expression Codes

The aggExpressioncodes used while creating Transaction Policies are mapped to expressions. Currently there are 8 predefined codes as detailed below.

Code	Expression	Description
1	dv - druv	Sum of debits except uncaptured ones, (excludes credit reversals as well)
2	cv - cruv	Sum of credits except uncaptured ones, (excludes debits reversals as well)
3	dc - druc	Count of debits except uncaptured ones, (excludes credit reversals as well)
4	cc - cruc	Count of credits except uncaptured ones, (excludes debit reversals as well)
5	dv - druv - drv + fdv - fdruv - fdrv	Sum of debits that are not reversed or are reversals
6	dc - druc - drc + fdc - fdruc - fdrc	Count of debits that are not reversed or are reversals
7	cv - cruv - crv + fcv - fcruv - fcrv	Sum of credits that are not reversed or are reversals
8	cc - cruc - crc + fcc - fcruc - fcrc	Count of credits that are not reversed or are reversals

API Key Parameters:

Name	Description
ifiID	IFI or Tenant Identifier
coaID	The CoA node identifier. Will be provided by Fusion Team
effectiveFrom	Policy Start Date
expiresAt	Policy Valid Till / End Date
violationAction	The action to be undertaken upon a policy violation. Values: DECLINE, DECLINE_AND_NOTIFY, NOTIFY

Transaction Category Examples for various channels:

ATM

JSON Sample

"transactionAttributes":[
   {
      "attrKey":"super-card.txn-type",
      "attrVal":"ATM",
      "txnCategoryComparator":"EQUALS"
   },
   {
      "attrKey":"super-card.card-id",
      "attrVal":"{{cardId}}",
      "txnCategoryComparator":"EQUALS"
   }
]

Code Copied

ECOM

JSON Sample

"transactionAttributes":[
   {
      "attrKey":"super-card.txn-type",
      "attrVal":"ECOM",
      "txnCategoryComparator":"EQUALS"
   },
   {
      "attrKey":"super-card.card-id",
      "attrVal":"{{cardId}}",
      "txnCategoryComparator":"EQUALS"
   }
]

Code Copied

POS

JSON Sample

"transactionAttributes":[
      {
         "attrKey":"super-card.txn-type",
         "attrVal":"POS",
         "txnCategoryComparator":"EQUALS"
      },
      {
         "attrKey":"super-card.card-id",
         "attrVal":"{{cardId}}",
         "txnCategoryComparator":"EQUALS"
      }
   ]

Code Copied

CONTACTLESS-POS (NFC)

JSON Sample

"transactionAttributes":[
      {
         "attrKey":"super-card.txn-contact-type",
         "attrVal":"CONTACTLESS",
         "txnCategoryComparator":"EQUALS"
      },
      {
         "attrKey":"super-card.card-id",
         "attrVal":"{{cardId}}",
         "txnCategoryComparator":"EQUALS"
      }
   ]

Code Copied

MID

JSON Sample

"transactionAttributes":[
      {
         "attrKey":"super-card.mid",
         "attrVal":"{{MerchantID}}",
         "txnCategoryComparator":"EQUALS"
      },
      {
         "attrKey":"super-card.card-id",
         "attrVal":"{{cardId}}",
         "txnCategoryComparator":"EQUALS"
      }
   ]

Code Copied

MCC

JSON Sample

"transactionAttributes":[
      {
         "attrKey":"super-card.mcc",
         "attrVal":"{{MerchantCatCode}}",
         "txnCategoryComparator":"EQUALS"
      },
      {
         "attrKey":"super-card.card-id",
         "attrVal":"{{cardId}}",
         "txnCategoryComparator":"EQUALS"
      }
   ]

Code Copied

Choose your product

Choose your product

Before you begin