Skip to content

Card Art

As a part of the tokenization process for Visa and Mastercard cards, a merchant can receive the customer’s card art provided to Visa and Mastercard by the card issuer.

This card art may then be shown in cardholder-facing PAN display interactions, for example:

  • when displaying linked cards in the customer's profile on the merchant's website or in the application.
  • when displaying available cards on the payment page.

To receive this file, a merchant needs

  • to specify notification_url in credit_card object for direct integrations.
  • to specify card_notification_url in settings object in the payment token request for widget integrations.

bePaid will then send a card notification to the merchant to the specified URL. The notification will contain a link to a PNG file in image parameter.

Requirements

  • Currently, the option is available for Visa and Mastercard cards.
  • Merchant needs to be registered in Visa Tokenization Service system (VTS) or Mastercard Checkout Solutions respectively. Both registrations are carried out by bePaid. Contact your Account Manager to make sure you are registered.

Request

Direct Integration

Specify notification_url in credit_card object in one of the following requests:

Parameter Type Description
credit_card object A section of credit card parameters.
notification_url
required		 string (255) A URL for receiving card notifications.
Payment request example with credit_card.notification_url 
{
  "request":{
      "amount":100,
      "currency":"USD",
      "description":"Test transaction",
      "tracking_id":"your_uniq_number",
      "language":"en",
      "test":true,
      "billing_address":{
        "first_name":"John",
        "last_name":"Doe",
        "country":"US",
        "city":"Denver",
        "state":"CO",
        "zip":"96002",
        "address":"1st Street"
      },
      "credit_card":{
        "number":"4200000000000000",
        "verification_value":"123",
        "holder":"John Doe",
        "exp_month": "05",
        "exp_year": "2026",
        "notification_url": "https://your-card-notification-url"
      },
      "customer":{
        "ip":"127.0.0.1",
        "email":"john@example.com"
      }
  }
}

Widget integration

Specify card_notification_url in settings object in payment token request.

Card notifications

The merchant will receive the file with the card art in the card notification sent to the provided URL.

The card notification will be sent in 2 cases:

  • When the merchant sends credit_card.notification_url in the authorization/tokenization/payment request (or settings.card_notification_url in payment token request for widget integrations).
  • When the card issuer changes the card art and informs Visa/Mastercard about it.

Verify webhook requests

Card notifications are verified the same way as webhook notifications.

Example of card notification 
{
  "holder": "John Doe",
  "stamp": "399c17cbfc7d07fe3351f031a0952152240492c0d5793bb972b0ceba2da9842b",
  "brand": "visa",
  "last_4": "0000",
  "first_1": "4",
  "token": "6045e2bd-5b0c-4a8c-8357-24d1cdfbb9df",
  "product": null,
  "bin": "420000",
  "bin_8": "42000000",
  "issuer_country": null,
  "issuer_name": null,
  "exp_month": 11,
  "exp_year": 2026,
  "image": "https://some-url-for-image.com/image.png"
}

Processing card notifications

Merchant's web server should return 200 HTTP status code if a card notification is processed successfully. Otherwise, bePaid will resend the data later.

Best practices for using card art on the payment page

  • The merchant needs to cache the received image file for further use, instead of requesting it multiple times.

  • The digital card art images provided by Visa/Mastercard do not include cardholder name, PAN, or expiration date, either in generic form or using actual values.

  • The last four digits of the card number or digital account number and cardholder name should be placed in the bottom left corner of the digital card art (if used).

  • No images or text, other than the last four digits of the card number or digital account number and/or cardholder name, may be placed over the card art.

  • Visa card art

  • The last four digits of the Visa card number and the digital account number must always be preceded by "Visa" (for example, Visa 9876).