# Register card with Protection Bulletin
Register a Pismo-issued card with the Protection Bulletin. This feature is available for Elo, Mastercard and Visa.
The Protection Bulletin is used before a transaction takes place in cases where the issuer is temporarily offline and unable to provide an authorization. In a process known as *stand-in*, the card network authorizes the transaction to avoid creating problems for the cardholder and merchant. Once the issuer is back online, the card network lets them know what was authorized while they were down.
You can add a card to the Protection Bulletin with this endpoint or [setting a card rule](ref:post-v1-bulletin-setup) so that when a card's status changes to a rule's configured status, the card is automatically added to the Protection Bulletin.
For more information, refer to [Protection Bulletin](doc:protection-bulletin).
**Note:** 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.
# 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": "Bulletin",
"description": "Endpoints to manage cards with the Protection Bulletin"
}
],
"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"
}
},
"XCustomerIdHeader": {
"name": "x-customer-id",
"in": "header",
"description": "Pismo customer ID. Must be associated with account whose ID is embedded in the access token.\n",
"required": true,
"schema": {
"type": "number"
}
}
},
"schemas": {
"BulletinPostEloModel": {
"type": "object",
"description": "Register a Elo card.",
"required": [
"card_id"
],
"properties": {
"card_id": {
"$ref": "#/components/schemas/CardID"
}
}
},
"BulletinPostMastercardModel": {
"type": "object",
"description": "Register a Mastercard card.",
"required": [
"card_id",
"reason"
],
"properties": {
"card_id": {
"$ref": "#/components/schemas/CardID"
},
"reason": {
"$ref": "#/components/schemas/ReasonMastercard"
},
"purge_date": {
"$ref": "#/components/schemas/PurgeDateMastercard"
}
}
},
"BulletinPostVisaModel": {
"type": "object",
"description": "Register a Visa card.",
"required": [
"card_id",
"reason",
"region_code",
"card_track_number",
"purge_date"
],
"properties": {
"card_id": {
"$ref": "#/components/schemas/CardID"
},
"reason": {
"$ref": "#/components/schemas/ReasonVisa"
},
"region_code": {
"$ref": "#/components/schemas/RegionCode"
},
"card_track_number": {
"$ref": "#/components/schemas/CardTrackNumberVisa"
},
"purge_date": {
"$ref": "#/components/schemas/PurgeDateVisa"
}
}
},
"BulletinResponseHistoryModel": {
"type": "array",
"description": "Response history model for the Bulletin API.",
"items": {
"type": "object",
"properties": {
"event": {
"$ref": "#/components/schemas/Event"
},
"event_date": {
"$ref": "#/components/schemas/EventDate"
},
"status": {
"$ref": "#/components/schemas/Status"
},
"reason": {
"$ref": "#/components/schemas/Reason"
},
"network_track_number": {
"$ref": "#/components/schemas/NetworkTrackNumber"
},
"was_automatically_purged": {
"$ref": "#/components/schemas/WasAutomaticallyPurged"
},
"card_track_number": {
"$ref": "#/components/schemas/CardTrackNumber"
},
"network_response_data": {
"$ref": "#/components/schemas/NetworkResponseData"
},
"region_code": {
"$ref": "#/components/schemas/RegionCode"
}
}
}
},
"BulletinResponseModel": {
"type": "object",
"description": "Response model for the Bulletin API.",
"properties": {
"card_id": {
"$ref": "#/components/schemas/CardID"
},
"org_id": {
"$ref": "#/components/schemas/OrgID"
},
"program_id": {
"$ref": "#/components/schemas/ProgramID"
},
"network_brand_type": {
"$ref": "#/components/schemas/NetworkBrandType"
},
"created_at": {
"$ref": "#/components/schemas/CreatedAt"
},
"updated_at": {
"$ref": "#/components/schemas/UpdatedAt"
},
"network_track_number": {
"$ref": "#/components/schemas/NetworkTrackNumber"
},
"state": {
"$ref": "#/components/schemas/State"
},
"status": {
"$ref": "#/components/schemas/Status"
},
"purge_date": {
"$ref": "#/components/schemas/PurgeDate"
},
"was_automatically_purged": {
"$ref": "#/components/schemas/WasAutomaticallyPurged"
},
"card_track_number": {
"$ref": "#/components/schemas/CardTrackNumber"
},
"region_code": {
"$ref": "#/components/schemas/RegionCode"
},
"histories": {
"$ref": "#/components/schemas/BulletinResponseHistoryModel"
}
}
},
"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"
}
}
},
"CardID": {
"description": "Pismo card ID.",
"type": "number",
"example": 10203040
},
"CardTrackNumber": {
"description": "Pismo card track number.",
"type": "number",
"example": 1
},
"CardTrackNumberVisa": {
"description": "Pismo card track number.\n\nThe card track number sent to the Account Screen Authorization File (ASAF). If `1`, the first copy is sent. If `2`, the second copy is sent. If `0`, all copies are sent. A card might be added to the Protection Bulletin, before being voided and reissued, resulting in more than one copy. \n\nVisa documentation: VisaNet Authorization-Only Online Messages – Technical Specifications - Field 23: Card Sequence Number\n",
"type": "number",
"example": 1
},
"CreatedAt": {
"type": "string",
"description": "Date and time when the Protection Bulletin registration was created. Format = ISO 8601.",
"format": "yyyy-mm-dd hh:mm:ss",
"example": "2025-04-22 20:31:50"
},
"Event": {
"type": "string",
"description": "Event performed in the request",
"enum": [
"POST",
"UPDATE",
"DELETE"
],
"example": "POST"
},
"EventDate": {
"type": "string",
"description": "Date and time when the event was received in the Protection Bulletin.",
"format": "yyyy-mm-dd hh:mm:ss",
"example": "2025-04-22 20:31:50"
},
"NetworkBrandType": {
"type": "string",
"description": "Card network brand.",
"enum": [
"ELO",
"MASTERCARD",
"VISA"
],
"example": "ELO"
},
"NetworkResponseData": {
"type": "string",
"description": "Response JSON data received from the network brand.\n\nThe content of this field will indicate the original response from the network brand, whether success or failure. The example provided in this model is for illustrative purposes only.\n",
"example": "{\"status\":\"SUCCESS\",\"message\":\"Card added to Protection Bulletin\"}"
},
"NetworkTrackNumber": {
"type": "string",
"description": "Created in the internal system to track the card's event history. This is a combination between the tenant and the truncated random uuid.",
"example": "TN-123XXX-XXXXXX-XXXXXXX::1a2b3c"
},
"OrgID": {
"description": "Pismo organization/tenant ID.",
"type": "string",
"example": "TN-123XXX-XXXXXX-XXXXXXX"
},
"ProgramID": {
"description": "Pismo program ID.",
"type": "number",
"example": 1010
},
"PurgeDate": {
"type": "string",
"description": "Date when the card will be removed from the Protection Bulletin in the network brand. Format = yyyy-mm-dd.\n",
"format": "yyyy-mm-dd",
"example": "2025-04-22"
},
"PurgeDateMastercard": {
"type": "string",
"description": "Date when the card should be removed from the Protection Bulletin. Format = yyyy-mm-dd.\n\nMastercard documentation: Customer Interface Specification - DE 120 (Record Data) Layout for MCC102 - Field ID 8 (Issuer-defined Purge Date)\n",
"example": "2024-10-22"
},
"PurgeDateVisa": {
"type": "string",
"description": "Date when the card should be removed from the Protection Bulletin. Format = yyyy-mm-dd.\n\nVisa documentation: VisaNet Authorization-Only Online Messages – Technical Specifications - Field 73: Action Date\n",
"example": "2024-10-22"
},
"Reason": {
"type": "string",
"description": "Reason that indicates why the card was added to the Protection Bulletin.",
"example": "L"
},
"ReasonMastercard": {
"type": "string",
"description": "Reason for adding card to Protection Bulletin. **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"
},
"ReasonVisa": {
"type": "string",
"description": "Reason for adding card to Protection Bulletin. **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"
},
"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"
]
}
},
"State": {
"type": "string",
"description": "Is card blocked or not in the network brand? When the state is empty, it means the network brand did not successfully receive any action.\n",
"enum": [
"",
"BLOCKED",
"UNBLOCKED"
],
"example": "BLOCKED"
},
"Status": {
"type": "string",
"description": "Request processing status.",
"enum": [
"PENDING",
"SUCCESS",
"FAILED"
],
"example": "PENDING"
},
"UpdatedAt": {
"type": "string",
"description": "Date and time when the Protection Bulletin was updated. Format = ISO 8601.\n",
"format": "yyyy-mm-dd hh:mm:ss",
"example": "2025-04-22 20:31:50"
},
"WasAutomaticallyPurged": {
"type": "boolean",
"description": "Was card removed from the network brand on the purge date?\n",
"example": true
}
},
"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": {
"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
}
}
}
}
}
},
"201PostBulletin": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulletinResponseModel"
},
"examples": {
"Register a Elo card": {
"value": {
"card_id": 10203040,
"org_id": "TN-123XXX-XXXXXX-XXXXXXX",
"program_id": 1010,
"network_brand_type": "ELO",
"created_at": "2025-04-22 20:31:50",
"network_track_number": "TN-123XXX-XXXXXX-XXXXXXX::1a2b3c",
"status": "PENDING",
"was_automatically_purged": true,
"histories": [
{
"event": "POST",
"event_date": "2025-04-22 20:31:50",
"status": "PENDING",
"network_track_number": "TN-123XXX-XXXXXX-XXXXXXX::1a2b3c",
"was_automatically_purged": true,
"network_response_data": "null",
"card_track_number": 1
}
]
}
},
"Register a Mastercard card": {
"value": {
"card_id": 10203040,
"org_id": "TN-123XXX-XXXXXX-XXXXXXX",
"program_id": 1010,
"network_brand_type": "MASTERCARD",
"created_at": "2025-04-22 20:31:50",
"purge_date": "2026-01-01",
"network_track_number": "TN-123XXX-XXXXXX-XXXXXXX::1a2b3c",
"status": "PENDING",
"was_automatically_purged": true,
"histories": [
{
"event": "POST",
"event_date": "2025-04-22 20:31:50",
"status": "PENDING",
"network_track_number": "TN-123XXX-XXXXXX-XXXXXXX::1a2b3c",
"reason": "O",
"was_automatically_purged": false,
"network_response_data": "null",
"card_track_number": 1
}
]
}
},
"Register a Visa card": {
"value": {
"card_id": 10203040,
"org_id": "TN-123XXX-XXXXXX-XXXXXXX",
"program_id": 1010,
"network_brand_type": "VISA",
"created_at": "2025-04-22 20:31:50",
"purge_date": "2026-01-01",
"network_track_number": "TN-123XXX-XXXXXX-XXXXXXX::1a2b3c",
"status": "PENDING",
"was_automatically_purged": true,
"card_track_number": 1,
"region_code": [
"A",
"B",
"C",
"D",
"E",
"F"
],
"histories": [
{
"event": "POST",
"event_date": "2025-04-22 20:31:50",
"status": "PENDING",
"network_track_number": "TN-123XXX-XXXXXX-XXXXXXX::1a2b3c",
"reason": "04",
"was_automatically_purged": false,
"network_response_data": "null",
"card_track_number": 1,
"region_code": [
"A",
"B",
"C",
"D",
"E",
"F"
]
}
]
}
}
}
}
}
},
"400PostBulletin": {
"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
}
}
}
}
}
},
"404PostBulletin": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessageModel"
},
"examples": {
"Wallets returned not found": {
"value": {
"code": "EBLT0009",
"message": "Wallets returned [Not found] using ID: 123",
"http_status_code": 404
}
}
}
}
}
},
"422PostBulletin": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorMessageModel"
},
"examples": {
"Error while validating fields for all brands (header and payload)": {
"value": {
"code": "BBLT0001",
"message": "Error while validating fields",
"http_status_code": 422,
"details": {
"header": [
{
"field": "x-customer-id",
"message": "This field is required"
}
],
"payload": [
{
"field": "card_id",
"message": "This field is required"
},
{
"field": "purge_date",
"message": "This field has an invalid date format. The correct format is yyyy-MM-dd"
}
]
}
}
},
"Error while validating fields for Mastercard": {
"value": {
"code": "BBLT0001",
"message": "Error while validating fields",
"http_status_code": 422,
"details": {
"payload": [
{
"field": "reason",
"message": "This field is required"
},
{
"field": "reason",
"message": "This field has an invalid value (A). The accepted values are: C, F, G, L, O, P, S, U, V, X"
},
{
"field": "purge_date",
"message": "This field need to be greater than 2025-10-20 (180 days)"
}
]
}
}
},
"Error while validating fields for Visa": {
"value": {
"code": "BBLT0001",
"message": "Error while validating fields",
"http_status_code": 422,
"details": {
"payload": [
{
"field": "reason",
"message": "This field is required"
},
{
"field": "reason",
"message": "This field has an invalid value (00). The accepted values are: 04, 05, 07, 11, 14, 41, 43, 46, 54"
},
{
"field": "region_code",
"message": "This field has an invalid value (X). 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."
}
]
}
}
},
"Bulletin card has an ongoing event in the network brand": {
"value": {
"code": "BBLT0003",
"message": "Bulletin card has an ongoing event in the network brand.",
"http_status_code": 422
}
},
"Bulletin card is already BLOCKED": {
"value": {
"code": "BBLT0004",
"message": "Bulletin card is already BLOCKED",
"http_status_code": 422
}
},
"The card with ID does not have a network brand": {
"value": {
"code": "BBLT0005",
"message": "The card with ID 123 does not have a network brand.",
"http_status_code": 422
}
}
}
}
}
}
}
},
"paths": {
"/v1/bulletin": {
"post": {
"summary": "Register card with Protection Bulletin",
"operationId": "post-v1-bulletin",
"description": "Register a Pismo-issued card with the Protection Bulletin. This feature is available for Elo, Mastercard and Visa.\n\nThe Protection Bulletin is used before a transaction takes place in cases where the issuer is temporarily offline and unable to provide an authorization. In a process known as *stand-in*, the card network authorizes the transaction to avoid creating problems for the cardholder and merchant. Once the issuer is back online, the card network lets them know what was authorized while they were down.\n\nYou can add a card to the Protection Bulletin with this endpoint or [setting a card rule](https://developers.pismo.io/pismo-docs/reference/post-v1-bulletin-setup) so that when a card's status changes to a rule's configured status, the card is automatically added to the Protection Bulletin.\n\nFor more information, refer to [Protection Bulletin](https://developers.pismo.io/pismo-docs/docs/protection-bulletin).\n\n**Note:** 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",
"tags": [
"Bulletin"
],
"parameters": [
{
"$ref": "#/components/parameters/AuthHeader"
},
{
"$ref": "#/components/parameters/XCustomerIdHeader"
}
],
"requestBody": {
"description": "Bulletin data. Enter data for one object, depending on brand (Elo, Visa, or Mastercard)",
"required": true,
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/BulletinPostEloModel"
},
{
"$ref": "#/components/schemas/BulletinPostMastercardModel"
},
{
"$ref": "#/components/schemas/BulletinPostVisaModel"
}
]
},
"examples": {
"Register a Elo card": {
"value": {
"card_id": 10203040
}
},
"Register a Mastercard card with purge date": {
"value": {
"card_id": 10203040,
"reason": "L",
"purge_date": "2026-01-01T00:00:00.000Z"
}
},
"Register a Mastercard card without purge date": {
"value": {
"card_id": 10203040,
"reason": "L"
}
},
"Register a Visa card with purge date": {
"value": {
"card_id": 10203040,
"card_track_number": 0,
"reason": "04",
"region_code": [
"A",
"B",
"C",
"D",
"E",
"F"
],
"purge_date": "2026-01-01T00:00:00.000Z"
}
},
"Register a Visa card without purge date": {
"value": {
"card_id": 10203040,
"card_track_number": 0,
"reason": "04",
"region_code": [
"A",
"B",
"C",
"D",
"E",
"F"
]
}
}
}
}
}
},
"responses": {
"201": {
"$ref": "#/components/responses/201PostBulletin"
},
"400": {
"$ref": "#/components/responses/400PostBulletin"
},
"401": {
"$ref": "#/components/responses/401"
},
"404": {
"$ref": "#/components/responses/404PostBulletin"
},
"422": {
"$ref": "#/components/responses/422PostBulletin"
},
"500": {
"$ref": "#/components/responses/500"
},
"504": {
"$ref": "#/components/responses/504"
}
}
}
}
}
}
```