visa offers platform - offerapi information is proprietary and confidential to visa. ... •...

Visa Offers Platform Offer API

August 2016

Visa Confidential

Important Information on Confidentiality and Copyright

© 2016 Visa. All Rights Reserved.

Notice: This information is proprietary and CONFIDENTIAL to Visa. It is distributed to Visa participants for use exclusively in managing their Visa programs. It must not be duplicated, published, distributed or disclosed, in whole or in part, to merchants, cardholders or any other person without prior written permission from Visa.

The trademarks, logos, trade names and service marks, whether registered or unregistered (collectively the “Trademarks”) are Trademarks owned by Visa. All other trademarks not attributed to Visa are the property of their respective owners.

Note: This document is not part of the Visa Rules. In the event of any conflict between any content in this document, any document referenced herein, any exhibit to this document, or any communications concerning this document, and any content in the Visa Rules, the Visa Rules shall govern and control.

Contents

August 2016 Visa Confidential i

Contents

Contents ............................................................................................................................................................................ i

Tables ................................................................................................................................................................................ii

Figures ............................................................................................................................................................................ iii

About This Guide .......................................................................................................................................................... 5

Purpose ......................................................................................................................................................................................... 5

Audience ....................................................................................................................................................................................... 5

Requirements .............................................................................................................................................................................. 5

1 Overview ................................................................................................................................................................. 6

2 Technical Specifications ...................................................................................................................................... 6

2.1 Create Offer ...................................................................................................................................................................... 6

2.1.1 CreateOffer Request............................................................................................................................................... 9

2.1.2 CreateOffer Response ......................................................................................................................................... 10

2.1.3 CreateOffer Errors ................................................................................................................................................. 12

2.2 Activate Published Offer for Enrollee .................................................................................................................... 14

2.2.1 SaveOfferActivation Request ............................................................................................................................ 14

2.2.2 SaveOfferActivation Response ......................................................................................................................... 15

2.2.3 SaveOfferActivation Errors ................................................................................................................................. 17

2.3 Offer Deactivation ........................................................................................................................................................ 18

2.3.1 OfferDeactivation Request ................................................................................................................................ 18

2.3.2 OfferDeactivation Response ............................................................................................................................. 19

2.3.3 OfferDeactivation Errors ..................................................................................................................................... 20

2.4 Update Offer ................................................................................................................................................................... 21

2.4.1 Offer Update Request.......................................................................................................................................... 21

2.4.2 Offer Update Response ...................................................................................................................................... 22

2.4.3 Offer Update Errors .............................................................................................................................................. 24

A Data Dictionary ................................................................................................................................................... 25

B Fields ...................................................................................................................................................................... 25

Tables

ii Visa Confidential August 2016

Tables

Table 2-1: Sample Template Name-Value Pairs................................................................................................................. 8

Table 2-2: CreateOffer Request Parameters ........................................................................................................................ 9

Table 2-3: CreateOffer Response Parameters ................................................................................................................... 10

Table 2-4: CreateOffer Error Codes....................................................................................................................................... 12

Table 2-5: SaveOfferActivation Request Parameters ..................................................................................................... 14

Table 2-6: SaveOfferActivation Response Parameters .................................................................................................. 15

Table 2-7: SaveOfferActivation Error Codes ...................................................................................................................... 17

Table 2-8: OfferDeactivation Request Parameters .......................................................................................................... 18

Table 2-9: OfferDeactivation Response Parameters ....................................................................................................... 19

Table 2-10: OfferDeactivation Error Codes ........................................................................................................................ 20

Table 2-11: UpdateOffer Request Parameters .................................................................................................................. 21

Table 2-12: UpdateOffer Response Parameters ............................................................................................................... 22

Table 2-13: UpdateOffer Error Codes .................................................................................................................................. 24

Figures

August 2016 Visa Confidential iii

Figures

Figure 2-1: CreateOffer Template Example ......................................................................................................................... 7

Figure 2-2: Sample CreateOffer Event Parameter Specification .................................................................................. 8

Figure 2-3: Sample CreateOffer Request .............................................................................................................................. 9

Figure 2-4: Sample CreateOffer Response ......................................................................................................................... 11

Figure 2-5: Sample CreateOffer Error Response .............................................................................................................. 11

Figure 2-6: Sample SaveOfferActivation Request ........................................................................................................... 15

Figure 2-7: Sample SaveOfferActivation Response ........................................................................................................ 16

Figure 2-8: Sample OfferActivation Error Response ....................................................................................................... 16

Figure 2-9: Sample OfferDeactivation Request ................................................................................................................ 18

Figure 2-10: Sample OfferDeactivation Response .......................................................................................................... 19

Figure 2-11: Sample OfferDeactivation Error Response ............................................................................................... 20

Figure 2-12: Sample UpdateOffer Request ........................................................................................................................ 22

Figure 2-13: Sample UpdateOffer Response ..................................................................................................................... 23

Figure 2-14: Sample UpdateOffer Error Response .......................................................................................................... 23

Figures

iv Visa Confidential August 2016


August 2016 Visa Confidential 5

About This Guide

Purpose

Visa Offers Platform (VOP) Implementation Guide provides partners with the following information:

• Technical specification and requirements for developers to implement Visa Offers Platform web services.

• References to other related publications required during development and implementation of the Visa Offers Platform tools.

Audience

This guide is designed to assist VOP partners in preparing to use the Visa VOP Web Services. This guide is intended for the following individuals:

• Application Developers • System Developers

Requirements

The users of this document must have access to:

• VOP Web Services • Visa Online

Visa Offers Platform Data Dictionary

6 Visa Confidential August 2016

1 Overview

The Offer API enables partners to create new offers and to notify VOP of a consumer subscribing to an offer.

To create new offers client developers need to work with their assigned Visa implementation manager. The Visa implementation manager collects details related to a partner’s program and creates offer templates. Offer templates abstract the complexities of the offer structure and allow client developers to concentrate only on the data elements relevant to the partner’s program. Once the offer template has been established, client developers can submit CreateOffer web service requests, supplying only data fields required by the template.

The SaveOfferActivation web service allows partners to notify VOP of a consumer subscribing to or “clipping” an offer. VOP does not track activity on enrolled cards unless a consumer ‘activates’ a specific offer.

Partners can also deactivate an offer now using the new OfferDeactivate web service.

Programmer’s note:

1. OfferDeactivation is a new API added to the VOP platform in version 6. This API enables clients to deactivate an offer for an enrollee that has been activated by means of the SaveOfferActivation API.

2. ReferenceId is a field added to all API responses in release 6. This attribute contains a unique value for each VOP response. It can be used for issue management and research.

3. The “M/O” column header in the Technical Specification stands for “Mandatory/Optional.”

2 Technical Specifications

2.1 Create Offer

Before a partner can create an offer the partner’s Visa implementation manager must configure VOP to accept CreateOffer requests.

To create new offers, developers must work with their assigned Visa implementation managers. The Visa implementation manager collects details related to partner’s program and establishes offer templates. Templates simplify the complexities of the offer construction and allow developers to concentrate only on the data elements relevant to their program. Once an offer template has been established by Visa, developers can submit CreateOffer web service requests containing only the data fields required by the template. Clients submit name-value pairs to specify parameter values.



Figure 2-1 displays a template as might be created for a partner. Note that the template has both an event criterion and a segmentation criterion. Note also that the template specifies explicit values for the “Transaction Amount” and “Enrollment Promo Code.” When you use CreateOffer to create an offer based on a template you will substitute your own values for the explicit values shown in the template.

Figure 2-1: CreateOffer Template Example

Once an offer is created it must be approved and published. The template you use may be set up to automatically approve and publish an offer created with the CreateOffer API. If not, someone with approval and publishing authority must be enlisted to do these tasks.

Once an offer is published it cannot be activated until 15 minutes after publication.

Figure 2-2 illustrates how the parameters corresponding the template in Figure 2-1 could be specified within a CreateOffer request. Note that the parameter values need not match the values shown in the template. This pattern holds when the parameters are custom. However, when the parameters to be specified are themselves are constrained to a preconfigured list of options, the parameter specified must match one of the allowable options.

Table 2-1 includes some sample values for parameter names and values allowed in CreateOffer API.

Table 2-1: Sample Template Name-Value Pairs

Name Sample “Value” Notes

TransactionMerchantAmount 20.00 Requires TransactionMerchantCurrency to be included in a second Name-Value pair.

TransactionMerchantCurrency USD GTQ

New in Version 7. Three character codes.

TransactionBillingAmount 20.00 Requires TransactionBillingCurrency to be included in a second Name-Value pair.

TransactionBillingCurrency USD GTQ

New in Version 7. Use the three character codes.

VisaMerchantId 52023613

VisaStoreId 145803525 Must also include a VisaMerchantId EventField

The general rule for creating a “Name” in a name-value pair is to take the CSC title and eliminate the spaces.

Once an offer has been created, it must pass through the offer workflow in the Client Service Center (CSC). After creating an offer the offer must be “Approved.” After it is approved it must be “Published,” before it can be made available to enrollees. These manual steps can be bypassed for offers that have no financial impact, for example, an offer that only generates an “End Point Message (EPM). However, for offers that have the following fulfillment actions:

• Point of Sale (POS) Discount • Statement Credit

Must be manually approved and published by means of the CSC.

Note: All CreateOffer templates that use “Transaction Amount” must be replaced with templates that use “TransactionMerchantAmount” and “TransactionMerchantCurrency” or “TransactionBillingAmount” and “TransactionBillingCurrency” and new offers created. This is true regardless of which version of the WSDL you are using.

Figure 2-2: Sample CreateOffer Event Parameter Specification <v71:Event> <v71:EventFields>  <v71:EventField> <v71:Name>TransactionMerchantAmount</v71:Name> <v71:Value>12.00</v71:Value> </v71:EventField> <v71:EventField> <v71:Name>TransactionMerchantCurrency</v71:Name>

<v71:Value>GTQ</v71:Value> </v71:EventField> </v71:EventFields> </v71:Event>

2.1.1 CreateOffer Request

Table 2-2: CreateOffer Request Parameters

CreateOffer Request

Fields Data Type M/O

CampaignName String M

CommunityCode String M

Description String O, nillable

EndDate DateTime M

Events List<Event> O

ExternalOfferId string O, nillable

Name String M The offer’s name

StartDate DateTime M

TemplateName String M

Event List<EventField> O

EventField Data Type M/O

name string O, nillable

value string O, nillable

Figure 2-3: Sample CreateOffer Request

Sample CreateOffer Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v7="http://services.visa.com/realtime/realtimeservice/v7" xmlns:v71="http://services.visa.com/realtime/realtimeservice/datacontracts/v7"> <soapenv:Header/> <soapenv:Body> <v7:CreateOffer>

Sample CreateOffer Request:

<v7:createOfferRequest> <v71:CampaignName>October2</v71:CampaignName> <v71:CommunityCode>SANDBOX</v71:CommunityCode> <v71:Description>VMID</v71:Description> <v71:EndDate>2015-12-15T00:00:00</v71:EndDate> <v71:Events>  <v71:Event> <v71:EventFields>  <v71:EventField> <v71:Name>VisaMerchantId</v71:Name> <v71:Value>52008073</v71:Value> </v71:EventField> </v71:EventFields> </v71:Event> </v71:Events> <v71:ExternalOfferId>123456</v71:ExternalOfferId> <v71:Name>OneConditionVMIDonly</v71:Name> <v71:StartDate>2013-11-29T00:00:00</v71:StartDate> <v71:TemplateName>Merchant</v71:TemplateName> </v7:createOfferRequest> </v7:CreateOffer> </soapenv:Body> </soapenv:Envelope>

2.1.2 CreateOffer Response

Table 2-3: CreateOffer Response Parameters

CreateOffer Response

Fields Data Type

Errors List<Error>

Information List<Message>

ReferenceId Guid

CommunityCode string

ExternalOfferId string

OfferId int

Error Data Type

ErrorCode string

ErrorMessage string



Message Data Type

Code string

Description string

Figure 2-4: Sample CreateOffer Response

Sample CreateOffer: Success <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <CreateOfferResponse xmlns="http://services.visa.com/realtime/realtimeservice/v7"> <CreateOfferResult xmlns:a="http://services.visa.com/realtime/realtimeservice/datacontracts/v7" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <a:Errors i:nil="true"/> <a:Information> <a:Message> <a:Code>Information Code</a:Code> <a:Description>Information Description</a:Description> </a:Message> </a:Information> <a:ReferenceId>45b412fa-12a4-4410-b4bd-cfbb76616d75</a:ReferenceId> <a:CommunityCode>SANDBOX</a:CommunityCode> <a:ExternalOfferId>123456</a:ExternalOfferId> <a:OfferId>4619195</a:OfferId> </CreateOfferResult> </CreateOfferResponse> </s:Body> </s:Envelope>

Figure 2-5: Sample CreateOffer Error Response

Sample CreateOffer: Error <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <CreateOfferResponse xmlns="http://services.visa.com/realtime/realtimeservice/v7"> <CreateOfferResult xmlns:a="http://services.visa.com/realtime/realtimeservice/datacontracts/v7" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <a:Errors> <a:Error> <a:ErrorCode>COVI0001</a:ErrorCode> <a:ErrorMessage>Offer name cannot be empty.</a:ErrorMessage> </a:Error> </a:Errors> <a:Information i:nil="true"/> <a:ReferenceId>ea1a6d58-0541-40ba-a52e-ee7e9a46dff9</a:ReferenceId> <a:CommunityCode>SANDBOX</a:CommunityCode> <a:ExternalOfferId>123456</a:ExternalOfferId> <a:OfferId i:nil="true"/> </CreateOfferResult> </CreateOfferResponse> </s:Body> </s:Envelope>



2.1.3 CreateOffer Errors

Below is a complete list of error codes that can be returned after web service user successfully passed HTTP and SOAP WSS security validations.

Table 2-4: CreateOffer Error Codes

Error Code Error Message

1000 Authentication Exception

1010 Unauthorized Exception

2000 Invalid Argument Exception

3000 SQL Exception

4000 Timeout Exception

5000 Internal Server Error

6000 External Provider Exception

7000 Not supported exception

COVI0001 Offer name cannot be empty.

COVI0004 Template Name cannot be empty.

COVI0006 Campaign name cannot be empty.

COVI0008 Start date is greater than end date.

RTMCSCE0001 Extra Event Rule in Request

RTMCSCE0002 Mismatch in number of Events

RTMCSCE0003 Event Rules Mismatch

RTMCSCE0004 Template name is required

RTMCSCE0005 Invalid Request

RTMCSCE0006 Invalid Request Format

RTMCSCE0007 Community Code is required

RTMCSCE0008 Campaign Name is required

RTMCSCE0009 Invalid Community Code , Template name combination

RTMCSCE0010 Request Mode is required

RTMCSCE0011 External OfferId is Invalid

RTMCSCE0012 Invalid Community Code , Template name combination

RTMCSCE0013 Offer Name is required

RTMCSCE0014 Offer Start Date is invalid or missing. Valid date format is YYYY-MM-DD.



RTMCSCE0015 Offer End Date is invalid or missing. Valid date format is YYYY-MM-DD.

RTMCSCE0016 Invalid Receipt message

RTMCSCE0017 Duplicate offer

RTMCSCE0018 Invalid Campaign Name

RTMCSCE0019 Event Validation Failed

RTMCSCE0021 Event Action Value is Locked

RTMCSCE0022 FulfillmentEventBudget is Required

RTMCSCE0023 Extra attribute (event action name e.g. POS) in Event Action

RTMCSCE0024 Invalid VisaStoreId

RTMCSCE0025 Event Condition custom Value is Locked

RTMCSCE0026 Discount Promo Code is Required

RTMCSCE0033 Event {#} {parameter} Comparison Value Required

RTMCSCE0053 Event {#} {parameter} Invalid Comparison Value

RTMCSCE0060 Invalid Limit value

RTMCSCE0082 Date is beyond acceptable range. Please re-enter.

RTMCSCE0085 Limit value in the request should not exceed Template''s Limit value

RTMCSCE0086 Offer Start Date is beyond acceptable range. Please re-enter.

RTMCSCE0087 Offer End Date is beyond acceptable range. Please re-enter.

RTMCSCE0100 Invalid Extra offer terms. The following special characters such as ~ \\ ^ '{' '}' | \: ; " < > are NOT allowed.

RTMCSCE0101 Offer Extra terms can be maximum 4000 characters.

RTMCSCE0102 Extra Offer Terms

RTMCSCE0108 Please provide a valid numeric value for Merchant Placement Fee.

RTMCSCE0109 Please provide a valid two decimal numeric value for Merchant Placement Fee.

RTMCSCE0110 Merchant Placement Fee Should be 0 to 100.

RTMCSCE0111 Discount Promo Code must be alphanumeric.

RTMCSCE0112 Discount Promo Code cannot be greater than 25 characters.

RTMCSCE0113 Discount Promo Description allows only alphanumeric characters and spaces.

RTMCSCE0114 Receipt Message allows .<(|&!$*);-/,%_?`:#@

RTMCSCE0115 Duplicate attribute Event Condition Attribute in Request

RTMCSCE0116 Invalid Receipt Message.

RTMCSCE0117 Recurrence Limit

RTMCSCE0119 User does not have permission for this Community.



RTMCSCE0120 Endpoint message does not exist for this community.

RTMPWSE0003 Request is null.

RTMPWSE0004 Offer Id cannot be empty.

RTMPWSE0006 Action cannot be empty.

2.2 Activate Published Offer for Enrollee

Partners call SaveOfferActivation to activate an offer for an enrollee. The offer being activated must contain an “Activation” event type. If the enrollee qualifies based upon the event’s action criteria, he or she will be considered to be participating in that specific offer. The response provided back to the partner indicates whether the offer has been “sent”. Note that having an offer activation sent to the backend does not guarantee that the offer will be activated. If the event’s action constrains the event to certain merchants or a minimum spend the offer will not be executed until these criteria are met.

Preconditions:

1. Community must be Active and within its Effective Dates.

2. Consumer must be enrolled in the community.

3. One or more Offers must be published and enabled in VOP with an Activated Event Type which the enrollee has not completed.

4. The Partner must have the Offer IDs associated to offers provided to the enrollee.

5. The Enrollee must have indicated his or her interest in activating the offer(s).

6. An OfferId key-value pair must be included, but the value of the OfferId will not be checked.

2.2.1 SaveOfferActivation Request

Use two pair of the PropertyDataType elements to identify the offer and community as follows:

• Property “OfferID” – Value <Numeric OfferId from CSC> • Property “ClientName” – Value <Client Level community> Table 2-5: SaveOfferActivation Request Parameters

SaveOfferActivation Request


AuthenticationDetail AuthenticationDetails M

Property List<PropertyDataType>

AuthenticationDetails Data Type M/O

CommunityCode string M

UserProfileId Guid M, Only UserProfileId or UserKey

UserKey string M, Only UserProfileId or UserKey

PropertyDataType Data Type M/O

Name string O

Value string O

Figure 2-6: Sample SaveOfferActivation Request

Sample SaveOfferActivation Request: <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v7="http://services.visa.com/realtime/realtimeservice/v7" xmlns:v71="http://services.visa.com/realtime/realtimeservice/datacontracts/v7" xmlns:enr="http://services.visa.com/realtime/realtimeservice/datacontracts/v7/Enrollment"> <soapenv:Header/> <soapenv:Body> <v7:SaveOfferActivation>  <v7:saveOfferActivationRequest> <v71:AuthenticationDetail> <enr:CommunityCode>SANDBOX</enr:CommunityCode>   <enr:UserProfileId>042C33DD-6039-42AA-91C7-2030F3DF0DB4</enr:UserProfileId> </v71:AuthenticationDetail> <v71:Property>  <v71:PropertyDataType> <v71:Name>OfferID</v71:Name> <v71:Value>4565540</v71:Value> </v71:PropertyDataType> <v71:PropertyDataType> <v71:Name>ClientName</v71:Name> <v71:Value>NOUNCL</v71:Value> </v71:PropertyDataType> </v71:Property> </v7:saveOfferActivationRequest> </v7:SaveOfferActivation> </soapenv:Body> </soapenv:Envelope>

2.2.2 SaveOfferActivation Response

Table 2-6: SaveOfferActivation Response Parameters

SaveOfferActivation Response

Fields Data Type



Errors List<Error>


ReferenceId GUID

IsSent bool

Error Data Type

ErrorCode string

ErrorMessage string

Message Data Type

Code string

Description string

Figure 2-7: Sample SaveOfferActivation Response

Sample SaveOfferActivation: Success <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <SaveOfferActivationResponse xmlns="http://services.visa.com/realtime/realtimeservice/v7"> <SaveOfferActivationResult xmlns:a="http://services.visa.com/realtime/realtimeservice/datacontracts/v7" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <a:Errors i:nil="true"/> <a:Information> <a:Message> <a:Code>Information Code</a:Code> <a:Description>Information Description</a:Description> </a:Message> </a:Information> <a:ReferenceId>84d8e801-7516-4372-86d9-319dc7f27dbc</a:ReferenceId> <a:IsSent>true</a:IsSent> </SaveOfferActivationResult> </SaveOfferActivationResponse> </s:Body> </s:Envelope>

Figure 2-8: Sample OfferActivation Error Response

Sample SaveOfferActivation: Error <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <SaveOfferActivationResponse xmlns="http://services.visa.com/realtime/realtimeservice/v7"> <SaveOfferActivationResult xmlns:a="http://services.visa.com/realtime/realtimeservice/datacontracts/v7" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <a:Errors>



Sample SaveOfferActivation: Error <a:Error> <a:ErrorCode>RTMEVTE0008</a:ErrorCode> <a:ErrorMessage>ClientName and CommunityName is either Empty or not valid.</a:ErrorMessage> </a:Error> </a:Errors> <a:Information i:nil="true"/> <a:ReferenceId>1afc95e8-f03b-4aeb-80ae-f68fd69667ff</a:ReferenceId> <a:IsSent>false</a:IsSent> </SaveOfferActivationResult> </SaveOfferActivationResponse> </s:Body> </s:Envelope>

2.2.3 SaveOfferActivation Errors

Table 2-7: SaveOfferActivation Error Codes





3000 SQL Exception





RTMEVTE0003 Root Community for Community code or Client name does not exists in the database.

RTMEVTE0004 Community code and Client Name does not belong to same root community and their respect root communities are ({0}), ({1}) (Community code and Client Name does not belong to same root community and their respect root communities are (GAP), (TRIALPAY))

RTMEVTE0005 OfferId is required.

RTMEVTE0008 {0} is either Empty or not valid.

RTMEVTE0009 {0} is either not provided or are not valid.

2.3 Offer Deactivation

The OfferDeactivation API enables clients to deactivate an offer for enrollee. The response provided to the partner indicates whether the Offer has been deactivated.

2.3.1 OfferDeactivation Request

Table 2-8: OfferDeactivation Request Parameters

OfferDeactivation Request


AuthenticationDetails AuthenticationDetails M

Property List<PropertyDataType> O

AuthenticationDetails Data Type M/O

CommunityCode string M

UserProfileId Guid One of UserProfileId or UserKey

UserKey string One of UserProfileId or UserKey

PropertyDataType Data Type M/O, Use two pairs to specify values for “OfferId” and “ClientName”

Name string O

Value string O

Figure 2-9: Sample OfferDeactivation Request

Sample OfferDeactivation Request <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v7="http://services.visa.com/realtime/realtimeservice/v7" xmlns:v71="http://services.visa.com/realtime/realtimeservice/datacontracts/v7" xmlns:enr="http://services.visa.com/realtime/realtimeservice/datacontracts/v7/Enrollment"> <soapenv:Header/> <soapenv:Body> <v7:OfferDeactivation>  <v7:saveOfferDeactivationRequest> <v71:AuthenticationDetails> <enr:CommunityCode>SANDBOX</enr:CommunityCode>   <enr:UserProfileId>042C33DD-6039-42AA-91C7-2030F3DF0DB4</enr:UserProfileId> </v71:AuthenticationDetails>

Sample OfferDeactivation Request <v71:Property>  <v71:PropertyDataType> <v71:Name>OfferID</v71:Name> <v71:Value>4565540</v71:Value> </v71:PropertyDataType> <v71:PropertyDataType> <v71:Name>ClientName</v71:Name> <v71:Value>NOUNCL</v71:Value> </v71:PropertyDataType> </v71:Property> </v7:saveOfferDeactivationRequest> </v7:OfferDeactivation> </soapenv:Body> </soapenv:Envelope>

2.3.2 OfferDeactivation Response

Table 2-9: OfferDeactivation Response Parameters

OfferDeactivation Response

Fields Data Type

Errors List<Error>


ReferenceId GUID

IsSent bool

Error Data Type

ErrorCode string

ErrorMessage string

Message Data Type

Code string

Description string

Figure 2-10: Sample OfferDeactivation Response

Sample OfferDeactivation Response: Success <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <OfferDeactivationResponse xmlns="http://services.visa.com/realtime/realtimeservice/v7">



Sample OfferDeactivation Response: Success <OfferDeactivationResult xmlns:a="http://services.visa.com/realtime/realtimeservice/datacontracts/v7" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <a:Errors i:nil="true"/> <a:Information> <a:Message> <a:Code>Information Code</a:Code> <a:Description>Information Description</a:Description> </a:Message> </a:Information> <a:ReferenceId>d45e82d3-cdf9-4a77-9d52-1ce9c62b47a3</a:ReferenceId> <a:IsSent>true</a:IsSent> </OfferDeactivationResult> </OfferDeactivationResponse> </s:Body> </s:Envelope>

Figure 2-11: Sample OfferDeactivation Error Response

Sample OfferDeactivation Response: Error <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <OfferDeactivationResponse xmlns="http://services.visa.com/realtime/realtimeservice/v7"> <OfferDeactivationResult xmlns:a="http://services.visa.com/realtime/realtimeservice/datacontracts/v7" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <a:Errors> <a:Error> <a:ErrorCode>RTMEVTE0008</a:ErrorCode> <a:ErrorMessage>ClientName And CommunityName is either Empty or not valid.</a:ErrorMessage> </a:Error> </a:Errors> <a:Information i:nil="true"/> <a:ReferenceId>5d762662-8c79-466c-8946-2c25eca98cb2</a:ReferenceId> <a:IsSent>false</a:IsSent> </OfferDeactivationResult> </OfferDeactivationResponse> </s:Body> </s:Envelope>

2.3.3 OfferDeactivation Errors

Table 2-10: OfferDeactivation Error Codes





3000 SQL Exception







RTMEVTE0003 Root Community for Community code or Client name does not exists in the database.

RTMEVTE0004 Community code and Client Name does not belong to same root community and their respect root communities are ({0}), ({1}) (Community code and Client Name does not belong to same root community and their respect root communities are (GAP), (TRIALPAY))

RTMEVTE0005 OfferId is required.

RTMEVTE0008 {0} is either Empty or not valid.

RTMEVTE0009 {0} is either not provided or are not valid.

2.4 Update Offer

An offer’s life cycle goes through the following stages:

• Draft • Approved - Rejected • Published - Disabled

Only approved offers may be rejected by means of the UpdateOffer API.

2.4.1 Offer Update Request

Table 2-11: UpdateOffer Request Parameters

UpdateOffer Request


Action String “Reject” M

CommunityCode String M

OfferId String M

The only valid value for the Action parameter is “Reject.”

Figure 2-12: Sample UpdateOffer Request

Sample UpdateOffer Request <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v7="http://services.visa.com/realtime/realtimeservice/v7" xmlns:v71="http://services.visa.com/realtime/realtimeservice/datacontracts/v7"> <soapenv:Header/> <soapenv:Body> <v7:UpdateOffer>  <v7:updateOfferRequest> <v71:Action>Reject</v71:Action> <v71:CommunityCode>SANDBOX</v71:CommunityCode> <v71:OfferId>123456</v71:OfferId> </v7:updateOfferRequest> </v7:UpdateOffer> </soapenv:Body> </soapenv:Envelope>

2.4.2 Offer Update Response

Table 2-12: UpdateOffer Response Parameters

UpdateOffer Response

Fields Data Type

Errors List<Error>


ReferenceId GUID

CommunityCode string

OfferId string

StatusMessage string

Error Data Type

ErrorCode String

ErrorMessage String

Message Data Type

Code string

Description string



Figure 2-13: Sample UpdateOffer Response

Sample UpdateOffer Response: Success <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <UpdateOfferResponse xmlns="http://services.visa.com/realtime/realtimeservice/v7"> <UpdateOfferResult xmlns:a="http://services.visa.com/realtime/realtimeservice/datacontracts/v7" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <a:Errors i:nil="true"/> <a:Information> <a:Message> <a:Code>Information Code</a:Code> <a:Description>Information Description</a:Description> </a:Message> </a:Information> <a:ReferenceId>c3e740b6-d680-42e4-9671-781ae36a4a9e</a:ReferenceId> <a:CommunityCode>SANDBOX</a:CommunityCode> <a:OfferId>123456</a:OfferId> <a:StatusMessage>Offer has been rejected successfully.</a:StatusMessage> </UpdateOfferResult> </UpdateOfferResponse> </s:Body> </s:Envelope>

Figure 2-14: Sample UpdateOffer Error Response

Sample UpdateOffer Response: Error <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:Body> <UpdateOfferResponse xmlns="http://services.visa.com/realtime/realtimeservice/v7"> <UpdateOfferResult xmlns:a="http://services.visa.com/realtime/realtimeservice/datacontracts/v7" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <a:Errors> <a:Error> <a:ErrorCode>RTMPWSE0006</a:ErrorCode> <a:ErrorMessage>Action cannot be empty.</a:ErrorMessage> </a:Error> </a:Errors> <a:Information i:nil="true"/> <a:ReferenceId>0539df5c-66f9-41ec-bf08-e7c7248672f0</a:ReferenceId> <a:CommunityCode>SANDBOX</a:CommunityCode> <a:OfferId>123456</a:OfferId> <a:StatusMessage i:nil="true"/> </UpdateOfferResult> </UpdateOfferResponse> </s:Body> </s:Envelope>



2.4.3 Offer Update Errors

Table 2-13: UpdateOffer Error Codes





3000 SQL Exception





RTMCSCE0121 CommunityCode is required.

RTMCSCE0122 OfferID is required.

RTMCSCE0123 Offer status is required.

RTMCSCE0124 Offer Id is not correct.

RTMCSCE0125 Not a recognized offer status.

RTMCSCE0126 Invalid Community Code.

RTMCSCE0127 RTM Internal Error.

RTMCSCE0128 Invalid Request.

RTMCSCE0129 Unable to find Offer, possibly offer id is wrong.

RTMCSCE0130 Offer is not eligible for rejection.

RTMCSCE0131 Invalid offer and community combination.

RTMCSCE0132 Invalid Child Offer.

RTMCSCE0133 Only rejection of an offer is supported.

RTMCSCE0134 Duplicate Organization Name.

RTMPWSE0003 Request is null.

RTMPWSE0004 Offer Id cannot be empty.

RTMPWSE0006 Action cannot be empty.



A Data Dictionary

Data types defined for Visa APIs have been standardized for field length. Refer to the table below for Data Types and their corresponding field lengths.

Data Type Field Length

String 255

String(Max) ** system max **

List<<…..>> ** system max **

bool 5

Int 10 (max value 2147483647)

GUID 36

DateTime 50

decimal 10 (max value 2147483647)

MonetaryAmount Money Data type

B Fields

Fields Description

AuthenticationDetail There are two types. Which one is appropriate for a given partner depends on the initial setup configuration. A client may choose the following combinations: • CommunityCode-UserProfileId • CommunityCode-UserKey

UserProfileId is Visa supplied and returned after a user is enrolled. It is guaranteed to be unique throughout VOP.

UserKey may be either a telephone number or an email address. In this case the client is responsible for maintaining uniqueness. If the client chooses to manage users by means of telephone numbers, the country code must be included. In the USA the area code is 1. A user enrolled with a ten digit telephone number cannot be unenrolled with a UserKey.

CampaignName Campaign name, has to be exact match with the campaign name provided by Visa.

CommunityCode Partner community code, has to be exact match with the community name provided by Visa.

Visa Offers Platform Fields


Description Offer description

EndDate Offer end date, sample value: 2016-04-17T09:20:03

ErrorCode A unique code to describe the type of validation error occurred

ErrorMessage A description of an error that occurred during the request

Errors A list of Error objects.

Events The list of events objects supported by the offer. The events objects contain list of event fields objects, which in turn contain name-value pairs of fields defined in the offer template. The sample structure is provided below.

ExternalOfferId Offer id, as defined in partner’s system. This value will be used for reporting and troubleshooting.

InformationCode Information Code

InformationMessage Information Message

Information A list of Information objects

IsSent Indicates whether the request for offer activation was sent to VOP Core for processing or not.

Name Unique offer name

OfferId VOP offer id of the newly created offer.

OriginatedFrom Originating channel for the request. For example, API or Merchant

Property A list of PropertyDataType objects.

Must include the name-value pair for OfferId and ClientName

ReferenceId Unique identifier defined by VOP associated with each API request

RequestType Optional Request Type

StartDate Offer start date, sample value: 2016-04-17T09:20:03

TargetedInterface Identifies an event type, typically “OnOfferActivation’

TemplateName Offer template name, has to be exact match with the template name provided by Visa.

UserKey "Unique Identifier provided by Partner– Email, GUID, mobile number, etc.

Mandatory for Enroll request.

Mutually Exclusive to UserKey for SaveCard, DeleteCard and Unenroll requests.



UserProfileId Unique enrollment record identifier or User ID generated by Visa as a part of Enroll response.

Optional for Enroll request.

Mutually Exclusive to UserKey for SaveCard, DeleteCard and Unenroll requests.

value Value Of Event

For Example: 52008403 will be a value for VisaMerchantId name

Technical Specifications

Offer API


visa offers platform - offerapi information is proprietary and confidential to visa. ... •...

Documents