Manage personalisation designs
Personalisation designs
A personalisation design is a logical grouping of all the design attributes required to personalise and ship a card. It includes both a physical bundle and any other elements needed to complete personalisation on a card:
- A physical bundle is a set of physical goods in inventory that are personalised and shipped when you issue a card. See Standard cards or Custom cards to learn more. You can also view all of your physical bundles
- Some bundles support or require other design attributes, such as card logos and carrier text.
A card logo is an image printed onto the card, which you provide to Stripe as a file upload. Stripe only prints card logos in one colour, so for the highest quality print we require that card logo images are purely binary containing a black logo on a white background with no greyscale. To upload a logo, use the File API with purpose
set to issuing_logo
.
curl https://files.stripe.com/v1/files \ -u
: \ -F "file"="@/path/to/a/file.jpg" \ -F "purpose"="issuing_logo"sk_test_4eC39HqLyjWDarjtT1zdp7dc
Carrier text is a set of content, which you provide as separate pieces of text, printed onto a carrier letter template. When creating a personalisation design, you need to specify both the physical bundle to use, as well as a card logo and carrier text if the bundle requires it.
Stripe must review and approve your design (and the underlying physical bundle) before fulfilling any cards made with that design. See Personalisation design review to learn more.
There is no limit to the number of personalisation designs you can create. This gives you the flexibility to express any number of combinations of a physical bundle, card logo, and carrier text to best suit your use case.
Personalisation design review
If your personalisation design includes a logo or carrier text, Stripe must review it to make sure they comply with the guidelines set by our partner networks. A design’s status
field indicates whether it’s under review, active, or rejected. Cards created with personalisation designs in review wait for fulfilment until the personalisation design clears review. A personalisation design can’t leave the review state if its physical bundle hasn’t been approved yet.
After approval, the personalisation design status advances to active. After becoming active, any cards with fulfilment waiting on the personalisation design may be fulfilled. Any cards created with a personalisation design that is already active may be fulfilled immediately. Note that other reviews, such as cardholder watchlist screening, may also prevent a card from being fulfilled immediately.
You can only set/update the physical_bundle
, card_logo
, and carrier_text
attributes when first creating the personalisation design, or after the personalisation design has been rejected.
Handle design rejection
When a personalisation design is rejected, you’re notified with a webhook if configured. The personalisation design object identifies which part of the design violated design guidelines and reason(s) for the rejection in the rejection_reasons
attribute.
Rejection reason | Explanation |
---|---|
non_binary_image | The image isn’t binary – it contains colours, including greyscale, other than black and white. You can use image manipulation software to threshold the image into binary form. |
network_name | The image or text improperly uses the name of a credit card network. |
other_entity | The image or text improperly uses the name of another entity. |
geographic_location | The image or text contains the name of a geographic location. |
non_fiat_currency | The image or text contains a reference to non-fiat currency. |
promotional_material | The image or text contains advertising, promotional material, or a tagline. |
inappropriate | The image or text contains inappropriate content. |
other | The image or text was flagged for some other reason. See Stripe Support to contact us about how to remediate the rejection. |
You can update the relevant design attributes to address the rejection. Any updates return the personalisation design to the review state, which prevents any further updates to those attributes.
Handle status changes programmatically
Stripe provides webhook events for personalisation design updates to help you integrate personalisation design management into your own platform.
Webhook event | Trigger |
---|---|
issuing_personalization_design.updated | Occurs whenever a personalisation design is updated by you or Stripe. |
issuing_personalization_design.activated | Occurs whenever Stripe activates the bundle for a personalisation design and design review approves the design. |
issuing_personalization_design.rejected | Occurs whenever a personalisation design is rejected. |
issuing_personalization_design.deactivated | Occurs whenever Stripe deactivates the bundle for a personalisation design. |
See webhooks to learn more.
Test status changes
Stripe drives all status changes to a personalisation design. However, we provide several test mode helpers so you can test your integration by triggering status changes yourself in test mode:
Set a default personalisation design
To help streamline your integration, you can set a default personalisation design so that you don’t need to explicitly specify a personalisation design for every card you create.
When creating or updating a personalisation design, set the is_default
preference to true
. The is_default
preference for the previous default design is automatically set to false
, as there can only be one default.
After you have a default set, any cards you create without specifying a personalisation design automatically use the default. Trying to create a card without specifying a personalisation design when you don’t have any defaults set results in an error.
You can always override the default personalisation design when creating a card by specifying the personalization_design
parameter.
Change personalisation designs without deploying code using lookup keys
Some businesses built on Stripe Issuing offer multiple card products to their cardholders. The personalisation design representing the card product can change over time. If you hardcode your personalisation designs and you want to change them, the process often requires you to deploy new code. You can use lookup keys to remove the need to deploy new code when you want to change personalisation designs.
To use lookup keys with personalisation designs, you can assign a unique lookup key by passing the lookup_key
parameter when creating or updating a personalisation design. Instead of hardcoding a personalisation design ID, you hardcode the lookup key value and query for the matching personalisation design using the personalisation design list endpoint.
To improve performance, you might want to cache and/or only reload the personalisation design occasionally. When it’s time to change the personalisation design for a card product, you can create or update a new personalisation design using the existing value for lookup_key
while setting transfer_lookup_key
to true
.
Manage personalisation designs using Connect
When using Connect, personalisation designs can be managed at both the platform and connected account levels, just as described above. However, Connect also grants you some ways to streamline your integration even further, by giving connected accounts access to resources at the platform level.
Personalisation designs and physical bundles
Each of your connected accounts can access personalisation designs and physical bundles created at the platform level. This means that you can:
- Issue cards from a connected account with a personalisation design created on the platform.
- Create a personalisation design on a connected account using a physical bundle available within the platform’s account. This allows you to create these resources on your platform account, and share them across all of your connected accounts. We recommend managing as much as possible at the platform level, unless there are any items that should explicitly be hidden from a connected account, or will only ever be used for specific connected accounts.
Default personalisation designs
Each of your connected accounts can set their own default personalisation design. You can also set a default personalisation design at the platform level. If set, the platform default is used when you issue a card for a connected account without specifying a design, and that connected account doesn’t have a default.
If you want issued cards to use the platform default, you can unset the default personalisation design for the connected account.