Guides
Sign UpLog InLearning CenterPlatform StatusPostman Collection

Custom Cards

Suggest Edits

Synctera offers the ability to create physical cards with custom images, such as customers' personal photos. To do this you must have a card program with this feature enabled. To check if custom images are enabled, you can perform a GET /v0/cards/products. Any entry in the list of card products with an image_mode field supports custom images.

All custom card images must be in JPEG format.

Card product image mode

If the card product has an image_mode then it supports custom images. The only supported image_mode is "REQUIRED_APPROVED_FIRST". In this mode card creation requests using that card product must include an image ID and the image ID included in the card creation request must refer to an image which is in the "APPROVED" state.

Image management

Custom card images are managed independently of the cards themselves. It is only during issuing a card that the images are associated with cards.

Card images start in the "NOT_UPLOADED" state and then transition to the "UNREVIEWED" state and finally to either "APPROVED" or "REJECTED".

%%{init: {"fontFamily": "sans-serif"}}%%
graph LR
NOT_UPLOADED-->UNREVIEWED
UNREVIEWED-->APPROVED
UNREVIEWED-->REJECTED
APPROVED-->REJECTED

Images that are "APPROVED" maybe be updated to "REJECTED" but not the other way around.

Create an image entity

Uploading a custom card image is a two-step process. First, you must create a card image entity. This is done by performing a POST /v0/cards/images. The request body must contain the customer ID and the ID of a card product that supports custom images.

{
  "customer_id": "{{customer_id}}",
  "card_product_id": "{{card_product_id}}"
}

This returns the newly-created card image entity in the "NOT_UPLOADED" state with its UUID.

{
  "customer_id": "{{customer_id}}",
  "id": "{{image_id}}",
  "status": "NOT_UPLOADED"
}

Upload the image data

The second step of uploading the card image is to send the binary JPEG image data. You can do this by performing a POST /v0/cards/images/{image_id}/data. Put the binary image data in the body of this request and be sure to set the Content-Type header to image/jpeg.

In the response you should see that the image is now in the "UNREVIEWED" state.

Once you have uploaded the image data for an image it can not be changed. If you want to upload a new image instead you must create a new image entity with a new ID. You must start the two-step process again at the first step.

Acceptable images

Images that you upload are subject to review and will not be printed on cards until they are approved. Prohibited images include but are not limited to:

  • Sexual subject matter of any nature
  • Political subject matter of any nature
  • Offensive racial/prejudicial subject matter of any nature
  • Offensive religious subject matter of any nature
  • Advertising of any nature1
  • Self-promotion of any nature (e.g., personal business card)
  • Copyrighted material of any nature
  • Branded products/services, including abbreviations, acronyms, and/or symbols of any nature
  • Solicitations, including telephone numbers or services of any nature (e.g., 900 or 800 numbers)
  • Celebrities/musicians/athletes/entertainers/public figures, etc., of any nature1 • Affiliation with groups that are
    determined to be of a “socially unacceptable” nature, including scenes, names, or symbols
  • Subject matter of any nature that might result in card acceptance confusion by merchants
  • Subject matter of any nature that might result in card fraud
  • Any graphic design element that might reflect poorly or might engender hostility toward or derision of all or any of
    the Mastercard family of brand

Get the card image

After it is created, you can look up the image entity by performing a GET /v0/cards/images/{image_id}. You can also list all of a customer's images by performing a GET /v0/cards/images?customer_id={{customer_id}}.

To get the JPEG image data, perform a GET /v0/cards/images/{{card_image_id}}/data.

Image review

Once the image data has been uploaded, it is ready to be reviewed. This is typically done through the Synctera application. Authorized users can log in, click on "Cases" in the navigation bar and then click on "Custom Card Review". From here they can preview the images as they would appear on a card and approve or reject them. In Synctera's sandbox, developers can review their own images by performing a PATCH /v0/cards/images/{image_id}. The content of this request is either:

{
  "status": "APPROVED"
}

or:

{
  "status": "REJECTED"
}

Card Creation

When you have an image ready for a card, you can create the card in the usual way by performing a POST /v0/cards using the card product that supports custom images and specifying the image ID in the card_image_id field.

{
  "form": "PHYSICAL",
  "type": "DEBIT",
  "customer_id": "{{customer_id}}",
  "card_image_id": "{{image_id}}",
  "card_product_id": "{{card_product_id}}",
  "account_id": "{{account_id}}"
}

Note that the response will not include some fields that are available when creating cards that don't have custom images. Specifically, the last four digits of the PAN and the expiration month and year will not be included. This is because the cards are not fully created until the image is processed and image processing happens once per day. If everything goes normally, these fields will be available the following day if you perform a GET /v0/cards/{{card_id}}. You can also get these updated fields as soon as the card is fully created via a webhook.

Updated about 1 year ago