Mastercard issuer guide

Lume Token handles MDES requests and scheme responses for your programme. Your backend receives the common notification envelope, delivers OTPs where required, and tracks the resulting token lifecycle.

Provisioning journey

MDES sends AuthorizeService and RequestActivationMethods (RAM) in parallel.
Lume Token validates the card and applies the enabled services and configured rules. Card checking can also produce a TER event.
Lume Token returns the provisioning decision in AuthorizeService. For step-up, activation methods are returned in RAM. An approve or decline returns no activation methods.
Your systems receive TAR and AMR records with eligible request data and the applicable enrichment. Contact-data retrieval can produce an RCD record.
If the cardholder selects an OTP method, MDES sends DeliverActivationCode. Lume Token forwards an OTP event, and you deliver the code through the selected channel.
NotifyServiceActivated and subsequent NotifyTokenUpdated messages produce lifecycle notifications. Update the affected token record from those events.

The steps describe dependencies, not a guaranteed ordering of notification delivery. In particular, do not implement RAM as a call that can arrive only after an AuthorizeService response.

Provisioning examples

Each sample is a complete Lume notification envelope containing selected eligible MDES fields. They follow one synthetic step-up journey; event timestamps illustrate the journey, not a delivery-order guarantee. Lume enrichment (paymentologyPublicCardToken, deviceBlocked, velocityRules, and decisioningReason) is illustrative. Protected card-data containers are replaced by the agreed card reference, so these are not raw requests to replay to MDES.

Scheme method	Event	Example
AuthorizeService	TAR	Provisioning decision
RequestActivationMethods	AMR	Activation methods
DeliverActivationCode	OTP	Code delivery
NotifyServiceActivated	TNR	Activation completion
NotifyTokenUpdated	TNR	Token status update

What the issuer receives

The five examples below retain each method's native context inside ADDITIONAL_MESSAGE_DATA. TER and RCD can also be emitted by the associated card-check and contact-lookup services; see the common notification examples.

AuthorizeService (TAR)

AuthorizeService asks whether a funding account may be digitized. For a protected issuer integration, Lume Token handles scheme decryption and card validation, retaining eligible native fields and substituting the agreed card reference for sensitive card data.

Data	Purpose
Native request identifiers and wallet/requestor fields	Identify and correlate the scheme operation
Card reference	Associate the request with the funding card
Velocity result	Explain an applicable provisioning-activity signal
Device-check result	Explain an applicable TokenGuard signal
Decisioning context	Show the outcome, matched rule and selected profiles where relevant

In Notification mode, Lume Token returns the native decision to MDES and your endpoint acknowledges TAR with HTTP 200. For issuer decision responses, see Advice mode.

Record the provisioning decision and risk-service results. This rule requires additional authentication. Activation profiles in the notification explain the decision; MDES obtains the methods through the parallel RAM response.

{
  "MESSAGE_TYPE": {
    "Message_Type": "TAR",
    "Message_Desc": "Tokenization Authorization Request",
    "Version": "2"
  },
  "SUMMARY": {
    "Api_Call_Unique_Identifier": "evt-mc-tar-001",
    "Token": 123456789,
    "Token_Status": 1000,
    "PID": 123,
    "Client_Id": 123456,
    "Source": "MDES",
    "Network": "MASTERCARD",
    "Date_Time": "2026-10-02 10:15:30.000",
    "Processor_Decision_Code": "REQUIRE_ADDITIONAL_AUTHENTICATION",
    "Wallet": "Apple",
    "Device": "PHONE",
    "OTP": null,
    "Message_Reason": "authorizeService",
    "Token_Requestor_Id": "50123456059"
  },
  "ADDITIONAL_MESSAGE_DATA": {
    "requestId": "as-example-001",
    "correlationId": "D202610020001",
    "services": [
      "DIGITIZATION"
    ],
    "tokenRequestorId": "50123456059",
    "walletId": "103",
    "tokenType": "EMBEDDED_SE",
    "fundingAccountInfo": {
      "panUniqueReference": "funding-mc-example-001",
      "paymentologyPublicCardToken": 123456789
    },
    "deviceInfo": {
      "formFactor": "PHONE",
      "osName": "IOS",
      "deviceBlocked": false
    },
    "velocityRules": {
      "blocked": false
    },
    "decisioningReason": {
      "decision": "REQUIRE_ADDITIONAL_AUTHENTICATION",
      "ruleName": "Default wallet step-up",
      "activationMethods": [
        {
          "type": "TEXT_TO_CARDHOLDER_NUMBER",
          "value": "*******4567"
        },
        {
          "type": "CARDHOLDER_TO_CALL_MANNED_NUMBER",
          "value": "+442079460123"
        }
      ]
    }
  }
}

RequestActivationMethods (AMR)

RAM shares the provisioning correlation ID with AuthorizeService. For this step-up path, record the offered methods. The reasonCodes field used for post-tokenization authentication is deliberately absent from this initial provisioning example.

{
  "MESSAGE_TYPE": {
    "Message_Type": "AMR",
    "Message_Desc": "Activation Methods Request",
    "Version": "2"
  },
  "SUMMARY": {
    "Api_Call_Unique_Identifier": "evt-mc-amr-002",
    "Token": 123456789,
    "Token_Status": 1000,
    "PID": 123,
    "Client_Id": 123456,
    "Source": "MDES",
    "Network": "MASTERCARD",
    "Date_Time": "2026-10-02 10:16:30.000",
    "Processor_Decision_Code": null,
    "Wallet": "Apple",
    "Device": "PHONE",
    "OTP": null,
    "Message_Reason": "requestActivationMethods",
    "Token_Requestor_Id": "50123456059"
  },
  "ADDITIONAL_MESSAGE_DATA": {
    "requestId": "ram-example-001",
    "correlationId": "D202610020001",
    "services": [
      "DIGITIZATION"
    ],
    "tokenRequestorId": "50123456059",
    "walletId": "103",
    "tokenType": "EMBEDDED_SE",
    "fundingAccountInfo": {
      "panUniqueReference": "funding-mc-example-001",
      "paymentologyPublicCardToken": 123456789
    },
    "decisioningReason": {
      "decision": "REQUIRE_ADDITIONAL_AUTHENTICATION",
      "ruleName": "Default wallet step-up",
      "activationMethods": [
        {
          "type": "TEXT_TO_CARDHOLDER_NUMBER",
          "value": "*******4567"
        },
        {
          "type": "CARDHOLDER_TO_CALL_MANNED_NUMBER",
          "value": "+442079460123"
        }
      ]
    }
  }
}

For this example, the selected methods returned to MDES are:

{
  "activationMethods": [
    {
      "type": "TEXT_TO_CARDHOLDER_NUMBER",
      "value": "*******4567"
    },
    {
      "type": "CARDHOLDER_TO_CALL_MANNED_NUMBER",
      "value": "+442079460123"
    }
  ]
}

An approve or decline provisioning outcome returns no activation methods. Your Notification endpoint acknowledges AMR; it does not return this scheme response.

Method selection may need masked contact details from the CMS or your contact-data service. Agree the source during implementation. An RCD notification can record the lookup; where your service supplies the data, it must also provide the separate lookup response. A masked method value is display data, not a delivery address.

DeliverActivationCode (OTP)

Code-delivery and lifecycle methods do not ask your Notification endpoint for a new provisioning decision. Card-data protection and notification formatting still apply; do not assume provisioning rules or risk checks run again for these informational messages.

Deliver the supplied code through the selected channel using your own cardholder contact record. activationMethod.value is masked display data. correlationId links provisioning activity; tokenUniqueReference identifies the individual token.

{
  "MESSAGE_TYPE": {
    "Message_Type": "OTP",
    "Message_Desc": "Tokenization Activation Code Request",
    "Version": "2"
  },
  "SUMMARY": {
    "Api_Call_Unique_Identifier": "evt-mc-otp-003",
    "Token": 123456789,
    "Token_Status": 1000,
    "PID": 123,
    "Client_Id": 123456,
    "Source": "MDES",
    "Network": "MASTERCARD",
    "Date_Time": "2026-10-02 10:17:30.000",
    "Processor_Decision_Code": null,
    "Wallet": "Apple",
    "Device": "PHONE",
    "OTP": "123321",
    "Message_Reason": "deliverActivationCode",
    "Token_Requestor_Id": "50123456059"
  },
  "ADDITIONAL_MESSAGE_DATA": {
    "requestId": "otp-example-001",
    "correlationId": "D202610020001",
    "tokenUniqueReference": "token-mc-example-001",
    "activationCode": "123321",
    "expirationDateTime": "2026-10-02T10:22:30Z",
    "activationMethod": {
      "type": "TEXT_TO_CARDHOLDER_NUMBER",
      "value": "*******4567"
    }
  }
}

NotifyServiceActivated (TNR)

This example represents successful activation following step-up. The native decision records the earlier provisioning decision; tokenActivatedDateTime records activation. Read those fields separately. The token reference is nested inside fundingAccountInfo for this method.

{
  "MESSAGE_TYPE": {
    "Message_Type": "TNR",
    "Message_Desc": "Tokenization Notification Request",
    "Version": "2"
  },
  "SUMMARY": {
    "Api_Call_Unique_Identifier": "evt-mc-tnr-004",
    "Token": 123456789,
    "Token_Status": 1000,
    "PID": 123,
    "Client_Id": 123456,
    "Source": "MDES",
    "Network": "MASTERCARD",
    "Date_Time": "2026-10-02 10:18:30.000",
    "Processor_Decision_Code": null,
    "Wallet": "Apple",
    "Device": "PHONE",
    "OTP": null,
    "Message_Reason": "Token Notification: ACTIVATED",
    "Token_Requestor_Id": "50123456059"
  },
  "ADDITIONAL_MESSAGE_DATA": {
    "requestId": "nsa-example-001",
    "correlationId": "D202610020001",
    "services": [
      "DIGITIZATION"
    ],
    "tokenRequestorId": "50123456059",
    "walletId": "103",
    "tokenType": "EMBEDDED_SE",
    "fundingAccountInfo": {
      "panUniqueReference": "funding-mc-example-001",
      "paymentologyPublicCardToken": 123456789,
      "tokenUniqueReference": "token-mc-example-001"
    },
    "accountPanSuffix": "4567",
    "serviceRequestDateTime": "2026-10-02T10:15:30Z",
    "decision": "REQUIRE_ADDITIONAL_AUTHENTICATION",
    "decisionMadeBy": "AUTHORIZATION_REQUEST",
    "tokenActivatedDateTime": "2026-10-02T10:18:30Z",
    "numberOfActivationAttempts": 1
  }
}

NotifyTokenUpdated (TNR)

This is an illustrative ACTIVE status update for the same token, not a promise that every successful provisioning journey emits both this event and NotifyServiceActivated. Process each entry in the native tokens array. The same method also reports later suspension and deletion events.

{
  "MESSAGE_TYPE": {
    "Message_Type": "TNR",
    "Message_Desc": "Tokenization Notification Request",
    "Version": "2"
  },
  "SUMMARY": {
    "Api_Call_Unique_Identifier": "evt-mc-tnr-005",
    "Token": 123456789,
    "Token_Status": 1000,
    "PID": 123,
    "Client_Id": 123456,
    "Source": "MDES",
    "Network": "MASTERCARD",
    "Date_Time": "2026-10-02 10:19:30.000",
    "Processor_Decision_Code": null,
    "Wallet": "Apple",
    "Device": "PHONE",
    "OTP": null,
    "Message_Reason": "Token Notification: STATUS_UPDATE",
    "Token_Requestor_Id": "50123456059"
  },
  "ADDITIONAL_MESSAGE_DATA": {
    "requestId": "ntu-example-001",
    "reasonCode": "STATUS_UPDATE",
    "tokens": [
      {
        "tokenUniqueReference": "token-mc-example-001",
        "status": "ACTIVE"
      }
    ]
  }
}

For a suspension, the selected native data can instead be:

{
  "reasonCode": "STATUS_UPDATE",
  "tokens": [
    {
      "tokenUniqueReference": "token-mc-example-001",
      "status": "SUSPENDED",
      "suspendedBy": [
        "ISSUER"
      ]
    }
  ]
}

SUMMARY.Token_Status remains the funding-card status. Use tokens[].status for the network-token state.

Post-tokenization authentication

For an existing e-commerce token, use the native reasonCodes and authRequestCorrelationId to identify the authentication context. MDES reserves these fields for post-tokenization authentication. Use this request context rather than the absence of a TAR notification. Do not create a new token or require a companion AuthorizeService.

Native reason	Meaning
`ADD_CARD`	Verify account ownership when the card is added to a requestor
`VERIFY_ACCOUNT`	Verify account ownership to use a service
`PAYMENT_TRANSACTION`	Authenticate the cardholder for a payment
`TOKEN_BINDING`	Authenticate to bind the token to a binding identifier
`ACCOUNT_BINDING`	Authenticate to bind the tokenized funding account to a binding identifier
`OTHER`	An authentication reason outside the listed values

These reasons describe different contexts; configure the methods for the ones enabled in your programme. The following synthetic AMR is for a payment using an existing token:

{
  "MESSAGE_TYPE": {
    "Message_Type": "AMR",
    "Message_Desc": "Activation Methods Request",
    "Version": "2"
  },
  "SUMMARY": {
    "Api_Call_Unique_Identifier": "evt-mc-auth-amr-001",
    "Token": 123456789,
    "Token_Status": 1000,
    "PID": 123,
    "Client_Id": 123456,
    "Source": "MDES",
    "Network": "MASTERCARD",
    "Date_Time": "2026-10-02 10:16:30.000",
    "Processor_Decision_Code": null,
    "Wallet": null,
    "Device": null,
    "OTP": null,
    "Message_Reason": "requestActivationMethods",
    "Token_Requestor_Id": "50123456059"
  },
  "ADDITIONAL_MESSAGE_DATA": {
    "requestId": "auth-ram-example-001",
    "correlationId": "D202610020001",
    "services": [
      "DIGITIZATION"
    ],
    "tokenRequestorId": "50123456059",
    "tokenType": "STATIC",
    "fundingAccountInfo": {
      "panUniqueReference": "funding-mc-example-001",
      "paymentologyPublicCardToken": 123456789,
      "tokenUniqueReference": "token-mc-ecom-example-001"
    },
    "decisioningReason": {
      "decision": "REQUIRE_ADDITIONAL_AUTHENTICATION",
      "ruleName": "E-commerce authentication",
      "activationMethods": [
        {
          "type": "TEXT_TO_CARDHOLDER_NUMBER",
          "value": "*******4567"
        }
      ]
    },
    "reasonCodes": [
      "PAYMENT_TRANSACTION"
    ],
    "authRequestCorrelationId": "auth-example-001"
  }
}

For an OTP path:

Record AMR against the existing fundingAccountInfo.tokenUniqueReference and retain authRequestCorrelationId for the authentication journey.
DeliverActivationCode produces OTP. Its reasonCodes, authRequestCorrelationId, and tokenUniqueReference preserve the authentication context; deliver the code through the selected channel.
Successful authentication is confirmed through NotifyTokenUpdated, forwarded as TNR. The AUTHENTICATION_PERFORMED reason records authentication without a token-status change:

{
  "MESSAGE_TYPE": {
    "Message_Type": "TNR",
    "Message_Desc": "Tokenization Notification Request",
    "Version": "2"
  },
  "SUMMARY": {
    "Api_Call_Unique_Identifier": "evt-mc-auth-tnr-001",
    "Token": 123456789,
    "Token_Status": 1000,
    "PID": 123,
    "Client_Id": 123456,
    "Source": "MDES",
    "Network": "MASTERCARD",
    "Date_Time": "2026-10-02 10:16:30.000",
    "Processor_Decision_Code": null,
    "Wallet": null,
    "Device": null,
    "OTP": null,
    "Message_Reason": "Token Notification: AUTHENTICATION_PERFORMED",
    "Token_Requestor_Id": "50123456059"
  },
  "ADDITIONAL_MESSAGE_DATA": {
    "requestId": "auth-ntu-example-001",
    "reasonCode": "AUTHENTICATION_PERFORMED",
    "tokens": [
      {
        "tokenUniqueReference": "token-mc-ecom-example-001"
      }
    ]
  }
}

Update authentication activity for that token rather than marking it as newly provisioned or activated. The native completion example identifies the token through tokens[]; it does not invent an authentication-correlation field in NotifyTokenUpdated. An AMR or OTP notification alone does not confirm successful authentication.

What to test

Exercise approve, decline and step-up decisions, parallel AuthorizeService/RAM processing, OTP delivery, and lifecycle updates. Check that the same funding card can retain several independent token records. The methods above cover the provisioning journey listed in scheme requests and issuer events; they do not imply support for every optional MDES service.