Tokenization notifications

In Notification mode, Lume Token responds to the scheme and sends your systems a record of the event. The message uses Paymentology's existing MESSAGE_TYPE, SUMMARY, and ADDITIONAL_MESSAGE_DATA envelope.

Use the common summary for routing and everyday processing. Use the additional data for the full scheme context and enabled-service results. You do not need to return the scheme's approve/decline response: acknowledge notification receipt with HTTP 200.

Connect your notification endpoint

Provide the implementations team with your receiver URL and agree its authentication configuration. Paymentology sends the JSON envelope to that configured URL using HTTP POST.

The API key and Basic authentication settings are independent: if both are configured, both headers are sent. Configure your receiver to require the authentication agreed for your endpoint. Notification credentials authenticate Paymentology's call to your system; they are separate from credentials you use to call Paymentology APIs.

Return HTTP 200 to acknowledge receipt. Do not put an approve/decline decision in the response. Test the configured URL and authentication with a notification before exercising the scheme-specific journeys.

Message structure

Card-data protection still applies. "Complete" does not mean forwarding raw PAN, CVV, or encrypted card data to a protected issuer integration. Lume Token handles scheme decryption and substitutes the agreed card reference while retaining other eligible data. Do not assume every service runs for every event.

MESSAGE_TYPE

SUMMARY

Field names retain the existing notification convention, including capitalization.

Values can be null when they are not applicable or unavailable. Preserve identifiers without interpreting them as quantities. The funding-card reference and a network-token reference serve different purposes: several network tokens can belong to one card.

ADDITIONAL_MESSAGE_DATA

The inner payload follows the relevant scheme's field names rather than the legacy generic field mapping. It includes the data eligible for delivery to your integration, plus the results of enabled services, such as velocity checks, device checks, and rule decisioning. The summary is a convenient extraction, not a replacement for that data.

For Visa operations with a token reference in the native URL, Lume includes it as ADDITIONAL_MESSAGE_DATA.tokenReferenceID. Use that reference to identify the network token. SUMMARY.Token and Visa's panReferenceID identify the funding card and cannot distinguish its individual network tokens.

Examples below use synthetic values and show selected fields to explain the integration. Lume enrichment object names, normalized values, and mappings are illustrative; implement against the interface agreed for your programme. Example subsets do not limit the fields delivered in an actual notification.

Notification message types

Not every scheme or programme produces every event. Names ending in "Request" are retained message-type names; they do not turn a Notification-mode event into an issuer decision request.

Tokenization eligibility request (TER)

TER records a card check where this event is part of the flow. It can carry the public card token and token reference. A successful eligibility check does not establish that provisioning or activation has completed. A failed check is not a reason to assume a separate provisioning request will always be absent.

{
  "MESSAGE_TYPE": {
    "Message_Type": "TER",
    "Message_Desc": "Tokenization Eligibility Request",
    "Version": "2"
  },
  "SUMMARY": {
    "Api_Call_Unique_Identifier": "evt-visa-ter-001",
    "Token": 123456789,
    "Token_Status": 1000,
    "PID": 123,
    "Client_Id": 123456,
    "Source": "VTS",
    "Network": "VISA",
    "Date_Time": "2026-10-02 10:15:30.000",
    "Processor_Decision_Code": "00",
    "Wallet": "Apple",
    "Device": "PHONE",
    "OTP": null,
    "Message_Reason": "checkEligibility",
    "Token_Requestor_Id": "40010030273"
  },
  "ADDITIONAL_MESSAGE_DATA": {
    "tokenRequestorID": 40010030273,
    "tokenReferenceID": "token-visa-example-001",
    "panReferenceID": "funding-visa-example-001",
    "paymentologyPublicCardToken": 123456789,
    "panSource": "KEY_ENTERED",
    "deviceInfo": {
      "deviceLanguageCode": "eng"
    }
  }
}

Follow the Visa eligibility journey.

Tokenization authorization request (TAR)

TAR records the provisioning operation and outcome. Its additional data includes eligible native request fields, the card reference, and applicable Velocity, TokenGuard, and Rule Engine results. Selected activation profiles can appear in the decision context even when the scheme obtains those methods through a separate response.

The following Mastercard example shows a step-up outcome with no velocity or device block. The activation-method details are decision context in the notification; methods sent back to MDES during provisioning belong in RAM.

{
  "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"
        }
      ]
    }
  }
}

For equivalent provisioning events using different native fields, see Visa and Jaywan.

Retrieve contact data request (RCD)

RCD records contact-data retrieval used in the activation journey. For CMS-sourced contact data, the flow obtains masked values from the CMS and can send you this notification. If you host the contact-data source, Lume Token also needs a separate lookup response containing the required masked details. Acknowledging the RCD notification does not supply those details.

The following CMS/contact-service example illustrates RCD context for a Mastercard journey. Its additional-data mapping is a Lume illustration, not a native MDES request or a definition of the separate contact-data API. The masked method value is display data, not a delivery destination.

{
  "MESSAGE_TYPE": {
    "Message_Type": "RCD",
    "Message_Desc": "Retrieve Contact Data Request",
    "Version": "2"
  },
  "SUMMARY": {
    "Api_Call_Unique_Identifier": "evt-mc-rcd-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": "requestCardholderData",
    "Token_Requestor_Id": "50123456059"
  },
  "ADDITIONAL_MESSAGE_DATA": {
    "paymentologyPublicCardToken": 123456789,
    "correlationId": "D202610020001",
    "activationMethods": [
      {
        "type": "TEXT_TO_CARDHOLDER_NUMBER",
        "value": "*******4567"
      }
    ]
  }
}

Tokenization activation code request (OTP)

Paymentology forwards the passcode to you. Deliver it to the cardholder through the selected channel. Use your own contact record to find the destination; a masked phone number or email is only a display value. Receiving or delivering an OTP is not proof that the cardholder completed authentication.

{
  "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"
    }
  }
}

Activation methods request (AMR)

AMR records method-selection activity and the applicable decision context. Mastercard provisioning sends AuthorizeService and RAM in parallel; methods are returned in RAM for step-up. Visa uses a separate step-up-method request. A RAM request for an existing e-commerce token is a different context from initial provisioning.

{
  "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"
        }
      ]
    }
  }
}

Device token binding request (DTB)

DTB is a scheme-specific event about binding a device to an existing token. Keep the device association separate from the funding-card record. Use the native binding information and the corresponding lifecycle event to track the result; do not treat receipt as automatic approval of every binding request.

{
  "MESSAGE_TYPE": {
    "Message_Type": "DTB",
    "Message_Desc": "Device Token Binding Request",
    "Version": "2"
  },
  "SUMMARY": {
    "Api_Call_Unique_Identifier": "evt-visa-dtb-007",
    "Token": 123456789,
    "Token_Status": 1000,
    "PID": 123,
    "Client_Id": 123456,
    "Source": "VTS",
    "Network": "VISA",
    "Date_Time": "2026-10-02 10:21:30.000",
    "Processor_Decision_Code": "85",
    "Wallet": null,
    "Device": "PHONE",
    "OTP": null,
    "Message_Reason": "deviceBinding",
    "Token_Requestor_Id": "40010030274"
  },
  "ADDITIONAL_MESSAGE_DATA": {
    "panReferenceID": "funding-visa-example-001",
    "paymentologyPublicCardToken": 123456789,
    "clientWalletAccountID": "wallet-example-001",
    "deviceInfo": {
      "deviceID": "device-example-001",
      "deviceIndex": 1
    },
    "decisioningReason": {
      "decision": "REQUIRE_ADDITIONAL_AUTHENTICATION",
      "ruleName": "Device binding step-up",
      "activationMethods": [
        {
          "type": "OTPSMS",
          "value": "*******4567",
          "identifier": "sms-example-001"
        }
      ]
    },
    "tokenReferenceID": "token-visa-cof-example-001"
  }
}

This selected body context belongs to an existing-token device-binding operation. See the Visa DTB example for token-reference and completion handling.

Tokenization notification request (TNR)

TNR records token lifecycle changes. Use the scheme token reference to identify the affected token and retain its relationship to the funding card. A CREATED event and an ACTIVATED event are distinct: creation may precede completion of step-up.

These retain the lifecycle reasons in the existing notification reference. They are not a promise that each scheme emits every reason. SUMMARY.Message_Reason can carry the operation or a description such as Token Notification: ACTIVATED; do not assume it is always the bare enum above. Keep the native scheme lifecycle data as well.

{
  "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"
      }
    ]
  }
}

Here, tokens[].status is the network-token state; SUMMARY.Token_Status is the funding-card status. For creation and activation examples, follow the scheme links below.

Examples by scheme method

The matrix describes the documented journeys. It does not require every scheme to emit every notification type. MADA's Lume contract must be agreed separately; another scheme's JSON is not a substitute for it.

Acknowledge and act

Return HTTP 200 for the notification:

HTTP/1.1 200 OK

Then perform the relevant issuer work. In particular, OTP delivery and cardholder-facing token updates are issuer responsibilities. Contact-data lookup and Advice decision responses have their own contracts; they are not replaced by notification acknowledgements.

Follow the scheme journey

• Mastercard: TER where generated, TAR and AMR decision events, contact retrieval, OTP, and token activation/update events.
• Visa: eligibility, provisioning, token creation, separate method selection, OTP, and activation.
• Jaywan: provisioning/ID&V and lifecycle context, including primary and auxiliary tokens.