Checking access…

Skip to main content
Version: v2

Manufacturer Card

Integration reference for managing manufacturer (MF) cards β€” request/response contract, terminology, and payload handling. For what a manufacturer card is and the business rules governing it, see the Manufacturer Card business guide.

Terminology​

Legacy MF Card​

A MF card not linked with a medication.

info

'Legacy' doesn't just imply existing older cards in the system, as a new legacy MF card can be added to the wallet by a legacy client.

Legacy Client​

Refers to an API consumer using the old contract format to manage MF cards.

A client is considered legacy if the request payload includes the manufacturerCard flag:

// sample req payload (add MF card flow / one time pay flow / pay and save flow)

{
"paymentMethod": {
"paymentMethodDetails": {
"manufacturerCard": true // boolean
}
}

New Client​

Refers to an API consumer using the new contract format to manage MF cards.

A client is considered new if the request payload includes the cardCategories structure:

// sample req payload (add MF card flow / one time pay flow / pay and save flow)
{
"paymentMethod": {
"paymentMethodDetails": {
"cardCategories": {
"type": "MANUFACTURER_CARD",
"medications": [
{
"label": "Tremfya", // string
"value": "5mg" // string
}
]
}
}
}

Manufacturer Card Category Structure​

FieldTypeValid valuesRequiredConstraintsExample
typeEnumMANUFACTURE_CARDYes"MANUFACTURER_CARD" only"MANUFACTURER_CARD"
labelStringYesMax 100 chars"Pharmacy card"
medicationsObjectMedicationNoList of {label, value}See below

Medication Structure​

FieldTypeRequiredExample
labelStringYes"Tremfya"
valueStringYes"10mg"

Constraints​

  • type must be "MANUFACTURER_CARD" for manufacturer cards.
  • label is required and ≀ 100 characters.
  • medications is optional; if present, each must have both label and value.

Validation Rules​

  • type must be a recognized enumeration value (e.g., MANUFACTURER_CARD).
  • If type is MANUFACTURER_CARD, medications must be present.
  • If label is present, it must be a non-empty string; if not provided, it defaults to the merchant-configured value.
  • Each entry in medications[] must include:
    • label: non-empty string and ≀ 100 characters.
    • value: non-empty string and ≀ 100 characters.

Handling Mixed Payload Formats​

When a client sends a request payload containing both the old (manufacturerCard flag) and new (cardCategories structure) formats, the system ignores the old format and processes the payload using the new format. This ensures consistency with the latest business rules and avoids ambiguity.

// sample req payload: (add MF card flow / one time pay flow / pay and save flow)
{
"paymentMethod": {
"paymentMethodDetails": {
"manufacturerCard": true, // boolean Old format (ignored)
"cardCategories": {
"type": "MANUFACTURER_CARD",
"medications": [
{
"label": "Tremfya", // string
"value": "5mg" // string
}
]
}
}
}
}

Use Case Handling Summary​

ScenarioMerchant Configured with MANUFACTURER_CARDMerchant Not Configured with MANUFACTURER_CARD
cardCategories present in session requestHonor cardCategories and persist in DB.Ignore cardCategories, save session without it
cardCategories is not present in session requestSave session request as-is in DB.Save session request as-is in DB.
cardCategories is present in session request and no medicationsHonor cardCategories and persist and persist without medications in DB.Ignore cardCategories, save session without it.

Technical Usecases​

Managing manufacturer card: UI Widget​


Managing manufacturer card: API​


Payment with Manufacturer card: UI Widget​


Payment with Manufacturer card: API​