9 - Benefits and Purchase Rules Management
Bind Card Purchase Rule
Used to associate a purchase rule with a specific card. Binding a purchase rule enables the enforcement of predefined spending restrictions on the card.
{
"Method": "BindCardPurchaseRule",
"PartnerId": 30326,
"BusinessUnitId": 30326,
"IdentifierCard": "800015485",
"PurchaseRuleId": null,
"LockerAccount": "123456"
}
{
"Success": "true",
"Message": "Rule successfully linked."
}
Field Descripition
| Field | Description | Type | Required |
|---|---|---|---|
| Method | API method to be invoked. | String | Yes |
| PartnerId | Identifier of the partner making the request. | Integer | Yes |
| BusinessUnitId | Identifier of the business unit associated with the partner. | Integer | Yes |
| IdentifierCard | Unique identifier of the card for which the purchase rule is being unbound. | String | Yes |
| PurchaseRuleId | Identifier of the purchase rule to be unbound from the card. - Null when binding to a Locker Account. | Integer | Conditional |
| LockerAccount | Identifier of the Locker Account to which the card will be bound. - Null when binding a purchase rule. | String | Conditional |
Unbind Card Purchase Rule
Used to remove a purchase rule previously linked to a card. Unlinking a purchase rule removes the specific restrictions associated with the rule.
{
"Method": "UnbindCardPurchaseRule",
"PartnerId": 30326,
"BusinessUnitId": 30326,
"IdentifierCard": 800015485,
"PurchaseRuleId": 1208,
"LockerAccount": "123456"
}
{
"Success": "true",
"Message": "Rule successfully unlinked."
}
Field Descripition
| Field | Description | Type | Required |
|---|---|---|---|
| Method | API method to be invoked. | String | Yes |
| PartnerId | Identifier of the partner making the request. | Integer | Yes |
| BusinessUnitId | Identifier of the business unit associated with the partner. | Integer | Yes |
| IdentifierCard | Unique identifier of the card for which the purchase rule is being unbound. | String | Yes |
| PurchaseRuleId | Identifier of the purchase rule to be unbound from the card. - Null when binding to a Locker Account. | Integer | Conditional |
| LockerAccount | Identifier of the Locker Account to which the card will be bound. - Null when binding a purchase rule. | String | Conditional |
Create Card Purchase Rule
This method is used to link a specific purchase rule to an active card. The purchase rule defines the spending restrictions and permissions, such as spending category (For example, food, transportation) and allowed merchants.
Important:
Rules are pre-defined and can only be linked to a card.
{
"Method": "CreateCardPurchaseRule",
"PartnerId": 30326,
"BusinessUnitId": 30326,
"IdentifierCard": 800015485,
"PurchaseRuleId": 1208
}
{
"Success": "true",
"Message": "Rule 1208 successfully linked to card 800015485"
}
Field Descripition
| Field | Description | Type | Required |
|---|---|---|---|
| Method | API method to be invoked. | String | Yes |
| PartnerId | Identifier of the partner making the request. | Integer | Yes |
| BusinessUnitId | Identifier of the business unit associated with the partner. | Integer | Yes |
| IdentifierCard | Unique identifier of the card for which the purchase rule is being created. | String | Yes |
| PurchaseRuleId | Identifier of the purchase rule to be applied to the card. | Integer | Yes |
Get Purchase Rules
This method is used to retrieve purchase rules available in the system. Purchase rules define the spending restrictions and permissions applied to cards, such as allowed or blocked MCC codes.
If LockerAccount is not provided, the RuleConfig parameter is required, determining whether the method retrieves:
- 0: Rules registered in the FitBank database.
- 1: Rules registered for a specific Business Unit (BU).
If LockerAccount is provided, the method retrieves purchase rules linked to that specific locker account, and RuleConfig is no longer required.
This method allows financial institutions to consult the spending controls applied to cards, identifying which categories (e.g., food, transportation, or health) are linked.
{
"Method": "GetPurchaseRules",
"PartnerId": 30326,
"BusinessUnitId": 30326,
"RuleConfig": 1,
"LockerAccount": 123456
}
{
"Success": true,
"Regras": [
{
"PurchaseRuleId": 10,
"Description": "Pedágio",
"CreationDate": "2022-08-11 10:46:17.627",
"Values": ["2","4", "5" ]
},
{
"PurchaseRuleId": 12,
"Description": "Refeição
"CreationDate": "2022-09-11 10:46:17.627",
"Values": 6
"MCC": ["6","9", "3"]
}
],
}
Field Descripition
| Field | Description | Type | Required |
|---|---|---|---|
| Method | API method to be invoked. | String | Yes |
| PartnerId | Identifier of the partner making the request. | Integer | Yes |
| BusinessUnitId | Identifier of the business unit associated with the partner. | Integer | Yes |
| RuleConfig | Configuration of the purchase rules to be retrieved. - If LockerAccount is not provided | Integer | Conditional |
| - 0 = Rules registered in the FitBank database | |||
| - 1 = Rules registered for a specific BU | |||
| LockerAccount | Identifier of the Locker Account to which the card will be bound. | String | Conditional |
Card Benefit Transfer
This method allows transferring values between different benefit rules (For example, from "Food" to "Transportation") within the card. It is useful for redistributing balances according to the user's needs.
{
"Method": "CardBenefitTransfer",
"PartnerId": 30326,
"BusinessUnitId": 30326,
"IdentifierCard": 800015485,
"BenefitFrom": 1208,
"BenefitTo": 1306,
"Value": 589.89,
"Identifier": "5ede542f-a7c4-4afb-9b63-129b8422d470"
}
{
"Success": "true",
"Message": "Transfer successfully completed!"
}
Field Descripition
| Field | Description | Type | Required |
|---|---|---|---|
| Method | API method to be invoked. | String | Yes |
| PartnerId | Identifier of the partner making the request. | Integer | Yes |
| BusinessUnitId | Identifier of the business unit associated with the partner. | Integer | Yes |
| IdentifierCard | Unique identifier of the card involved in the benefit transfer. | String | Yes |
| BenefitFrom | The identifier of the benefit source (from which the value will be transferred). | Integer | Yes |
| BenefitTo | The identifier of the benefit destination (to which the value will be transferred). | Integer | Yes |
| Value | The amount to be transferred between the benefits. | Decimal | Yes |
| Identifier | Unique identifier for the benefit transfer request. | String | Yes |
Bind Locker Purchase Rule
Bind a purchase rule to a Locker Account, allowing granular control over the types of transactions that can be performed from the Locker Account.
{
"Method": "BindLockerPurchaseRule",
"PartnerId": 12345,
"BusinessUnitId": 67890,
"LockerAccount": "042983-251119-8700459-6",
"PurchaseRuleId": 16
}
{
"Success": "true",
"Message": "Method successfully completed!"
}
Field Descripition
| Field | Description | Type | Required |
|---|---|---|---|
| Method | API method to be invoked. | String | Yes |
| PartnerId | Identifier of the partner making the request. | Integer | Yes |
| LockerAccount | Unique identifier of the Locker Account to which the purchase rule will be bound or unbound. | Integer | Yes |
| PurchaseRuleId | Identifier of the purchase rule that will be applied or removed from the Locker Account. | String | Yes |
Unbind Locker Purchase Rule
Remove a purchase rule linked to a Locker Account, providing more flexibility in the use of the Locker Account.
{
"Method": "UnbindLockerPurchaseRule",
"PartnerId": 12345,
"BusinessUnitId": 67890,
"LockerAccount": "042983-251119-8700459-6",
"PurchaseRuleId": 16
}
{
"Success": "true",
"Message": "Method successfully completed!"
}
Field Descripition
| Field | Description | Type | Required |
|---|---|---|---|
| Method | API method to be invoked. | String | Yes |
| PartnerId | Identifier of the partner making the request. | Integer | Yes |
| LockerAccount | Unique identifier of the Locker Account to which the purchase rule will be bound or unbound. | Integer | Yes |
| PurchaseRuleId | Identifier of the purchase rule that will be applied or removed from the Locker Account. | String | Yes |
Updated about 1 month ago