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

FieldDescriptionTypeRequired
MethodAPI method to be invoked.StringYes
PartnerIdIdentifier of the partner making the request.IntegerYes
BusinessUnitIdIdentifier of the business unit associated with the partner.IntegerYes
IdentifierCardUnique identifier of the card for which the purchase rule is being unbound.StringYes
PurchaseRuleIdIdentifier of the purchase rule to be unbound from the card.

- Null when binding to a Locker Account.
IntegerConditional
LockerAccountIdentifier of the Locker Account to which the card will be bound.

- Null when binding a purchase rule.
StringConditional

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

FieldDescriptionTypeRequired
MethodAPI method to be invoked.StringYes
PartnerIdIdentifier of the partner making the request.IntegerYes
BusinessUnitIdIdentifier of the business unit associated with the partner.IntegerYes
IdentifierCardUnique identifier of the card for which the purchase rule is being unbound.StringYes
PurchaseRuleIdIdentifier of the purchase rule to be unbound from the card.

- Null when binding to a Locker Account.
IntegerConditional
LockerAccountIdentifier of the Locker Account to which the card will be bound.

- Null when binding a purchase rule.
StringConditional

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

FieldDescriptionTypeRequired
MethodAPI method to be invoked.StringYes
PartnerIdIdentifier of the partner making the request.IntegerYes
BusinessUnitIdIdentifier of the business unit associated with the partner.IntegerYes
IdentifierCardUnique identifier of the card for which the purchase rule is being created.StringYes
PurchaseRuleIdIdentifier of the purchase rule to be applied to the card.IntegerYes

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

FieldDescriptionTypeRequired
MethodAPI method to be invoked.StringYes
PartnerIdIdentifier of the partner making the request.IntegerYes
BusinessUnitIdIdentifier of the business unit associated with the partner.IntegerYes
RuleConfigConfiguration of the purchase rules to be retrieved.

- If LockerAccount is not provided
IntegerConditional
- 0 = Rules registered in the FitBank database
- 1 = Rules registered for a specific BU
LockerAccountIdentifier of the Locker Account to which the card will be bound.StringConditional

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

FieldDescriptionTypeRequired
MethodAPI method to be invoked.StringYes
PartnerIdIdentifier of the partner making the request.IntegerYes
BusinessUnitIdIdentifier of the business unit associated with the partner.IntegerYes
IdentifierCardUnique identifier of the card involved in the benefit transfer.StringYes
BenefitFromThe identifier of the benefit source (from which the value will be transferred).IntegerYes
BenefitToThe identifier of the benefit destination (to which the value will be transferred).IntegerYes
ValueThe amount to be transferred between the benefits.DecimalYes
IdentifierUnique identifier for the benefit transfer request.StringYes

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

FieldDescriptionTypeRequired
MethodAPI method to be invoked.StringYes
PartnerIdIdentifier of the partner making the request.IntegerYes
LockerAccountUnique identifier of the Locker Account to which the purchase rule will be bound or unbound.IntegerYes
PurchaseRuleIdIdentifier of the purchase rule that will be applied or removed from the Locker Account.StringYes

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

FieldDescriptionTypeRequired
MethodAPI method to be invoked.StringYes
PartnerIdIdentifier of the partner making the request.IntegerYes
LockerAccountUnique identifier of the Locker Account to which the purchase rule will be bound or unbound.IntegerYes
PurchaseRuleIdIdentifier of the purchase rule that will be applied or removed from the Locker Account.StringYes

Did this page help you?