Visa Offers Network

How To Use

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

1. Enroll users with Primary Account Numbers (PANs) and manage additional cards using the Consumer Enrollment Service.
2. Retrieve eligible or personalized offers for enrolled users using the Eligibility Service.
3. 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.

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:

{...}

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.

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.

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.