# Visa Travel Notification Service
Incorporate cardholder self-reported travel into your authorization decisions.
## Version: 1
### Servers
| URL | Description |
| --- | ----------- |
| https://sandbox.api.visa.com | Sandbox server |
---
## Visa Travel Notification API
Incorporate cardholder self-reported travel into your authorization decisions
### [POST] /travelnotificationservice/v1/travelnotification/itinerary
**Add Travel Itinerary**
Add Travel Itinerary allows you to send travel itinerary details to Visa. A successful response includes a Travel Itinerary ID created by Visa. You will use this API when cardholders inform you of their upcoming travel plans.
#### Request Body
Request body
| Required | Schema |
| -------- | ------ |
| Yes | **application/json**: { **"userId"**: string, **"partnerBid"**: string, **"returnDate"**: string, **"destinations"**: [ { **"state"**: string, **"country"**: string } ], **"departureDate"**: string, **"primaryAccountNumbers"**: [ { **"cardAccountNumber"**: string } ] }
|
#### Responses
| Code | Description | Schema |
| ---- | ----------- | ------ |
| 200 | AddTravelItinerary response with travelItineraryId | **application/json**: { **"failureCode"**: string, **"responseCode"**: string, **"responseMessage"**: string, **"travelItinerary"**: { **"source"**: string, **"userId"**: string, **"partnerBid"**: string, **"returnDate"**: string, **"destinations"**: [ { **"state"**: string, **"country"**: string } ], **"departureDate"**: string, **"lastUpdatedBy"**: string, **"lastUpdateTime"**: string, **"travelItineraryId"**: string, **"primaryAccountNumbers"**: [ { **"cardAccountNumber"**: string } ] }, **"failureDescription"**: string }
|
| 202 | Validation Failures | **application/json**: { **"responseCode"**: string,
**Available values:** "0", "5", "10", "15", "20", **"responseMessage"**: string }
|
| 400 | Bad Request | **application/json**: string
|
| 403 | Forbidden Operation to requested resource | **application/json**: string
|
| 500 | Temporary Downtime - retry operation after waiting | **application/json**: string
|
| 503 | Temporary Downtime for maintenance - retry operation after waiting | **application/json**: string
|
---
### Schemas
#### UpdateTravelItineraryResponse Schema
Itinenary from the System after Update Operations
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| failureCode | string | Error code specific for CRUD operations | No |
| responseCode | string | Web service response code | No |
| responseMessage | string | service response text specific for CRUD operations | No |
| travelItinerary | { **"source"**: string, **"userId"**: string, **"partnerBid"**: string, **"returnDate"**: string, **"destinations"**: [ { **"state"**: string, **"country"**: string } ], **"departureDate"**: string, **"lastUpdatedBy"**: string, **"lastUpdateTime"**: string, **"travelItineraryId"**: string, **"primaryAccountNumbers"**: [ { **"cardAccountNumber"**: string } ] } | An itinierary detail | No |
| failureDescription | string | Error description specific for CRUD operations | No |
#### Destination Schema
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| state | string | The state or province where your cardholder will travel. Must be a 2 character State Code for a state in the United States or a province in Canada and must not be included in the request if the Destination-Country is not the United States or Canada.A state in the United States must be included if the Destination – Country in the request is the United States. A province in Canada must be included if the Destination – Country in the request is Canada. If your cardholder will travel to multiple states or provinces, you can include multiple states or provinces in a single request. | No |
| country | string | The country where your cardholder will travel. If your cardholder will travel to multiple countries, you can include multiple countries in a single request.Must be a 3 character country code, as specified in the ISO 3166-1. | Yes |
#### TravelItineraries Schema
List of travel itineraries based on the search criteria provided
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| TravelItineraries | [ { **"source"**: string, **"userId"**: string, **"partnerBid"**: string, **"returnDate"**: string, **"destinations"**: [ { **"state"**: string, **"country"**: string } ], **"departureDate"**: string, **"lastUpdatedBy"**: string, **"lastUpdateTime"**: string, **"travelItineraryId"**: string, **"primaryAccountNumbers"**: [ { **"cardAccountNumber"**: string } ] } ] | List of travel itineraries based on the search criteria provided | |
#### RegisterUserforTravelNotificationServiceResponse Schema
Registration Information of a Developer for Travel Notification Service in VDP gateway
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| userId | string | VDP User/application Id | No |
| partnerBid | string | The issuer BID associated with Itinerary | No |
| failureCode | string | Error code specific for CRUD operations | No |
| responseCode | string | Web service response code | No |
| responseMessage | string | service response text specific for CRUD operations | No |
| failureDescription | string | Error description specific for CRUD operations | No |
#### AddTravelItinerary Schema
Adds an Itineray for the User
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| userId | string | User ID you assigned to identify the cardholder using the service. | No |
| partnerBid | string | Your Visa Business Identifier (BID). | Yes |
| returnDate | string | The date your cardholder will return from the trip. Must be in format YYYY-MM-DD and must not be before the Departure Date in the request or before the current date. | Yes |
| destinations | [ { **"state"**: string, **"country"**: string } ] | | Yes |
| departureDate | string | The date your cardholder will start their trip. Must be in format YYYY-MM-DD and must not be after the Return Date in the request. | Yes |
| primaryAccountNumbers | [ { **"cardAccountNumber"**: string } ] | | Yes |
#### TravelItinerary Schema
An itinierary detail
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| source | string | The source of the travel itinerary in the Visa system. When a travel itinerary is submitted to Visa through the Visa Travel Notification Service, the Source field in the response will be Cardholder Self Reported. | Yes |
| userId | string | User ID you assigned to identify the cardholder using the service. | No |
| partnerBid | string | Your Visa Business Identifier (BID). | Yes |
| returnDate | string | The date your cardholder will return from their trip. Format is YYYY-MM-DD. | No |
| destinations | [ { **"state"**: string, **"country"**: string } ] | | Yes |
| departureDate | string | The date your cardholder will start their trip. Format is YYYY-MM-DD. | Yes |
| lastUpdatedBy | string | User who updated the itinerary in current state. | Yes |
| lastUpdateTime | string | Time in format YYYY-MM-DDTHH:MM:SS. | No |
| travelItineraryId | string | Itinerary ID for the travel plan stored in the system. | Yes |
| primaryAccountNumbers | [ { **"cardAccountNumber"**: string } ] | | Yes |
#### DeleteTravelItinerary Schema
Updates an Itineray for the User
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| userId | string | User ID you assigned to identify the cardholder using the service. | No |
| partnerBid | string | Your Visa Business Identifier (BID). This field is required for OBO issuer or third part resellers. | No |
| travelItineraryId | string | Itinerary ID for the travel plan stored in the system. | Yes |
#### AddTravelItineraryResponse Schema
Itinenary from the System after Add Operations
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| failureCode | string | Error code specific for CRUD operations | No |
| responseCode | string | Web service response code | No |
| responseMessage | string | service response text specific for CRUD operations | No |
| travelItinerary | { **"source"**: string, **"userId"**: string, **"partnerBid"**: string, **"returnDate"**: string, **"destinations"**: [ { **"state"**: string, **"country"**: string } ], **"departureDate"**: string, **"lastUpdatedBy"**: string, **"lastUpdateTime"**: string, **"travelItineraryId"**: string, **"primaryAccountNumbers"**: [ { **"cardAccountNumber"**: string } ] } | An itinierary detail | No |
| failureDescription | string | Error description specific for CRUD operations | No |
#### PrimaryAccountNumbers Schema
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| PrimaryAccountNumbers | [ { **"cardAccountNumber"**: string } ] | | |
#### Destinations Schema
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| Destinations | [ { **"state"**: string, **"country"**: string } ] | | |
#### RegisterUserforTravelNotificationService Schema
Registers a VDP User for Travel Notification Service in VDP gateway
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| userId | string | VDP User/application Id | Yes |
#### DeleteTravelItineraryResponse Schema
Deleted an Itineray for the User
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| failureCode | string | Error code specific for CRUD operations | No |
| responseCode | string | Web service response code | No |
| responseMessage | string | service response text specific for CRUD operations | No |
| travelItineraryId | string | Itinerary ID for the travel plan stored in the system | No |
| failureDescription | string | Error description specific for CRUD operations | No |
#### UpdateTravelItinerary Schema
Updates an Itineray for the User
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| userId | string | User ID you assigned to identify the cardholder using the service. | No |
| partnerBid | string | Your Visa Business Identifier (BID). This field is required for OBO issuer or third part resellers. | No |
| returnDate | string | The date your cardholder will return from the trip. Must be in format YYYY-MM-DD and must not be before the Departure Date in the request or before the current date. | Yes |
| destinations | [ { **"state"**: string, **"country"**: string } ] | | Yes |
| departureDate | string | The date your cardholder will start their trip. Must be in format YYYY-MM-DD and must not be after the Return Date in the request. | Yes |
| travelItineraryId | string | Itinerary ID for the travel plan stored in the system. | Yes |
| primaryAccountNumbers | [ { **"cardAccountNumber"**: string } ] | | Yes |
#### RetrieveTravelItinerary Schema
Retrieves a list of itineray from the System for the given criteria
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| toDate | string | The end date of your search for travel itineraries. Must be in format YYYY-MM-DD and must not be before the To Date in the request. | No |
| userId | string | The User ID for which you want to retrieve travel itineraries. | No |
| fromDate | string | The start date of your search for travel itineraries. Must be in format YYYY-MM-DD and must not be after the To Date in the request or earlier than 30 days from the current date. | No |
| partnerBid | string | Your Visa Business Identifier (BID). | Yes |
| travelItineraryId | string | The ID of the travel itinerary that you want to retrieve. | No |
| primaryAccountNumber | { **"cardAccountNumber"**: string } | Card account number for which your cardholder has reported a travel plan. A maximum of 10 Primary Account Numbers can be included in a request, and all Primary Account Numbers must be associated with the Holding BID of the Partner BID in the request. | No |
#### UpdateTravelItineraryTestData Schema
List of update travel itineray request and response combination
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| UpdateTravelItineraryTestData | [ { **"updateTravelItineraryRequestResponse"**: { **"updateTravelItinerary"**: { **"userId"**: string, **"partnerBid"**: string, **"returnDate"**: string, **"destinations"**: [ { **"state"**: string, **"country"**: string } ], **"departureDate"**: string, **"travelItineraryId"**: string, **"primaryAccountNumbers"**: [ { **"cardAccountNumber"**: string } ] }, **"updateTravelItineraryResponse"**: { **"failureCode"**: string, **"responseCode"**: string, **"responseMessage"**: string, **"travelItinerary"**: { **"source"**: string, **"userId"**: string, **"partnerBid"**: string, **"returnDate"**: string, **"destinations"**: [ { **"state"**: string, **"country"**: string } ], **"departureDate"**: string, **"lastUpdatedBy"**: string, **"lastUpdateTime"**: string, **"travelItineraryId"**: string, **"primaryAccountNumbers"**: [ { **"cardAccountNumber"**: string } ] }, **"failureDescription"**: string } } } ] | List of update travel itineray request and response combination | |
#### GetTravelNotificationServiceTestDataResponse Schema
This is a list of test data for all the operations for the web services
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| userId | string | VDP User Id | No |
| failureCode | string | Error code specific for CRUD operations | No |
| responseCode | string | Web service response code | No |
| responseMessage | string | service response text specific for CRUD operations | No |
| failureDescription | string | Error description specific for CRUD operations | No |
| addTravelItineraryTestData | [ { **"addTravelItineraryRequestResponse"**: { **"addTravelItinerary"**: { **"userId"**: string, **"partnerBid"**: string, **"returnDate"**: string, **"destinations"**: [ { **"state"**: string, **"country"**: string } ], **"departureDate"**: string, **"primaryAccountNumbers"**: [ { **"cardAccountNumber"**: string } ] }, **"addTravelItineraryResponse"**: { **"failureCode"**: string, **"responseCode"**: string, **"responseMessage"**: string, **"travelItinerary"**: { **"source"**: string, **"userId"**: string, **"partnerBid"**: string, **"returnDate"**: string, **"destinations"**: [ { **"state"**: string, **"country"**: string } ], **"departureDate"**: string, **"lastUpdatedBy"**: string, **"lastUpdateTime"**: string, **"travelItineraryId"**: string, **"primaryAccountNumbers"**: [ { **"cardAccountNumber"**: string } ] }, **"failureDescription"**: string } } } ] | List of add itinerary request and response combination | No |
| deleteTravelItineraryTestData | [ { **"deleteTravelItineraryRequestResponse"**: { **"deleteTravelItinerary"**: { **"userId"**: string, **"partnerBid"**: string, **"travelItineraryId"**: string }, **"deleteTravelItineraryResponse"**: { **"failureCode"**: string, **"responseCode"**: string, **"responseMessage"**: string, **"travelItineraryId"**: string, **"failureDescription"**: string } } } ] | List of retrieve travel itineray request and response combination | No |
| updateTravelItineraryTestData | [ { **"updateTravelItineraryRequestResponse"**: { **"updateTravelItinerary"**: { **"userId"**: string, **"partnerBid"**: string, **"returnDate"**: string, **"destinations"**: [ { **"state"**: string, **"country"**: string } ], **"departureDate"**: string, **"travelItineraryId"**: string, **"primaryAccountNumbers"**: [ { **"cardAccountNumber"**: string } ] }, **"updateTravelItineraryResponse"**: { **"failureCode"**: string, **"responseCode"**: string, **"responseMessage"**: string, **"travelItinerary"**: { **"source"**: string, **"userId"**: string, **"partnerBid"**: string, **"returnDate"**: string, **"destinations"**: [ { **"state"**: string, **"country"**: string } ], **"departureDate"**: string, **"lastUpdatedBy"**: string, **"lastUpdateTime"**: string, **"travelItineraryId"**: string, **"primaryAccountNumbers"**: [ { **"cardAccountNumber"**: string } ] }, **"failureDescription"**: string } } } ] | List of update travel itineray request and response combination | No |
| retrieveTravelItineraryTestData | [ { **"retrieveTravelItineraryRequestResponse"**: { **"retrieveTravelItinerary"**: { **"toDate"**: string, **"userId"**: string, **"fromDate"**: string, **"partnerBid"**: string, **"travelItineraryId"**: string, **"primaryAccountNumber"**: { **"cardAccountNumber"**: string } }, **"retrieveTravelItineraryResponse"**: { **"failureCode"**: string, **"responseCode"**: string, **"responseMessage"**: string, **"travelItineraries"**: [ { **"source"**: string, **"userId"**: string, **"partnerBid"**: string, **"returnDate"**: string, **"destinations"**: [ { **"state"**: string, **"country"**: string } ], **"departureDate"**: string, **"lastUpdatedBy"**: string, **"lastUpdateTime"**: string, **"travelItineraryId"**: string, **"primaryAccountNumbers"**: [ { **"cardAccountNumber"**: string } ] } ], **"failureDescription"**: string } } } ] | List of retrieve travel itineray request and response combination | No |
#### RetrieveTravelItineraryResponse Schema
It is a list of itineray from the System for the criteria provided in the request
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| failureCode | string | Error code specific for CRUD operations | No |
| responseCode | string | Web service response code | No |
| responseMessage | string | service response text specific for CRUD operations | No |
| travelItineraries | [ { **"source"**: string, **"userId"**: string, **"partnerBid"**: string, **"returnDate"**: string, **"destinations"**: [ { **"state"**: string, **"country"**: string } ], **"departureDate"**: string, **"lastUpdatedBy"**: string, **"lastUpdateTime"**: string, **"travelItineraryId"**: string, **"primaryAccountNumbers"**: [ { **"cardAccountNumber"**: string } ] } ] | List of travel itineraries based on the search criteria provided | No |
| failureDescription | string | Error description specific for CRUD operations | No |
#### apiResponse Schema
Basic Travel Itinerary
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| responseCode | string,
**Available values:** "0", "5", "10", "15", "20" | Service response code
*Enum:* `"0"`, `"5"`, `"10"`, `"15"`, `"20"`
*Example:* `"0"` | Yes |
| responseMessage | string | Service response text specific for CRUD operations
*Example:* `"Successfully processed"` | Yes |
#### PrimaryAccountNumber Schema
Card account number for which your cardholder has reported a travel plan. A maximum of 10 Primary Account Numbers can be included in a request, and all Primary Account Numbers must be associated with the Holding BID of the Partner BID in the request.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| cardAccountNumber | string | Card Account Number holds the numeric PAN and PAN should always be between 16 - 19 digits | No |
#### AddTravelItineraryTestData Schema
List of add itinerary request and response combination
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| AddTravelItineraryTestData | [ { **"addTravelItineraryRequestResponse"**: { **"addTravelItinerary"**: { **"userId"**: string, **"partnerBid"**: string, **"returnDate"**: string, **"destinations"**: [ { **"state"**: string, **"country"**: string } ], **"departureDate"**: string, **"primaryAccountNumbers"**: [ { **"cardAccountNumber"**: string } ] }, **"addTravelItineraryResponse"**: { **"failureCode"**: string, **"responseCode"**: string, **"responseMessage"**: string, **"travelItinerary"**: { **"source"**: string, **"userId"**: string, **"partnerBid"**: string, **"returnDate"**: string, **"destinations"**: [ { **"state"**: string, **"country"**: string } ], **"departureDate"**: string, **"lastUpdatedBy"**: string, **"lastUpdateTime"**: string, **"travelItineraryId"**: string, **"primaryAccountNumbers"**: [ { **"cardAccountNumber"**: string } ] }, **"failureDescription"**: string } } } ] | List of add itinerary request and response combination | |
#### DeleteTravelItineraryTestData Schema
List of retrieve travel itineray request and response combination
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| DeleteTravelItineraryTestData | [ { **"deleteTravelItineraryRequestResponse"**: { **"deleteTravelItinerary"**: { **"userId"**: string, **"partnerBid"**: string, **"travelItineraryId"**: string }, **"deleteTravelItineraryResponse"**: { **"failureCode"**: string, **"responseCode"**: string, **"responseMessage"**: string, **"travelItineraryId"**: string, **"failureDescription"**: string } } } ] | List of retrieve travel itineray request and response combination | |
#### RetrieveTravelItineraryTestData Schema
List of retrieve travel itineray request and response combination
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| RetrieveTravelItineraryTestData | [ { **"retrieveTravelItineraryRequestResponse"**: { **"retrieveTravelItinerary"**: { **"toDate"**: string, **"userId"**: string, **"fromDate"**: string, **"partnerBid"**: string, **"travelItineraryId"**: string, **"primaryAccountNumber"**: { **"cardAccountNumber"**: string } }, **"retrieveTravelItineraryResponse"**: { **"failureCode"**: string, **"responseCode"**: string, **"responseMessage"**: string, **"travelItineraries"**: [ { **"source"**: string, **"userId"**: string, **"partnerBid"**: string, **"returnDate"**: string, **"destinations"**: [ { **"state"**: string, **"country"**: string } ], **"departureDate"**: string, **"lastUpdatedBy"**: string, **"lastUpdateTime"**: string, **"travelItineraryId"**: string, **"primaryAccountNumbers"**: [ { **"cardAccountNumber"**: string } ] } ], **"failureDescription"**: string } } } ] | List of retrieve travel itineray request and response combination | |
#### GetTravelNotificationServiceTestData Schema
Retrieves the set of test data for an application id in VDP gateway
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| userId | string | VDP User Id | Yes |
| partnerBid | string | The issuer BID associated with Itinerary | Yes |