Visa Offers Network

Best Practices

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

Authentication Management

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.
• 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

Performance Optimization

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 (create or update multiple offers 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.

Request and Response Patterns

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)
  • Query Parameters – Required: false (except offerType in Eligibility), 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
  • Error Responses – ErrorResponse (with reason, status, details, message, errorCode)
  • Bulk Operation Responses – BulkMerchantResponse (with errorResults, successResults, resultCounts, responseMessage), BulkOfferResponse (variants 1-7), BulkMerchantResponse-1 (includes partialSuccessResults)
  • 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
  • Date Formats – date, date-time (ISO 8601)
  • Numeric Formats – int32, int64, float, double

Status Values

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

Testing and Validation

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
  • MerchantRequestV2 – merchantId is 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)
  • Server Errors – 500 (Internal server error) in Consumer Enrollment, Eligibility, Ledger, and Payout 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