# Get nominal encrypted card data for embossing

Get encrypted card embossing data. This is for issuers doing their own embossing and require a card's data, which needs to be encrypted as per regulations.

**To use this endpoint:**
  * Open a [Jira ticket](https://developers.pismo.io/pismo-docs/docs/opening-a-service-desk-ticket) with type = **Settings** and ask to use on-demand embossing.
  * Generate and register a symmetric key with Pismo: open a Jira ticket with type = **Settings** and request an asymmetric key (RSA 2048 PKCS1) to send the symmetric key.

While the return values are shown as JSON, they are encrypted and not returned as clear text.

The endpoint generates a [Card embossing notification received](https://developers.pismo.io/events/docs/cards-embossing-1) event.

**Note:** This is a PCI endpoint, use the https://gw-pci.pismolabs.io environment.


# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "Card issuing - Cards",
    "version": "1.4.6",
    "description": "Card endpoints API",
    "contact": {
      "name": "API Support",
      "url": "https://developers.pismo.io/support/"
    },
    "license": {
      "name": "Copyright Pismo"
    }
  },
  "servers": [
    {
      "url": "https://sandbox.pismolabs.io",
      "description": "Sandbox API server for testing."
    },
    {
      "url": "https://gw-pci.pismolabs.io",
      "description": "Sandbox PCI API server for testing"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Embossing encrypted",
      "description": "Embossing encrypted data endpoints"
    }
  ],
  "components": {
    "schemas": {
      "AccountID": {
        "type": "integer",
        "description": "Pismo account ID",
        "example": 7654776
      },
      "CardID": {
        "type": "object",
        "description": "Pismo card ID object",
        "properties": {
          "cardId": {
            "type": "string",
            "description": "Card ID",
            "example": "737040484"
          }
        }
      },
      "CardID2": {
        "type": "integer",
        "description": "Pismo card ID",
        "example": 123456
      },
      "CustomerID": {
        "type": "integer",
        "description": "Pismo customer ID",
        "example": 765476676
      },
      "EmbossingCustomField": {
        "type": "string",
        "description": "For physical cards. Additional information for embossing company. For example: tracking number or whether the card should be plastic or metal. \n\nYou can use this field for any embossing needs specific to your business.  Whatever is sent must be agreed upon with the embosser—what to send, what values to send, what format to send, what size to send for each value, and so on.\n",
        "example": "Tracking ID = 5859930",
        "maxLength": 1000
      },
      "EncryptedCardContent": {
        "type": "object",
        "properties": {
          "org_id": {
            "$ref": "#/components/schemas/OrgID"
          },
          "card_id": {
            "$ref": "#/components/schemas/CardID2"
          },
          "account_id": {
            "$ref": "#/components/schemas/AccountID"
          },
          "customer_id": {
            "$ref": "#/components/schemas/CustomerID"
          },
          "program_id": {
            "$ref": "#/components/schemas/ProgramID"
          },
          "embossing_custom_field": {
            "$ref": "#/components/schemas/EmbossingCustomField"
          },
          "encrypted_card_data": {
            "$ref": "#/components/schemas/EncryptedCardData"
          }
        }
      },
      "EncryptedCardData": {
        "type": "string",
        "description": "Encrypted card data\n\nWhen decrypted, this field will have the following JSON:  \n\n* **`card_number`**\n  type: string\n  description: Primary Account Number (PAN)\n\n* **`printed_name`** \n  type: string \n  description: Printed/embossed card holder name.\n\n* **`expiration_date`**\n  type: string\n  description: Card expiration date (format:yymm)\n\n* **`pinblock`**  \n  type: string\n  description: \n    PINBlocks are 64-bit strings that encode a PIN ready for encryption and secure transmission in banking networks. PIN block ISO 9564-1 format 0. It contains both the PIN and additional data needed to encrypt it for transmission. The PIN block is typically encrypted using a secure cryptographic algorithm to prevent unauthorized access or tampering during transmission. \n\n* **`cvv`** \n  type: string \n  description: |\n    Card Verification Value (CVV) is a three- or four-digit security code that is printed on payment cards to help verify that the cardholder is the one making a transaction. \n\n* **`cvv2`**: \n  type: string \n  description: |\n    Card Verification Value 2 (CVV2) is also a three-digit code printed on the back of the card. While CVV and CVV2 are both three-digit codes, CVV is numeric only, while CVV2 can contain letters and numbers. \n\n* **`service_code_cvv1`**:  \n  type: string\n  description: |\n   Service code for the card verification value 1 (CVV1) is a three-digit code that is encoded on the magnetic stripe of a payment card  and is used to verify the card's authenticity during a transaction. It is different from the CVV2 or CVC2 codes, which are three- or four-digit codes printed on the back of the card and used for online or phone transactions. \n\n* **`service_code_cvv2`**:  \n  type: string\n  description: |\n    Service code for the card verification value 2 (CVV2) is a three- or four-digit security code. It is a security feature that helps verify that the card is physically present during card-not-present transactions. It is not encoded on the card's magnetic stripe.\n\n* **`service_code_icvv`**:  \n  type: string\n  description: |\n     Service code for the ICVV (Issuer Controlled Card Verification Value) is a dynamic security code the issuing bank generates generated and is used to verify the payment card authenticity during transactions.\n\n* **`track2_chip`**:  \n  type: string\n  description: |\n    Analogous to the `track2_magnetic_stripe`, but instead of being recorded on the magnetic stripe it is stored inside the chip. Instead of the CVV2, which is included on the magnetic stripe's track 2, the chip (and therefore this field) contains the iCVV. The same applies for the service code: on the magnetic track2 it `service_code_cvv2`, but here it is `service_code_icvv`.\n\n* **`track1_magnetic_stripe`**:  \n  type: string\n  description: |\n  Track 1 of the card's magnetic stripe located on the back of the card and is read by card readers and point-of-sale (POS) terminals. It contains several fields of information, including the cardholder's name, account number, expiration date, and other identifying information.\n\n* **`track2_magnetic_stripe`**:  \n  type: string\n  description: |\n    Track 2 of the magnetic stripe is similar to track 1 magnetic stripes but contains less information and include only the cardholder's account number, expiration date, and a discretionary data field.\n"
      },
      "GetEncryptedCardDataRequest": {
        "type": "object",
        "required": [
          "card_id",
          "iv",
          "key_id"
        ],
        "properties": {
          "card_id": {
            "$ref": "#/components/schemas/CardID"
          },
          "iv": {
            "$ref": "#/components/schemas/InitialVector"
          },
          "key_id": {
            "$ref": "#/components/schemas/KeyID3"
          }
        }
      },
      "InitialVector": {
        "type": "string",
        "description": "Initial vector (IV) value, needs to be 16 bytes and hexadecimal. An IV is a random or pseudo-random value used as the starting point for an encryption algorithm to generate a unique cipher text for each message. The IV is used in combination with a secret key (`key_id`) to ensure that the same message encrypted with the same key does not result in the same cipher text.\n"
      },
      "KeyID3": {
        "type": "string",
        "description": "Encryption key ID to embossing, used in conjunction with the initial vector value.\n"
      },
      "OrgID": {
        "type": "string",
        "description": "Organization/tenant ID",
        "example": "TN-f878e4a1-2879-48ba-be16-821e73ac98db"
      },
      "ProgramID": {
        "type": "integer",
        "description": "Pismo program ID",
        "example": 7654
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Account token - an access token encoded with a Pismo account ID. Tokens can expire quickly, which can result in an \"Unauthorized\" error.",
        "bearerFormat": "JWT"
      }
    },
    "responses": {
      "401Unauthorized": {
        "description": "Access token is missing or invalid"
      },
      "500InternalServer": {
        "description": "Internal server error"
      }
    }
  },
  "paths": {
    "/embossing/v1/cards/generate-embossing": {
      "post": {
        "summary": "Get nominal encrypted card data for embossing",
        "description": "Get encrypted card embossing data. This is for issuers doing their own embossing and require a card's data, which needs to be encrypted as per regulations.\n\n**To use this endpoint:**\n  * Open a [Jira ticket](https://developers.pismo.io/pismo-docs/docs/opening-a-service-desk-ticket) with type = **Settings** and ask to use on-demand embossing.\n  * Generate and register a symmetric key with Pismo: open a Jira ticket with type = **Settings** and request an asymmetric key (RSA 2048 PKCS1) to send the symmetric key.\n\nWhile the return values are shown as JSON, they are encrypted and not returned as clear text.\n\nThe endpoint generates a [Card embossing notification received](https://developers.pismo.io/events/docs/cards-embossing-1) event.\n\n**Note:** This is a PCI endpoint, use the https://gw-pci.pismolabs.io environment.\n",
        "operationId": "post-generate-embossing",
        "tags": [
          "Embossing encrypted"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GetEncryptedCardDataRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Encrypted card embossing data (shown here as unencrypted JSON)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EncryptedCardContent"
                },
                "example": {
                  "org_id": "TN-5aea4104-7994-46d5-83d6-a55cxxxxxxxx",
                  "card_id": 19509998,
                  "correlation_id": "9f46663d-34dc-9e37-a89a-a1d6ef56039a",
                  "password_updated": true,
                  "account_id": 116871845,
                  "card_number": "123456******7890",
                  "program_id": 11084,
                  "printed_name": "Tupper Weir",
                  "expiration_date": "2805",
                  "customer_id": 116906961,
                  "cvv": "468",
                  "cvv2": "178",
                  "icvv": "010",
                  "track1_magnetic_stripe": "B6505670006255449^DOE/JOHN^2805201000000000000000468000000?",
                  "track1_chip": "B6505670006255449^DOE/JOHN ^2805201000000000000000010000000?",
                  "track2_chip": "6505670006255449D28052010000001000000F",
                  "track2_magnetic_stripe": "6505670006255449=28052010000046800000?",
                  "pinblock": "E6203FAE966D7D90",
                  "service_code_cvv1": "201",
                  "service_code_cvv2": "000",
                  "service_code_icvv": "999"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "description": "",
                  "type": "object",
                  "properties": {
                    "error_code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/401Unauthorized"
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "description": "",
                  "type": "object",
                  "properties": {
                    "error_code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "error": {
                      "type": "string"
                    }
                  }
                },
                "examples": {
                  "example-bad-request": {
                    "value": {
                      "message": "Not found configurations ondemand to org",
                      "error": "Not_found",
                      "status": 404
                    }
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/500InternalServer"
          }
        }
      }
    }
  }
}
```