v1

latestOpenAPI 3.1.0Copyright Pismo2026-07-247702,7523.1 MB

Embossing encrypted

Get nominal encrypted card data for embossing V2 [beta]

Get encrypted card embossing data.

Issuers who do their own embossing can use this endpoint to get a card's data, which needs to be encrypted as per regulations.

This endpoint uses AES256 with the GCM mode, and randomly generates the initialization vector, returning it in the response. AES-256 GCM is an authenticated encryption mode that uses the Advanced Encryption Standard (AES) with a 256-bit key in Galois/Counter Mode (GCM) to provide both confidentiality and integrity for data. The Additional Authenticated Data (AAD) parameter used is the organization/tenant ID. AAD, in AES-GCM, is unencrypted data that is authenticated alongside the ciphertext to ensure the message's integrity and authenticity.

To use this endpoint:

Open a Jira 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 event.

Notes:

This endpoint requires an account token - an access token encoded with a Pismo account ID.
This is a PCI endpoint, use the https://gw-pci.pismolabs.io environment.

post/embossing/v2/cards/generate-embossing

Request body

card_idinteger required

Enrolled card ID

key_idstring required

Encryption key ID to embossing, used in conjunction with the initial vector value.

Example request

{
  "card_id": 6743052
}

Response

Encrypted card embossing data (shown here as unencrypted JSON)

org_idstring

Organization ID

card_idinteger

ID of card to create relationship for

account_idinteger

Account ID

customer_idinteger

Pismo customer ID.

program_idnumber

Pismo program ID.

embossing_custom_fieldstring

For physical cards. Additional information for embossing company. For example: tracking number or whether the card should be plastic or metal.

You 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.

ivstring

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.

encrypted_card_datastring

Encrypted card data

When decrypted, this field will have the following JSON:

card_number type: string description: Primary Account Number (PAN)
printed_name type: string description: Printed/embossed card holder name.
expiration_date type: string description: Card expiration date (format:yymm)
pinblock
type: string description: 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.
cvv type: string description: | 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.
cvv2: type: string description: | 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.
service_code_cvv1:
type: string description: | 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.
service_code_cvv2:
type: string description: | 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.
service_code_icvv:
type: string description: | 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.
track2_chip:
type: string description: | 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.
track1_magnetic_stripe:
type: string description: | 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.
track2_magnetic_stripe:
type: string description: | 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.

Example response

{
  "org_id": "TN-cc8f8b89-233a-4582-9f36-63ee85278d6d",
  "card_id": 6743052,
  "account_id": 6912345,
  "customer_id": 5648988,
  "program_id": 1010,
  "embossing_custom_field": "Tracking ID = 5859930"
}