Add Card Art

DOCS

Last updated: Sept 23rd, 8:18pm

Card art is available through the issuer network for cards that are eligible for tokenization. We recommend using the Card Art API in regions where tokenization is not available or for cards that are ineligible for tokenization.

You can add card art in different ways:

  • As part of the initial onboarding call. The following sample code shows how to create a consumer referral resource for a customer with a credit card. This sample sends card art.
    1curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v1/customer/consumer-referrals' \
    2  -H 'Authorization: Bearer A21AAHnicuqnZrlX4qzrm2stVYC2eYnJFhnO_ZfEAs3-kTYUU9gRHSo_WLRipfArOuoUz0DETX-J-A0hgb5eO0k75vjuCKsiw' \
    3  -H 'Accept: application/json' \
    4  -H 'Content-Type: multipart/form-data' -F 'request={"person_details":{"names":[{"given_name":"Niklas","surname":"Frangos"}],"phone_contacts":[{"phone":{"country_code":"43","national_number":"123456789"},"phone_type":"MOBILE"}],"addresses":[{"address":{"line1":"20/Wolfengasse 3","line2":"Fleischmarkt","city":"Vienna","country_code":"AT","postal_code":"A-1010"},"address_type":"HOME"}],"email_addresses":[{"email_address":"consumer@example.com","primary":true,"confirmed":false}],"locale":"en_US"},"paypal_account_properties":{"account_country_code":"AT"},"linked_instruments":{"card_accounts":[{"identifier":"4185560131914493","reference_financial_instrument_id":"B2121XYZ","expiry_date":"2020-12","billing_address":{"address_line_1":"2211 N 1st Street","admin_area_1":"CA","admin_area_2":"San Jose","country_code":"US","postal_code":"95035"},"account_holder_name":{"given_name":"John","surname":"Smith"},"card_art":{"reference_id":"GAT13576232","product":{"id":"AEG123ba08y08y3","customer_support":{"email":"help@example.com","phone_number":{"country_code":"1","national_number":"4089671000"}},"product_description":"Discover Rewards"},"primary_content":{"id":"UNIQUE_ID_SAMPLE_1A","format":"image/png","width":500,"height":500},"thumbnail_content":{"id":"UNIQUE_ID_SAMPLE_1B","format":"image/png","width":50,"height":50},"metadata":{"id":"AEG123ba08y08y3","background_color":"0xe6e6e6","foreground_color":"0xddeeff","label_color":"0x214121"}}}]}};type=application/json' \
    5  -F 'UNIQUE_ID_SAMPLE_1A=@./discover.png' \
    6  -F 'UNIQUE_ID_SAMPLE_1B=@./discover_thumb.png'

    There are advantages to each method:

    Method of adding card art Advantage
    Card Metadata Tags resource Faster, enables access to the customer's card art in PayPal.

    For card-issuing partners, the Card Metadata Tags resource enables them to add their card art to the card.
    Inside the flow Simpler integration.

    Once completed, the image of the card displays in the cardholder's PayPal wallet.

    When the cardholder views their card with card art in their PayPal wallet, it appears similar to this image: Card,art,details

    At checkout, a card with card art appears similar to this image: Checkout,with,card,art

    The partner can identify and use PAN data to connect the card art to a card.

    PAN is used to tie the card art to the card number. This provides two advantages:

    • When a card account owner has a custom picture on their card.
    • When the card-issuing partner uses the same BIN range for multiple products. For example, a card beginning with 551122 could be either a Rewards Mastercard or a Points Mastercard.

    Use the Card Metadata Tags resource

    Using the Card Metadata Tags resource, the partner can associate card art to a card in these ways:

    Upload card art

    The card art image files need to be a quality resolution that allows for upscaling, and in an aspect ratio that represents a credit card.

    • Use POST /v1/payment-networks/card-metadata-tags to upload card art via multipart file upload request. In a multipart request, the image file passes in as one part of the form request.
    • The form parameter name must match the unique ID the partner assigns to the image. This ID is also passed in the card_arts[].primary_content.id or card_arts[].thumbnail_content.id fields.
    • Requests must be in multipart/form-data format.

    The following code sample shows a multipart/form-data request to the Card Metadata Tags resource to add card art using PAN data:

      1curl -v -k -X POST https://api-m.sandbox.paypal.com/v1/payment-networks/card-metadata-tags
      2-H 'Authorization: Bearer A21AAHrWw4CqSgeeSE-6Z-R0D0N6W5sHE1DczDMjzTWGVc_vOA1YnsJNP6iCk_sW773F07zeoxYoggauOezURvdFWUeuy4bbg'
      3-H 'Content-Type: multipart/form-data'
      4-H 'Accept: application/json'
      5-F 'request={  
      6   "card_arts":[  
      7      {  
      8         "reference_id":"fa984a46-0534-4f1c-97fc-49c0cabec1ab",
      9         "card_pan":"4143416767061433",
      10         "product":{  
      11            "id":"6ca52e37-ef2e-45c9-895c-8555fa7484a8",
      12            "customer_support":{  
      13               "email":"customer_support@bank.com"
      14            },
      15            "product_description":"Bank Classic Visa"
      16         },
      17         "primary_content":{  
      18            "id":"611cd4a7-b5dd-4a96-a701-a4dbf058a23b",
      19            "height":939,
      20            "width":1536,
      21            "format":"image/png"
      22         },
      23         "thumbnail_content":{  
      24            "id":"8b3ef902-a912-4080-a1c6-024a8bc6ea4a",
      25            "height":29,
      26            "width":50,
      27            "format":"image/png"
      28         },
      29         "metadata":{  
      30            "id":"a2d07c5a-3a19-45e0-afcc-ee65cc5dd0ee",
      31            "background_color":"0xffffff",
      32            "foreground_color":"0xc0c0c0",
      33            "label_color":"0x212121"
      34         }
      35      }
      36   ]
      37};type=application/json'
      38-F'611cd4a7-b5dd-4a96-a701-a4dbf058a23b=@/tmp/ybCard.png;type=image/png'
      39-F'8b3ef902-a912-4080-a1c6-024a8bc6ea4a=@/tmp/cardThumbnailTwo.png;type=image/png'

      To link a new card with uploaded card art:

      • Pass the id of an uploaded image in primary_content.id or thumbnail_content.id. The system links the new card with the image referenced by id.
      • This request must be in application/json format.

      The following code sample shows an application/json request to the Card Metadata Tags resource to add card art using PAN data:

        1curl -k -X POST https://api-m.sandbox.paypal.com/v1/payment-networks/card-metadata-tags  -H 'Authorization: Bearer A21AAHrWw4CqSgeeSE-6Z-R0D0N6W5sHE1DczDMjzTWGVc_vOA1YnsJNP6iCk_sW773F07zeoxYoggauOezURvdFWUeuy4bbg' -H 'Content-Type: application/json' -H 'Accept: application/json'
        2-d '{  
        3   "card_arts":[  
        4      {  
        5         "reference_id":"093d1833-47d9-4f88-a9f3-bd6b96efa5e5",
        6         "card_pan":"4018355564538098",
        7         "product":{  
        8            "id":"6ca52e37-ef2e-45c9-895c-8555fa7484a8"
        9         },
        10         "primary_content":{  
        11            "id":"611cd4a7-b5dd-4a96-a701-a4dbf058a23b"
        12         },
        13         "thumbnail_content":{  
        14            "id":"8b3ef902-a912-4080-a1c6-024a8bc6ea4a"
        15         },
        16         "metadata":{  
        17            "id":"a2d07c5a-3a19-45e0-afcc-ee65cc5dd0ee"
        18         }
        19      }
        20   ]
        21}'

        Restrictions

        • The POST API payload must be 1MB or smaller.
        • The following APIs are not ready yet:
          • PATCH /v1/payment-networks/card-metadata-tags/{id}
          • GET /v1/payment-networks/card-metadata-tags/{id}
          • GET /v1/payment-networks/card-metadata-tags by reference_id

        Best practices for card art integration

        Reuse partner-defined IDs for subsequent calls

        Use POST /v1/payment-networks/card-metadata-tags (multipart request) to upload each image once.

        After uploading images and card metadata tags, reuse the same IDs in JSON payloads for subsequent calls.

        Store PayPal-generated IDs

        After a successful card metadata tags resource call, a response is returned and PayPal generates an ID. Use this ID for subsequent update or read API calls. PayPal recommends the partner stores this ID.

        To obtain the ID, call our "future" read API with the reference_id as a query parameter. The partner provides this reference_id during the card metadata tags resource call. When this API becomes available, it returns the reference_id.

        Use optional fields

        The context of an API call determines whether a field is mandatory. For example, the partner must include foreground color for metadata in the first call. In subsequent calls, the partner only needs to include the IDs.

        Field Comment
        Image height and width This field is derived if not passed.
        Foreground color This is the only mandatory field for metadata. Background and label color are optional and not currently used.

        Within each linked_card_art object, provide a unique ID in the primary_content and thumbnail elements. This ID maps to the name of part of the request.

        Next

        You can optionally Add Mutual SSL for additional channel protection.

        ReferencePayPal.comPrivacyCookiesSupportLegalContact

        If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more