DpaAddUpdateRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/mastercard/main/json-schema/mastercard-dpa-add-update-request-schema.json",
  "title": "DpaAddUpdateRequest",
  "description": "The DpaAddUpdateRequest is used to add, update, or delete DPAs from the Mastercard system. Additionally, the DpaAddUpdateRequest can be used to generate serviceIds in Commerce Platform use cases.\n\nA Digital Payment Application (DPA) is a website, web or mobile application operated by a Merchant, marketplace, or other service provider where a consumer can purchase goods or services.\n\nA ServiceId is a unique identifier assigned by Mastercard for which tokens are created uniquely for the entity onboarded. A serviceId can have multiple associated DPAs.\n\nThe DpaAddUpdateRequest request must contain the following values:\n\n * items\n * action\n * programType\n\n The contents of the DPA items will vary based on the operation requested.\n",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/mastercard-batch-api-openapi.yml#/components/schemas/DpaAddUpdateRequest",
  "type": "object",
  "required": [
    "items"
  ],
  "properties": {
    "requestId": {
      "description": "This field allows the Integrator to assign an internal reference to a batch request so that it can be used for internal tracking purposes.",
      "type": "string"
    },
    "items": {
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/AddUpdateItems"
      },
      "type": "array",
      "description": "Items\n\nObject for Integrator to provide a list of Digital Payment Applications (DPA) to be enrolled in a given program. A minimum of 1 item must be provided in a request.\n"
    }
  },
  "$defs": {
    "AcquirerData": {
      "type": "object",
      "description": "\nObject for details about the acquiring institution (for example, merchant bank) or its agent. This includes acquirerIca, acquirerMerchantId and acquirerBin. This object may be used to improve transaction acceptance rates.\n",
      "required": [
        "acquirerIca",
        "acquirerMerchantId"
      ],
      "properties": {
        "acquirerIca": {
          "type": "string",
          "description": "An Acquirer Interbank Card Association (ICA) value is an identifier assigned to the Acquirer by Mastercard."
        },
        "acquirerBin": {
          "type": "string",
          "description": "Each Acquirer Interbank Card Association (ICA) identifier may be assigned one or more BINs by Mastercard.\n\nNote: It is important to use the correct Acquirer ICA associated with the Acquirer BIN.\n"
        },
        "acquirerMerchantId": {
          "type": "string",
          "description": "A Merchant Identifier (MID) is a unique code assigned to the Merchant by the Acquirer once the Merchant has successfully opened an account. A MID identifies the Merchant to the Acquirer."
        }
      }
    },
    "AddUpdateItems": {
      "type": "object",
      "required": [
        "action",
        "programType"
      ],
      "properties": {
        "action": {
          "description": "The action to be performed on the Digital Payment Application (DPA). The selected action will be applied to all DPAs provided in the items list.\n\nADD - Add DPA\n\nUPDATE - Update DPA\n\nDELETE - Delete DPA\n\nNote:\n* A limited number of DPA fields can be changed using the __UPDATE__ action. These are `dpaPresentationName`, `programName`, `dpaLogoUri`, `debitTokenRequested`, `merchantCategoryCode`, and `threeDSDefaultData`. Please refer to the example for a minimal use case.\n* All DPA data from the original request (including non-updatable fields) will also need to be provided unchanged in the __PUT__ request for the operation to process successfully.\n",
          "enum": [
            "ADD",
            "UPDATE",
            "DELETE"
          ],
          "type": "string"
        },
        "customerId": {
          "maxLength": 60,
          "description": "Conditional: The Customer Identifier (CID) must be passed when the Integrator is acting On-Behalf-Of (OBO) a client, registering through the Mastercard Connect (MC Connect) portal, or participating in the Secure Card on File (SCOF) program.\n\nThis field should be populated with the CID of the Integrator's client (e.g., a Payment Service Provider (PSP) would pass the CID of the client they are integrating, i.e. DASP model).\n",
          "type": "string"
        },
        "programType": {
          "description": "The Mastercard program that the Integrator would like to add their client(s) to. The Integrator must be enrolled in the program prior to enrolling their client(s). Integrators may view their active programs in the Mastercard Connect (MC Connect) portal.\n\n`SECURE_COF_MERCHANT` -  Integrating Merchant managing network tokenization. Tokens generated are unique for each merchant.\n\n`SECURE_COF_MERCHANT_OBO` - Integrating Payment Service Provider (PSP) managing network tokenization for their Merchant(s). Tokens generated are unique for each merchant.\n\n`SECURE_COF_COMMERCE_PLATFORM` - Integrating Commerce Platform managing network tokenization. Tokens are generated unique for each Commerce Platform (tokens will be shared among their marketplace).\n\n`SECURE_COF_COMMERCE_PLATFORM_OBO` - Integrating PSPs managing network tokenization for their Commerce Platform(s). Tokens are generated unique for each Commerce Platform (tokens will be shared among their marketplace).\n\n`SECURE_COF_MERCHANT_OBO_SHARED` - Integrating PSPs managing network tokenization for their sub-Merchants. Tokens generated are unique for each Merchant Group.\n\n`SRC` - Integrating Merchants and PSPs participating in or offering the Click to Pay (C2P) program.\n\n`GUEST_CHECKOUT_TOKENIZATION` - A checkout solution that uses an alternative identifier to Account PANs, generated by the issuing network for guest checkout tokenization.\n\nNote: Other programTypes (e.g., AUTOFILL, SQR_DEVICE etc.) may be available to select regions. Please contact your Mastercard representative for more details.\n",
          "enum": [
            "SRC",
            "SECURE_COF_MERCHANT_OBO",
            "SECURE_COF_MERCHANT",
            "SECURE_COF_MERCHANT_OBO_SHARED",
            "SECURE_COF_COMMERCE_PLATFORM",
            "SECURE_COF_COMMERCE_PLATFORM_OBO",
            "SQR_DEVICE",
            "AUTOFILL",
            "GUEST_CHECKOUT_TOKENIZATION"
          ],
          "type": "string"
        },
        "trid": {
          "description": "The Token Requestor Identifier (TRID) should be passed by MDES for Merchants (M4M) Integrators who would like to onboard their M4M TRIDs to be used on Secure Card on File (SCOF).",
          "type": "string"
        },
        "serviceId": {
          "description": "A unique identifier assigned by Mastercard for which tokens are created uniquely for the entity onboarded.",
          "maxLength": 255,
          "type": "string"
        },
        "category": {
          "maxLength": 255,
          "description": "Assign a category to the sub-merchant group identified in the request. For example, sub-merchants can be grouped by common attributes such as merchant category code (MCC), volume of transactions, or geography. Required for the SECURE_COF_MERCHANT_OBO_SHARED program type. Examples: \"discount stores\" and \"bakeries\"",
          "type": "string"
        },
        "programName": {
          "maxLength": 100,
          "description": "The Cardholder facing name of the Merchant.\n\nConditional: Must be supplied when adding Merchants to all Secure Card On File (SECURE_COF) programs.\n",
          "type": "string"
        },
        "dpas": {
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/Dpas"
          },
          "type": "array",
          "description": "Dpas\n\nObject for Integrator to provide a list of Digital Processing Application (DPA) objects. Each DPA object is used to create a corresponding DPA. A minimum of 1 DPA object (to a maximum of 80 DPA objects) must be provided in the request.\n"
        }
      }
    },
    "Address": {
      "type": "object",
      "description": "The Digital Payment Application (DPA) business address.",
      "properties": {
        "name": {
          "maxLength": 100,
          "description": "Contact name for the address.",
          "type": "string"
        },
        "line1": {
          "maxLength": 75,
          "description": "First line of the address.",
          "type": "string"
        },
        "line2": {
          "maxLength": 75,
          "description": "Second line of the address.",
          "type": "string"
        },
        "line3": {
          "maxLength": 75,
          "description": "Third line of the address.",
          "type": "string"
        },
        "city": {
          "maxLength": 50,
          "description": "Address of city",
          "type": "string"
        },
        "state": {
          "maxLength": 30,
          "description": "Address of state",
          "type": "string"
        },
        "countryCode": {
          "maxLength": 2,
          "description": "Address country code. ISO 3166 alpha 2 country code.",
          "type": "string"
        },
        "zip": {
          "maxLength": 20,
          "description": "Address zip/postal code.",
          "type": "string"
        }
      }
    },
    "DpaData": {
      "type": "object",
      "description": "DpaData\nObject for Integrator to populate Digital Payment Application (DPA) information, including the Merchant name, address, and other relevant data.\n",
      "properties": {
        "dpaPresentationName": {
          "type": "string",
          "maxLength": 255,
          "description": "The name of the Merchant that the Cardholder will see when checking out with the Digital Payment Application (DPA).\n\nConditional: Required for Guest Checkout Tokenization (GCT) and SQR programs.\n"
        },
        "dpaAddress": {
          "$ref": "#/$defs/Address"
        },
        "dpaName": {
          "type": "string",
          "maxLength": 255,
          "description": "Legal name of Merchant (which may differ from dpaPresentationName)."
        },
        "dpaLogoUri": {
          "type": "string",
          "maxLength": 1024,
          "description": "URI for the logo displayed to Cardholders during C2P checkout."
        },
        "dpaUri": {
          "type": "string",
          "maxLength": 1024,
          "description": "Digital Payment Application (DPA) identifier. This field may contain the DPA website URI, a mobile application identifier, or another unique identifier (UUID, URL, APK package name, etc.)."
        }
      }
    },
    "Dpas": {
      "type": "object",
      "required": [
        "srcDpaId"
      ],
      "properties": {
        "srcDpaId": {
          "type": "string",
          "description": "\nThe registered identifier for the Digital Payment Application (DPA) accessing the service. At least one DPA needs to be registered for each Merchant/Merchant OBO/Sub-Merchant (PF) needed, with additional DPAs being added as required.\n\nConditional: Required if you are a Merchant directly integrating with Mastercard Checkout Solutions (MCS) APIs, a Payment Service Provider (PSP) integrating On-Behalf-Of (OBO) a Merchant, a Payment Facilitator, or if you are enrolling in the Secure Card on File (SCOF) QR program.\n",
          "maxLength": 255
        },
        "hasAcquirerRelationship": {
          "type": "string",
          "description": "Indicates if the Digital Payment Application (DPA) has an Acquirer relationship. This field may be used to improve acceptance rates.",
          "enum": [
            "Y",
            "N"
          ]
        },
        "subMerchantId": {
          "type": "string",
          "description": "Identifier assigned to a Sub-Merchant by the Payment Facilitator (PF). This field may be used to improve transaction security and acceptance rates."
        },
        "paymentFacilitatorId": {
          "type": "string",
          "description": "Payment Facilitator (PF) identifier that may be used to improve transaction security and acceptance rates."
        },
        "dpaData": {
          "$ref": "#/$defs/DpaData"
        },
        "debitTokenRequested": {
          "type": "boolean",
          "description": "Conditional: Must be set to true when the Digital Payment Application (DPA) processes in the United States (US) under the Click to Pay (C2P) program.\n"
        },
        "merchantCategoryCodes": {
          "type": "array",
          "maxItems": 200,
          "description": "Object for the array of Merchant Category Codes (MCC) that the Merchant processes transactions under, and is used for risk-scoring transactions by the issuer. All MCC codes that will be processed by a DPA should be provided here (typically, this will be a single item).\n\nAn MCC is a four-character code assigned by Mastercard to the Merchant that indicates the type of business, service, or product provided by the Merchant.\n\nNote: MCC's may be assigned differently across payment networks. To avoid errors, be sure to use your assigned Mastercard MCC. This code is required for 3-D Secure (3DS) and risk profiling. If the Merchant has more than one MCC, the code most relevant to their business should be used.\n",
          "items": {
            "type": "string",
            "maxLength": 4
          }
        },
        "threeDSDefaultdata": {
          "$ref": "#/$defs/ThreeDSDefaultData"
        },
        "acquirerData": {
          "items": {
            "$ref": "#/$defs/AcquirerData"
          },
          "type": "array"
        }
      }
    },
    "ThreeDSDefaultData": {
      "type": "object",
      "description": "Enables a Merchant to supply their existing 3-D Secure (3DS) integration details at the time of Digital Payment Application (DPA) registration.",
      "properties": {
        "defaultAcquirerBin": {
          "type": "string",
          "description": "Allows a Merchant to set a default Acquirer. An Acquirer BIN is an identifier assigned by Mastercard to an Acquirer.\n\nIf this field is not defined and acquirerData has only one entry, this field will be populated with the value from acquirerBin.\n"
        },
        "defaultAcquirerMerchantId": {
          "type": "string",
          "description": "An identifier assigned to the Merchant by their Acquirer. If this field is not populated and acquirerData has only one entry, this field will be populated with the value from acquirerMerchantId."
        },
        "defaultMerchantCountryCode": {
          "type": "string",
          "description": "Allows a Merchant to set a default Merchant Country Code (CC).\n\nA Merchant CC is a two-character code indicating the country the Merchant is doing business in.\n"
        },
        "defaultMerchantCategoryCode": {
          "type": "string",
          "description": "Allows a Merchant to set a default Merchant Category Code (MCC).\n\nAn MCC is a four-character code assigned by Mastercard to the Merchant that indicates the type of business, service, or product provided by the Merchant.\n\nNote: MCC's may be assigned differently across payment networks. To avoid errors, be sure to use your assigned Mastercard MCC. This code is required for 3-D Secure (3DS) and risk profiling. If the Merchant has more than one MCC, the code most relevant to their business should be used.\n"
        }
      }
    }
  }
}