Visa Offers Network

How to use Visa Offers Network

Available for use by:

Issuer banks Merchants Issuer banks for small businesses

Follow this implementation sequence to integrate Visa Offers Network (VON) API services for complete offers ecosystem management.

Enroll users with Primary Account Numbers (PANs) and manage additional cards using the Consumer Enrollment Service.
Retrieve eligible or personalized offers for enrolled users using the Eligibility Service.
Track user events and retrieve dashboard data showing earnings and transaction history using the Ledger Service.

VON API Endpoints Reference

All endpoints require authentication using an API key (X-GOR-API-KEY) and shared secret (X-GOR-SHARED-SECRET), together with the appropriate headers.

This table provides a comprehensive overview of all HTTP methods, endpoints, and authentication headers used for the VON services, including standard endpoints and generic transform endpoints.

Service Category	Service Name	HTTP Method	Endpoint	Authentication Header
Offers	Create New Offer	POST	/von/gor-gateway/gor-offers/v1/offers	No header is required; however, authentication through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required.
Offers	Get and Filter Offers	GET	/von/gor-gateway/gor-offers/v1/offers	No header is required; however, authentication through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required.
Offers	Get Offer by GOR Merchant ID	GET	/von/gor-gateway/gor-offers/v1/offers/{gorMerchantId}	No header is required; however, authentication through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required.
Offers	Update Offers	PUT	/von/gor-gateway/gor-offers/v1/offers	No header is required; however, authentication through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required.
Offers	Delete Offer	DELETE	/von/gor-gateway/gor-offers/v1/offers/{gorMerchantId}	No header is required; however, authentication through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required.
Offers	Get Offers for a Specific Merchant	GET	/von/gor-gateway/gor-offers/v2/merchants/{merchantId}/offers	No header is required; however, authentication through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required.
Offers	Create Offers under a Merchant	POST	/von/gor-gateway/gor-offers/v2/merchants/offers	No header is required; however, authentication through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required.
Offers	Update Offer for a Merchant	PATCH	/von/gor-gateway/gor-offers/v2/merchants/offers	No header is required; however, authentication through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required.
Offers	Delete Offer for a Merchant	DELETE	/von/gor-gateway/gor-offers/v2/merchants/{merchantId}/offers/{offerId}	No header is required; however, authentication through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required.
Offers (Generic)	Create Offers - Generic	POST	/von/gor-gateway/gor-offers/generic/transform/v1/offers	No header is required; however, authentication through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required.
Offers (Generic)	Update Offers - Generic	PUT	/von/gor-gateway/gor-offers/generic/transform/v1/offers	No header is required; however, authentication through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required.
Offers (Generic)	Create Merchant Offers - Generic	POST	/von/gor-gateway/gor-offers/generic/transform/v2/merchants/offers	No header is required; however, authentication through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required.
Offers (Generic)	Update Merchant Offers - Generic	PATCH	/von/gor-gateway/gor-offers/generic/transform/v2/merchants/offers	No header is required; however, authentication through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required.
Consumer Enrollment	Consumer Opt-In	POST	/von/gor-gateway/gor-consumer-enrollment/v1/optIn	No header is required; however, authentication through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required.
Consumer Enrollment	CLO Opt-In and Offer Activation	POST	/von/gor-gateway/gor-consumer-enrollment/v1/optInClo	No header is required; however, authentication through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required.
Consumer Enrollment	Add PAN for a User	POST	/von/gor-gateway/gor-consumer-enrollment/v1/addPan/{trackingId}	No header is required; however, authentication through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required.
Consumer Enrollment	Delete Consumer Opt-In	DELETE	/von/gor-gateway/gor-consumer-enrollment/v1/optOut/{trackingId}	No header is required; however, authentication through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required.
Consumer Enrollment (Generic)	Consumer Enrollment - Opt In - Generic	POST	/von/gor-gateway/gor-consumer-enrollment/generic/transform/v1/optIn	No header is required; however, authentication through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required.
Eligibility	Get Offers for User	POST	/von/gor-gateway/gor-eligibility/v1/offers/user	No header is required; however, authentication through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required.
Eligibility
Get Segments By Card ID	GET	/von/gor-gateway/gor-eligibility/v1/segment/{userId}/{cardId}	No header is required; however, authentication through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required.
Eligibility	Get Segment By User ID	GET	/von/gor-gateway/gor-eligibility/v1/segment/{userId}	No header is required; however, authentication through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required.
Eligibility	Get Merchant Ranks for a Card Id	GET	/von/gor-gateway/gor-eligibility/v1/merchants/ranks/{userId}/{cardId}	No header is required; however, authentication through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required.
Eligibility	Get Merchant Ranks for a User	GET	/von/gor-gateway/gor-eligibility/v1/merchants/ranks/{userId}	No header is required; however, authentication through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required.
Ledger	Ledger Add Event	POST	/von/gor-gateway/gor-ledger/v1/event	EX-CORRELATION-ID (optional)
Ledger	Consumer Dashboard	GET	/von/gor-gateway/gor-ledger/v1/consumer-dashboard	No header is required; however, authentication through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required.
Ledger (Generic)	Ledger Add Event - Generic	POST	/von/gor-gateway/gor-ledger/generic/transform/v1/event	No header is required; however, authentication through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required.
Payout	Payout Request	POST	/von/gor-gateway/gor-payout/v1/payout	clientId (required)
Payout (Generic)	Payout Request - Generic	POST	/von/gor-gateway/gor-payout/generic/transform/v1/payout	No header is required; however, authentication through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required.

Make Your First API Call

Make your first API call to the Visa Offers Network (VON) to verify your integration setup and authentication configuration. The first API call serves as a connectivity and authentication test.

1. Prepare your HTTP client with the required headers for authentication.

The Consumer Opt-In endpoint is ideal for testing authentication setup.

2. Construct a POST request to the Consumer Opt-In endpoint for initial testing.

This endpoint validates user enrollment data and provides comprehensive testing of authentication and request body handling.

3. Set the request URL to: https://sandbox.api.visa.com/von/gor-gateway/gor-consumer-enrollment/v1/optIn.

This endpoint enrolls consumers in VON using Primary Account Number (PAN) details and returns a unique tracking ID for future operations.

4. Add the required headers including Content-Type and authentication.

Set Content-Type: application/json and X-GOR-CLIENT-ID: your-client-id-here (replace with your actual client ID from the Visa Developer Center).

5. Prepare the request body with required enrollment data.

Include the following JSON structure in your request body:

{
   "appId": "12345678-1234-5123-a123-123456789012",
   "externalUserId": "user123",
   "cards": [
      {
        "pan": "XXXXXXXXXXXXXXXX",
        "isPayoutPan": true
      }
   ]
}

Copied!

Replace the values with your application ID (must follow the UUID pattern), external user identifier (1-255 characters), and card details. The PAN must be a 16-19 digit card number or can be empty.

6. Execute the POST API call and examine the response.

A successful response returns HTTP 200 (Opt-In enrollment successful) with OptInResponse schema including a trackingId for the enrolled user. Store this trackingId for subsequent API calls.

7. Verify the response format and validate the tracking ID.

Check that the response includes status, message, and trackingId fields. Handle error responses (400 Invalid request or 500 Internal server error) by examining the error details in the OptInResponse schema.

You have successfully made your first VON API call and verified that your authentication and connectivity are working correctly.

Offers Service

The Offers Service provides comprehensive merchant offer lifecycle management through Create, Read, Update, and Delete (CRUD) operations, enabling third-party aggregators to manage offers across the Visa Offers Network (VON) platform.

This service enables third-party aggregators and content providers to manage merchant offers, coupons, and promotional campaigns within VON. There are 13 endpoints supporting both individual offer management and bulk operations for large-scale merchant programs.

Create New Offer

Use this service to create new offers in the Visa Offers Network (VON).

Endpoint details are as follows:

HTTP Method – POST
URL – /von/gor-gateway/gor-offers/v1/offers
Operation ID – createOffers

The typical implementation sequence is as follows:

1. Set the required X-GOR-CLIENT-ID header (Client ID).

2. Prepare offer data with merchant details, reward structure, and terms. Each offer can include multiple components:

Merchant Information – Basic merchant details including name, ID, category, contact information, and business details
Offer Details – Offer-specific information including rewards, limits, dates, terms and conditions, and qualification criteria
Coupon Information – Coupon codes, descriptions, validity periods, and usage restrictions for promotional offers
Images and Media – Merchant logos, offer images, and other visual assets with specified dimensions and formats
Store Locations – Physical store information including addresses, coordinates, and location-specific details

The request body must include Content-Type: application/json and contain an array of MerchantRequest objects to support bulk creation of multiple offers in a single request.

3. Submit POST request with offer array.

4. Process bulk response with success or error results.

Successful request returns HTTP 200 (Offers created successfully) with the BulkMerchantResponse schema. BulkMerchantResponse provides comprehensive feedback including errorResults, successResults, and resultCounts for detailed processing status of each offer in the bulk request.
Unsuccessful request returns HTTP 400 (Bad request) with the ErrorResponse schema.

Get and Filter Offers

Use this service to retrieve paginated offers with filtering by type, merchant name, category, and sorting capabilities.

Endpoint details are as follows:

HTTP Method – GET
URL – /von/gor-gateway/gor-offers/v1/offers
Operation ID – getOffersByTypeAndMerchant

The typical implementation sequence for this API endpoint is as follows:

1. Set the required X-GOR-CLIENT-ID header (Client ID).

2. Add query parameters for filtering and set pagination parameters if needed

Parameter	Type	Required?	Description
offerType	string	No	Offer type filter. Enum values are:
C – coupons	O – offers
merchantName	string	No	Merchant name filter
merchantCategory	string	No	Merchant category filter
page	integer	No	Page number for pagination (default: 0, format: int32)
size	integer	No	Page size for pagination (default: 10, format: int32)
sort	string	No	Sort field (default: externalMerchantScore)
direction	string	No	Sort direction (default: DESC)

3. Submit GET request.

4. Process paginated offer results.

Successful request returns HTTP 200 (Offers retrieved successfully) with the PageOfferAllResponse schema.
Unsuccessful request returns HTTP 400 (Bad request) with the ErrorResponse schema.

Get Offer by GOR Merchant ID

Use this service to retrieve an offer by its GOR Merchant ID.

Endpoint details are as follows:

HTTP Method – GET
URL – /von/gor-gateway/gor-offers/v1/offers/{gorMerchantId}
Operation ID – getOffer

The typical implementation sequence is as follows:

1. Set the required X-GOR-CLIENT-ID header (Client ID).

2. Provide the required GOR Merchant ID (gorMerchantId) in the URL path.

3. Submit GET request.

4. Process single offer response with success or error results.

Successful request returns HTTP 200 (Offer retrieved successfully) with the MerchantResponse schema.
Unsuccessful request returns HTTP 400 (Bad request) or 404 (Offer not found) with the ErrorResponse schema.

Update Offers

Use this service to update multiple offers.

Endpoint details are as follows:

HTTP Method – PUT
URL – /von/gor-gateway/gor-offers/v1/offers
Operation ID – updateOffer

The typical implementation sequence is as follows:

1. Set the required X-GOR-CLIENT-ID header (Client ID).

2. Prepare updated offer data array. The request body must include Content-Type: application/json and contain an array of MerchantRequest objects to support bulk update of multiple offers in a single request.

3. Submit PUT request with modified offer details.

4. Process bulk response with success or error results.

Successful request returns HTTP 200 (Offers updated successfully) with the BulkMerchantResponse schema. BulkMerchantResponse provides comprehensive feedback including errorResults, successResults, and resultCounts for detailed processing status of each offer in the bulk request.
Unsuccessful request returns HTTP 400 (Bad request) or 404 (Offer not found) with the ErrorResponse schema.

Delete Offer

Use this service to delete an offer by its GOR Offer ID.

Endpoint details are as follows:

HTTP Method – DELETE
URL – /von/gor-gateway/gor-offers/v1/offers/{gorMerchantId}
Operation ID – deleteOffer

The typical implementation sequence is as follows:

1. Set the required X-GOR-CLIENT-ID header (Client ID).

2. Provide the GOR Offer ID (gorMerchantId) of the specific offer you want to delete in the URL path (required).

3. Submit DELETE request.

4. Confirm deletion success.

Successful request returns HTTP 200 (Offer deleted successfully) with the MerchantResponse schema.
Unsuccessful request returns HTTP 400 (Bad request) or 404 (Offer not found) with the ErrorResponse schema.

Get Offers for a Specific Merchant (for VOX)

Use this service to retrieve all offers for a specific merchant by external merchantId. This endpoint is used for Visa Offers Exchange (VOX) only.

Endpoint details are as follows:

HTTP Method – GET
URL – /von/gor-gateway/gor-offers/v2/merchants/{merchantId}/offers
Operation ID – getMerchantOffers

The typical implementation sequence is as follows:

1. Set the required X-GOR-CLIENT-ID header (Client ID).

2. Provide the required merchantId (external merchant identifier) in the URL path parameter.

3. Submit GET request.

4. Process merchant-specific offer response.

Successful request returns HTTP 200 (Offers retrieved successfully) with the PagedResponse schema containing all offers associated with the specified merchant.
Unsuccessful request returns HTTP 400 (Bad request) or 404 (Merchant not found or no offers available) with the ErrorResponse schema.

Create Offers under a Merchant (for VOX)

Use this service to create or update offers for an existing merchant. The merchantId must exist in the system. This endpoint is used for Visa Offers Exchange (VOX) only.

Endpoint details are as follows:

HTTP Method – POST
URL – /von/gor-gateway/gor-offers/v2/merchants/offers
Operation ID – addOffersToMerchant

The typical implementation sequence is as follows:

1. Set the required X-GOR-CLIENT-ID header (Client ID).

2. Prepare merchant offer data with merchantId, offers, and action specification.

The request body must include Content-Type: application/json and contain an array of MerchantRequestV2 objects with the action field specifying the desired operation.

3. Submit POST request with merchant offer array.

4. Process bulk response with success or error results.

Successful request returns HTTP 200 (Offers processed successfully) with the BulkOfferResponse schema providing detailed feedback for each offer operation.
Unsuccessful request returns HTTP 400 (Bad request - Invalid action or data) or 404 (Merchant not found) with the ErrorResponse schema.

Update Offer for a Merchant (for VOX)

Use this service to update offers for existing merchants. This endpoint is used for Visa Offers Exchange (VOX) only.

Endpoint details are as follows:

HTTP Method – PATCH
URL – /von/gor-gateway/gor-offers/v2/merchants/offers
Operation ID – updateMerchantOffer

The typical implementation sequence is as follows:

1. Set the required X-GOR-CLIENT-ID header (Client ID).

2. Prepare merchant offer update data with merchantId, offers, and action specification. The request body must include Content-Type: application/json and contain an array of MerchantRequestV2 objects with the action field specifying the update operation.

3. Specify the action type for each offer update operation:

UPDATE – Modify existing offer details
ACTIVATE – Enable previously inactive offers
DEACTIVATE – Disable currently active offers

4. Submit PATCH request with merchant offer update array.

5. Process bulk response with success or error results.

Successful request returns HTTP 200 (Offers updated successfully) with the BulkOfferResponse schema providing detailed feedback for each offer update operation.
Unsuccessful request returns HTTP 400 (Bad request - Invalid action or data) or 404 (Merchant or offer not found) with the ErrorResponse schema.

Delete Offer for a Merchant (for VOX)

Use this service to delete a specific offer by marking it as inactive. This endpoint is used for Visa Offers Exchange (VOX) only.

Endpoint details are as follows:

HTTP Method – DELETE
URL – /von/gor-gateway/gor-offers/v2/merchants/{merchantId}/offers/{offerId}
Operation ID – deleteMerchantOffer

The typical implementation sequence is as follows:

1. Set the required X-GOR-CLIENT-ID header (Client ID).

2. Provide the required merchantId (external merchant identifier) and offerId (external offer identifier) in the URL path parameters.

3. Submit DELETE request.

4. Confirm deletion success.

Successful request returns HTTP 200 (Offer deleted successfully) with the MerchantResponse schema confirming the deletion operation.
Unsuccessful request returns HTTP 400 (Bad request) or 404 (Merchant or offer not found) with the ErrorResponse schema.

Create Offers - Generic

Use this generic endpoint to create offers with generic payload. This endpoint requires mapping configuration on Visa Offers Network (VON) prior to use. Contact your Visa Implementation Manager to set up the required payload mapping.

Endpoint details are as follows:

HTTP Method – POST
URL – /von/gor-gateway/gor-offers/generic/transform/v1/offers
Operation ID – handleGenericRequest_2

The typical implementation sequence is as follows:

1. Coordinate with Visa to configure payload mapping for your specific data structure before using this endpoint.

2. Prepare generic payload structure based on your configured mapping requirements for creating offers.

3. Submit POST request with generic object payload. The request body must include Content-Type: application/json and contain a generic object structure as configured in your VON mapping.

4. Process generic response.

Successful request returns HTTP 200 (OK) indicating the generic payload was processed successfully through the configured mapping.
Unsuccessful request returns HTTP 400 (Bad Request) with the ErrorResponse schema.

Update Offers - Generic

Use this generic endpoint to update offers with generic payload. This endpoint requires mapping configuration on Visa Offers Network (VON) prior to use. Contact your Visa Implementation Manager to set up the required payload mapping.

Endpoint details are as follows:

HTTP Method – PUT
URL – /von/gor-gateway/gor-offers/generic/transform/v1/offers
Operation ID – handleGenericRequest_1

The typical implementation sequence is as follows:

1. Coordinate with Visa to configure payload mapping for your specific data structure before using this endpoint.

2. Prepare generic payload structure based on your configured mapping requirements for updating offers.

3. Submit PUT request with generic object payload. The request body must include Content-Type: application/json and contain a generic object structure as configured in your VON mapping.

4. Process generic response.

Successful request returns HTTP 200 (OK) indicating the generic payload was processed successfully through the configured mapping.
Unsuccessful request returns HTTP 400 (Bad Request) with the ErrorResponse schema.

Create Merchant Offers - Generic

Use this generic endpoint to create merchant offers with generic payload. This endpoint requires mapping configuration on Visa Offers Network (VON) prior to use. Contact your Visa Implementation Manager to set up the required payload mapping.

Endpoint details are as follows:

HTTP Method – POST
URL – /von/gor-gateway/gor-offers/generic/transform/v2/merchants/offers
Operation ID – handleGenericRequest_1

The typical implementation sequence is as follows:

1. Coordinate with Visa to configure payload mapping for your specific data structure before using this endpoint.

2. Prepare generic payload structure based on your configured mapping requirements.

3. Submit POST request with generic object payload. The request body must include Content-Type: application/json and contain a generic object structure as configured in your VON mapping.

4. Process generic response.

Successful request returns HTTP 200 (OK) indicating the generic payload was processed successfully through the configured mapping.
Unsuccessful request returns HTTP 400 (Bad Request) with the ErrorResponse schema.

Update Merchant Offers - Generic

Use this generic endpoint to update merchant offers with generic payload. This endpoint requires mapping configuration on Visa Offers Network (VON) prior to use. Contact your Visa Implementation Manager to set up the required payload mapping.

Endpoint details are as follows:

HTTP Method – PATCH
URL – /von/gor-gateway/gor-offers/generic/transform/v2/merchants/offers
Operation ID – handleGenericRequest_2

The typical implementation sequence is as follows:

1. Coordinate with Visa to configure payload mapping for your specific data structure before using this endpoint.

2. Prepare generic payload structure based on your configured mapping requirements for updating merchant offers.

3. Submit PATCH request with generic object payload. The request body must include Content-Type: application/json and contain a generic object structure as configured in your VON mapping.

4. Process generic response.

Successful request returns HTTP 200 (OK) indicating the generic payload was processed successfully through the configured mapping.
Unsuccessful request returns HTTP 400 (Bad Request) with the ErrorResponse schema.

Consumer Enrollment Service

The Consumer Enrollment Service manages consumer opt-in and opt-out processes for personalized offers using Primary Account Numbers (PANs), serving as the gateway for user participation in Visa Offers Network (VON).

This service facilitates consumer enrollment and card management within the VON platform, enabling users to opt-in for personalized merchant offers and manage their payment card associations for cash back rewards. There are five endpoints supporting the complete consumer enrollment lifecycle from initial opt-in through card management to opt-out.

Consumer Opt-In

Use this service to enroll consumers in the Visa Offers Network (VON) using card details, which consist of Primary Account Numbers (PANs). This service returns a unique tracking ID for future API operations.

Endpoint details are as follows:

HTTP Method – POST
URL – /von/gor-gateway/gor-consumer-enrollment/v1/optIn
Operation ID – optInEnrollment

The typical implementation sequence is as follows:

1. Set the required X-GOR-CLIENT-ID header (Client ID).

2. Prepare user enrollment data with appId, externalUserId, and card details. The request body must include the required fields (appId, cards, and externalUserId).

If you are adding a single PAN, set isPayoutPAN=true to designate it as the payout PAN.
If you are adding multiple PANs in a single request, you must set isPayoutPAN=true for at least one PAN. If no payout PAN is specified, the API will return an error.

3. Submit POST request.

4. Process response with success or error results.

Successful request returns HTTP 200 (Opt-In enrollment successful) with the OptInResponse schema including the trackingId, which is a unique identifier for enrolled users in VON. Store returned trackingId and userID for future API calls. The response also includes a cardDetails array containing the cardId, isPayoutPan flag, and lastFour (last four digits of the enrolled card number) for each enrolled card.
Unsuccessful request returns HTTP 400 (Invalid request) or 500 (Internal server error) with the OptInResponse schema.

CLO Opt-In and Offer Activation

Use this service to enroll an existing Visa Offers Network (VON) consumer in Visa Offers Platform (VOP) for Card-Linked Offer (CLO) participation. The user must already be enrolled in VON through the Consumer Opt-In endpoint before calling this endpoint.

Endpoint details are as follows:

HTTP Method – POST
URL – /von/gor-gateway/gor-consumer-enrollment/v1/optInClo
Operation ID – cloEnrollment

The typical implementation sequence is as follows:

1. Set the optional X-GOR-CLIENT-ID header (Client ID).

2. Prepare the request body with the user identifier and offer details.

The request body must include at least one of these - userId (unique GOR user identifier), trackingId (GOR tracking identifier), or a combination of externalUserId and appId to identify the existing VON-enrolled user. The appId is the application identifier (issuer ID) associated with the enrollment.

These fields are optional:

Include cardId to specify the unique GOR card identifier for the card to be enrolled in CLO.
Include offerId to specify the offer identifier to be enrolled.

3. Submit POST request.

4. Process response with success or error results.

Successful request returns HTTP 200 (CLO enrollment successful) with the CloEnrollConsumerResponse schema containing the message and status fields.
Unsuccessful request returns HTTP 400 (Invalid request — userId or trackingId must be provided), 404 (User or card not found), 408 (Request timeout), or 500 (Internal server error) with the ErrorResponse schema.

Add PAN for a User

Use this service to associate additional card details, which consist of Primary Account Numbers (PANs), with an existing Visa Offers Network (VON)-enrolled user for multi-card support.

Endpoint details are as follows:

HTTP Method – POST
URL – /von/gor-gateway/gor-consumer-enrollment/v1/addPan/{trackingId}
Operation ID – addPanForExistingUser

The typical implementation sequence is as follows:

1. Set the required X-GOR-CLIENT-ID header (Client ID).

2. Provide the existing user's trackingId in the URL path (required).

3. Prepare the card data with PAN details. The request body must include Content-Type: application/json and contain a CardRequest object with PAN details.

4. Indicate if the PAN is used for payout purposes in the isPayoutPan field.

5. Submit POST request.

6. Confirm PAN addition success.

Successful request returns HTTP 200 (PAN added successfully) with the OptInResponse schema including the trackingId, which indicates the user's encrypted PAN.
Unsuccessful request returns HTTP 400 (Invalid request), 404 (User not found), or 500 (Internal server error) with the OptInResponse schema.

Delete Consumer Opt-In

Use this service to remove consumer enrollment from Visa Offers Network (VON) using their unique tracking ID and optional card details for complete opt-out processing.

Endpoint details are as follows:

HTTP Method – DELETE
URL – /von/gor-gateway/gor-consumer-enrollment/v1/optOut/{trackingId}
Operation ID – deleteOptInEnrollment

The typical implementation sequence is as follows:

1. Set the required X-GOR-CLIENT-ID header (Client ID).

2. Provide the existing trackingId of the specific user enrollment you want to delete in the URL path (required).

3. Prepare optional request body with OptOutRequest schema containing Primary Account Number (PAN) details and isOptOutUser field to indicate complete opt-out.

4. Submit DELETE request.

5. Confirm deletion success.

Successful request returns HTTP 200 (Opt-In enrollment deleted successfully) with an object response containing string key-value pairs for deletion confirmation details.
Unsuccessful request returns HTTP 400 (Invalid request), 404 (Opt-In enrollment not found), or 500 (Internal server error) with an object response containing string key-value pairs.

Consumer Enrollment - Opt In - Generic

Use this generic endpoint to do opt-in for cardholders. This endpoint requires mapping configuration on Visa Offers Network (VON) prior to use. Contact your Visa Implementation Manager to set up the required payload mapping.

Endpoint details are as follows:

HTTP Method – POST
URL – /von/gor-gateway/gor-consumer-enrollment/generic/transform/v1/optIn
Operation ID – handleGenericRequest

The typical implementation sequence is as follows:

1. Coordinate with Visa to configure payload mapping for your specific data structure before using this endpoint.

2. Prepare generic payload structure based on your configured mapping requirements for consumer enrollment.

3. Submit POST request with generic object payload. The request body must include Content-Type: application/json and contain a generic object structure as configured in your VON mapping.

4. Process generic response.

Successful request returns HTTP 200 (OK) indicating the generic payload was processed successfully through the configured mapping.
Unsuccessful request returns HTTP 400 (Bad Request) with the ErrorResponse schema.

Eligibility Service

The Eligibility Service provides intelligent offer-to-user matching and segmentation capabilities, enabling personalized offer delivery by associating offers with enrollment collections and user characteristics.

This service delivers personalized offer experiences by determining user eligibility, segmentation, and merchant rankings based on user enrollment status, card characteristics, and behavioral patterns within the VON platform. There are five endpoints providing comprehensive eligibility determination from user enrollment verification through segmentation analysis to merchant ranking insights.

Get Offers for User

Use this service to verify user enrollment status and retrieve personalized eligible offers based on user ID, application ID, and filtering criteria with pagination support.

Endpoint details are as follows:

HTTP Method – POST
URL – /von/gor-gateway/gor-eligibility/v1/offers/user
Operation ID – getOffersByUser

The typical implementation sequence is as follows:

1. Prepare request body with required fields appId (ID of the client application) and externalUserId (unique identifier for a user within your application).

2. Add query parameters for filtering and set pagination parameters if needed.

Parameter	Type	Required?	Description
offerType	string	No	Indicates the type of offer requested.
O – offers	C – coupons	OC – offers and coupons
channel	string	No	Indicates whether offer is distributed online, instore, or both (default: both)
page	integer	No	Indicates the page number used in pagination (default: 1)
size	integer	No	Indicates the number of items displayed per page (default: 50)
sort	string	No	Provides the Visa merchant score for the merchant's offer ranking (default: visaMerchantScore)
direction	string	No	Indicates the sorting order (ascending or descending) (default: DESC)
isActivated	string	No	Specifies whether to return activated offers or all offers (default: false)
includeOfferTypeOnly	string	No	Filters to include only offers with specific offer type code (AFF or CLO)

3. Submit POST request.

4. Process results with eligible offers and user details.

Successful request returns HTTP 200 (Eligible offers retrieved successfully) with the GetOffersByUserResponseDto schema. The response includes details about the user and the offers (including Card-Linked Offer or CLO) they can receive, including eligible merchants and offers, enrolled card information (last four digits), available merchant categories, cash back percentages, and pagination details for larger result sets.
Unsuccessful request returns HTTP 400 (Invalid request) or 500 (Internal server error) with the ErrorResponse schema.

Get Segments By Card ID

Use this service to retrieve segment details for the specified card ID.

Endpoint details are as follows:

HTTP Method – GET
URL – /von/gor-gateway/gor-eligibility/v1/segment/{userId}/{cardId}
Operation ID – getSegmentsByCardLevel

The typical implementation sequence is as follows:

1. Provide the required userId and cardId in the URL path parameters.

2. Add optional merchantId query parameter if needed for merchant-specific segment filtering.

3. Submit GET request.

4. Process segment response.

Successful request returns HTTP 200 (getSegment retrieved successfully) with the SegmentsResponseDto schema containing segments with merchantId, segmentName, and effectiveDate fields.
Unsuccessful request returns HTTP 400 (Invalid request) or 500 (Internal server error) with the ErrorResponse schema.

Get Segment By User ID

Use this service to retrieve segment details for the specified user.

Endpoint details are as follows:

HTTP Method – GET
URL – /von/gor-gateway/gor-eligibility/v1/segment/{userId}
Operation ID – getSegmentsByCardHolderLevel

The typical implementation sequence is as follows:

1. Provide the required userId in the URL path parameter.

2. Add optional merchantId query parameter if needed for merchant-specific segment filtering.

3. Submit GET request.

4. Process segment response.

Successful request returns HTTP 200 (getSegment retrieved successfully) with the SegmentsResponseDto schema containing segments with merchantId, segmentName, and effectiveDate fields.
Unsuccessful request returns HTTP 400 (Invalid request) or 500 (Internal server error) with the ErrorResponse schema.

Get Merchant Ranks for a Card Id

Use this service to retrieve card-specific merchant rank details for a given user and card ID combination.

Endpoint details are as follows:

HTTP Method – GET
URL – /von/gor-gateway/gor-eligibility/v1/merchants/ranks/{userId}/{cardId}
Operation ID – getMerchantRanksByCardLevel

The typical implementation sequence is as follows:

1. Provide the required userId and cardId in the URL path parameters.

2. Submit GET request.

3. Process merchant ranking response.

Successful request returns HTTP 200 (getMerchantsRanks retrieved successfully) with the SegmentsResponseDto schema.
Unsuccessful request returns HTTP 400 (Invalid request) or 500 (Internal server error) with the ErrorResponse schema.

Get Merchant Ranks for a User

Use this service to retrieve user-level merchant rank details for all cards associated with a given user.

Endpoint details are as follows:

HTTP Method – GET
URL – /von/gor-gateway/gor-eligibility/v1/merchants/ranks/{userId}
Operation ID – getMerchantRanksByCardHolderLevel

The typical implementation sequence is as follows:

1. Provide the required userId in the URL path parameter.

2. Submit GET request.

3. Process merchant ranking response.

Successful request returns HTTP 200 (getMerchantsRanks retrieved successfully) with the SegmentsResponseDto schema.
Unsuccessful request returns HTTP 400 (Invalid request) or 500 (Internal server error) with the ErrorResponse schema.

Ledger Service

The Ledger Service provides comprehensive event tracking and analytics capabilities, enabling the capture of user interactions, commission status updates, and dashboard insights for pending and paid events within Visa Offers Network (VON).

This service tracks user engagement and financial transactions across the VON ecosystem, providing detailed event logging for analytics, commission tracking, and consumer dashboard reporting of offer performance and payout status. There are three endpoints supporting comprehensive event lifecycle management from real-time interaction tracking through commission processing to consumer dashboard reporting.

Ledger Add Event

Use this service to send events and user-level details, such as commission status and interactions with merchant offers on the Issuer's application.

Endpoint details are as follows:

HTTP Method – POST
URL – /von/gor-gateway/gor-ledger/v1/event
Operation ID – createEvent

The typical implementation sequence is as follows:

1. Set the optional EX-CORRELATION-ID header for request tracking.

2. Prepare event data with eventType and eventDateTime.

Field	Type	Required?	Description
eventType	string	No	Type of event. Enum values are:
MERCHANT_VIEW – User viewed a merchant's offer details	MERCHANT_REDIRECT – User clicked through to merchant website	CLICK – General click events within the application	CATEGORY_SELECT – User selected a specific merchant category
AVG_TIME_SPENT – Time spent viewing offers or merchant content	MERCHANT_WALL_LOAD – Merchant offer wall page loaded	BROKEN_LINK – User encountered a broken merchant link	SCROLL_DEPTH – User scrolling behavior and engagement depth
OFFER_REDEEM – User redeemed an offer or coupon	STMT_CREDIT – Statement credit processed for user
eventDateTime	string	No	Date and time when the event occurred (date-time format)

3. Add relevant attribute objects based on the event type.

userAttributes – User identification and association data. Consists of User ID, tracking code, and external user identifier for user association.
merchantAttributes – Merchant identification and context. Consists of merchant identifiers, URLs, and category information.
offerAttributes – Offer and promotion tracking data. Consists of offer and coupon identifiers for tracking specific promotions.
clickAttributes – User interaction details. Consists of specific UI elements clicked and user input details.
stmtCreditAttributes – Financial transaction information. Consists of commission amounts, payout status, transaction details, and statement credit information.
couponAttributes – Coupon identification and tracking data. Consists of coupon identifiers for tracking specific coupon usage.
issuerAttributes – Issuer application context. Consists of application ID and issuer-specific information.
redemptionAttributes – Redemption tracking information. Consists of commission ID and redemption-specific details.

4. Submit POST request.

5. Process EventResponse confirmation.

Successful request returns HTTP 200 (Event created successfully) with the EventResponse schema.
Unsuccessful request returns HTTP 400 (Invalid request) with the ErrorResponse schema or 500 (Internal server error) with the EventResponse schema.

Consumer Dashboard

Use this service to get consumer view dashboard, providing a unified view of user analytics, including total earned, pending, and paid amounts, as well as detailed lists of pending and paid offers and a full transaction history with dates and amounts.

Endpoint details are as follows:

HTTP Method – GET
URL – /von/gor-gateway/gor-ledger/v1/consumer-dashboard
Operation ID – getConsumerDashboard

The typical implementation sequence is as follows:

1. Identify the user using either the userId (user identifier for dashboard data) or trackingCode (tracking code for user identification) query parameter. This endpoint requires no authentication headers.

2. Set optional date range filters (startDate and endDate) in yyyy-MM-dd format. The dashboard data is filtered to show only transactions and offers within the specified date range. If no dates are specified all available data is returned.

3. Submit GET request with query parameters.

4. Process results with earnings summary and offer details, as well as pending and paid offers with amounts.

Successful request returns HTTP 200 (Dashboard details retrieved successfully) with the DashboardResponse schema. The DashboardResponse includes the data structure provided in this table. The total amounts (earned, pending, paid) represent cumulative values across all user transactions and offers within the specified date range or lifetime if no range is provided.
Unsuccessful request returns HTTP 400 (Invalid request) with the ErrorResponse schema or 500 (Internal server error) with the DashboardResponse schema.

Field	Type	Description
totalEarnedAmount	double	Total amount earned by the user across all offers
totalPendingAmount	double	Total amount pending for the user (not yet paid)
totalPaidAmount	double	Total amount already paid to the user
pendingOffers	array	List of OfferDetails objects for pending offers with merchant info, amounts, and dates
paidOffers	array	List of OfferDetails objects for paid offers with payout details and card information

Ledger Add Event - Generic

Use the Ledger Service generic endpoint to push ledger events to Visa Offers Network (VON). This endpoint requires mapping configuration on VON prior to use. Contact your Visa Implementation Manager to set up the required payload mapping.

Endpoint details are as follows:

HTTP Method – POST
URL – /von/gor-gateway/gor-ledger/generic/transform/v1/event
Operation ID – handleGenericRequest

The typical implementation sequence is as follows:

1. Coordinate with Visa to configure payload mapping for your specific data structure before using this endpoint.

2. Prepare generic payload object based on your configured mapping requirements.

3. Submit POST request with generic object payload. The request body must include Content-Type: application/json and contain a generic object structure.

4. Process generic response.

Successful request returns HTTP 200 (OK) indicating the generic payload was processed successfully through the configured mapping.
Unsuccessful request returns HTTP 400 (Bad Request) with the ErrorResponse schema.

Payout Service

The Payout Service enables third-party aggregators to send commission details and process statement credits within Visa Offers Network (VON), facilitating cash back and reward fulfillment for enrolled consumers.

This service processes commission payouts and statement credits for consumer cash back rewards, enabling third-party aggregators to submit detailed transaction and commission information for financial settlement within the VON ecosystem. There are two endpoints supporting the complete commission payout lifecycle from transaction capture through financial processing to statement credit issuance.

Payout Request

Use this service to initiate the creation of a commission payout request.

Endpoint details are as follows:

HTTP Method – POST
URL – /von/gor-gateway/gor-payout/v1/payout
Operation ID – savePayoutDetails

The typical implementation sequence is as follows:

1. Set the required clientId header.

2. Prepare payout data with ID, Type, and Action fields.

Field	Type	Required?	Description
ID	string	No	Unique partner ID.
Type	string	No	Specifies the payout type.
Action	string	No	Specifies the intent of the operation by the third-party aggregator. Different action types specify the intent of the payout operation.

3. Include detailed payout commission information in the Payload object.

4. Submit POST request.

5. Process PayoutResponse with operation status.

Successful request returns HTTP 200 (Payout details processed successfully) with the PayoutResponse schema.
Unsuccessful request returns HTTP 400 (Invalid request) or 500 (Internal server error) with the PayoutResponse schema.

Payout Request - Generic

Use the Payout Service generic endpoint to take any payload to issue statement credit. This endpoint requires mapping configuration on Visa Offers Network (VON) prior to use. Contact your Visa Implementation Manager to set up the required payload mapping.

Endpoint details are as follows:

HTTP Method – POST
URL – /von/gor-gateway/gor-payout/generic/transform/v1/payout
Operation ID – handleGenericRequest

The typical implementation sequence is as follows:

1. Coordinate with Visa to configure payload mapping for your specific data structure before using this endpoint.

2. Prepare generic payload object based on your configured mapping requirements.

3. Submit POST request with generic object payload. The request body must include Content-Type: application/json and contain a generic object structure.

4. Process generic response.

Successful request returns HTTP 200 (OK) indicating the generic payload was processed successfully through the configured mapping.
Unsuccessful request returns HTTP 400 (Bad Request) with the ErrorResponse schema.