Add Card Art
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'
- Using the Card Metadata Tags resource which is explained later in this topic. The Card Metadata Tags resource is part of the Instrument Linking API.
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:
At checkout, a card with card art appears similar to this image:
Note: Adding card art is optional, but recommended for a better user experience.
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
orcard_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-tags2-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'
Link card to existing art
To link a new card with uploaded card art:
- Pass the
id
of an uploaded image inprimary_content.id
orthumbnail_content.id
. The system links the new card with the image referenced byid
. - 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.