# Create Protection Bulletin rule
Register a new Protection Bulletin setup rule. This feature is available for Elo, Mastercard and Visa.
When you set a card rule, for example, when a card status is changed to `LOST`, it is automatically added to the Protection Bulletin.
This operation executes asynchronously. When complete, a [Bulletin rule event](https://developers.pismo.io/events/docs/bulletin-bulletin-rule-1) is generated.
**Notes:**
* This endpoint takes an account token - an access token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a 401 Unauthorized message.
* Deactivating a rule after it has been created requires re-calling this endpoint with `active` set to `false`.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "Card issuing - Protection Bulletin",
"version": "2.0.3",
"description": "Bulletin API endpoints",
"contact": {
"name": "API Support",
"url": "https://developers.pismo.io/support/"
},
"license": {
"name": "Copyright Pismo"
}
},
"servers": [
{
"url": "https://sandbox.pismolabs.io/protection-bulletin",
"description": "Sandbox API server for testing"
}
],
"security": [
{
"BearerAuth": []
}
],
"tags": [
{
"name": "Rules",
"description": "Endpoints to manage Protection Bulletin rules"
}
],
"components": {
"parameters": {
"AuthHeader": {
"in": "header",
"name": "Authorization",
"required": true,
"description": "Account token - an access token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a 401 Unauthorized message.",
"schema": {
"type": "string",
"example": "Bearer eyJhbGci...IUzUx"
}
}
},
"schemas": {
"AllowedStatusEloModel": {
"type": "array",
"description": "If `allowed_status` is passed, the Pismo Protection Bulletin service starts monitoring [Card updated events](https://developers.pismo.io/events/docs/cards-update-1). \n\nThe `status_pismo` status determines if the card is sent to the network via the Protection Bulletin.\n",
"items": {
"type": "object",
"properties": {
"status_pismo": {
"$ref": "#/components/schemas/StatusPismo"
},
"default_purge_days": {
"$ref": "#/components/schemas/DefaultPurgeDays"
}
}
}
},
"AllowedStatusMastercardModel": {
"type": "array",
"description": "If `allowed_status` is provided, the Pismo Protection Bulletin service starts monitoring [Card updated events](https://developers.pismo.io/events/docs/cards-update-1). \n\nThe `status_pismo` status determines if the card is sent to the network via the Protection Bulletin.\n",
"items": {
"type": "object",
"properties": {
"status_pismo": {
"$ref": "#/components/schemas/StatusPismo"
},
"status_network": {
"$ref": "#/components/schemas/StatusNetworkMastercard"
},
"default_purge_days": {
"$ref": "#/components/schemas/DefaultPurgeDays"
}
}
}
},
"AllowedStatusVisaModel": {
"description": "When passed, the Pismo Protection Bulletin service starts monitoring [Card updated events](https://developers.pismo.io/events/docs/cards-update-1). \n \n The `status_pismo` status determines if the card is sent to the network via the Protection Bulletin.\n",
"type": "array",
"items": {
"type": "object",
"required": [
"status_pismo",
"status_network",
"default_purge_days"
],
"properties": {
"status_pismo": {
"$ref": "#/components/schemas/StatusPismo"
},
"status_network": {
"$ref": "#/components/schemas/StatusNetworkVisa"
},
"default_purge_days": {
"$ref": "#/components/schemas/DefaultPurgeDaysVisa"
}
}
}
},
"BulletinSetupEloModel": {
"type": "object",
"description": "Register a Elo Protection Bulletin setup.",
"required": [
"active",
"program_id"
],
"properties": {
"active": {
"$ref": "#/components/schemas/Active"
},
"program_id": {
"$ref": "#/components/schemas/ProgramID"
},
"allowed_status": {
"$ref": "#/components/schemas/AllowedStatusEloModel"
}
}
},
"BulletinSetupMastercardModel": {
"type": "object",
"description": "Register a Mastercard Protection Bulletin setup.",
"required": [
"active",
"ica",
"program_id"
],
"properties": {
"active": {
"$ref": "#/components/schemas/Active"
},
"ica": {
"$ref": "#/components/schemas/Ica"
},
"program_id": {
"$ref": "#/components/schemas/ProgramID"
},
"allowed_status": {
"$ref": "#/components/schemas/AllowedStatusMastercardModel"
}
}
},
"BulletinSetupVisaModel": {
"type": "object",
"description": "Register a Visa Protection Bulletin setup.",
"required": [
"active",
"bid",
"program_id",
"region_code",
"allowed_status"
],
"properties": {
"active": {
"$ref": "#/components/schemas/Active"
},
"bid": {
"$ref": "#/components/schemas/Bid"
},
"program_id": {
"$ref": "#/components/schemas/ProgramID"
},
"region_code": {
"$ref": "#/components/schemas/RegionCode"
},
"allowed_status": {
"$ref": "#/components/schemas/AllowedStatusVisaModel"
}
}
},
"ErrorDetailMessageModel": {
"description": "Detailed information about the error.",
"type": "object",
"properties": {
"payload": {
"type": "array",
"description": "List of payload-related error details.",
"items": {
"$ref": "#/components/schemas/ErrorPayloadMessageModel"
}
},
"header": {
"type": "array",
"description": "List of header-related error details.",
"items": {
"$ref": "#/components/schemas/ErrorHeaderMessageModel"
}
},
"parameters": {
"type": "array",
"description": "List of parameter-related error details.",
"items": {
"$ref": "#/components/schemas/ErrorParameterMessageModel"
}
}
}
},
"ErrorHeaderMessageModel": {
"description": "Details about header-related errors.",
"type": "object",
"properties": {
"field": {
"type": "string",
"description": "Header name related to the error.",
"example": "x-field"
},
"message": {
"type": "string",
"description": "Error message for the header.",
"example": "Generic error"
}
}
},
"ErrorMessageModel": {
"title": "ErrorModel",
"type": "object",
"description": "API generic returned error.",
"properties": {
"code": {
"type": "string",
"description": "Error code."
},
"message": {
"type": "string",
"description": "Error description."
},
"http_status_code": {
"type": "integer",
"description": "HTTP status code."
},
"details": {
"$ref": "#/components/schemas/ErrorDetailMessageModel"
}
}
},
"ErrorParameterMessageModel": {
"description": "Details about parameter-related errors.",
"type": "object",
"properties": {
"field": {
"type": "string",
"description": "Parameter name related to the error.",
"example": "query_parameter"
},
"message": {
"type": "string",
"description": "Parameter error message"
}
}
},
"ErrorPayloadMessageModel": {
"description": "Details about payload-related errors.",
"type": "object",
"properties": {
"field": {
"type": "string",
"description": "Field name related to the error.",
"example": "field"
},
"message": {
"type": "string",
"description": "Error message for the field.",
"example": "Generic error"
}
}
},
"Active": {
"type": "boolean",
"description": "Is rule active? An inactive rule is not applied to transactions.\n",
"example": true
},
"Bid": {
"type": "string",
"description": "Business ID (BID) number - a six-digit account number through which Visa bills their clients. **REQUIRED** for Visa.\n\nIt **must** be padded with leading zeros.\n",
"example": "012345"
},
"DefaultPurgeDays": {
"type": "number",
"description": "After the specified number of days, a request to remove the card will be automatically sent to the network through the Protection Bulletin.\n\nThe `default_purge_days` field is optional, and if not provided, no action will be taken to remove this card from the Protection Bulletin.\n",
"example": 30
},
"DefaultPurgeDaysVisa": {
"type": "number",
"description": "After the specified number of days, a request to remove the card is automatically sent to the Protection Bulletin.\n",
"example": 30
},
"Ica": {
"type": "string",
"description": "Interbank Card Association (ICA) number - a six-digit account number that identifies a financial institution or third-party processor operating in the Mastercard network. **REQUIRED** for Mastercard.\n\nIt must be padded with leading zeros.\n",
"example": "012345"
},
"ProgramID": {
"description": "Pismo program ID.",
"type": "number",
"example": 1010
},
"RegionCode": {
"type": "array",
"description": "Region code contains one or more Account Screen Authorization File (ASAF) region codes that define the distribution of a Visa cardholder account number in Card Recovery Bulletin Service files. **REQUIRED** for Visa. \n `0` - No Bulletin / V.I.P. Only (cannot be combined with other region codes)\n `A` - All Asia-Pacific region countries\n `B` - All Central Europe, Middle East, and Africa (CEMEA) region countries.\n `C` - All Visa Canada\n `D` - National Card Recovery Bulletin\n `E` - All European countries\n `F` - All Latin America and Caribbean (LAC) region countries \n\nRegion codes can be in any order, except no other region code can be specified in combination with region code 0.\n\nVisa documentation: VisaNet Authorization-Only Online Messages – Technical Specifications - Table 215: Field 127E.2 Account Screen Authorization File (ASAF) Region Codes\n",
"items": {
"type": "string",
"enum": [
"0",
"A",
"B",
"C",
"D",
"E",
"F"
]
}
},
"StatusNetworkMastercard": {
"type": "string",
"description": "Network status equivalent to Pismo status. **REQUIRED** for Mastercard. \n `C` - Credit \n `F` - Fraud \n `G` - ATM Premium Listing \n `L` - Lost \n `O` - Other \n `P` - Capture card \n `S` - Stolen \n `U` - Unauthorized use \n `V` - Premium listing \n `X` - Counterfeit \n\nMastercard documentation: Customer Interface Specification - DE 120 (Record Data) Layout for MCC102 - Field ID 2 (Entry Reason).\n",
"enum": [
"C",
"F",
"G",
"L",
"O",
"P",
"S",
"U",
"V",
"X"
],
"example": "F"
},
"StatusNetworkVisa": {
"type": "string",
"description": "Network status equivalent to Pismo status. **REQUIRED** for Visa.\n `04` - Pickup card\n `05` - Do not honor\n `07` - Pickup card, special condition\n `11` - Approval for **VIP**\n `14` - Invalid account number (no such number)\n `41` - Lost card, pickup\n `43` - Stolen card, pickup\n `46` - Closed account\n `54` - Expired card\n\nVisa documentation: VisaNet Authorization-Only Online Messages – Technical Specifications - Table 214: Field 127E.1 Account Screen Authorization File (ASAF) Action Codes.\n",
"enum": [
"04",
"05",
"07",
"11",
"14",
"41",
"43",
"46",
"54"
],
"example": "04"
},
"StatusPismo": {
"type": "string",
"description": "Pismo card status. For more information, see [Card lifecycle and statuses](https://developers.pismo.io/pismo-docs/docs/card-lifecycle-and-statuses).\n",
"example": "LOST"
}
},
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Account token - token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a **401 Unauthorized** error.\n",
"bearerFormat": "JWT"
}
},
"responses": {
"202": {
"description": "Accepted"
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessageModel"
},
"examples": {
"Missing or invalid Authorization header": {
"value": {
"code": "EBLT0005",
"message": "Missing or invalid Authorization header",
"http_status_code": 401
}
},
"Invalid Authorization header, missing account-id": {
"value": {
"code": "EBLT0006",
"message": "Invalid Authorization header, missing account-id",
"http_status_code": 401
}
},
"Invalid Authorization header, missing tenant": {
"value": {
"code": "EBLT0007",
"message": "Invalid Authorization header, missing tenant",
"http_status_code": 401
}
}
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessageModel"
},
"examples": {
"Something went wrong when try to process a request in another service": {
"value": {
"code": "EBLT9998",
"message": "Something went wrong when try to process a request in Programs API using ID: 123",
"http_status_code": 500
}
},
"Something went wrong, please try again later": {
"value": {
"code": "EBLT9999",
"message": "Something went wrong, please try again later",
"http_status_code": 500
}
}
}
}
}
},
"504": {
"description": "Gateway Timeout",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessageModel"
},
"examples": {
"Request timeout": {
"value": {
"code": "EBLT0001",
"message": "Request timeout",
"http_status_code": 504
}
}
}
}
}
},
"400PostSetup": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessageModel"
},
"examples": {
"Failed to parse request payload": {
"value": {
"code": "EBLT0003",
"message": "Failed to parse request payload",
"http_status_code": 400
}
}
}
}
}
},
"404PostSetup": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessageModel"
},
"examples": {
"Programs API returned not found": {
"value": {
"code": "EBLT0009",
"message": "Programs API returned [Not found] using ID: {program_id}",
"http_status_code": 404
}
}
}
}
}
},
"422PostSetup": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessageModel"
},
"examples": {
"Required fields for all brands": {
"value": {
"code": "BBLT0001",
"message": "Error while validating fields",
"http_status_code": 422,
"details": {
"payload": [
{
"field": "program_id",
"message": "This field is required"
},
{
"field": "active",
"message": "This field is required"
}
]
}
}
},
"Required fields for Mastercard brand": {
"value": {
"code": "BBLT0001",
"message": "Error while validating fields",
"http_status_code": 422,
"details": {
"payload": [
{
"field": "ica",
"message": "This field need to be length equals 6"
},
{
"field": "allowed_status.status_network",
"message": "This field has an invalid value (A). The accepted values are: C, F, G, L, O, P, S, U, V, X"
}
]
}
}
},
"Required fields for Visa brand": {
"value": {
"code": "BBLT0001",
"message": "Error while validating fields",
"http_status_code": 422,
"details": {
"payload": [
{
"field": "bid",
"message": "This field need to be length equals 6"
},
{
"field": "region_code",
"message": "This field is required"
},
{
"field": "region_code",
"message": "This field has an invalid value (Z). The accepted values are: 0, A, B, C, D, E, F"
},
{
"field": "region_code",
"message": "The value '0' in region_code is not allowed with other region_code."
},
{
"field": "allowed_status.status_network",
"message": "This field has an invalid value (00). The accepted values are: 04, 05, 07, 11, 14, 41, 43, 46, 54"
}
]
}
}
},
"The program with ID does not have a network brand": {
"value": {
"code": "BBLT0006",
"message": "The program with ID 123 does not have a network brand.",
"http_status_code": 422
}
}
}
}
}
}
}
},
"paths": {
"/v1/bulletin/setup": {
"post": {
"summary": "Create Protection Bulletin rule",
"operationId": "post-v1-bulletin-setup",
"description": "Register a new Protection Bulletin setup rule. This feature is available for Elo, Mastercard and Visa.\n\nWhen you set a card rule, for example, when a card status is changed to `LOST`, it is automatically added to the Protection Bulletin.\n\nThis operation executes asynchronously. When complete, a [Bulletin rule event](https://developers.pismo.io/events/docs/bulletin-bulletin-rule-1) is generated.\n\n**Notes:** \n * This endpoint takes an account token - an access token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a 401 Unauthorized message.\n * Deactivating a rule after it has been created requires re-calling this endpoint with `active` set to `false`.\n",
"tags": [
"Rules"
],
"parameters": [
{
"$ref": "#/components/parameters/AuthHeader"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/BulletinSetupEloModel"
},
{
"$ref": "#/components/schemas/BulletinSetupMastercardModel"
},
{
"$ref": "#/components/schemas/BulletinSetupVisaModel"
}
]
},
"examples": {
"Setup Rule Elo with allowed status": {
"value": {
"active": true,
"program_id": 1010,
"allowed_status": [
{
"status_pismo": "LOST",
"default_purge_days": 30
},
{
"status_pismo": "ROBBED",
"default_purge_days": 15
}
]
}
},
"Setup Rule Elo without allowed status": {
"value": {
"active": true,
"program_id": 1010
}
},
"Setup Rule Mastercard with allowed status": {
"value": {
"active": true,
"ica": "012345",
"program_id": 1010,
"allowed_status": [
{
"status_pismo": "LOST",
"status_network": "L",
"default_purge_days": 30
},
{
"status_pismo": "ROBBED",
"status_network": "O",
"default_purge_days": 15
}
]
}
},
"Setup Rule Mastercard without allowed status": {
"value": {
"active": true,
"ica": "012345",
"program_id": 1010
}
},
"Setup Rule Visa with allowed status": {
"value": {
"active": true,
"bid": "012345",
"program_id": 1010,
"region_code": [
"A",
"B",
"C",
"D",
"E",
"F"
],
"allowed_status": [
{
"status_pismo": "LOST",
"status_network": "41",
"default_purge_days": 30
},
{
"status_pismo": "ROBBED",
"status_network": "43",
"default_purge_days": 15
}
]
}
},
"Setup Rule Visa without allowed status": {
"value": {
"active": true,
"bid": "012345",
"program_id": 1010,
"region_code": [
"A",
"B",
"C",
"D",
"E",
"F"
]
}
}
}
}
}
},
"responses": {
"202": {
"$ref": "#/components/responses/202"
},
"400": {
"$ref": "#/components/responses/400PostSetup"
},
"401": {
"$ref": "#/components/responses/401"
},
"404": {
"$ref": "#/components/responses/404PostSetup"
},
"422": {
"$ref": "#/components/responses/422PostSetup"
},
"500": {
"$ref": "#/components/responses/500"
},
"504": {
"$ref": "#/components/responses/504"
}
}
}
}
}
}
```