Best practices

This section provides guidance for optimal Visa Offers Network (VON) API integration, covering authentication, performance, and common implementation patterns.

The Visa Offers Network (VON) API uses different authentication approaches depending on the endpoint type (standard versus generic). Authentication requirements vary significantly across services and endpoint types.

• Standard Endpoints
  • Offers Service – Requires the X-GOR-CLIENT-ID header for all operations.
  • Consumer Enrollment Service – Requires the X-GOR-CLIENT-ID header for all operations.
  • Ledger Service – Uses the EX-CORRELATION-ID header (optional for event creation). No header is required for consumer dashboard retrieval; however, authentication and authorization through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required.
  • Payout Service – Requires the clientId header for payout requests.
  • Eligibility Service – No header is required; however, authentication and authorization through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required.
  • Consent Service – No header is required; however, authentication and authorization through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required.
  • Merchant Service – No header is required; however, authentication and authorization through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required.
• Generic Transform Endpoints

  You must pre-configure payload mapping with VON before using generic transform endpoints (paths containing /generic/transform/) for these services, though the API calls themselves do not require authentication headers:

  • Generic Offers Service
  • Generic Consumer Enrollment Service
  • Generic Ledger Service
  • Generic Payout Service
• Generic Merchant Service – Unlike the other generic transform endpoints, the Merchant Service's generic-transform endpoints accept the same structured payload as the standard Create Merchants and Update Merchants endpoints; therefore, no VON-side payload mapping is required. Authentication and authorization through X-GOR-API-KEY and X-GOR-SHARED-SECRET are required, the same as the standard endpoints.
• Recommended Practice for Correlation IDs – Even though EX-CORRELATION-ID is optional, Visa strongly recommends that all VON clients generate and include a correlation ID (for example, a UUID v4) in every API request for every endpoint that supports the header. Consistent use of correlation IDs enables Visa support teams to trace a single logical transaction across service boundaries, such as a Consumer Opt-In request that triggers downstream eligibility processing and ledger operations, helping to significantly reduce mean time to resolution for production incidents.

Some Visa Offers Network (VON) APIs require Message Level Encryption (MLE) to protect sensitive request and response payloads.

Per Visa Developer Center (VDC) requirements, APIs that process Personally Identifiable Information (PII) or Personal Account Information (PAI) require MLE. Client applications must encrypt request payloads before sending them to VDC and VON, and must decrypt the responses that VDC returns.

This table lists the endpoints that currently require MLE. Because MLE is required for APIs that process PII or PAI, this list is not exhaustive and may change as additional endpoints are introduced. Always consult the current VDC specification for the latest MLE requirements.

MLE requirements apply at the endpoint level. Not all endpoints within an API service bundle require MLE. The Offers, Merchant, Consent, and Payout API service bundles do not require MLE.

For detailed information about generating MLE keys, configuring certificates, and implementing request and response encryption, see the Visa Offers Network (VON) Client Implementation Guide and the VDC documentation for MLE.

Optimize your Visa Offers Network (VON) API integration using these essential practices.

• Use pagination effectively – Leverage documented pagination parameters (page and size) with appropriate page sizes. The Eligibility Service defaults to 50 items per page, while the Offers Service defaults to 10 items per page.
• Implement bulk operations – Use bulk endpoints for the Offers Service and Merchant Service (create or update multiple offers or merchants in single requests) to reduce API call volume and improve efficiency.
• Cache relatively static data – Cache offer data, merchant information, and other relatively static content to reduce redundant API calls, especially for frequently accessed offer catalogs.
• Use appropriate filtering – Apply filtering parameters (offerType, merchantName, or merchantCategory) in GET requests to retrieve only needed data and reduce response payload sizes.
• Implement connection pooling – Use HTTP connection pooling and keep-alive connections to reduce connection overhead, especially important for high-volume integrations.
• Handle errors efficiently – Implement proper error handling for bulk operations where some items may succeed while others fail, processing successful items without resubmitting entire batches.

After deploying an integration, continuously monitor operational metrics to detect performance regressions and integration issues in Visa Offers Network (VON).

• API Latency – Track p50, p95, and p99 response times for each endpoint. Configure alerts for sustained deviations from established baselines.
• Error Rates – Monitor 4xx and 5xx response rates separately for each API service bundle. A rising 4xx rate often indicates a client-side integration regression, while a rising 5xx rate may indicate a VON-side issue.
• Volume Trends – Monitor request volume for each endpoint to identify unexpected drops that may indicate an integration break and spikes that may indicate retry storms or runaway loops.
• Correlation-ID-Based Tracing – Use the correlation ID strategy described in the Authentication Headers and Authentication Management sections to correlate latency and error spikes with specific transaction flows when escalating issues to the Visa support team.

These are the Visa Offers Network (VON) API request and response specifications.

• HTTP Protocol Details
  • HTTP Methods – GET, POST, PUT, PATCH, DELETE
  • Content Type – application/json (all request and response bodies)
  • OpenAPI Version – 3.1.0
  • API Version – 1
  • Operation Versioning – All endpoints include x-operationVersions with labels (v1, v1 - Latest, v2 - Latest)
  • Try It Functionality – All endpoints have x-hideTryIt: true
• Request Parameter Patterns
  • Path Parameters – Required: true, explode: false (userId, cardId, trackingId, gorMerchantId, merchantId, offerId, clientAppId, externalId, consentType)
  • Query Parameters – Required: false (except offerType in Eligibility and appId in Get User Consents), explode: true
  • Header Parameters – Required varies by service, explode: false
  • Request Bodies – Content: application/json, required: true (opt-out endpoint has requestBody but not required)
• Pagination and Sorting
  • Eligibility Service – page (default: 1), size (default: 50), sort (default: "visaMerchantScore"), direction (default: "DESC")
  • Offers Service – page (default: 0), size (default: 10), sort (default: "externalMerchantScore"), direction (default: "DESC")
  • Parameter Format – int32 format for page/size parameters
• Filtering and Search Parameters
  • Offers Service GET – offerType (enum: C, O), merchantName, merchantCategory
  • Eligibility Service POST – offerType (required: true, supports O for offers, C for coupons, OC for offers and coupons per description), region, search, countryCode, itpCompliant, merchantName, merchantCategory
  • Consumer Dashboard – userId, trackingCode, startDate (yyyy-MM-dd), endDate (yyyy-MM-dd)
  • Multi-field Search – Search across offer title, description, merchant name, merchant category, coupon name
• Response Schema Categories
  • Success Responses – SegmentsResponseDto, GetOffersByUserResponseDto-1, MerchantResponse, EventResponse, DashboardResponse, OptInResponse, PayoutResponse, PagedResponse, ConsentResponse-1, UserConsentsResponse-2, ConsentDetailResponse-1, UserConsentResponse, MerchantDetailResponseV2-18, MerchantResponse-2
  • Error Responses – ErrorResponse (with reason, status, details, message, errorCode)
  • Bulk Operation Responses – BulkMerchantResponse (with errorResults, successResults, resultCounts, responseCode, responseMessage, partialSuccessResults), BulkOfferResponse (variants 1-7)
  • Pagination Responses – PageableObject, PagingDto, PageOfferAllResponse, PageDashboardDetailsResponse
  • Specialized Responses – JobStatusResponse, AppEnrollmentsResponse, PullOfferDeletionResponse
• Content Type and Format Standards
  • Request Content – application/json for all structured data
  • Response Content – application/json for all responses
  • Generic Endpoints – Accept generic object type payloads, except the Merchant Service's generic endpoints, which accept the same structured MerchantOnlyRequestV2 payload as the standard Create or Update Merchants endpoints
  • Date Formats – date, date-time (ISO 8601)
  • Numeric Formats – int32, int64, float, double

Refer to these status enumeration values used in various Visa Offers Network (VON) API response schemas.

• Statement Credit Status Values (stmtCreditStatus field in UserEvent, UserEvent-1, StmtCreditAttributes, StmtCreditAttributes-1)
  • PENDING
  • SUCCESS
  • FAILED
• External Statement Credit Status Values (externalStmtCreditStatus field)
  • StmtCreditAttributes-1 version: PENDING, CONFIRMED, READY, PAID, FAILED
  • StmtCreditAttributes version: PENDING, CONFIRMED, READY, PAID
• Job Status Values (status field in JobStatusResponse)
  • IN_PROGRESS
  • COMPLETE
  • FAILED
• Commission Status Values (status field)
  • Payload-1 version (explicit enum): PENDING, CONFIRMED, READY, PAID, FAILED
  • Payload version (description only): pending, confirmed, ready, paid
• Event Type Values (eventType field in EventRequest and EventRequest-1)
  • EventRequest (10 values): MERCHANT_VIEW, MERCHANT_REDIRECT, CLICK, CATEGORY_SELECT, AVG_TIME_SPENT, MERCHANT_WALL_LOAD, BROKEN_LINK, SCROLL_DEPTH, OFFER_REDEEM, STMT_CREDIT
  • EventRequest-1 (18 values): OFFER_VIEWED, OFFER_DISMISSED, OFFER_ACTIVATE, EXTENSION_INSTALL, EXTENSION_UPDATE, EXTENSION_UNINSTALL, COUPON_SESSION, COUPON_APPLIED, MERCHANT_VIEW, MERCHANT_REDIRECT, CLICK, CATEGORY_SELECT, AVG_TIME_SPENT, MERCHANT_WALL_LOAD, BROKEN_LINK, SCROLL_DEPTH, OFFER_REDEEM, STMT_CREDIT
  • UserEvent (10 values): MERCHANT_VIEW, MERCHANT_REDIRECT, CLICK, CATEGORY_SELECT, AVG_TIME_SPENT, MERCHANT_WALL_LOAD, BROKEN_LINK, SCROLL_DEPTH, OFFER_REDEEM, STMT_CREDIT
  • UserEvent-1 (18 values): OFFER_VIEWED, OFFER_DISMISSED, OFFER_ACTIVATE, EXTENSION_INSTALL, EXTENSION_UPDATE, EXTENSION_UNINSTALL, COUPON_SESSION, COUPON_APPLIED, MERCHANT_VIEW, MERCHANT_REDIRECT, CLICK, CATEGORY_SELECT, AVG_TIME_SPENT, MERCHANT_WALL_LOAD, BROKEN_LINK, SCROLL_DEPTH, OFFER_REDEEM, STMT_CREDIT
• Offer Type Code Values (offerTypeCode field in OfferRequest, OfferRequest-1, OfferResponse)
  • CLO
  • AFF
• Click Item Values (clickItem field in ClickAttributes)
  • SETTINGS
  • PAYOUT_SETTINGS
  • LOCATION_SETTINGS
  • FAQ
  • DASHBOARD
  • SEARCH
  • CATEGORY
  • COUPON_CODE
  • TERMS_AND_CONDITIONS
• Merchant Identifier Action Values (action field in MerchantIdentifier - pattern: "^(ADD|DELETE)$")
  • ADD (add this identifier)
  • DELETE (remove this identifier)
• Offer Type Filter Values (offerType parameter in Offers Service GET endpoint)
  • C (coupons)
  • O (offers)
• PATCH Action Values (action field in MerchantRequestV2 variants - maxLength: 20)
  • UPDATE
  • ACTIVATE
  • DEACTIVATE
• Consent Type Values (consentType field in ConsentItemRequest-1, nested in ConsentRequest.consents, and Consent Service path parameters)
  • PERSONALIZATION
  • LOCATION
  • MEASUREMENT
  • MARKETING
  • THIRD_PARTY_SHARING
• Consent Operation Action Values (action field in ConsentOperationResult, ConsentOperationResult-1)
  • ENROLL
  • UNENROLL
  • DELETE
  • ADD_CARD
  • DELETE_CARD
  • UPDATE

Implement comprehensive testing strategies to ensure reliable Visa Offers Network (VON) API integration and optimal performance.

• Sandbox Environment

  Perform all testing against the sandbox server: https://sandbox.api.visa.com.

• Data Validation Patterns
  • PAN Validation – Pattern: ^\\d{16,19}$|^$ (16-19 digits or empty)
  • Application ID – Two patterns: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-5][0-9a-fA-F]{3}-[089abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ (OptInRequest) and ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ (OptInRequest-1)
  • Country Code – Pattern: ^[A-Z]{2}$ (ISO 3166-1 alpha-2)
  • Currency Code – Pattern: ^[A-Z]{3}$ (3-letter currency codes)
• Required Field Validation
  • OptInRequest – appId, cards (minimum 1), externalUserId are required
  • PayoutRequest-1 – Action, ID, Type are required
  • Payload-1 – 10 required fields: Amounts, ApplicationID, CommissionID, CreatedDate, DeviceID, EventDate, MerchantID, MerchantOrderID, ModifiedDate, TrackingCode
  • OfferRequest-1 – offerId, offerName are required
  • MerchantRequest – merchantId is required
  • ConsentRequest – clientId, externalId, and consents (minimum 1) are required
  • MerchantOnlyRequestV2 – externalClientId, merchantId, and merchantName are required
• HTTP Status Code Validation
  • Success Responses – 200 (OK) across all endpoints
  • Client Errors – 400 (Bad Request/Invalid request) across all endpoints
  • Resource Not Found – 404 (Offer not found, Merchant not found, User not found, Opt-In enrollment not found)
  • Forbidden – 403 (Client type not allowed to access this endpoint) in the Merchant Service's Create Merchants and Create Merchants - Generic endpoints
  • Server Errors – 500 (Internal server error) in Consumer Enrollment, Eligibility, Ledger, Payout services, and Consent services
• Date Format Validation
  • Date Fields – Format: yyyy-MM-dd (startDate, endDate in Consumer Dashboard; for example, "2024-10-23")
  • DateTime Fields – Format: date-time (ISO 8601 format)
• Enum Value Testing
  • Offer Type – "C" (coupons), "O" (offers), "OC" (offers and coupons)
  • Job Status – "IN_PROGRESS", "COMPLETE", "FAILED"
  • Commission Status – "PENDING", "CONFIRMED", "READY", "PAID", "FAILED"
  • Statement Credit Status – "PENDING", "SUCCESS", "FAILED"
  • External Statement Credit Status – StmtCreditAttributes-1 includes "FAILED" (5 values), StmtCreditAttributes excludes "FAILED" (4 values): "PENDING", "CONFIRMED", "READY", "PAID"
  • Offer Type Code – "CLO", "AFF" (defaults to AFF)
  • Event Types – EventRequest-1/UserEvent-1 schemas (18 values), EventRequest/UserEvent schemas (10 values), including OFFER_VIEWED, MERCHANT_VIEW, STMT_CREDIT
• Field Length Limits Testing
  • Error Response Fields – reason (max 100), message (max 1000), errorCode (max 500)
  • Error Detail Fields – field/reason/errorCode/errorDesc (max 200 each)
  • Merchant Fields – merchantId/merchantName (max 150), legalName/doingBusinessAs (max 255)
  • Commission Amount – Maximum 1,000,000