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.
'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β
| Field | Type | Valid values | Required | Constraints | Example |
|---|---|---|---|---|---|
type | Enum | MANUFACTURE_CARD | Yes | "MANUFACTURER_CARD" only | "MANUFACTURER_CARD" |
label | String | Yes | Max 100 chars | "Pharmacy card" | |
medications | Object | Medication | No | List of {label, value} | See below |
Medication Structureβ
| Field | Type | Required | Example |
|---|---|---|---|
label | String | Yes | "Tremfya" |
value | String | Yes | "10mg" |
Constraintsβ
typemust be"MANUFACTURER_CARD"for manufacturer cards.labelis required and β€ 100 characters.medicationsis optional; if present, each must have bothlabelandvalue.
Validation Rulesβ
typemust be a recognized enumeration value (e.g.,MANUFACTURER_CARD).- If
typeisMANUFACTURER_CARD,medicationsmust be present. - If
labelis 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β
| Scenario | Merchant Configured with MANUFACTURER_CARD | Merchant Not Configured with MANUFACTURER_CARD |
|---|---|---|
cardCategories present in session request | Honor cardCategories and persist in DB. | Ignore cardCategories, save session without it |
| cardCategories is not present in session request | Save session request as-is in DB. | Save session request as-is in DB. |
| cardCategories is present in session request and no medications | Honor cardCategories and persist and persist without medications in DB. | Ignore cardCategories, save session without it. |