Visa issuer guide

Lume Token handles Visa Token Service requests and responses in Notification mode. Your integration receives the common envelope and interprets Visa's native fields inside ADDITIONAL_MESSAGE_DATA.

A wallet step-up journey

Stage	Lume Token processing	Issuer event/action
Card eligibility	Check the card through the configured CMS	TER where generated; record the available card and token references
Approve Provisioning	Evaluate enabled risk services and provisioning rules; return the decision to Visa	TAR with the eligible request and enriched decision context
Token created	Process Visa's creation event	TNR with CREATED context; do not equate creation with completed activation
Retrieve Step-Up Methods	Select the applicable activation profiles and resolve required masked contact data	AMR; RCD where the contact lookup produces an event
Send Passcode	Forward the code for the selected method	OTP; deliver it through your selected cardholder channel
Token activated	Process the resulting lifecycle update	TNR with ACTIVATED context; update the token in your systems

Approve Provisioning does not return the native step-up-method list. Visa obtains it through the separate method-selection request. The TAR notification can still include selected profiles as decisioning context.

Provisioning examples

These synthetic issuer notifications contain selected eligible native VTS fields and illustrative Lume enrichment. They are not encrypted wire requests to Visa. paymentologyPublicCardToken, deviceBlocked, velocityRules, and decisioningReason are Lume additions; the final delivery mapping is agreed for your programme.

Scheme method	Event	Example
Check Eligibility	TER	Eligibility
Approve Provisioning	TAR	Provisioning decision
Token Create Notification	TNR	Token creation
Get Cardholder Verification Methods / Retrieve Step-Up Methods	AMR	Activation methods
Send Passcode	OTP	Code delivery
Token Notification	TNR	Activation result
Device Token Binding Request	DTB	Related existing-token journey

Visa can carry tokenRequestorID and tokenReferenceID in the native URL for some operations and in the body for others. For operations with the token reference in the URL, Lume copies it into ADDITIONAL_MESSAGE_DATA.tokenReferenceID in your notification. The examples include this issuer-facing field even when it is not a native request-body field. Use it to select the network-token record; panReferenceID and the Paymentology card token identify the funding card.

Check Eligibility (TER)

Record the eligibility check and available references. A successful check does not mean a token has been created or activated. This sample shows the protected issuer payload after card-data handling.

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

Approve Provisioning (TAR)

The manual-entry example selects step-up. 85 represents the scheme provisioning outcome; decisioningReason explains the illustrative Lume rule result. Methods shown in that context are not an activation-method list returned by the native Approve Provisioning response.

{
  "MESSAGE_TYPE": {
    "Message_Type": "TAR",
    "Message_Desc": "Tokenization Authorization Request",
    "Version": "2"
  },
  "SUMMARY": {
    "Api_Call_Unique_Identifier": "evt-visa-tar-002",
    "Token": 123456789,
    "Token_Status": 1000,
    "PID": 123,
    "Client_Id": 123456,
    "Source": "VTS",
    "Network": "VISA",
    "Date_Time": "2026-10-02 10:16:30.000",
    "Processor_Decision_Code": "85",
    "Wallet": "Apple",
    "Device": "PHONE",
    "OTP": null,
    "Message_Reason": "approveProvisioning",
    "Token_Requestor_Id": "40010030273"
  },
  "ADDITIONAL_MESSAGE_DATA": {
    "panReferenceID": "funding-visa-example-001",
    "panSource": "KEY_ENTERED",
    "tokenInfo": {
      "tokenType": "SECURE_ELEMENT"
    },
    "deviceInfo": {
      "deviceType": "MOBILE_PHONE",
      "osType": "IOS",
      "deviceBlocked": false
    },
    "paymentologyPublicCardToken": 123456789,
    "velocityRules": {
      "blocked": false
    },
    "decisioningReason": {
      "decision": "REQUIRE_ADDITIONAL_AUTHENTICATION",
      "ruleName": "Manual wallet step-up",
      "activationMethods": [
        {
          "type": "OTPSMS",
          "value": "*******4567",
          "identifier": "sms-example-001"
        }
      ]
    },
    "lifeCycleTraceID": 202610020001
  }
}

Token Create Notification (TNR)

In this step-up journey, the token exists but is still INACTIVE. Retain the creation event without showing it as ready to use. The native operation is a token-change call with TOKEN_CREATED context.

Native operation context for this example (handled by Lume):

POST /vtis/v2/tokenRequestors/40010030273/tokens/token-visa-example-001/tokenChanged?eventType=TOKEN_CREATED

{
  "MESSAGE_TYPE": {
    "Message_Type": "TNR",
    "Message_Desc": "Tokenization Notification Request",
    "Version": "2"
  },
  "SUMMARY": {
    "Api_Call_Unique_Identifier": "evt-visa-tnr-003",
    "Token": 123456789,
    "Token_Status": 1000,
    "PID": 123,
    "Client_Id": 123456,
    "Source": "VTS",
    "Network": "VISA",
    "Date_Time": "2026-10-02 10:17:30.000",
    "Processor_Decision_Code": null,
    "Wallet": "Apple",
    "Device": "PHONE",
    "OTP": null,
    "Message_Reason": "Token Notification: CREATED",
    "Token_Requestor_Id": "40010030273"
  },
  "ADDITIONAL_MESSAGE_DATA": {
    "panReferenceID": "funding-visa-example-001",
    "paymentologyPublicCardToken": 123456789,
    "messageReasonCode": "TOKEN_CREATED",
    "dateTimeOfEvent": "2026-10-02T10:17:30.000Z",
    "lifeCycleTraceID": 202610020001,
    "panSource": "KEY_ENTERED",
    "tokenInfo": {
      "tokenType": "SECURE_ELEMENT",
      "tokenStatus": "INACTIVE"
    },
    "tokenReferenceID": "token-visa-example-001"
  }
}

Retrieve Step-Up Methods (AMR)

The VTS specification calls this service Get Cardholder Verification Methods and uses retrieveStepUpMethods. The native otpReason identifies PROVISIONING. The profile identifier selected here is returned later as otpMethodIdentifier in Send Passcode.

{
  "MESSAGE_TYPE": {
    "Message_Type": "AMR",
    "Message_Desc": "Activation Methods Request",
    "Version": "2"
  },
  "SUMMARY": {
    "Api_Call_Unique_Identifier": "evt-visa-amr-004",
    "Token": 123456789,
    "Token_Status": 1000,
    "PID": 123,
    "Client_Id": 123456,
    "Source": "VTS",
    "Network": "VISA",
    "Date_Time": "2026-10-02 10:18:30.000",
    "Processor_Decision_Code": null,
    "Wallet": "Apple",
    "Device": "PHONE",
    "OTP": null,
    "Message_Reason": "retrieveStepUpMethods",
    "Token_Requestor_Id": "40010030273"
  },
  "ADDITIONAL_MESSAGE_DATA": {
    "tokenRequestorID": 40010030273,
    "tokenReferenceID": "token-visa-example-001",
    "panReferenceID": "funding-visa-example-001",
    "paymentologyPublicCardToken": 123456789,
    "lifeCycleTraceID": 202610020001,
    "panSource": "KEY_ENTERED",
    "otpReason": "PROVISIONING",
    "otpMaxReached": false,
    "decisioningReason": {
      "decision": "REQUIRE_ADDITIONAL_AUTHENTICATION",
      "ruleName": "Manual wallet step-up",
      "activationMethods": [
        {
          "type": "OTPSMS",
          "value": "*******4567",
          "identifier": "sms-example-001"
        }
      ]
    }
  }
}

Selected native response fields for this method are:

{
  "responseCode": "STEPUP",
  "stepUpMethods": [
    {
      "type": "OTPSMS",
      "value": "*******4567",
      "identifier": "sms-example-001"
    }
  ]
}

Lume returns these methods to Visa. Your endpoint records AMR and acknowledges receipt. A contact lookup can separately produce RCD.

Send Passcode (OTP)

Use otpMethodIdentifier to identify the selected channel and deliver otpValue before otpExpirationDate. The identifier refers to the method offered earlier; it is not a telephone number.

{
  "MESSAGE_TYPE": {
    "Message_Type": "OTP",
    "Message_Desc": "Tokenization Activation Code Request",
    "Version": "2"
  },
  "SUMMARY": {
    "Api_Call_Unique_Identifier": "evt-visa-otp-005",
    "Token": 123456789,
    "Token_Status": 1000,
    "PID": 123,
    "Client_Id": 123456,
    "Source": "VTS",
    "Network": "VISA",
    "Date_Time": "2026-10-02 10:19:30.000",
    "Processor_Decision_Code": null,
    "Wallet": "Apple",
    "Device": "PHONE",
    "OTP": "123321",
    "Message_Reason": "sendPasscode",
    "Token_Requestor_Id": "40010030273"
  },
  "ADDITIONAL_MESSAGE_DATA": {
    "tokenRequestorID": 40010030273,
    "tokenReferenceID": "token-visa-example-001",
    "panReferenceID": "funding-visa-example-001",
    "paymentologyPublicCardToken": 123456789,
    "otpMethodIdentifier": "sms-example-001",
    "otpValue": "123321",
    "otpExpirationDate": "2026-10-02T10:24:30.000Z"
  }
}

Token Notification (TNR)

This example follows successful OTP verification. OTP_VERIFICATION_RESULT is the native reason, while ACTIVATED is the common lifecycle interpretation for this successful result with an ACTIVE token. Do not treat every verification-result event as successful without checking its outcome and token state.

Native operation context for this example (handled by Lume):

POST /vtis/v2/tokenRequestors/40010030273/tokens/token-visa-example-001/tokenChanged?eventType=TOKEN_STATUS_UPDATED

{
  "MESSAGE_TYPE": {
    "Message_Type": "TNR",
    "Message_Desc": "Tokenization Notification Request",
    "Version": "2"
  },
  "SUMMARY": {
    "Api_Call_Unique_Identifier": "evt-visa-tnr-006",
    "Token": 123456789,
    "Token_Status": 1000,
    "PID": 123,
    "Client_Id": 123456,
    "Source": "VTS",
    "Network": "VISA",
    "Date_Time": "2026-10-02 10:20:30.000",
    "Processor_Decision_Code": null,
    "Wallet": "Apple",
    "Device": "PHONE",
    "OTP": null,
    "Message_Reason": "Token Notification: ACTIVATED",
    "Token_Requestor_Id": "40010030273"
  },
  "ADDITIONAL_MESSAGE_DATA": {
    "panReferenceID": "funding-visa-example-001",
    "paymentologyPublicCardToken": 123456789,
    "messageReasonCode": "OTP_VERIFICATION_RESULT",
    "dateTimeOfEvent": "2026-10-02T10:20:30.000Z",
    "lifeCycleTraceID": 202610020001,
    "actionCode": "00",
    "tokenInfo": {
      "tokenType": "SECURE_ELEMENT",
      "tokenStatus": "ACTIVE"
    },
    "tokenReferenceID": "token-visa-example-001"
  }
}

Device Token Binding Request (DTB)

This related journey binds a device to an existing e-commerce/card-on-file token. It is separate from the device-wallet provisioning examples above. Lume copies the native path token reference into ADDITIONAL_MESSAGE_DATA.tokenReferenceID; the remaining selected fields describe the device and funding-card context. Record the binding decision separately from token creation.

Native operation context for this example (handled by Lume):

POST /vtis/v1/tokenRequestors/40010030274/tokens/token-visa-cof-example-001/deviceBinding

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

A later Token Notification can report messageReasonCode: TOKEN_DEVICE_BINDING_RESULT and the native deviceBindingResult. A DTB decision alone is not proof that binding completed.

What to test

Check eligibility, all three provisioning outcomes, inactive token creation during step-up, method selection, issuer OTP delivery, and successful activation. For device binding, test the decision and the subsequent result separately. Preserve native reason codes alongside the common summary.