# 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