McAfee Consumer Partner Services XMLComm Guide V3.5

User Manual:

Open the PDF directly: View PDF .
Page Count: 83

Download
Open PDF In Browser	View PDF

Partner Services XML Communication Guide
Revision 3.5

McAfee® Consumer

Primary Author

Asha B A

COPYRIGHT
Copyright ® 2001 - 2015 McAfee, Inc. All Rights Reserved.
This document contains proprietary information of McAfee Inc. and is subject to a license agreement or nondisclosure agreement. No part of this document
may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into another language, in any form or by any means, without the
prior written consent of McAfee.
For more information, contact:
McAfee Inc.

Telephone: 408.346.3832

McAfee Consumer Group
3965, Freedom Circle
Santa Clara, CA 95054, USA

DISCLAIMER
The information contained in this document is subject to change without notice.
MCAFEE INC. MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THIS MATERIAL, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. McAfee Inc. shall not be liable for errors contained herein or for
incidental or consequential damages in connection with the furnishing, performance, or use of this material.

TRADEMARKS
This document may make reference to other software and hardware products by name. In most if not all cases, the companies that manufacture these other
products claim these product names as trademarks. It is not the intention of McAfee Inc. to claim these names or trademarks as its own.

Partner Services XML Communication Guide

CONFIDENTIAL

Contents
Preface ........................................................................................................... 6
About This Guide ....................................................................................................................... 6
Audience .................................................................................................................................... 6
Revision History ......................................................................................................................... 7
What’s New in This Release?..................................................................................................... 7
Conventions Used in This Guide ................................................................................................ 8

Introducing McAfee Partner Services XML Communication ............. 9

Overview .................................................................................................................................... 9
Secure Communication Protocol ................................................................................................ 9

Message Formats ................................................................................. 10

Overview .................................................................................................................................. 10
Partner Message Format.......................................................................................................... 10
PARTNERCONTEXT ........................................................................................................ 10
CUSTOMERCONTEXT ..................................................................................................... 10
Partner Request Sample XML ........................................................................................... 15
McAfee Message Format ......................................................................................................... 16
PARTNERRESPONSECONTEXT .................................................................................... 16
RESPONSECONTEXT ..................................................................................................... 16
McAfee Response Sample XML ........................................................................................ 18

Message Details ................................................................................... 19

Overview .................................................................................................................................. 19
Creating a New Customer and New Subscription ..................................................................... 19
Partner Request ................................................................................................................ 19
McAfee Response ............................................................................................................. 20
Updating an Existing Customer ................................................................................................ 21
Scenario 1 ......................................................................................................................... 21
Scenario 2 ......................................................................................................................... 22
Scenario 3 ......................................................................................................................... 23
Updating the Existing User Profile ............................................................................................ 25

SOAP Interface Specifications............................................................ 27

Understanding Web Services Details ....................................................................................... 27
PostRequest Web Service................................................................................................. 27
Defining Web Services Description Language .......................................................................... 28

Query SOAP Interface Specifications ...... Error! Bookmark not defined.

Overview ......................................................................................Error! Bookmark not defined.
Web Services Details ...................................................................Error! Bookmark not defined.
PostQueryRequest Web Service .......................................... Error! Bookmark not defined.
Request and Response Messages ...............................................Error! Bookmark not defined.
Customer Identifier Request ................................................. Error! Bookmark not defined.
Customer Subscription and Installation Details Response .... Error! Bookmark not defined.
License Query ...................................................................... Error! Bookmark not defined.
Query Request and License Query Requests ....................... Error! Bookmark not defined.
Defining Web Services Description Language ..............................Error! Bookmark not defined.

Multi-Licensing Implementation ......................................................... 30

iii
CONFIDENTIAL

Overview .................................................................................................................................. 30
Introducing New Attribute ......................................................................................................... 30
Creating New Subscription ....................................................................................................... 31
Updating Existing User Subscription ........................................................................................ 32
Canceling Existing User Subscription ....................................................................................... 33
Understanding Response Messages ........................................................................................ 34
Defining Response Code 1000 .......................................................................................... 34
Defining Response Code 4000 .......................................................................................... 35
Defining Response Code 6007 .......................................................................................... 36

McAfee Partner Services Requests for Mobile Products ................. 37

Overview .................................................................................................................................. 37
New Elements and Attributes ................................................................................................... 37
Understanding Partner Service Requests and Responses ....................................................... 38
Partner Response Context ....................................................................................................... 38
Non-Unified SKU Request and Response ................................................................................ 39
Request and Response – Create New Subscription .......................................................... 39
Request and Response – Update Phone Number ............................................................. 41
Unified SKU Request and Response ........................................................................................ 42
Request and Response – Create New Subscription .......................................................... 42
Request and Response – Cancel Existing User Subscription ................................................... 44
Smartphone XML Request ................................................................................................ 45
Tablet XML Request.......................................................................................................... 45
Request and Response – Disconnect Mobile Devices for Cancelled Subscription .................... 46
XML Request .................................................................................................................... 46
XML Response.................................................................................................................. 47

Error Responses for Mobile Products ............................................... 48

Cross Device Trade-Up Implementation ............................................ 49

Overview .................................................................................................................................. 49
Introducing New Action Type and New Elements ..................................................................... 49
Trading Up Existing Subscription.............................................................................................. 50
Trade-Up Request with PRODUCTKEY ............................................................................ 50
Trade-Up Request with SOURCESKU .............................................................................. 51
Canceling Trade-Up Subscription ............................................................................................. 51

10.

Product Download ............................................................................. 52

Overview .................................................................................................................................. 52
Subscription Creation Flow ...................................................................................................... 52
New Subscription Creation ................................................................................................ 52
On Trade-Up ..................................................................................................................... 53
Existing User ..................................................................................................................... 54
Request for Multi-device Download URL .................................................................................. 54
Request for MMS Download URL for Multi-device SKU............................................................ 55
If Partner provides the ProductKey instead of SKU .................................................................. 56
URLs ........................................................................................................................................ 57
Product Download Web Service ............................................................................................... 57
Return Codes ........................................................................................................................... 59

11.

Error Messages .................................................................................. 60

Overview .................................................................................................................................. 60
Error Response 2001 – Invalid Schema ................................................................................... 61
Error Response 2002 – Invalid Data......................................................................................... 62
Error Response 2003 – Invalid SKU ......................................................................................... 62
Error Response 4000 – General Error ...................................................................................... 62

Country Codes and International Dialing Codes .............................. 64

XML Field Length and Character Restriction ................................... 74

iv
CONFIDENTIAL

XML Field Length ..................................................................................................................... 74
Character Restriction ............................................................................................................... 74

Response Code Matrix ........................................................................ 76

Paid Transaction ...................................................................................................................... 76
Canceled Transaction .............................................................................................................. 78
Existing Customer .................................................................................................................... 79

Index ............................................................................................................. 81

v
CONFIDENTIAL

Preface
Thank you for becoming a McAfee Partner. This preface briefly introduces the
McAfee Partner Services XML Communication Guide, its audience, the document’s
revision history, and updates to this version of the guide.

About This Guide
This guide:




Introduces McAfee Partner Services XML communication
Describes the secure communication protocols
Explains the message formats that McAfee and its Partners use to
communicate with each other.

Audience
This guide helps McAfee Partners to understand the Partner Services XML
communication protocol and message formats that Partners use to send customer
and services information to McAfee.

Partner Services XML Communication Guide
CONFIDENTIAL

Preface
6

Revision History
This guide includes these revisions:
Date

Document
Version

Description

February 23, 2015 3.5

Added section ‘Request and Response – Disconnect
Mobile devices for cancelled subscription’

December 3, 2014 3.4

Added Product Download chapter.

October 27, 2014

3.3

License Query

June 13, 2014

3.2

Included the following sections:

June 03, 2013

3.1



Non-Unified Sku Request and Response



Unified Sku Request and Response

Included the following chapters:


SOAP Interface Specifications



Error! Reference source not found.



McAfee Partner Services Requests for Mobile
Products



Multi-Licensing Implementation



Error! Not a valid result for table.

June 26, 2009

2.1

Changed ‘Email 2’ to ‘Email 1’ in the McAfee DB Store
column, last row in the Table 22.

May 18, 2009

2.0

Includes the updates listed in the section,
What’s New in This Release?.

August 22, 2007

1.8

See the Revision History of the guide revision 1.8.

October 27, 2003

1.4

See the Revision History of the guide revision 1.4.

What’s New in This Release?
The McAfee Partner Services XML Communication Guide version 3.4 includes the
new chapter Product Download.

Partner Services XML Communication Guide

CONFIDENTIAL

Preface

Conventions Used in This Guide
This document uses these typographical conventions:
Convention

Example

Terms that identify fields, buttons,
tabs, options, selections, and
commands on the User Interface
(UI) are shown in Arial Narrow bold
font.

The Service field on the Properties tab specifies the
name of the requested service.

Menu or action group selections
are indicated using a right angle
bracket (>).

Select My Company > Admin Domain > View Details.

Procedures are presented as a
series of numbered steps.

1. On the Configuration tab, click Backup.

Names of keys on the keyboard
Press ENTER.
are denoted using UPPER CASE.
Text such as syntax, keywords,
and values that you must type
exactly are denoted using
Courier New font.

Type: setup and then press ENTER.

Variable information that you must Type: sensor-IP-address and then press ENTER.
type based on your specific
situation or environment is shown
in italics.
Parameters that you must supply
are shown enclosed in angle
brackets.

set sensor ip

Information that you must read
before beginning a procedure or
that alerts you to negative
consequences of certain actions,
such as loss of data is denoted
using “Caution” notation.

Caution:

Information that you must read to
prevent injury, accidents from
contact with electricity, or other
serious consequences is denoted
using “Warning” notation.

Warning:

Important:
Information that is critical and
must be followed to get the correct
related results denoted with
“Important” notation.
Notes that provide related, but
non-critical, information are
denoted using “Note” notation.

Partner Services XML Communication Guide

CONFIDENTIAL

Note:

Preface

Introducing McAfee Partner Services XML
Communication
Overview
McAfee Partner Services is a platform of callable services that are exposed to the
Partners. When the Partners sell McAfee products and services to their customers,
the Partners send customer and service information to McAfee. Using this
information, McAfee provides service provisioning to customers. The following section
briefly explains the secure communication protocol.

Secure Communication Protocol
A Partner can send a service request to McAfee using real-time communication. In
the real-time communication, a Partner sends one request per customer to subscribe
or unsubscribe to the McAfee products and services:


Partner posts Extensible Markup Language (XML) messages to a secure
McAfee Uniform Resource Locator (URL) using Hypertext Transfer Protocol
Secure (HTTPS).

McAfee sends an XML response message to the Partner with a result code.
This communication method assumes that the Partner has the skills and resources to
develop code to send messages in real-time, and also to handle responses from
McAfee Partner Services.

Partner Services XML Communication Guide

CONFIDENTIAL

Introducing McAfee Partner Services XML Communication

Message Formats
This chapter describes the Partner request and McAfee response XML message
formats along with sample XML code.

Overview
All communication from the Partners is message-based. A message is an XML
document that has the HEADER and DATA sections. For Partner and McAfee
message formats, see Partner Message Format and McAfee Message Format
respectively.

Partner Message Format
This section describes the fields in the Partner message.

PARTNERCONTEXT
PARTNERCONTEXT is the root node of the Partner message. PARTNERCONTEXT
contains HEADER and DATA sections.
Table 1: Sections in PARTNECONTEXT
Section

Description

HEADER

Contains information about the Partner that is required for McAfee
to process and apply the correct business rules and configuration.

DATA

Contains the payload of the message. This section has
CUSTOMERCONTEXT, ACCOUNT, and ORDER subsections. The
CUSTOMERCONTEXT section is mandatory for each customer. The
information in the ACCOUNT and ORDER sections depend on the
request action.

Table 2: PARTNERCONTEXT XML Field Matrix
Field

Description

Mandatory?

PARTNER

Identifies the Partner with a unique
PARTNER_ID.

Yes

PARTNER_ID

Specifies the number that McAfee assigns to
each Partner.

Yes

CUSTOMERCONTEXT
CUSTOMERCONTEXT contains customer profile and order information for a specific
customer. The DATA section contains this field.

Partner Services XML Communication Guide

CONFIDENTIAL

Message Formats

Table 3: CUSTOMERCONTEXT XML Field Matrix
Field

Mandatory?

Specifies a unique identifier that the
Partner assigns to a specific customer.
This ID remains constant during the
customer’s life time.

Yes

REQUESTTYPE

Defines the type of message.
NEW – Purchase transactions
UPDATE – Cancellation transactions
UPDPROFILE – Update user profile

Yes

ACCOUNT

Contains customer profile information.
See ACCOUNT.

Yes

ORDER

Contains customer order information.
See ORDER.

Yes

PAYMENTINFO

Contains the payment information and the No
billing address of the customer.
See PAYMENTINFO.

Partner Services XML Communication Guide

CONFIDENTIAL

Description

Message Formats

ACCOUNT
The following table lists the ACCOUNT XML field matrix:
Table 4: ACCOUNT XML Field Matrix
Field

Subfield or
Attribute

Description

Mandatory?

ACCOUNT

EMAILADDRESS

Contains the customer’s email
address.

Yes; for Purchase
transactions

ACCOUNT

FIRSTNAME

Contains the customer’s first name.

Yes; for Purchase
transactions

ACCOUNT

LASTNAME

Contains the customer’s last name.

Yes; for Purchase
transactions

ACCOUNT

PASSWORD

Contains the customer’s password.
If the Partner requests McAfee to
generate a random password for each
user, then this field will be blank.

Yes; for Purchase
transactions

ACCOUNT

PREFERENCES

Contains all of the customer’s
preferences.

Yes

ACCOUNT

OPTINS

Contains different programs in which a Yes
user can be opted-in.

PREFERENCES

PREFERENCE

Contains different types of customer
preferences. Currently, this field
determines only the site and language
to assign to the customer.

PREFERENCES

TYPE

Defines the type of preference. For
example, LANG.
See Language Code and Description .

OPTINS

OPTINGROUP

Specifies the category of opt-in.
No
Currently, the category is limited to NL
for Newsletter.
ID – Indicates the Group ID for the optin programs in which a user will be
enrolled.
CODE – Indicates the code for the optin program.

OPTINS

OPTIN

Specifies the actual program in which
a user will be opted-in.
ID – Indicates the Program ID for the
opt-in program in which a user will be
enrolled. Currently, the category is
limited to VN for Virus newsletter.

CODE – Indicates the Program code for
the opt-in program.

Partner Services XML Communication Guide

CONFIDENTIAL

Message Formats

The following table lists the language codes and descriptions for preference type:
Table 5: Language Code and Description
Language Code

Description

Language Code

Description

en-us

English – United
States

Japanese

en-au

English – AUSTRALIA

pt-br

Portuguese – Brazil

en-ca

English – CANADA

Spanish – Standard

en-gb

English – United
Kingdom

es-mx

Spanish – Mexico

French – Standard

zh-cn

Simplified Chinese

fr-ca

French – CANADA

zh-tw

Traditional Chinese

German – Standard

Korean

Italian – Standard

ORDER
The following table lists the ORDER XML field matrix:
Table 6: ORDER XML Field Matrix
Field

Subfield or
Attribute

Description

Mandatory?

ORDER

PARTNERREF Specifies a unique Partner order reference
number associated with an order. The Partner
sends the order number for the customer’s
order.

Yes

ORDER

REF

Contains the McAfee order reference number.

ORDER

ITEMS

Contains all items associated with an order.

Yes

ITEMS

ITEM

Contains an individual line item for an order.

Yes

ITEM

SKU

Specifies the product ID or the stock-keeping
unit (SKU) number that the customer intends
to purchase or cancel.

Yes

Either McAfee provides SKUs to the Partner or
the Partner specifies the SKUs to use. If the
Partner provides SKUs, McAfee maps the
Partner SKUs to the McAfee product IDs.
ITEM

QTY

Specifies the quantity of products or services.

Yes

ITEM

ACTION

Specifies the transaction type as either Paid
(PD) or Cancel (CN).

Yes

Partner Services XML Communication Guide

CONFIDENTIAL

Message Formats

PAYMENTINFO
The following table lists the PAYMENTINFO XML field matrix:
Table 7: PAYMENTINFO XML Field Matrix
Field

Description

PAYMENTINFO

TYPE

Contains the type of payment used for a
purchase.
CC – Credit Card

PAYMENTINFO

AUTHCODE

Specifies the authorization code from the
payment processor.

PAYMENTINFO

CREDITCARD

Contains the customer’s credit card details.

PAYMENTINFO

BILLINGADDRESS

Contains the customer’s billing address.

CREDITCARD

CCTYPE

Contains the type of credit card used for
the transaction.
1 – VISA
2 – MASTERCARD
3 – AMEX
4 – Discover
5 – Diner’s Club 6 – JCB

CREDITCARD

CCNUMBER

Contains the credit card number used for
the transaction.

CREDITCARD

CCEXPIREMONTH

Contains the credit card expiration month.

CREDITCARD

CCEXPIREYEAR

Contains the credit card expiration year.

BILLINGADDRESS

BILLINGFIRSTNAME

Contains the customer’s first name.

BILLINGADDRESS

BILLINGLASTNAME

Contains the customer’s last.

BILLINGADDRESS

BILLINGADDRESS1

Contains the customer’s address.

BILLINGADDRESS

BILLINGADDRESS2

Contains the continued address of the
customer.

Partner Services XML Communication Guide

CONFIDENTIAL

Subfield or Attribute

Message Formats

Field

Subfield or Attribute

Description

BILLINGADDRESS

BILLINGCITY

Contains the customer’s city.

BILLINGADDRESS

BILLINGSTATE

Contains the customer’s state.

BILLINGADDRESS

BILLINGZIP

Contains the zip code of the state.

BILLINGADDRESS

BILLINGCOUNTRY

Contains the customer’s country name.

BILLINGADDRESS

BILLINGPHONE

Contains the customer’s phone number.

BILLINGADDRESS

BILLINGFAX

Contains the customer’s fax number.

Partner Request Sample XML
A typical Partner request message to create an account and services for a customer
is as follows:

SARA@HOTMAIL.COM

en-us

YES

Partner Services XML Communication Guide

CONFIDENTIAL

Message Formats

1
4111111111111111
1
05

CA
94085
US
4082222222

McAfee Message Format
This section describes the fields in the McAfee message.

PARTNERRESPONSECONTEXT
PARTNERRESPONSECONTEXT is the root node of the Partner response message. The
HEADER section contains this field. For PARTNER and PARTNER_ID details, see Table
2.

RESPONSECONTEXT
RESPONSECONTEXT contains the Partner’s customer identifier. The DATA section
contains this field.
Table 8: RESPONSECONTEXT XML Field Matrix

Partner Services XML Communication Guide

CONFIDENTIAL

Message Formats

Field

Description

Mandatory?

RESPONSECONTEXT

Specifies a unique customer
identifier that Partner provides
and maintains. This field is
identical to the
CUSTOMERCONTEXT ID.

Yes

RESPONSECONTEXT

RETURNCODE

Specifies the transaction code
that McAfee returns to the
request.

Yes

RESPONSECONTEXT

RETURNDESC

Contains a short description of
the transaction code. See Table
17.

Yes

RESPONSECONTEXT

ORDER

Contains information specific to
the order.

Yes

RESPONSECONTEXT

ACCOUNT

For Paid transactions, McAfee
Yes
returns the email address and
password available in the
McAfee database.
This information helps the user to
log on to the McAfee Web site.

ORDER

PARTNERREF

Contains the Partner order
reference number that the
Partner associated with this
order.

Yes

ORDER

REF

Specifies the McAfee sales order
ID that is passed for all
successful trial, purchase, and
renewal orders.
McAfee does not send this field
for cancellations and for failed
transactions.

Yes, if
McAfee
created a
new
subscription.

ACCOUNT

EMAILADDRESS

Contains the customer’s email
address in the McAfee database.
The customer must log on to the
McAfee Web site using this email
address.

Yes;
returned
value for
Purchase
transactions

ACCOUNT

PASSWORD

Contains the customer’s
password of record in the
McAfee database. The customer
must log on to the McAfee Web
site using this password.

Yes;
returned
value for
Purchase
transactions

Partner Services XML Communication Guide

CONFIDENTIAL

Subfield or
Attribute

Message Formats

McAfee Response Sample XML
A typical successful response message from McAfee for a first-time paid customer is
as follows:

1000
Success

SARA@HOTMAIL.COM

Partner Services XML Communication Guide

CONFIDENTIAL

Message Formats

Message Details
This chapter explains the Partner request messages and McAfee response
messages for several scenarios.

Overview
The message exchange between the Partner and McAfee happens for the following
transactions:





Creating an account and a subscription for a new customer.
Updating the existing customer by cancelling SKU.
Updating the existing customer by including additional SKU.
Updating the existing user’s profile.

For information about the message fields and formats, see:



Partner Message Format
McAfee Message Format

Creating a New Customer and New Subscription
This section provides examples of Partner request message to create an account and
services for a new customer, and McAfee response.

Partner Request
The Partner request message is as follows. This example contains all the mandatory
and optional fields.

PAUL@HOTMAIL.COM

en-us

YES

Partner Services XML Communication Guide

CONFIDENTIAL

Message Details

1
4111111111111111
1
05

CA
94085
US
4082434563

McAfee Response
The McAfee response message is as follows:

1000
Success

PAUL@HOTMAIL.COM

Partner Services XML Communication Guide

CONFIDENTIAL

Message Details

Updating an Existing Customer
This section provides examples of message exchanges between the Partner and
McAfee to update an existing customer in different scenarios.

Scenario 1
This section provides an example of the Partner request message and McAfee
response message when updating a customer’s subscription with a cancellation of
the existing SKU.

Partner Request
The Partner request message is as follows. This example contains all the mandatory
and optional fields.
Note: McAfee strongly recommends that Partners include the PARTNERREF
from the original Paid transaction. By doing so, McAfee links the purchase
with the cancellation. The PARTNERREF value also serves as a backup
when McAfee cannot link the CUSTOMERCONTEXT ID to the information in
the McAfee database.
If technical limitations prevent a Partner from sending the original
PARTNERREF, the Partner can send a new PARTNERREF. The Partner also
sends the McAfee’s REF from the original purchase.

McAfee Response
The McAfee response message is as follows:

Partner Services XML Communication Guide

CONFIDENTIAL

Message Details

1000
Success

Scenario 2
This section provides an example of the Partner request message and McAfee
response message when updating a customer’s subscription with an additional SKU.

Partner Request
The Partner request message is as follows. This example includes only the minimum
required mandatory fields for the Paid transactions.

PAUL@HOTMAIL.COM

en-us

Partner Services XML Communication Guide

CONFIDENTIAL

Message Details

Note: The CUSTOMERCONTEXT ID and EMAILADDRESS are the same as the
original order but the PASSWORD is different from the original order. Also
note that the Partner sends a new PARTNERREF.

McAfee Response
The McAfee response message is as follows:

5001
Transaction success: Warning, Email Address Exists.

PAUL@HOTMAIL.COM

Note: The transaction code is 5001. This code means that McAfee
recognized the customer as an existing customer and found the email
address in the McAfee database. McAfee sends the existing email address
and password to the customer. The customer requires this information to
log on to the McAfee system.

Scenario 3
This section provides an example of the Partner request message and McAfee
response message when updating a customer’s subscription with an additional SKU.

Partner Request
The Partner request message is as follows. This example includes only the minimum
required fields.

PAUL456@YAHOO.COM

Partner Services XML Communication Guide

CONFIDENTIAL

Message Details

en-us

Note: The CUSTOMERCONTEXT ID and PASSWORD are the same as the
original order but the EMAILADDRESS is different. Also note that the Partner
sends a new PARTNERREF.

McAfee Response
The McAfee response message is as follows:

5002
Transaction success: Warning, Customer Context ID exists
for another Email address. Email Address is ignored

PAUL@HOTMAIL.COM

Note: The transaction code is 5002. This code means that McAfee
recognized the CUSTOMERCONTEXT ID but the email address does not
match with the entry in the McAfee database. McAfee does not overwrite
the customer’s email address and password with the information from the
Partner. McAfee responds with the customer’s current email address and

Partner Services XML Communication Guide

CONFIDENTIAL

Message Details

password existing in the McAfee database. The customer requires this
information to log on to the McAfee system.

Updating the Existing User Profile
This section provides an example of the message exchanges between the Partner
and McAfee to update an existing user profile.

Partner Request
The Partner request message is as follows. This feature is new on the Partner
Services Platform, and enables the Partners to update the email address, password,
first name, and last name of a customer.

unicom100@mcafee.com

zh-cn

Notes:
The CUSTOMERCONTEXT ID and EMAILADDRESS fields are mandatory. The
PREFERENCES and OPTINS fields are optional.
McAfee displays an Invalid Data error when a Partner sends the ORDER
and PAYMENTINFO fields.
McAfee ignores the empty FIRSTNAME, LASTNAME, and PASSWORD when
updating the user’s profile.
If a Partner does not send the preference language value, McAfee ignores
this field.

Partner Services XML Communication Guide

CONFIDENTIAL

Message Details

McAfee Response
The McAfee response message is as follows:

1000
Transaction is successful

unicom053120061@mcafee.com

Partner Services XML Communication Guide

CONFIDENTIAL

Message Details

SOAP Interface Specifications
This chapter explains the SOAP interface of McAfee partner services.

Understanding Web Services Details
The McAfee partners must send one Web service Simple Object Access Protocol
(SOAP) request per customer to query the McAfee subscription and machine
installation data.
A partner invokes the Web service method using SOAP over HTTPS protocol by
passing an XML request message. McAfee sends an XML response message to the
partner.
The Web service SOAP implementation of McAfee Partner Services exposes a Web
method that the partner application invokes to perform the following transactions:


Create new user subscription



Cancel existing user subscription



Update user profile details

PostRequest Web Service
McAfee hosts the PostRequest Web service at the following location:
https://partnersvc.mcafee.com/request/postrequest.asmx
The PostRequest Web service exposes the ProcessRequestWS method, which
takes a Request XML message as a string parameter for processing. The return
value is a string containing the Response XML message.
The following table lists the details about the ProcessRequestWS method:
Table 9: ProcessRequestWS Method
Method

ProcessRequestWS

Partner Services XML Communication Guide

CONFIDENTIAL

Parameter

string (Request XML)

Return Value

string (Response XML)

SOAP Interface Specifications

Defining Web Services Description Language
The Web Services Description Language (WSDL) definition is as follows:

Partner Services XML Communication Guide

CONFIDENTIAL

SOAP Interface Specifications

Partner Services XML Communication Guide

CONFIDENTIAL

SOAP Interface Specifications

Multi-Licensing Implementation
This chapter introduces the Multi-Licensing feature that McAfee provides to its
partners.

Overview
The Multi-Licensing feature enables the partners to procure additional licenses of a
McAfee product, to sell it to its customer base. The partners place such orders or
requests through XML.
In the ITEM node, the new LIC_QTY attribute represents the total number of licenses
that user has purchased, which is the sum of base subscription license plus additional
license. The maximum number of additional licenses that a partner can avail is 100.
The following transactions involve LIC_QTY:




Creating New Subscription
Updating Existing User Subscription
Canceling Existing User Subscription

Note: Cannot combine the licenses of different products or of different
licensing models.

Introducing New Attribute
The new LIC_QTY attribute in the ITEM node specifies the total number of licenses that
a user has purchased. The following table lists the attribute details:
Table 10: LIC_QTY Details
Attribute
Name

LIC_QTY

XML Node

ITEM

Type

Int

Valid Values

Integer value
[range: 1-100]

Mandatory?

Yes; optional for paid,
and mandatory for
upgrade or downgrade
XML requests

Note: A Cancel XML request does not include this attribute. See
Canceling Trade-Up Subscription.

Partner Services XML Communication Guide

CONFIDENTIAL

Multi-Licensing Implementation

Creating New Subscription
The partners send an XML request to McAfee to create a new Paid subscription. In
such a request, the ACTION attribute is set to PD. McAfee processes the request as
follows:



If the user already exists, but has not subscribed to the product, McAfee
creates a new subscription for the requested product.
If the user already exists and has activated the product subscription, and if
the requested license quantity is different from the existing quantity, McAfee
processes the XML request as an update transaction.

For information about the response codes, see Table 17: List of Transaction Codes.
In the following example, the partner has one base license, and requests for two
additional licenses.

en-us

Partner Services XML Communication Guide

CONFIDENTIAL

Multi-Licensing Implementation

Updating Existing User Subscription
The partners send an XML request to McAfee to either upgrade or downgrade the
license quantities. In such a request, the ACTION attribute is set to UD.
McAfee processes the request as follows:




If the user adds more licenses or removes a few licenses from the product
subscription, McAfee performs an update action.
If the user subscription does not exist, McAfee creates a new subscription
for the user with the license quantity specified in the XML request.
If the user already has a subscription and the subscription’s license quantity
is same as value specified in the XML request, McAfee does not revise the
user subscription record; returns the response code, 5001.

For information about the response codes, see Table 17: List of Transaction Codes.
In the following example, the partner has one base license and five additional
licenses.

en-us

Partner Services XML Communication Guide

CONFIDENTIAL

Multi-Licensing Implementation

Canceling Existing User Subscription
The partners send an XML request to McAfee to cancel all the licenses that a user
had purchased for a product. In such a request, the ACTION attribute is set to CN.


Note: McAfee strongly recommends that Partners include the PARTNERREF
from the original Paid transaction. By doing so, McAfee links the purchase
with the cancellation. The PARTNERREF value also serves as a backup
when McAfee cannot link the CUSTOMERCONTEXT ID to the information in
the McAfee database.
If technical limitations prevent a Partner from sending the original
PARTNERREF, the Partner can send a new PARTNERREF. The Partner also
sends the McAfee’s REF from the original purchase.

For more information, see Defining Response Code 4000.
In the following example, the partner requests McAfee to cancel all the user licenses
(both the base and additional licenses) for a product:

Partner Services XML Communication Guide

CONFIDENTIAL

Multi-Licensing Implementation

Understanding Response Messages
The McAfee response message includes a mandatory field, RETURNCODE. The value
of this code indicates whether the transaction was successful or not. The following
sections provide response messages that McAfee sends to the partners.
Table 11: List of Response Codes
Response
Code

Message Displayed

Transaction
Type

1000

Transaction is successful

Normal

2001

Invalid schema

Error

2002

Invalid data

Error

2003

Item error: invalid SKU

Error

4000

Transaction failed

Error

5001

Transaction success: Warning, Email
Address Exists.

Success:
Warning

6004

Transaction Failed - Additional license
quantity exceeded maximum allowed limit

Error

6007

The Query API returns this error code when
the license information is not available.

Error

Defining Response Code 1000
The following XML defines the response code, 1000:

1000
Transaction is successful

Partner Services XML Communication Guide

CONFIDENTIAL

Multi-Licensing Implementation

Defining Response Code 4000
The following XML defines the response code, 4000:

4000
Transaction Failed

Table 12: List of Messages Displayed for Response Code 4000
Message Displayed

Scenario

Action

Transaction Failed.

Generic system error

NEW
UPDATE

Paid (PD), Upgrade
or Downgrade (UD),
Cancel (CN)

Transaction Failed – SKUs
repeated in the request.

When same SKU is
repeated as multiple
nodes under

NEW
UPDATE

Paid (PD), Upgrade
or Downgrade (UD)

Transaction Failed – Partner
reference already exists in the
system.

PARTNERREF already
exists in our system for a
different order

NEW
UPDATE

Paid (PD), Upgrade
or Downgrade (UD)

Transaction Failed – No
transaction details record to
cancel.

When subscription is
already cancelled or
expired

UPDATE

Cancel (CN)

Transaction Failed – No Valid
Subscription Record.

When no valid subscription
found for the user & SKU

UPDATE

Cancel (CN)

UPDATE

Cancel (CN)

Transaction Failed – Cust Context When customer context id
ID does not exist in the System.
for which the subscription
cancel is requested does
not exist

Partner Services XML Communication Guide

CONFIDENTIAL

Request
Type

Multi-Licensing Implementation

Defining Response Code 6007
When no license information is specified in the XML request, McAfee sends an error
code, 6007. The following XML defines the response code, 6007:

6007
No License information available.

Partner Services XML Communication Guide

CONFIDENTIAL

Multi-Licensing Implementation

McAfee Partner Services Requests for Mobile
Products
This chapter explains the partner services requests for McAfee mobile products.

Overview
The new extended Partner Service Web handler method accepts an XML message
for handling mobile products subscription, cancellation, and phone number change as
described in the following sections. The new elements, such as PHONE, TABLET, and
PRODUCTKEY, are introduced in the ITEM node for new subscription, cancellation, and
update phone requests.

New Elements and Attributes
This table lists details about the new elements:
Table 13: New Elements in ITEM XML Node
Element Name

Type

Valid Value

PRODUCT KEY

String

Product Key length is variable;
however, the maximum number
of characters is 256.

PHONE

String

Not applicable

TABLET

String

Not applicable

Note: The PHONE or TABLET element must be passed with the mobile product
SKU. The PRODUCTKEY element is unique key per subscription, and McAfee
requires this information during cancellation of subscriptions. Therefore, the
partner must store the PRODUCTKEY information.

Partner Services XML Communication Guide

CONFIDENTIAL

McAfee Partner Services Requests for Mobile Products

This table lists details about the new attributes:
Table 14: New Attributes to Support Mobile Products Implementation
Element Name

XML Node

Type

Valid Value

NUMBER

PHONE

String

[0-9] (50 characters length)

OLDNUMBER

PHONE

String

[0-9] (50 characters length)

COUNTRYCODE

PHONE

String

[a-z]/[A-Z] (three characters length)

Understanding Partner Service Requests and Responses
This will explain the Partner Service requests and response for mobile products.

Partner Response Context
The partner Response XML is as follows:

1000
Transaction is successful

When the mobile product SKU is added to the XML implementation for Windows
products, the following change becomes standard to the Response XML. A new
attribute, PRODUCTKEY, is always included in the Response XML irrespective of
whether the SKU is for Windows or for mobile product.
Note: The LIC_QTY field is not supported for mobile products. McAfee displays
an invalid data error, if LIC_QTY is sent in the Request XML for mobile products
transactions.

Partner Services XML Communication Guide

CONFIDENTIAL

McAfee Partner Services Requests for Mobile Products

Non-Unified SKU Request and Response
1.
2.

Create New Subscription
Update Phone Number

Request and Response – Create New Subscription
The partner sends a paid XML request to McAfee, to create a new user subscription.

Smartphone XML Request and Response
A sample XML request for the Smartphone subscription creation is as follows:

SARA@HOTMAIL.COM

en-us

A sample successful XML response is as follows:

1000
Transaction is successful

Partner Services XML Communication Guide

CONFIDENTIAL

McAfee Partner Services Requests for Mobile Products

Tablet XML Request and Response
A sample XML request for the tablet subscription creation is as follows:

SARA@HOTMAIL.COM

en-us

A sample successful XML response is as follows:

1000

Partner Services XML Communication Guide

CONFIDENTIAL

McAfee Partner Services Requests for Mobile Products

Transaction is successful

Request and Response – Update Phone Number
The partner must send XML request to McAfee, to update the phone number of an
existing user subscription. The product key with the original subscription must be sent
in the request along with the old phone number and new phone number.
The new action type, CD, needs to be passed in case of the Phone Number update
flow. McAfee updates the new phone number unless the phone number sent is
associated to another active account.

Partner Services XML Communication Guide

CONFIDENTIAL

McAfee Partner Services Requests for Mobile Products

Unified SKU Request and Response
Create New Subscription

Request and Response – Create New Subscription
The partner sends a paid XML request to McAfee, to create a new user subscription.

Smartphone XML Request and Response
A sample XML request for the Smartphone subscription creation is as follows:

ABC123d45@test.COM

en-us

Here’s a sample of a successful XML response:

Partner Services XML Communication Guide

CONFIDENTIAL

McAfee Partner Services Requests for Mobile Products

1000
Transaction is successful

ABC123d45@test.COM

Tablet XML Request and Response
Here’s a sample XML request for the tablet subscription creation:

mmsUnifiedMay29zda@mma.com

en-us

Partner Services XML Communication Guide

CONFIDENTIAL

McAfee Partner Services Requests for Mobile Products

Here’s a sample of a successful XML response:

1000
Transaction is successful

mmsUnifiedMay29zda@mma.com

Request and Response – Cancel Existing User Subscription
The cancel XML request will cancel the user subscription at McAfee. Pass both the
product key of the subscription and the phone number in the ITEM node to indicate
the specific subscription that has to be canceled. The expiration date will be set to the
date when cancellation is received (immediate cancellation) or just stops autorenewal based on partner configuration.

Partner Services XML Communication Guide

CONFIDENTIAL

McAfee Partner Services Requests for Mobile Products

Smartphone XML Request
Here’s a sample XML request:

Tablet XML Request
Here’s a sample XML request:

Note: We need a element as part of the above Tablet cancel request to
do specific validations depending on the device type (phone or tablet).

Partner Services XML Communication Guide

CONFIDENTIAL

McAfee Partner Services Requests for Mobile Products

Request and Response – Disconnect Mobile Devices for
Cancelled Subscription
The Disconnect XML request will disconnect user's mobile devices from the SKU
subscription. Each device is disconnected even if a failure occurs for earlier devices.
The disconnect request only supports one SKU at a time. If disconnects for more than
one SKU are sent, a data validation error is returned.
Before sending a Disconnect request, a Cancel request should be sent for the SKU. If
the SKU is not cancelled before the Disconnect request, a Transaction Failure error is
returned. On successful disconnection, all smartphone and tablet devices are
removed from the subscription immediately and the user can’t retrieve any backed up
data. Disconnected devices can then be used to subscribe to a different SKU.

XML Request
Here’s a sample XML request:

Partner Services XML Communication Guide

CONFIDENTIAL

McAfee Partner Services Requests for Mobile Products

XML Response
Here’s a sample of a successful XML response:

1000
Transaction is successful

Partner Services XML Communication Guide

CONFIDENTIAL

McAfee Partner Services Requests for Mobile Products

Error Responses for Mobile Products
The following table lists the failure return codes applicable for Mobile Products.
Table 15: Error Responses
Return
Code

Scenario

Request
Type

Action

4000

Transaction Failed.

Phone Number passed
is already active for
another user.

NEW

Paid (PD)

4000

Transaction Failed

One or more devices
failed to disconnect.

UPDATE

Disconnect
(DC)

7001

No Valid
Invalid Product Key
Subscription Record. passed.

UPDATE

Change
Device (CD)

7002

Old Phone Number
is not valid.

UPDATE

Change
Device (CD)

7003

New Phone Number New Phone Number is
is already used.
already active for
another user.

UPDATE

Change
Device (CD)

7004

No Active
User subscription has
Subscription Record. expired.

UPDATE

Change
Device (CD)

Partner Services XML Communication Guide

CONFIDENTIAL

Return Description

Invalid Old Phone
Number passed.

Error Responses for Mobile Products

Cross Device Trade-Up Implementation
This chapter documents the new attribute and the transactions involving the attribute,
and sample code for the transactions for the Cross Device trade-up transactions.

Overview
McAfee and its partners exchange messages during the Cross Device trade-up
transactions. This chapter provides the revised XML code for the following
transactions:



Trading Up Existing Subscription
Canceling Trade-Up Subscription

Introducing New Action Type and New Elements
The Partner Services platform provides support for trade-up through a new action
type, TU. The new elements, PRODUCTKEY and SOURCESKU, are introduced in the ITEM
node to trade up an existing subscription.
The following table lists the attribute details:
Table 16: Details of New Elements for Trade Up
Element Name

XML Node

Type

Valid Values

PRODUCTKEY

ITEM

String

Product key value

SOURCESKU

ITEM

String

Source key value

Notes:


The LIC_QTY and ADDL_LIC_QTY fields are not supported for Trade-Up. If the
partners include these fields in the Request XML for Trade-Up, the system
raises an invalid data error.



The Trade-Up feature is available only for the WSS products.



An existing paid subscription cannot be traded up to trial subscription.

Partner Services XML Communication Guide
CONFIDENTIAL

Cross Device Trade-Up Implementation
49

Trading Up Existing Subscription
The partners send a XML request to trade-up an existing user subscription. This
request must contain the product key or the source SKU with the original subscription
along with the action type, TU. If both the product key and source SKU are present,
the system uses the product key to identify the existing subscription.

Trade-Up Request with PRODUCTKEY
In the following example, the trade-up request type passes the PRODUCTKEY as well as
action, which is TU.

Partner Services XML Communication Guide
CONFIDENTIAL

Cross Device Trade-Up Implementation
50

Trade-Up Request with SOURCESKU
In the following example, the trade-up request type passes the SOURCESKU as well as
action, which is TU.

737-35356-3usermtp

Canceling Trade-Up Subscription
The Cancel XML request cancels the user subscription at McAfee. The partner has to
pass the Trade-Up SKU of the subscription in the ITEM node to indicate that the
specific subscription that has to be canceled. After cancelling the traded-up
subscription, McAfee cancels both the source subscription and the traded-up
subscription.
The McAfee system sets the subscription expiration date to the date on which the
cancellation was received (immediate cancellation), or just stops the automatic
renewal based on the partner configuration.

Partner Services XML Communication Guide
CONFIDENTIAL

Cross Device Trade-Up Implementation
51

Product Download
Overview
This feature provides the Product Download page URL to the partners.
Note: This URL is provided only for multi-device products.
The Product Download page URL can be provided to the user in the following flows.

Subscription Creation Flow
New Subscription Creation
In the new subscription flow for multi-device SKUs, the product download URL is sent
back in response.

Request
No new elements need to be passed in the subscription creation flow.

Response
The node will be embedded in the current response
with the URL value.

Response XML

1000
Transaction is successful

nov17_new_New@mcafee.com

Partner Services XML Communication Guide
CONFIDENTIAL

Product Download
52

On Trade-Up
If the trade-up destination is multi-device SKU, the product download URL will be part
of the response.

Request XML

737-53294-mcafee mobile securi

Response XML

1000
Transaction is successful

mms737nov20@mma.com

Partner Services XML Communication Guide
CONFIDENTIAL

Product Download
53

Existing User
A new Product Download API is introduced to provide the Product Download page
URL to the Partners.
New API request and response XMLs contains these parameters:



CUSTOMERCONTEXTID:
CUSTOMERCONTEXTID identifies the customer account.



REQUESTTYPE:
The new RequestType PRODUCTDOWNLOAD identifies the XML as the
request for the product download page URL.



SKU or PRODUCTKEY:
The SKU or PRODUCTKEY must be part of the request XML.



DEVICE TYPE:
This is an optional parameter. If this is left blank, a multi-device URL will be sent
in response. If the device type is set to ‘Phone’ or ‘Tablet,’ then an MMS
download URL is sent in response.

Request for Multi-device Download URL
URL Request XML

Partner Services XML Communication Guide
CONFIDENTIAL

Product Download
54

URL Response

####

{ Transaction success or Error Message }

Request for MMS Download URL for Multi-device SKU
URL Request XML

Partner Services XML Communication Guide
CONFIDENTIAL

Product Download
55

URL Response

####

{ Transaction success or Error Message }

If Partner provides the ProductKey instead of SKU
URL Request XML

Partner Services XML Communication Guide
CONFIDENTIAL

Product Download
56

URL Response

####

{ Transaction success or Error Message }

URLs
Partners should use these URLS to post their XMLs to use the new Product Download API.
URL to post for plain request:
http://partnersvc.mcafee.com/Request/PostProductDownloadRequest.aspx
URL to post for RIJNDAEL encrypted request:
http://partnersvc.mcafee.com/Request/postrijndaelencryptedPDreq.aspx
URL to post for TRIPLEDES encrypted request:
http://partnersvc.mcafee.com/Request/posttripledesencryptedPDreq.aspx

Product Download Web Service
To use the Product Download web service, a request should be posted to the below web service.
McAfee hosts the ProductDownloadPostRequest Web service at the following location:
https://partnersvc.mcafee.com/request/productdownloadpostrequest.asmx
The ProductDownloadPostRequest Web service exposes the ProcessRequestWS method,
which takes a Request XML message as a string parameter for processing. The return value is a
string containing the Response XML message.
This table includes details about the ProcessRequestWS method:

Partner Services XML Communication Guide
CONFIDENTIAL

Product Download
57

Method

ProcessRequestWS

Parameter

string (Request XML)

Return Value

string (Response XML)

The Web Services Description Language (WSDL) definition is as follows:

Partner Services XML Communication Guide
CONFIDENTIAL

Product Download
58

Return Codes
These are the possible return codes:

Code
1000
2001
2002
2003
7001
4000

Description
Transaction is successful
Invalid schema
Invalid data
Invalid SKU
No valid subscription record
Transaction failed

Partner Services XML Communication Guide
CONFIDENTIAL

Product Download
59

10. Error Messages
This chapter explains the McAfee response messages when an error occurs during a
transaction between McAfee and Partner.

Overview
The McAfee response message includes a mandatory field, RETURNCODE. The value
of this code indicates whether the transaction was successful or not. The following
sections provide the response message that McAfee sends to the Partner when an
errors occurs during a transaction.
During the development and quality assurance (QA) process, McAfee discusses with
the Partner to identify the potential reasons for an invalid data response.
Table 17: List of Transaction Codes
Transaction
Code

Transaction
Type

1000

Transaction is successful

Normal

2001

Invalid schema

Error

2002

Invalid data

Error

2003

Item error: invalid SKU

Error

4000

Transaction failed

Error

5001

Transaction success: Warning, Email
Address Exists.

Success:
Warning

5002

Transaction success: Warning, Customer
Context ID exists for another Email address.
Email Address is ignored

Success:
Warning

Partner Services XML Communication Guide
CONFIDENTIAL

Message Displayed

Error Messages
60

Transaction
Code

Message Displayed

Transaction
Type

6001

Email address exists in the system

Error

6002

Account has active subscriptions from other
partners

Error

6003

AFFID/CCID combination does not exist in
the system.

Error

6004

Transaction failed: Additional license quantity Error
exceeded maximum allowed limit.

6005

Transaction failed: Base subscription does
not exist. Invalid Additional license purchase.

Error

6006

Transaction failed: Cannot cancel additional
licenses. Invalid additional license quantity.

Error

6007

No license information available.

Error

7001

No valid subscription record.

Error

7002

Old phone number Is not valid.

Error

7003

New phone number is already used.

Error

7004

No active subscription record.

Error

For more information about AFF_ID and CCID, see the McAfee Consumer Partner
Login API White Paper. Contact McAfee Consumer Sales to obtain this White Paper.

Error Response 2001 – Invalid Schema
The Invalid Schema error occurs when the Partner message does not contain the
required elements and attributes.
An example of the Invalid Schema error response from McAfee is as follows:

2001
Invalid schema

Partner Services XML Communication Guide
CONFIDENTIAL

Error Messages
61

Error Response 2002 – Invalid Data
The Invalid Data error occurs due to one of the following possible reasons:







PARTNERREF is unavailable.
EMAILADDRESS is unavailable.
CUSTOMERCONTEXT ID is unavailable.
Invalid CCTYPE, CCNUMBER, CCEXPIREMONTH, or CCEXPIREYEAR.
A single Partner message includes both the purchase and cancellation
transactions.
A single real-time Partner message includes transactions for more than one
user.

An example of the Invalid Data error response from McAfee is as follows:

2002
Invalid data

Error Response 2003 – Invalid SKU
The Invalid SKU error occurs when the Partner message contains a SKU that does
not map to the McAfee SKUs for that Partner.
An example of the Invalid SKU error response from McAfee is as follows:

2003
Item error: invalid SKU

Error Response 4000 – General Error

Partner Services XML Communication Guide
CONFIDENTIAL

Error Messages
62

The messages from a Partner can fail due to one of the following possible reasons:






Invalid PARTNER_ID.
After an initial Paid message, the same PARTNERREF repeats for a
subsequent Paid message. McAfee rejects this PARTNERREF as a duplicate.
The Partner message attempts to cancel a subscription that does not exist.
The Partner message attempts to add a trial for a customer that already has
a trial for that product.
McAfee system errors.

An example of a general error response from McAfee is as follows:

4000
Transaction Failed

Partner Services XML Communication Guide
CONFIDENTIAL

Error Messages
63

A. Country Codes and International Dialing Codes
The following table lists the country codes and international dialing codes.
Table 18: Country Codes and International Dialing Codes
Country

Dialing Code

Albania

355

Algeria

213

American Samoa

1684

Andorra

376

Angola

244

Anguilla

1264

Antigua and Barbuda

1268

Argentina

Armenia

374

Aruba

297

Australia

Austria

Azerbaijan

994

Bahamas

1242

Bahrain

973

Bangladesh

880

Barbados

246

Belarus

375

Belgium

Belize

501

Partner Services XML Communication Guide
CONFIDENTIAL

Code

Error Messages
64

Benin

229

Bermuda

441

Bhutan

975

Bolivia

591

Bosnia and Herzegovina

387

Botswana

267

Brazil

Brunei Darussalam

673

Bulgaria

359

Burkina Faso

226

Burundi

257

Cambodia

855

Cameroon

287

Canada

Cape Verde

238

Cayman Islands

345

Central African Republic

236

Chad

235

Chile

China

Partner Services XML Communication Guide
CONFIDENTIAL

Error Messages
65

Country

Dialing Code

Colombia

Comoros

269

Congo

242

Congo, The Democratic Republic
of the

243

Cook Islands

682

Costa Rica

506

Cote D'ivoire

225

Croatia

385

Cyprus

357

Czech Republic

420

Denmark

Djibouti

253

Dominica

1767

Dominican Republic

Ecuador

593

Egypt

El Salvador

503

Equatorial Guinea

240

Eritrea

291

Estonia

372

Ethiopia

251

Falkland Islands (Malvinas)

679

Partner Services XML Communication Guide
CONFIDENTIAL

Code

Error Messages
66

Country

Dialing Code

Faroe Islands

298

Fiji

679

Finland

358

France

French Guiana

594

French Polynesia

689

Gabon

241

Gambia

220

Georgia

995

Germany

Ghana

233

Gibraltar

350

Greece

Greenland

299

Grenada

1473

Guadeloupe

590

Guam

1671

Guatemala

502

Guinea

224

Guinea-bissau

245

Guyana

592

Haiti

509

Partner Services XML Communication Guide
CONFIDENTIAL

Code

Error Messages
67

Country

Dialing Code

Holy See (Vatican City State)

Honduras

504

Hong Kong

852

Hungary

Iceland

354

India

Indonesia

Iraq

964

Ireland

353

Israel

972

Italy

Jamaica

1876

Japan

Jordan

962

Kazakhstan

Kenya

254

Kiribati

686

Korea, Republic of

Kuwait

965

Kyrgyzstan

996

Lao People’s Democratic Republic

856

Latvia

371

Partner Services XML Communication Guide
CONFIDENTIAL

Code

Error Messages
68

Country

Dialing Code

Lebanon

961

Lesotho

266

Liberia

231

Libyan Arab Jamahiriya

218

Liechtenstein

423

Lithuania

370

Luxembourg

352

Macau

853

Macedonia, The Former Yugoslav
Republic of

389

Madagascar

261

Malaysia

Maldives

960

Mali

223

Malta

356

Marshall Islands

692

Martinique

596

Mauritania

222

Mauritius

230

Mexico

Micronesia, Federated States of

691

Moldova, Republic of

373

Monaco

377

Mongolia

976

Partner Services XML Communication Guide
CONFIDENTIAL

Code

Error Messages
69

Country

Dialing Code

Montenegro

382

Montserrat

664

Morocco

212

Mozambique

258

Myanmar

Namibia

264

Nauru

674

Nepal

977

Netherlands

Netherlands Antilles

599

New Caledonia

687

New Zealand

Nicaragua

505

Niger

227

Nigeria

234

Northern Mariana Islands

670

Norway

Oman

968

Pakistan

Palau

680

Panama

507

Papua New Guinea

675

Partner Services XML Communication Guide
CONFIDENTIAL

Code

Error Messages
70

Country

Dialing Code

Paraguay

595

Peru

Philippines

Poland

Portugal

351

Puerto Rico

Qatar

974

Reunion

262

Romania

Rwanda

Saint Kitts and Nevis

869

Saint Lucia

758

Saint Vincent and the Grenadines

809

Samoa

685

San Marino

378

Sao Tome and Principe

239

Saudi Arabia

966

Senegal

221

Serbia

381

Seychelles

248

Sierra Leone

232

Singapore

Partner Services XML Communication Guide
CONFIDENTIAL

Code

Error Messages
71

Country

Dialing Code

Slovakai (Slovak Republic)

421

Slovenia

386

Solomon Islands

677

Somalia

252

South Africa

Spain

Sri Lanka

St. Pierre and Miquelon

508

Suriname

597

Swaziland

268

Sweden

Switzerland

Taiwan

886

Tajikistan

992

Tanzania, United Republic of

255

Thailand

Togo

228

Tonga

676

Trinidad and Tobago

868

Tunisia

216

Turkey

Turkmenistan

993

Partner Services XML Communication Guide
CONFIDENTIAL

Code

Error Messages
72

Country

Dialing Code

Turks and Caicos Islands

649

Uganda

256

Ukraine

380

United Arab Emirates

971

United Kingdom

United States

Uruguay

598

Uzbekistan

998

Vanuatu

678

Venezula

Vietnam

Virgin Islands (British)

284

Virgin Islands (U S)

340

Wallis and Futuna Islands

681

Yemen

967

Zambia

260

Zimbabwe

263

Partner Services XML Communication Guide
CONFIDENTIAL

Code

Error Messages
73

B. XML Field Length and Character Restriction
This chapter documents the XML field length and character restriction for both the
Partner request and McAfee response messages.

XML Field Length
The following table lists the XML field length:
Table 19: List of XML Field Length
Field

Data Length
(in characters)

Double-byte
Support

CUSTOMERCONTEXTID

100

EMAILADDRESS

100

FIRSTNAME

Yes

LASTNAME

Yes

PASSWORD

50
No
Minimum of eight
characters.

PARTNERREF

100

The double-byte data requires UTF-8 encoding. For more information, see
http://en.wikipedia.org/wiki/UTF-8.

Character Restriction
The following table lists the restricted characters. The XML parser will check the
special characters mentioned in the SpecialChars node with the FIRSTNAME, LASTNAME,
CCID, and PARTNERREF. The parser will also check the additional characters, such as
&, !, ~, and #, mentioned in the SpecialCharsEx node with the EMAILADDRESS.
For example,

Table 20: List of Special Characters

Partner Services XML Communication Guide
CONFIDENTIAL

Error Messages
74

Special Characters

;

:\\

((

))

xp_

[

]

(

)

Partner Services XML Communication Guide
CONFIDENTIAL

Error Messages
75

C. Response Code Matrix
This chapter documents that response code matrix for Paid and Cancel transactions
and for existing customers.

Paid Transaction
This section lists the transaction codes that Partner receives for Paid transactions.
This matrix assumes that the Partner’s request message was properly formatted and
does not contain invalid data.

Transaction Code 1000
The following table lists the response code matrix for transaction code 1000 and
transaction status Success:
Table 21: Lists Transaction Details for Code 1000 and Status Success
Partner
Sends

McAfee DB
Stores

Comments

CCID 1,
Email 1,
Password 1

Nothing

CCID 1,
Email 1,
Password 1

McAfee captures this transaction
as new user

CCID 1,
Email 2,
Password 1

No CCID 1,
Email 1,
Password 1

CCID 1,
Email 2,
Password 1

New user transaction. No
relationships among users except
that they share passwords.

CCID 1,
Email 2,
Password 2

No CCID 1,
Email 1,
Password 1

CCID 1,
Email 2,
Password 2

New user transaction. No
relationships among users.

CCID 2,
Email 2,
Password 1

CCID 1,
Email 1,
Password 1

CCID 2,
Email 2,
Password 1

New user transaction. No
relationship to CCID 1 or Email 1
except that they share passwords.

Partner Services XML Communication Guide
CONFIDENTIAL

Previously in
McAfee DB

Error Messages
76

Transaction Code 5001
The following table lists the response code matrix for transaction code 5001 and
transaction status Success: Warning:
Table 22: Lists Transaction Details for Code 5001 and Status Success: Warning
Partner
Sends

Previously in
McAfee DB

McAfee DB
Stores

Comments

CCID 1,
Email 1,
Password 1

Standard behavior

CCID 1,
Email 1,
Password 1

No CCID 1,
Email 1,
Password 1

CCID 1,
Email 1,
Password 1

CCID stored

CCID 1,
Email 1,
Password 2

No CCID 1,
Email 1,
Password 1

CCID 1,
Email 1,
Password 1

CCID stored; Password 2 ignored

CCID 1,
Email 1,
Password 2

CCID 1,
Email 1,
Password 1

Password 2 ignored

CCID 2,
Email 1,
Password 1

CCID 1,
Email 1,
Password 1

CCID 2,
CCID 1,
Email 1,
Password 1

McAfee assigns user to CCID 2
along with CCID 1.

Transaction Code 5002
The following table lists the response code matrix for transaction code 5002 and
transaction status Success: Warning:
Table 23: Lists Transaction Details for Code 5002 and Status Success: Warning
Partner
Sends

McAfee DB
Stores

Comments

CCID 1,
Email 2,
Password 1

CCID 1,
Email 1,
Password 1

Email 2 ignored

CCID 1,
Email 2,
Password 2

CCID 1,
Email 1,
Password 1

Email 2 and Password 2 ignored

Partner Services XML Communication Guide
CONFIDENTIAL

Previously in
McAfee DB

Error Messages
77

Canceled Transaction
This section lists the transaction codes that Partner receives for cancel messages.

Transaction Code 1000
The following table lists the response code matrix for transaction code 1000:
Table 24: Lists Transaction Details for Code 1000 and Status Success
Partner
Sends

Previously in
McAfee DB

McAfee DB

Comments

CCID 1,
Email 2

CCID 1,
Email 1

Cancels
subscription

CCID 1 remains linked to Email 1. Subscription
gets canceled. No special message from
McAfee.

CCID 1,
Email 1

Cancels
subscription

Normal

Transaction Code 4000
The following table lists the response code matrix for transaction code 4000 and
transaction status Failure:
Table 25: Lists Transaction Details for Code 4000 and Status Failure
Partner
Sends

CCID 1,
Email 1

McAfee
DB

Comments

Nothing

This account never existed, and therefore, no account
to cancel. After having sent a Paid transaction, Partner
can send a cancellation to McAfee.

No CCID 1,
Email 1

Nothing

After having sent a Paid transaction, Partner can send a
cancellation to McAfee. Thereby, associating Email 1
with CCID 1.

CCID 1,
Email 2

No CCID 1,
Email 1

Nothing

No relationship among these accounts. If CCID 1 does
not exist in the McAfee DB, then transaction fails. If
CCID 1 previously existed in the McAfee DB, then the
application will cancel the CCID 1.

CCID 2,
Email 1

CCID 1,
Email 1

Nothing

If CCID 2 does not exist in the McAfee DB, then
transaction fails. If CCID 2 previously existed in the
McAfee DB, then the application will cancel the CCID 2.

CCID 2,
Email 2

CCID 1,
Email 1

Nothing

No relationship among the accounts.

Partner Services XML Communication Guide
CONFIDENTIAL

Previously in
McAfee DB

Error Messages
78

Existing Customer
The following matrix explains the different transaction codes that a Partner will
receive if a user has already subscribed to McAfee. This matrix assumes that the
Partner properly formatted the request message and that the message does not
contain invalid data.

Transaction Codes 1000 and 5001
The following table lists the response code matrix for transaction codes 1000 and
5001:
Table 26: Lists Transaction Details for Codes 1000 and 5001
Partner Sends

Previously in
McAfee DB

Transaction
Status

Comments

1 month
No previous
subscription
VS
for VirusScan subscription
(VS) with trial

Creates VS
subscription and
sets autorenewal

Success

If user has an existing McAfee
account, then this transaction
returns 5001.

1 month
subscription
for VS
without trial

Active VS
subscription
with current or
previous trial

Adds 1 month to
VS subscription
and sets autorenewal

Success:
Warning

System assumes that Partner
wants to add additional month to
the existing VS subscription.

Active VS
subscription
without current
or previous
trial

Adds 1 month to
VS subscription
and sets autorenewal

Success:
Warning

System assumes that Partner
wants to add additional month to
the existing VS subscription.

Active VS
subscription

Creates VS plus
MPFP suite
subscription and
sets autorenewal. Original
VS subscription
remains active.

Success:
Warning

The VS plus MPFP suite is
treated as independent product.
Users can have trial versions of
VS and the VS plus MPFP suite
without any issues.

Creates VS plus
MPFP suite
subscription and
sets autorenewal. Original
VS subscription
becomes
inactive.

Success:
Warning

1 month
subscription
for VS plus
McAfee
Personal
Firewall Plus
(MPFP) suite
with trial

Expired VS
subscription

Partner Services XML Communication Guide
CONFIDENTIAL

McAfee DB

Rather than counting the user
twice, McAfee suggests that
Partner cancel the VS
subscription.
The VS plus MPFP suite is
treated as independent product.
Users can have trial versions of
VS and the VS plus MPFP suite
without any issues.

Error Messages
79

Partner
Sends

1 month
subscription
for VS plus
MPFP suite
without trial

Previously in
McAfee DB

Active VS
subscription

McAfee DB

Transaction
Status

Retains existing
subscription.

Success:
Warning

Comments

The VS plus MPFP suite is
treated as independent product.
Users can have trial versions of
VS and the VS plus MPFP suite
without any issues.
Rather than counting the user
twice, McAfee suggests that
Partner cancel the VS
subscription.

Expired VS
subscription

Creates VS plus
Success:
MPFP suite
Warning
subscription and
sets auto-renewal.
Original VS
subscription
becomes inactive.

The VS plus MPFP suite is
treated as independent product.
Users can have trial versions of
VS and the VS plus MPFP suite
without any issues.

Transaction Code 4000
The following table lists the response code matrix for transaction code 4000 and
transaction status Failure. For the transactions listed, the users are not entitled to
new trial of product that they have already subscribed.
Table 27: Lists Transaction Details for Code 4000 and Status Failure
Partner Sends

1 month
subscription for
VS with trial

Partner Services XML Communication Guide
CONFIDENTIAL

Previously in McAfee DB

McAfee DB

Active VS subscription
with current or previous
trial

Retains existing
subscription.

Active VS subscription
without current or
previous trial

Retains existing
subscription.

Expired VS subscription
does not include trial

Nothing

Expired VS subscription
includes trial

Nothing

Error Messages
80

Index
ACCOUNT ............................................................ 12

JCB.................................................................. 17

EMAILADDRESS ............................................. 13

VISA ................................................................ 17

FIRSTNAME .................................................... 13

CCEXPIREMONTH ......................................... 17

OPTINS ............................................................ 13

CCEXPIREYEAR............................................. 17

PASSWORD .................................................... 13

CCNUMBER .................................................... 17

PREFERENCES .............................................. 13

CCTYPE .......................................................... 17

additional licenses ............................... 40, 41, 42, 61

customer identifier .......................................... 19, 20

ADDL_LIC_QTY ........................................................ 60

Customer Identifier Request ................................. 34

AUTHCODE

Customer Subscription and Installation Details

authorization code ............................................ 17

Response ........................................................ 34

payment processor ........................................... 17

CUSTOMERCONTEXT ........................................ 11

base license .................................................... 40, 41

ACCOUNT ....................................................... 11

BILLING ADDRESS

ID 11

BILLING CITY .................................................. 18

ORDER ........................................................... 11

BILLING COUNTRY ......................................... 18

PAYMENTINFO ............................................... 11

BILLING FAX ................................................... 18

REQUESTTYPE .............................................. 11

BILLING FIRSTNAME ...................................... 17

DATA.................................................................... 10

BILLING PHONE .............................................. 18

Defining Response Code 1000 ............................. 44

BILLING STATE ............................................... 18

Defining Response Code 4000 ............................. 46

BILLING ZIP ..................................................... 18

List of Messages Displayed for Response Code

BILLING LASTNAME
BILLING ADDRESS ......................................... 17

4000 ........................................................... 46
Error Messages

Canceling Existing User Subscription .................... 42

General Error ................................................... 76

Canceling Trade-Up Subscription .......................... 62

Invalid Data...................................................... 75

Communication

Invalid Schema ................................................ 74

message-based ................................................ 10

Invalid SKU ...................................................... 75

Country Codes and International Dialing Codes .... 77

Error Responses................................................... 59

COUNTRYCODE .................................................. 49

first-time paid customer ........................................ 21

Create New Subscription ................................. 50, 53

HEADER .............................................................. 10

Creating New Subscription .................................... 40

HTTPS

Paid XML request ............................................. 40
Credit Card Type

Hypertext Transfer Protocol Secure ................... 9
Introducing New Action Type and New Elements.. 60

Diner’s Club...................................................... 17

Introducing New Attribute ..................................... 39

Discover ........................................................... 17

ITEM ................................................................ 39

Partner Services XML Communication Guide
CONFIDENTIAL

CREDITCARD

LASTNAME ...................................................... 13

Index
81

LIC_QTY .......................................................... 39
ITEM

PARTNERRESPONSECONTEXT ........................ 19

ACTION ........................................................... 15

PAYMENTINFO.................................................... 16

Cancel .............................................................. 15

AUTHCODE .................................................... 17

CN 15

BILLING ADDRESS ......................................... 17

LIC_QTY .......................................................... 39

CREDITCARD ................................................. 17

Paid .................................................................. 15

TYPE ............................................................... 17

PD 15

PHONE ................................................................ 48

QTY.................................................................. 15

PostQueryRequest ............................................... 33

quantity of products or services ........................ 15

PostRequest ......................................................... 30

SKU.................................................................. 15

PREFERENCES

stock-keeping unit ............................................ 15
ITEMS

PREFERENCE ................................................ 13
TYPE ............................................................... 13

ITEM ................................................................ 15

ProcessQueryWS ................................................. 33

language codes ..................................................... 14

ProcessRequestWS ............................................. 30

LIC_QTY ............................................. 39, 40, 41, 60

Product Download page

McAfee Partner ....................................................... 6

ProductKey ...................................................... 68

McAfee Partner Services ......................................... 9

Request for Mobile Component Download URL 67

McAfee response .................................................. 10

Request for Multi-device Download URL .......... 66

McAfee sales order ID ........................................... 20

Subscription Creation Flow .............................. 64

message formats............................................... 6, 10

Product Download Web Service ........................... 69

New Elements and Attributes ................................ 48

PRODUCT KEY.................................................... 48

NUMBER .............................................................. 49

PRODUCTKEY ......................................................... 60

OLDNUMBER ....................................................... 49

Request and Response – Cancel Existing User .... 55

OPTINS

Request and Response – Disconnect Cancelled

OPTIN .............................................................. 13
OPTINGROUP ................................................. 13

Subscription .................................................... 57
Response Messages

ORDER ................................................................. 14

List of Response Codes ................................... 43

ITEMS .............................................................. 15

Response Code 1000 ...................................... 44

PARTNERREF ................................................. 15

Response Code 2001 ...................................... 44

REF .................................................................. 15

Response Code 2002 ...................................... 44

PARTNER

Response Code 2003 ...................................... 44

PARTNER_ID................................................... 11

Response Code 4000 ...................................... 44

Partner Message Format ....................................... 10

Response Code 5001 ...................................... 44

PARTNERCONTEXT ....................................... 10

Response Code 6004 ...................................... 44

Partner order reference number ...................... 15, 20

Response Code 6007 ...................................... 44

Partner request ..................................................... 10

RESPONSECONTEXT ......................................... 19

Partner Response Context .................................... 49

RETURNCODE .................................................... 43

PARTNERCONTEXT

Revision History...................................................... 7

Partner Services XML Communication Guide
CONFIDENTIAL

PARTNER ....................................................... 11

Index
82

root node......................................................... 10, 19

Update Phone Number ......................................... 52

Secure Communication Protocol

Updating Existing User Subscription ..................... 41

Real-time communication ................................... 9
service provisioning................................................. 9

Update XML request .................................. 41, 42
URL

SOURCESKU ........................................................... 60

McAfee Uniform Resource Locator .................... 9

TABLET ................................................................ 48

Web Services Description Language definition .... 31,

Trade-Up Request with PRODUCTKEY ................ 61

37, 70

Trade-Up Request with SOURCESKU .................. 62

WSS ..................................................................... 60

Trading Up Existing User Subscription .................. 61

WT - Wire Transfer ............................................... 17

transaction code ............................ 20, 89, 90, 91, 93

XML

Understanding Web Services Details .................... 33
Updaing Existing User Subscription

Extensible Markup Language ............................. 9
XML Specifications ................................................ ii

5001 ................................................................. 41

Partner Services XML Communication Guide
CONFIDENTIAL

Index
83

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.5
Linearized                      : No
Page Count                      : 83
Language                        : en-US
Tagged PDF                      : Yes
Title                           : McAfee Consumer
Author                          : Asha B A, McAfee,Inc.
Subject                         : Partner Services XML Communication Guide
Creator                         : Microsoft® Word 2013
Create Date                     : 2015:04:22 16:29:17-03:00
Modify Date                     : 2015:04:22 16:29:17-03:00
Producer                        : Microsoft® Word 2013

EXIF Metadata provided by EXIF.tools

McAfee Consumer Partner Services XMLComm Guide V3.5

Navigation menu

Versions of this User Manual:

Views

Navigation