# RevCent MCP Operation: `CreateBinProfile` This document explains the `CreateBinProfile` MCP operation and how an MCP should reason about creating BIN Profiles. A BIN Profile is a reusable list of credit card BINs. In RevCent, a BIN is the first 6 digits of a credit card number. BIN Profiles can be useful for organization, filtering, reporting, and advanced payment routing workflows. Source: - RevCent API/MCP schema for `CreateBinProfile` --- ## Operation Summary `CreateBinProfile` creates a new BIN Profile and returns a unique 20-character `bin_profile_id`. A BIN Profile stores one or more 6-digit credit card BINs. A BIN Profile does **not** process payments by itself. It is a reusable data object that can be referenced elsewhere in RevCent. Common uses include: - Storing known BIN lists. - Grouping BINs for review or reporting. - Supporting future filtering workflows. - Supporting advanced Payment Profile filtering or routing, when appropriate. --- # What Is a BIN? A BIN is the first 6 digits of a credit card number. Example: ```text 411111 ``` If a card number starts with: ```text 411111 ``` then it matches BIN: ```text 411111 ``` Important: - Only the first 6 digits should be stored. - Do not store full card numbers. - Do not store CVV. - Do not store expiration dates. - Do not store cardholder names. - Do not store any other sensitive payment credential data. --- # What Is a BIN Profile? A BIN Profile is a named list of BINs. Example: ```json { "name": "Known BIN List", "description": "User-provided list of 6-digit BINs for reporting and possible advanced Payment Profile filtering.", "enabled": true, "bin_6": [ "411111", "422222", "433333" ] } ``` The key idea: ```text BIN Profile = reusable list of 6-digit BINs ``` It does not automatically cause routing, blocking, or payment-processing behavior. --- # Important Concept: A BIN Profile Is Not Payment Logic Creating a BIN Profile does not automatically: - Block cards. - Route payments. - Retry payments. - Abort payment flows. - Change gateway selection. - Change checkout behavior. A BIN Profile only becomes part of payment behavior if it is used by another workflow, such as a Payment Profile with BIN-based filtering. MCP should not assume that a user wants BIN-based blocking or routing simply because they want to create a BIN Profile. --- # Input Fields ## Required and Optional Fields | Field | Type | Required | Description | |---|---:|---:|---| | `name` | string | Yes | Unique BIN Profile name. | | `description` | string | No, but recommended | Human-readable explanation of the BIN Profile purpose. | | `enabled` | boolean | No | Whether the BIN Profile is enabled. | | `bin_6` | array | No | List of 6-digit BIN strings to associate with the BIN Profile. | Only `name` is required by the schema, but a useful BIN Profile should normally include a clear description and the intended BIN list. --- ## `name` The BIN Profile name must be unique from other BIN Profile names. Good names are specific and explain why the BIN list exists. Examples: ```text Business A - BIN Review List Known Prepaid BINs High Decline BIN List Gateway Review BINs International BIN Watchlist Reporting BIN Group ``` Avoid vague names: ```text BINs Profile 1 Test List New BIN Profile ``` --- ## `description` A description is highly recommended. The description should explain: - Why the BIN Profile exists. - Who provided the BIN list. - Whether the list is for reporting, review, filtering, or advanced payment logic. - Whether the BIN Profile is intended for future Payment Profile use. - Whether the list should be reviewed before production use. Example: ```text User-provided BIN list for reporting and possible future Payment Profile filtering. This BIN Profile does not block or route payments by itself. ``` If the BIN Profile is intended for advanced Payment Profile use, say that clearly: ```text User-provided BIN list intended for advanced Payment Profile filtering. Any routing or blocking behavior must be configured separately in the Payment Profile flow. ``` --- ## `enabled` `enabled` determines whether the BIN Profile is active. Use: ```json "enabled": true ``` when the BIN Profile is ready to be used. Use: ```json "enabled": false ``` when the BIN Profile is still being drafted, imported, reviewed, or tested. Important: An enabled BIN Profile still does not affect payment behavior unless another workflow references it. --- ## `bin_6` `bin_6` is an array of 6-digit strings. Example: ```json "bin_6": [ "411111", "422222", "433333" ] ``` Rules: - Each BIN must be exactly 6 digits. - Each BIN should be represented as a string. - Do not include spaces. - Do not include dashes. - Do not include full card numbers. - Do not include duplicate values if avoidable. - Do not guess or invent BINs. Correct: ```json "411111" ``` Incorrect: ```json 411111 ``` Incorrect: ```json "4111" ``` Incorrect: ```json "4111111" ``` Incorrect: ```json "4111111111111111" ``` Incorrect: ```json "411-111" ``` --- # Example Request ```json { "name": "Business A - BIN Review List", "description": "User-provided list of 6-digit BINs for review, reporting, and possible future advanced Payment Profile filtering. This BIN Profile does not block or route payments by itself.", "enabled": true, "bin_6": [ "411111", "422222", "433333" ] } ``` --- # Output Schema A successful response returns: ```json { "api_call_id": "XXXXXXXXXXXXXXXXXXXX", "api_call_unix": 1740000000, "code": 1, "bin_profile_id": "YYYYYYYYYYYYYYYYYYYY", "result": "..." } ``` Fields: | Field | Description | |---|---| | `api_call_id` | 20-character API call ID. | | `api_call_unix` | Unix timestamp when the API call was initiated. | | `code` | API response code. `1` indicates success. | | `bin_profile_id` | 20-character BIN Profile ID. | | `result` | Human-readable result message. | --- # Advanced Use: BIN Profiles in Payment Profiles An advanced use of BIN Profiles is inside Payment Profiles. Payment Profiles can use BIN Profiles as part of payment-flow filtering. This allows a Payment Profile to make decisions based on whether the card BIN matches a specific BIN Profile. This is an advanced payment capability. MCP should only use BIN Profiles for Payment Profile filtering or routing when the user has advanced payment needs and clearly understands what should happen when a BIN matches. Examples of advanced needs: - Route certain BINs to a specific gateway group. - Route certain BINs away from a gateway group. - Apply special handling for known high-decline BINs. - Send known BIN groups through a fallback path. - Abort processing for a user-confirmed blocked BIN list. - Separate routing by business/corp strategy. - Record metadata when certain BINs are used. Important: ```text BIN-based payment filtering/routing should not be added casually. ``` It can directly affect credit card processing behavior. --- ## Payment Profile `filter_bin_profile` In a Payment Profile, a BIN Profile may be used by a BIN filter node. Conceptually: ```text filter_bin_profile ├─ output_1: card BIN matched the BIN Profile └─ output_2: card BIN did not match the BIN Profile ``` The Payment Profile then decides what to do next. For example: ```text output_1 match → route to special gateway group output_2 no match → route to default gateway group ``` or: ```text output_1 match → abort flow output_2 no match → continue normal processing ``` MCP should use exact `output_1` and `output_2` terminology. --- ## Advanced Routing Example A business with advanced routing needs might say: ```text If a card matches this BIN Profile, route the payment to Business A Preferred Gateway Group. Otherwise use Business A Default Gateway Group. ``` Conceptual flow: ```text start_payment_request ↓ filter_bin_profile ├─ output_1 match → action_choose_gateway: Business A Preferred Gateway Group └─ output_2 no match → action_choose_gateway: Business A Default Gateway Group ``` This can be useful when the business knows certain BINs perform better through a specific gateway group. --- ## Advanced Blocking Example A business with advanced blocking needs might say: ```text If a card matches this BIN Profile, do not process it. ``` Conceptual flow: ```text start_payment_request ↓ filter_bin_profile ├─ output_1 match → action_abort_flow └─ output_2 no match → action_choose_gateway → action_process_payment ``` This is high-impact because matching cards will not be processed. MCP should only build or recommend this behavior when the user explicitly confirms that matching BINs should be blocked. --- ## MCP Warning for Payment Profile Use If a user asks to use a BIN Profile inside a Payment Profile, MCP should warn: ```text BIN-based filtering or routing inside a Payment Profile is an advanced payment-routing capability. It can affect whether a credit card payment is routed, retried, blocked, or processed. Please confirm the exact behavior you want when a card BIN matches this BIN Profile. ``` MCP should not infer routing or blocking behavior. The user must provide the desired behavior. --- # When BIN-Based Filtering/Routing Is Appropriate BIN-based filtering/routing may be appropriate when: - The user has known BIN performance data. - The user has gateway-specific BIN requirements. - The user has a specific business/corp routing strategy. - The user has a confirmed risk or fraud policy tied to specific BINs. - The user has a defined fallback strategy. - The user has a reporting or metadata strategy tied to BIN groups. - The user understands the effect on payment processing. --- # When BIN-Based Filtering/Routing Is Not Appropriate MCP should avoid BIN-based Payment Profile logic when: - The user only wants to store a BIN list. - The user has not explained what should happen on match. - The user does not know whether routing or blocking is desired. - The user has not provided exact BINs. - The BIN list is speculative. - The user does not have advanced payment-routing needs. - The behavior can be handled more safely by normal gateway group routing. - Blocking has not been explicitly confirmed. Default assumption: ```text CreateBinProfile creates a reusable BIN list only. Payment Profile routing/blocking is separate and advanced. ``` --- # MCP Questions Before Creating a BIN Profile Before calling `CreateBinProfile`, MCP should ask: 1. What should the BIN Profile be named? 2. What is the purpose of the BIN Profile? 3. Which exact 6-digit BINs should be included? 4. Did the user explicitly provide the BINs? 5. Should the profile be enabled immediately? 6. Is this only for storing/reporting/review, or will it be used in a Payment Profile? 7. If intended for Payment Profile use, does the user have advanced payment-routing needs? 8. If intended for Payment Profile use, what exactly should happen when the BIN matches? 9. If intended for Payment Profile use, what exactly should happen when the BIN does not match? 10. If blocking is requested, has the user explicitly confirmed matching BINs should not be processed? --- # MCP Safety Rules ## Do Not Invent BINs MCP must not invent BIN values. The user must provide the exact 6-digit BINs, or the BINs must come from trusted account/business data. MCP should not guess BINs based on: - Card brand - Issuer - Country - Gateway behavior - General internet knowledge - Assumptions about risk Rule: ```text No explicit BIN list = no BIN Profile with guessed BINs. ``` --- ## Validate BIN Format Before creating the BIN Profile, MCP should validate every BIN. Each value must: - Be exactly 6 digits. - Contain digits only. - Be stored as a string. - Not be a full card number. - Not include spaces, dashes, or symbols. Validation examples: ```text 411111 → valid 41111 → invalid, only 5 digits 4111111 → invalid, 7 digits 411-11 → invalid, contains dash 4111111111111111 → invalid, full card number ``` --- ## Do Not Store Sensitive Payment Data If the user provides full card data, MCP must not include it in the BIN Profile. Do not store: - Full card number - CVV - Expiration date - Cardholder name - Track data - Any sensitive payment credential data MCP should ask the user to provide only the first 6 digits if a BIN Profile is still needed. --- ## Do Not Assume Blocking A BIN Profile is a list. MCP should not assume blocking. User says: ```text Create a BIN Profile for these BINs. ``` This means create the list only. User says: ```text Create a BIN Profile for these BINs and block them in the payment flow. ``` This indicates a separate advanced Payment Profile change is needed. --- ## Warn Before Blocking or Routing If the user wants to use the BIN Profile in a Payment Profile, MCP should warn that this is advanced and can affect payment processing. If blocking is requested, MCP should warn: ```text If the Payment Profile routes matching BINs to action_abort_flow, cards matching this BIN Profile will not be processed. Please confirm this is intended. ``` If routing is requested, MCP should confirm: ```text Which gateway group should matching BINs use, and which gateway group should non-matching BINs use? ``` Gateway groups should generally be preferred over individual gateways. --- # Create Checklist Before calling `CreateBinProfile`: 1. User provided a clear purpose. 2. User provided exact 6-digit BINs, unless creating an empty placeholder intentionally. 3. No BINs were invented. 4. Every BIN is exactly 6 digits. 5. Every BIN is a string. 6. No full card numbers or sensitive card data are included. 7. Description explains the purpose. 8. Description clarifies that the BIN Profile does not route or block by itself. 9. `enabled` state is intentional. 10. If Payment Profile use is mentioned, user understands it is advanced. 11. If routing is requested, the desired match/no-match behavior is explicit. 12. If blocking is requested, the user explicitly confirmed matching BINs should not be processed. --- # Quick Reference Minimum request: ```json { "name": "Business A BIN List" } ``` Recommended request: ```json { "name": "Business A BIN List", "description": "User-provided 6-digit BIN list for review and possible future advanced Payment Profile filtering. This BIN Profile does not block or route payments by itself.", "enabled": true, "bin_6": [ "411111", "422222" ] } ``` Most important rules: ```text A BIN Profile is a reusable 6-digit BIN list. A BIN Profile does not block, route, or process payments by itself. Payment Profile BIN filtering/routing is advanced and should only be used for advanced payment needs. MCP must not invent BINs. MCP must not store full card numbers or sensitive payment data. MCP must not assume blocking or routing unless the user explicitly requests it. ``` --- Document Parent Directory * [Operations](https://revcent.com/documentation/markdown/mcp/operation/index.md) - AI/MCP details and overviews for operations available within the RevCent MCP.