Masking card numbers in messages

When the maskCreditCardNumbers setting is enabled on a Sunshine Conversations app, incoming message text is automatically scanned for payment card numbers and redacted before the message is stored or forwarded to any downstream system.

maskCreditCardNumbers is separate from the Zendesk ticket redact credit card numbers and hiding credit card numbers in chat. maskCreditCardNumbers applies only to Sunshine Conversations messages.

What this setting does

When a message arrives, its text is scanned for payment card numbers. If a match is found, all digits except the last four are replaced with asterisks before the message is stored or forwarded.

Formatting characters such as spaces and hyphens are removed during redaction. The number of asterisks reflects the total number of digits of the card number minus four:

Original (16-digit): 4444-3333-2222-1111
Redacted:            ************1111

Original (16-digit): 4444 3333 2222 1111
Redacted:            ************1111

Original (16-digit): 4444333322221111
Redacted:            ************1111

Original (15-digit Amex): 3782-822467-11005
Redacted:                 ***********1005

If a card number appears mid-sentence, it is masked in place and the surrounding text is left untouched:

Original: Here is my credit card: 4444-3333-2222-1111
Redacted: Here is my credit card: ************1111

How numbers are detected

A sequence of digits is only masked if it passes all three of the following checks:

• Shape
• Checksum
• Known network pattern

Shape

The number must consist of 13–19 digits, optionally separated by spaces or hyphens:

Format	Example
No separators	4444333322221111
Space-separated	4444 3333 2222 1111
Hyphen-separated	4444-3333-2222-1111

If there are exactly two letters immediately before the digits (and those letters are not themselves preceded by another letter or digit), the prefix is preserved and the digits are still masked:

Original: VI4444-3333-2222-1111
Redacted: VI************1111

Checksum

The sequence must pass the Luhn algorithm, the standard checksum used by all major card networks to detect transcription errors. Numbers that fail this check are not masked.

Known network pattern

The sequence must match the digit length and leading-digit prefix of a recognized card network:

Network	Coverage	Notes
Visa	Global
Mastercard	Global
American Express	Global
Discover	Global
Diners Club	Global
JCB	Global
UnionPay	Global
Maestro	Global	Debit-only network
Elo	Brazil
Mir	Russia
Hiper	Brazil
Hipercard	Brazil
UATP	Global

If a number doesn't match any of these patterns, it is not masked, even if it has the right length and passes the Luhn algorithm.

What is excluded from masking

To minimize false positives, the following are not treated as card numbers even if the sequence has the right shape, passes Luhn, and matches a known network:

• Numbers starting with +: To avoid masking phone numbers.
• Numbers embedded in a URL: For example, "facebook.com/posts/4444333322221111" is left untouched.
• Digits that are part of a longer number: If another digit appears immediately before or after the matched sequence, the full sequence is assumed to be part of a longer number and is skipped.
• Digits that resemble a decimal number: Digits adjacent to a period (.) or comma (,) with neighboring digits are skipped, unless the context makes two separate card numbers unambiguous.
• Numbers with one or three or more letters immediately preceding them: For example, "aVI4444333322221111" is not masked. Numbers with exactly 2 leading letters (such as "VI4444333322221111") are still masked, provided those letters are not themselves preceded by another letter or digit.

Note: As with any pattern-based detection, some real card numbers may not be masked, and in rare cases a non-card number that has the right shape and passes the Luhn algorithm might be masked.

Does this mask debit card numbers?

Detection is based on the card number, not on whether the card is a credit or debit product. For all major global networks, such as Visa, Mastercard, American Express, Discover, and JCB, debit and credit cards share the same numbering scheme, so a debit card number is masked exactly as a credit card number would be. Maestro, a debit-only network, is also supported.

Local and bank-proprietary debit networks not included in the recognized network list above are not supported. Numbers from those networks cannot be detected because there is no publicly documented, standardized numbering scheme that covers every regional debit network worldwide.

Enabling and disabling this setting

maskCreditCardNumbers is an app-level boolean setting managed with the Create App endpoint.

To enable masking:

curl -X PATCH https://{subdomain}.zendesk.com/sc/v2/apps/{appId} \
  -H "Authorization: Bearer {jwt}" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "maskCreditCardNumbers": true
    }
  }'

To disable masking:

curl -X PATCH https://{subdomain}.zendesk.com/sc/v2/apps/{appId} \
  -H "Authorization: Bearer {jwt}" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "maskCreditCardNumbers": false
    }
  }'

Replace {subdomain} with your Zendesk subdomain, {appId} with your app id, and {jwt} with a signed JSON Web Token. For information on generating a JWT and authenticating API requests, see API authentication.