Build Your First Card

This quickstart is the minimum user-initiated path. It deliberately uses a Data Transmit Link so that you can validate card design, token generation and device behaviour before adding inbound partner APIs or advanced capabilities.

Before you start

You need a card programme in Testing Mode, its Card ID, the approved certificate information, the matching partner private key, a supported test device and non-production sample card data. If any item is missing, return to Prerequisites and Onboarding and Credentials.

Step 1 — define one card instance

  1. Select the applicable card specification.
  2. Start with the common fields, then add every required field from the selected card type.
  3. Assign a stable and unique refId to the logical card instance. If the value is exposed as pdata in a Data Fetch Link, it must also be non-guessable.
  4. Use epoch timestamps in milliseconds where the specification defines a timestamp.
  5. Validate images and any barcode, QR-code or structured string against Chapter 2.

Output: one valid card JSON object containing non-production data.

Step 2 — protect the card data

Create cdata as specified in Card Data Token. Use the algorithms and certificate identifiers issued for your integration, generate the token on a trusted server and apply the documented validity rules.

Output: one serialised cdata value that can be validated with the configured test credentials.

Insert the Card ID and URL-encoded cdata into the Data Transmit Link format. Do not substitute a Partner ID, template identifier or refId for the Card ID path value.

Output: one ATW URL for the test card instance.

Step 4 — expose and exercise the entry point

Use the Add to Samsung Wallet entry-point guidance for the test channel. Open it on the supported device, review the preview, add the card and inspect the resulting card details.

Output: the card is visible in Samsung Wallet with the expected text, images, dates and barcode behaviour.

Step 5 — verify completion and lifecycle

Confirm that the partner can correlate the add result with the original Card ID and refId. Re-open or repeat the same user action to verify duplicate-safe behaviour. Then plan the callback and update interfaces in Manage Card Lifecycle.

Definition of done

The quickstart is complete when:

  • the test device adds the expected card from the partner entry point;
  • the displayed card matches the selected card specification and template;
  • an expired, altered or invalid token is rejected rather than accepted;
  • repeating the same journey does not create an unintended second logical card; and
  • request identifiers and relevant server events can be traced without logging card secrets.

Next, implement the lifecycle behaviour required by your service and run the broader Test Strategy and Acceptance Checklist.