Card Risk Mitigation-Travel Exemptions API - Fiserv Confidential Distribution restricted to clients of Fiserv August 2021
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
Card Risk Mitigation—Travel Exemptions API Fiserv Confidential Distribution restricted to clients of Fiserv August 2021
Fiserv and the Fiserv logo are registered marks of Fiserv, Inc. Copyright © 2021 Fiserv, Inc. All rights reserved. This document contains confidential and proprietary information of Fiserv, Inc. and may not be disclosed to others than those to whom it was originally distributed. It must not be duplicated, published, or used for any other purpose than originally intended without the prior written permission of Fiserv, Inc. Information described in this document is believed to be accurate and reliable, and much care has been taken in its preparation. However, no responsibility, financial or otherwise, is accepted for any consequences arising out of the use or misuse of this material.
Contents Revisions, August 2021 5 About Travel Exemptions 6 Business Case 6 Summary of Operations 6 Authorization and Authentication 7 Using the Portal 7 Viewing OpenAPI REST Specification 7 Sandbox Test Cases 7 Target Host URLs 8 Using the Travel Exemption API 8 Data Definitions 9 searchExemptions Request 9 searchExemptions Response 10 addTravelExemption Request 11 addTravelExemption Response 13 updateTravelExemption Request 14 updateTravelExemption Response 16 expireTravelExemption Request 17 expireTravelExemption Response 18 Sandbox Use Cases 20 Sandbox Data 20 Request Header 20 Use Case 1—Retrieve Travel Exemptions 21 Use Case 2—Add Travel Exemptions 24 Use Case 3—Update Travel Exemptions 27 Use Case 4—Expire Travel Exemptions 29 Exception Scenarios 32 Request Header Errors 32 x-fapi-financial-id 32 x-fapi-interaction-id 33 Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 3
Card Risk Mitigation—Travel Exemptions API Contents Invalid Resource URL 33 Bearer Token 34 Request Body Errors 35 $client.id 35 $client.applicationName 36 $client.vendorName 37 $client.auditId 37 $cardholder.zip and middleInitial 38 $cardholder.pan 39 $cardholder.pan and name and zip 40 $travelExemptions.exemptionNumber 40 $travelExemptions.startDateTime 41 $travelExemptions.endDateTime 41 $exemptionCodes.stateCountryCodes 42 Reference 43 Error Condition Codes 43 RetrieveTravel Exemptions—Error Codes 43 Add Travel Exemptions—Error Codes 44 Update Travel Exemptions—Error Codes 45 Expire Travel Exemptions—Error Codes 47 Country and Currency Codes 48 State Codes 56 Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 4
Revisions, August 2021 Section Description All. New. Exception Scenarios Remove missing Name and zipCode scenario; remove zipCode and wrong MiddleInitial scenario; add valid Pan but invalid/missing zipCode or Name scenarios Error Codes Remove code WS101 Data Definitions and Sandbox Test Cases Update time and date to UTC Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 5
About Travel Exemptions Travel Exemptions is a rule used by the RuleManager application that exempts a card from specific rules. It enables unrestricted card activity in states or countries outside of their normal location for users during a specific period of time. Another case can exempt the card from specific rules, example: travel to specific states for large purchases. The Travel Exemptions RESTful API provides integration partners the ability to view, add, create, update, and remove travel exemptions for a specific card. The design requires a Primary Account Number (PAN), in addition to validating fields—member number, cardholder name, Zip code to enable the system to access correct card. Business Case A busy, traveling user seeks convenience. Keep your users loyal to the traveling site by providing ability to set up travel exemptions for a card before traveling. During travel, the same user can make changes, on the go, using a mobile watch or mobile phone from an online banking app. Use the Travel Exemptions API to provide the functionality for this feature. Summary of Operations The current list of operations include: HTTP API Operation Description Method POST v1/exemptions/search Retrieves a travel exemption list for the requested PAN. POST v1/exemptions Adds travel exemptions for the requested PAN. PUT v1/exemptions Updates travel exemptions for the requested PAN. PUT v1/exemptions/expire Expires the travel exemptions created by the user. Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 6
Card Risk Mitigation—Travel Exemptions API About Travel Exemptions Authorization and Authentication The APIs available on the Fiserv Card Developer portal are secured with OAuth2 security scheme . Financial Institutions (FIs) need to pass a valid bearer token to get access to the APIs. See the API for Card Developer user manual for details. Note: You can call Token API to retrieve a Bearer token. Token remains valid for 15 minutes. Using the Portal The Fiserv API Portal for Card Developers is used for onboarding users, viewing and retrieving security keys for authentication, and to view API documentation. Information for using the portal, getting started, generating access tokens, and understanding OpenAPI specifications is available in the API for Card Developer user manual. Viewing OpenAPI REST Specification The OpenAPI REST specification is available in YAML format on the Card Developers Portal. The specification describes the URL, endpoints, parameters and schema, and data definitions, required to complete call requests, expected responses, and response codes. An OpenAPI file can be opened in any swagger or text editor. Example: editor.swagger.io. 1. Go to APIs and navigate to the required product. 2. Use Swagger or Text Editor to view the OpenAPI file. Sandbox Test Cases The sample data required for working in the sandbox environment and additional examples for product use are available in this document. Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 7
Card Risk Mitigation—Travel Exemptions API About Travel Exemptions Target Host URLs Type API Operation Target URL Sandbox Search Travel v1/exemptions/search https://card- Exemptions sandbox.api.fiservapps.com/cs/travel/v1/exemptions/search Add Travel v1/exemptions https://card-sandbox.api.fiservapps.com/cs/travel/v1/exemptions Exemptions Update Travel v1/exemptions https://card-sandbox.api.fiservapps.com/cs/travel/v1/exemptions Exemptions Expire Travel v1/exemptions/expire https://card- Exemptions sandbox.api.fiservapps.com/cs/travel/v1/exemptions/expire Production Search Travel v1/exemptions/search https://card.api.fiservapps.com/cs/travel/v1/exemptions/search Exemptions Add Travel v1/exemptions https://card.api.fiservapps.com/cs/travel/v1/exemptions Exemptions Update Travel v1/exemptions https://card.api.fiservapps.com/cs/travel/v1/exemptions Exemptions Expire Travel v1/exemptions/expire https://card.api.fiservapps.com/cs/travel/v1/exemptions/expire Exemptions Using the Travel Exemption API A user can have maximum two travel plans at a time in a travel exemptions list (arrayNum 1 and arrayNum 2). • Travel exemptions are user-defined actions. A user specifies the start and end dates of travel and the countries and/or states to exempt card rules. • Travel exclusions are FI-defined actions setting permanent card restrictions in countries and states on behalf of all of its members based on internal and federal regulations. Reference the travel exclusions to ensure the user does not attempt to exempt a card in these areas. If FI-specified exclusion codes are included in a travel exemption list, an error response occurs. Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 8
Data Definitions The definitions of specific properties used for the Travel Exemptions APIs. All dates and times are shown in UTC (Universal Time Code). searchExemptions Request Data Attributes Description Type client id String Required. Fiserv assigned financial institution identifier (FIID) associated with the client. Length: 8 Example: 84014831 applicationName String Required. Name of the application calling this API. Length: 50 Example: Open Systems vendorName String Required. Client vendor identifier. Length: 30 Example: Mobiliti auditId String Required. Identifier provided by the FI to track user activities. Length: 13 Example: 84014831 cardholder pan String Required. Full card number or the primary account number (PAN). Length: 25 Example: 2222979764340017 memberNumber String Member number. Distinguishes between cardholders sharing the same card number or joint accounts. Length: 1 Example: 0 firstName String First name of the primary cardholder. Length: First & Last +1 for Middle=60 Example: SUMITRA lastName String Last name of the primary cardholder. Length: First & Last +1 for Middle=60 Example: VEER Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 9
Card Risk Mitigation—Travel Exemptions API Data Definitions Data Attributes Description Type middleInitial String Middle initial of the primary cardholder. Length: 1 Example: S zip String Card billing postal code. Length: 15 Example: 20120 searchExemptions Response Data Attributes Description Type travelExemptions Array List of existing exemptions. Repeats up to 2 times. Note: If there are no exemptions, the array displays with empty brackets [ ]. exemptionNumber Number Required. Number required to identify the travel plan within the cardholder record to be updated or expired. Each cardholder record can hold 2 travel plans; each plan can cover up to 15 states and/or countries. Length: 1 Example: 1 startDateTime String Required. Start date and time of the exemption. The value takes the format yyyy-mm-ddThh:mm:ss[.mmm]Z. Seconds of the time will always be 00. Example: 2019-11-19T14:36:00Z endDateTime String Required. End date and time of the exemption. The value takes the format yyyy-mm-ddThh:mm:ss[.mmm]Z. Seconds of the time will always be 00. Example: 2019-11-19T14:36:00Z lastUpdatedDateTime String Required. Date and time the exemption data was last modified. The value takes the format yyyy-mm-ddThh:mm:ss[.mmm]Z. Seconds of the time will always be 00. Example: 2019-11-19T14:36:00Z exemptionCodes Object List of state and country codes that are part of the exemption. Repeats up to 15 times. Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 10
Card Risk Mitigation—Travel Exemptions API Data Definitions Data Attributes Description Type stateCountryCodes Array Required. State and Country codes. See State Codes on page 56 and . Length: State code (2-alphabetical), Country code (3-alphabetical) Example: AFG exclusions Array List of states and countries not available to the users for travel exemption setting set by the FI. Repeats up to 50 times to provide up to 50 exclusions. type String Required. Provides the type of exclusion code. Values: • C=Country • S=State Length: 1 code String Required. State and country code. Length: State code (2-alphabetical), Country code (3-alphabetical) Example: AFG addTravelExemption Request Data Attributes Description Type client id String Required. Fiserv assigned financial institution identifier (FIID) associated with the client. Length: 8 Example: 84014831 applicationName String Required. Name of the application calling this API. Length: 50 Example: Open Systems vendorName String Required. Client vendor identifier. Length: 30 Example: Mobiliti auditId String Required. Identifier provided by the FI to track user activities. Length: 13 Example: 84014831 Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 11
Card Risk Mitigation—Travel Exemptions API Data Definitions Data Attributes Description Type cardholder pan String Required. Full card number or primary account number (PAN). Length: 25 Example: 2222979764340017 memberNumber String Member number. Length: 1 Example: 0 firstName String First name of the primary cardholder. Length: First & Last +1 for Middle=60 Example: SUMITRA lastName String Last name of the primary cardholder. Length: First & Last +1 for Middle=60 Example: VEER middleInitial String Middle initial of the primary cardholder. Length: 1 Example: S zip String Card billing postal code. Length: 15 Example: 20120 startDateTime String Required. Start date and time of the exemption. Date cannot be prior to current calendar date the request is being sent. This string takes the format yyyy-mm-ddThh:mm:ss[.mmm]±[hh]:[mm] or yyyy-mm- ddThh:mm:ss[.mmm]Z. Example: 2019-01-05T13:15:34Z endDateTime String Required. . End date and time of the exemption. Date cannot be prior to current calendar date the request is being sent. This string takes the format yyyy-mm-ddThh:mm:ss[.mmm]±[hh]:[mm] or yyyy-mm- ddThh:mm:ss[.mmm]Z. Example: 2019-01-05T13:15:34Z exemptionCodes Object List of state and country codes that are part of the exemption. Repeats up to 15 times. stateCountryCodes Array Required. State and Country codes. See State Codes on page 56 and . Length: State code (2-alphabetical), Country code (3-alphabetical) Example: AFG Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 12
Card Risk Mitigation—Travel Exemptions API Data Definitions addTravelExemption Response Data Attributes Description Type travelExemptions Array List of existing exemptions. Repeats up to 2 times. Note: If there are no exemptions, the array displays with empty brackets [ ]. exemptionNumber Number Required. Identifies the travel plan associated with the cardholder record to be updated or expired. Each cardholder record can hold 2 travel plans; each plan can cover up to 15 states and/or countries. Length: 1 Example: 1 startDateTime String Required. Start date and time of the exemption. The value takes the format yyyy-mm-ddThh:mm:ss[.mmm]Z. Seconds of the time will always be 00. Example: 2019-11-19T14:36:00Z endDateTime String Required. End date and time of the exemption. The value takes the format yyyy-mm-ddThh:mm:ss[.mmm]Z. Seconds of the time will always be 00. Example: 2019-11-19T14:36:00Z lastUpdatedDateTime String Required. Date and time the exemption data was last modified. The value takes the format yyyy-mm-ddThh:mm:ss[.mmm]Z. Seconds of the time will always be 00. Example: 2019-11-19T14:36:00Z exemptionCodes Object List of state and country codes that are part of the exemption. Repeats up to 15 times. stateCountryCodes Array State and Country codes. See State Codes on page 56 and . Length: State code (2-alphabetical), Country code (3-alphabetical) Example: AFG exclusions Array List of states and countries the FI does not want available to the users for travel exemption setting. Repeats up to 50 times to provide up to 50 exclusions. Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 13
Card Risk Mitigation—Travel Exemptions API Data Definitions Data Attributes Description Type type String Required. Provides the type of exclusion code. Values: • C=Country • S=State Length: 1 code String Required. State and country code Length: State code (2-alphabetical), Country code (3-alphabetical) Example: AFG updateTravelExemption Request Data Attributes Description Type client id String Required. Fiserv assigned financial institution identifier (FIID) associated with the client. Length: 8 Example: 84014831 applicationName String Required. Name of the application calling this API. Length: 50 Example: Open Systems vendorName String Required. Client vendor identifier. Length: 30 Example: Mobiliti auditId String Required. Identifier provided by the FI to track user activities. Length: 13 Example: 84014831 cardholder pan String Required. Full card number or the primary account number (PAN). Length: 25 Example: 2222979764340017 memberNumber String Member number. Distinguishes between cardholders sharing the same card number or joint accounts. Length: 1 Example: 0 Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 14
Card Risk Mitigation—Travel Exemptions API Data Definitions Data Attributes Description Type firstName String First name of the primary cardholder. Length: First & Last +1 for Middle=60 Example: SUMITRA lastName String Last name of the primary cardholder. Length: First & Last +1 for Middle=60 Example: VEER middleInitial String Middle initial of the primary cardholder. Length: 1 Example: S zip String Card billing postal code. Length: 15 Example: 20120 exemptionNumber Number Required. Identifies the travel plan associated with the cardholder record to be update or expire. Each cardholder record can hold 2 travel plans; each plan can cover up to 15 states and/or countries. Length: 1 Example: 1 startDateTime String Required. Start date and time of the exemption. Date cannot be prior to current calendar date the request is being sent. This string takes the format yyyy-mm-ddThh:mm:ss[.mmm]±[hh]:[mm] or yyyy-mm- ddThh:mm:ss[.mmm]Z. Example: 2019-11-19T14:36:00Z endDateTime String Required. End date and time of the exemption. Date cannot be prior to current calendar date the request is being sent. This string takes the format yyyy-mm-ddThh:mm:ss[.mmm]±[hh]:[mm] or yyyy-mm- ddThh:mm:ss[.mmm]Z. Example: 2019-11-19T14:36:00Z exemptionCodes Object List of state and country codes that are part of the exemption. Repeats up to 15 times. stateCountryCodes Array Required. State and Country codes. See State Codes on page 56 and . Length: State code (2-alphabetical), Country code (3-alphabetical) Example: AFG Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 15
Card Risk Mitigation—Travel Exemptions API Data Definitions updateTravelExemption Response Data Attributes Description Type travelExemptions Array List of existing exemptions. Repeats up to 2 times. Note: If there are no exemptions, the array displays with empty brackets []. exemptionNumber Number Required. Identifies the travel plan associated with the cardholder record to update or expire. Each cardholder record can hold 2 travel plans; each plan can cover up to 15 states and/or countries. Length: 1 Example: 1 startDateTime String Required. Start date and time of the exemption. The value takes the format yyyy-mm-ddThh:mm:ss[.mmm]Z. Seconds of the time will always be 00. Example: 2019-11-19T14:36:00Z endDateTime String Required. End date and time of the exemption. The value takes the format yyyy-mm-ddThh:mm:ss[.mmm]Z. Seconds of the time will always be 00. Example: 2019-11-19T14:36:00Z lastUpdatedDateTime String Required. Date and time the exemption data was last modified. The value takes the format yyyy-mm-ddThh:mm:ss[.mmm]Z. Seconds of the time will always be 00. Example: 2019-11-19T14:36:00Z exemptionCodes Object List of state and country codes that are part of the exemption. Repeats up to 15 times. stateCountryCodes Array Required. State and Country codes. See State Codes on page 56 and . Length: State code (2-alphabetical), Country code (3-alphabetical) Example: AFG Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 16
Card Risk Mitigation—Travel Exemptions API Data Definitions Data Attributes Description Type exclusions Array List of states and countries the FI does not want to be available for users for travel exemption setting. Repeats up to 50 times to provide up to 50 exclusions. type String Required. Type of exclusion code. Values: • C=Country • S=State Length: 1 code String Required. State and country code. Length: State code (2-alphabetical), Country code (3-alphabetical) Example: AFG expireTravelExemption Request Attributes Data Type Description client id String Required. Fiserv assigned financial institution identifier (FIID) associated with the client. Length: 8 Example: 84014831 applicationName String Required. Name of the application calling the API. Length: 50 Example: Open Systems vendorName String Required. Client vendor identifier. Length: 30 Example: Mobiliti auditId String Required. Identifier provided by the FI to track user activities. Length: 13 Example: 84014831 cardholder pan String Required. Full card number or the primary account number. Length: 25 Example: 2222979764340017 Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 17
Card Risk Mitigation—Travel Exemptions API Data Definitions Attributes Data Type Description memberNumber String Member number. Distinguishes between cardholders sharing the same card number or joint accounts. Length: 1 Example: 0 firstName String First name of the primary cardholder. Length: First & Last +1 for Middle=60 Example: SUMITRA lastName String Last name of the primary cardholder. Length: First & Last +1 for Middle=60 Example: VEER middleInitial String Middle initial of the primary cardholder. Length: 1 Example: S zip String Card billing postal code. Length: 15 Example: 20120 exemptionNumber Number Required. Identifies the travel plan associated with the cardholder record to update or expire. Each cardholder record can hold 2 travel plans; each plan can cover up to 15 states and/or countries. Length: 1 Values: Can only be 1 or 2. Value of 2 is only valid if there are 2 live exemptions. Example: 1 expireTravelExemption Response Data Attributes Description Type travelExemptions Array List of existing exemptions. Repeats up to 2 times. Note: If there are no exemptions, the array displays with empty brackets [ ]. exemptionNumber Number Required. Identifies the travel plan associated with the cardholder record to update or expire. Each cardholder record can hold 2 travel plans; each plan can cover up to 15 states and/or countries. Length: 1 Example: 1 Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 18
Card Risk Mitigation—Travel Exemptions API Data Definitions Data Attributes Description Type startDateTime String Required. Start date and time of the exemption. The value takes the format yyyy-mm-ddThh:mm:ss[.mmm]Z. Seconds of the time will always be 00. Example: 2019-11-19T14:36:00Z endDateTime String Required. End date and time of the exemption. The value takes the format yyyy-mm-ddThh:mm:ss[.mmm]Z. Seconds of the time will always be 00. Example: 2019-11-19T14:36:00Z lastUpdatedDateTime String Required. Date and time the exemption data was last modified. The value takes the format yyyy-mm-ddThh:mm:ss[.mmm]Z. Seconds of the time will always be 00. Example: 2019-11-19T14:36:00Z exemptionCodes Object List of state and country codes that are part of the exemption. Repeats up to 15 times. stateCountryCodes Array Required. State and Country codes. See State Codes on page 56 and . Length: State code (2-alphabetical), Country code (3-alphabetical) Example: AFG exclusions Array List of states and countries the FI does not want to make available for users for travel exemption setting. Repeats up to 50 times to provide up to 50 exclusions. type String Required. Type of exclusion code. Values: • C=Country • S=State Length: 1 code String Required. State and country code Length: State code (2- alphabetical), Country code (3-alphabetical) Example: AFG Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 19
Sandbox Use Cases The sandbox application is a static repository that includes all of the test data required to practice sending calls and become familiar with the API. Maps are created and filled in with static data so the server cannot fulfill modification requests but does return responses with matching record data. Sandbox Data Use the supplied data in the following table to make the sandbox test calls. See for further details about attributes. All data is case-sensitive. Request Header Parameter Required Data Type Description content-type Yes string Identifies the type of the payload (for POST and PUT operations) the FI is sending. It should be the same as what the server is expecting. Value: application/json Authorization Yes string Retrieves an access token through the Access Token API. Access tokens are required in every call request. Tokens expire after 15 minutes. Example: Authorization: bearer aBa0Ab00a0a=aBBa00aaB0AaAaAB00 x-fapi- Yes string Company client ID. financial-id x-fapi- No string Identifies a transaction (transaction or correlation ID) value for interaction-id tracking purposes. Optional in the request but always returned in the response. If a value is provided in the request, the same value is returned in the response. Otherwise, a Fiserv-generated ID is added to the response. Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 20
Card Risk Mitigation—Travel Exemptions API Sandbox Use Cases Use Case 1—Retrieve Travel Exemptions Use to search and retrieve a travel exemption list for the requested primary account number (PAN). A list of cardholder-configured exemptions and all FI predefined travel exclusions for its members are returned. • If the cardholder has not created a list, the return displays an empty list, designated as [ ], but the FI-defined travel exclusions is still listed, see response message. • See or State Codes on page 56 for code abbreviation references. Method: POST URL: https://card-sandbox.api.fiservapps.com/cs/travel/v1/exemptions/search This operation searches and retrieves any existing travel exemptions created by a cardholder. Two travel exemption lists are possible. To add, update or remove travel exemptions, this search request must be conducted first to understand what and if any lists exist for a cardholder. The following request example for the cardholder, with PAN 222297976430017, returns 2 exemption lists with effective start and end dates, and the FI-applied exclusion codes. Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 21
Card Risk Mitigation—Travel Exemptions API Sandbox Use Cases REQUEST 200 RESPONSE { { "client":{ "travelExemptions": [ "id":"84014831", { "applicationName":"OpenSystems", "exemptionNumber": 1, "vendorName":"Mobiliti", "startDateTime": "2019-07-20T07:00:00Z", "auditId":"Mobiliti" "endDateTime": "2020-07-31T03:59:00Z", }, "lastUpdatedDateTime": "2019-06-07T07:00:00Z", "cardholder":{ "exemptionCodes": { "pan":"2222979764340017", "stateCountryCodes": [ "memberNumber":"0", "AFG" "firstName":"SUMITRA", ] "middleInitial":"S", } "lastName": "VEER", }, "zip": "20120" { } "exemptionNumber": 2, } "startDateTime": "2019-05-03T21:14:00Z", "endDateTime": "2019-05-16T20:16:00Z", "lastUpdatedDateTime": "2019-05-16T20:16:00Z", "exemptionCodes": { "stateCountryCodes": [ "AL", "ARM", "AUS", "BIH", "BRA", "BRB", "BWA", "CA", "CT", "DE", "ID", "IL", "IOT", "GA" ] } } ], "exclusions": [ { "code": "AGO", "type": "C" }, Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 22
Card Risk Mitigation—Travel Exemptions API Sandbox Use Cases REQUEST 200 RESPONSE { "code": "DZL", "type": "C" }, { "code": "FL", "type": "S" }, { "code": "GA", "type": "S" }, { "code": "USA", "type": "C" } ] } Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 23
Card Risk Mitigation—Travel Exemptions API Sandbox Use Cases Use Case 2—Add Travel Exemptions Use to add new travel exemption data for the requested card number or create a new list. Before you begin, retrieve the Travel Exemption List that includes FI exclusions. Important! A cardholder can have a maximum of two travel plans on a specified card at any given time. If two active travel exemptions exist, an error code results in the statusCode field of the response. See Error Condition Codes on page 43. To include the new information, update an existing list, or expire an existing list to add a new list. • If FI-specified exclusion codes are included in a new list request, an error response occurs. • If a cardholder has not created a list, the return displays an empty list, designated as [ ], but the FI-defined travel exclusions is listed. • See or State Codes on page 56 for abbreviation references. Method: POST URL: https://card-sandbox.api.fiservapps.com/cs/travel/v1/exemptions This operation adds travel exemptions to an exemption list (1 or 2). Note: For now, there are some discrepancies in the Request and Response messages for this operation. The changes in progress and a revised document will be available. Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 24
Card Risk Mitigation—Travel Exemptions API Sandbox Use Cases REQUEST 200 RESPONSE { { "client":{ "travelExemptions": [ "id":"84014831", { "applicationName":"OpenSystems", "exemptionNumber":1 "vendorName":"Mobiliti", "startDateTime": "2020-07-31T02:15:00Z", "auditId":"84014831" "endDateTime": "2020-08-11T14:50:00Z", }, "lastUpdatedDateTime": "2019-11-19T18:12:00Z", "cardholder":{ "exemptionCodes": { "pan":"2222979764340017", "stateCountryCodes": [ "memberNumber": "0", "CAN" "firstName":"SUMITRA", ] "middleInitial":"S", "lastName":"VEER", } "zip":"20120" }, }, { "startDateTime":"2020-07-30T22:15:00Z", "exemptionNumber": 2, "endDateTime":"2020-08-11T10:50:00Z", "startDateTime": "2019-06-13T19:27:00Z", "exemptionCode":{ "endDateTime": "2019-06-14T19:27:00Z", "lastUpdatedDateTime": "2019-06-13T19:27:00Z", "stateCountryCodes": [ "exemptionCodes": { "CAN" "stateCountryCodes": [ ] "AL", } "ARM", } "AUS" ,"BIH" ,"BRA" ,"BRB" ,"BWA", "CA", "CT", "DE" ,"ID" ,"IL" ,"IOT", "GA" ] } } ], "exclusions": [] { "code": "AGO", "type": "C" }, Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 25
Card Risk Mitigation—Travel Exemptions API Sandbox Use Cases REQUEST 200 RESPONSE { "code": "DZL", "type": "C" }, { "code": "FL", "type": "S" }, { "code": "GA", "type": "S" }, { "code": "USA", "type": "C" } ] } Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 26
Card Risk Mitigation—Travel Exemptions API Sandbox Use Cases Use Case 3—Update Travel Exemptions You must first retrieve a travel exemption list for the requested primary account number (PAN). Using this information, you can then make any necessary updates. The following example illustrates a successful response when contacting the POST SSO URL endpoint. Method: PUT URL: https://card-sandbox.api.fiservapps.com/cs/travel/v1/exemptions Example: Correct request and the expected response. Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 27
Card Risk Mitigation—Travel Exemptions API Sandbox Use Cases REQUEST 200 RESPONSE { { "client":{ "travelExemptions": [ "id":"84014831", { "applicationName":"OpenSystem", "exemptionNumber": 1, "vendorName":"Mobiliti", "startDateTime": "2019-11-12T18:15:00Z", "auditId":"84014831" "endDateTime": "2019-12-15T18:15:00Z", }, "lastUpdatedDateTime": "2019-11- "cardholder":{ 19T18:12:00Z", "pan":"2222979764340017", "exemptionCodes": { "memberNumber": "0", "stateCountryCodes": [ "firstName":"SUMITRA", "CAN" "middleInitial":"", ] "lastName":"VEER", } "zip":"20120" } }, ], "exemptionNumber":"1", "exclusions": [ "startDateTime":"2019-11-12T13:15:30Z", "endDateTime":"2019-12-15T13:15:30Z", { "exemptionCodes":{ "code": "AGO", "stateCountryCodes":[ "type": "C" "CAN" }, ] { } "code": "DZL", } "type": "C" }, { "code": "FL", "type": "S" }, { "code": "GA", "type": "S" }, { "code": "USA", "type": "C" } ] } } Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 28
Card Risk Mitigation—Travel Exemptions API Sandbox Use Cases Use Case 4—Expire Travel Exemptions Use to expire a travel exemptions plan for the requested PAN. Before you begin, retrieve the specified card Travel Exemption List including FI exclusions. Important! A cardholder can have a maximum of two travel plans on a specified card at any given time. If two lists already exist, an error code results in the statusCode field of the response. See Error Condition Codes on page 43. To include the new information, an update request can be made to an existing list, or an existing list must first be expired so the new list can be added. • If FI-specified exclusion codes are included in a new list request, an error response occurs. • If a cardholder has not created a list, the return displays an empty list, designated as [ ], but the FI-defined travel exclusions is listed. • See or State Codes on page 56 for abbreviation references. Method: PUT URL: https://card-sandbox.api.fiservapps.com/cs/travel/v1/exemptions/expire This operation expires existing travel exemptions in an exemption list (1 or 2). The process requires a search and retrieve request first to understand the lists available for a cardholder. Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 29
Card Risk Mitigation—Travel Exemptions API Sandbox Use Cases REQUEST 200 RESPONSE { { "client":{ "travelExemptions": [ "id":"84014831", { "applicationName":"OpenSystems", "exemptionNumber": 1, "vendorName":"Mobiliti", "startDateTime": "2019-11-19T18:12:00Z", "auditId":"Mobiliti" "endDateTime": "2019-11-19T18:12:00Z", }, "lastUpdatedDateTime": "2019-11-19T18:12:00Z", "cardholder":{ "exemptionCode": { "pan":"2222979764340017", "stateCountryCodes": [ "memberNumber": "0", "AFG" "firstName":"SUMITRA", ] "middleInitial":"S", } "lastName":"VEER", }, "zip":"20120" { }, "exemptionNumber": 2, "exemptionNumber":"1" } "startDateTime": "2019-05-03T21:14:00Z", "endDateTime": "2019-05-03T21:14:00Z", "lastUpdatedDateTime": "2019-05-03T21:14:00Z", "exemptionCodes": { "stateCountryCodes": [ "AL", "ARM", "AUS", "BIH", "BRA", "BRB", "BWA", "CA", "CT", "DE", "ID", "IL", "IOT", "GA" ] } } ], "exclusions": [ { "code": "AGO", "type": "C" }, Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 30
Card Risk Mitigation—Travel Exemptions API Sandbox Use Cases REQUEST 200 RESPONSE { "code": "DZL", "type": "C" }, { "code": "FL", "type": "S" }, { "code": "GA", "type": "S" }, { "code": "USA", "type": "C" } ] } } Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 31
Exception Scenarios Error responses can occur if the API call request is not formatted correctly or contains incorrect values. The server returns HTTP response codes with errors if the parameters or schema attributes do not meet Fiserv requirements. Some errors are further defined with status codes. Request Header Errors The following examples are situations that can occur if parameters are incorrect in the request header. x-fapi-financial-id The x-fapi-financial-id is a required parameter in the request header of each REST API call. An error can result if a value is not provided, exceeds 8 digits, or includes letters and symbols. HTTP Response Error Scenario Response Example Solution Code Missing header x- 400 Bad Request { x-fapi-financial id is fapi-financial-id "errors": [ missing from the { request header. "code": 400, Add the x-fapi- "description": "missing header x-fapi- financial-id to the financial-id" request header. Enter the Company } client ID. ] } Header x-fapi- 400 Bad Request { Recheck the value. financial-id greater "errors": [ than 8 digits { "code": 400, "description": "invalid x-fapi-financial- id" } ] } Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 32
Card Risk Mitigation—Travel Exemptions API Exception Scenarios HTTP Response Error Scenario Response Example Solution Code Header x-fapi- 400 Bad Request { Recheck the value. financial-id "errors": [ alphanumeric { "code": 400, "description": "invalid x-fapi-financial- id" } ] } x-fapi-interaction-id HTTP Response Error Scenario Response Example Solution Code x-fapi-interaction id 400 Bad Request { Recheck the value. less than "errors": [ 15 characters { "code": 400, "description": "invalid x-fapi- interaction-id" } ] } Invalid Resource URL Error Scenario HTTP Response Solution Code Incorrect URL. 404 Not Found Resource file names must match exactly. Extra values, as in the following example are not allowed: Invalid Resource URL: https://card- sandbox.api.fiservapps.com/cs/travel/v1/exemptions/search123 Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 33
Card Risk Mitigation—Travel Exemptions API Exception Scenarios Bearer Token Fiserv uses bearer tokens as an access key in the request header for authenticating an API REST call. The token must be generated separately from the Access Token API. See the API for Card Developers user manual for details. If the token is missing, incorrect or expired, the server returns an error. HTTP Response Error Scenario Response Example Solution Code Invalid acces token 401 Unauthorized { Bearer token entered "errors": [ is not correctly { formatted or value is misspelled. "code": 401, "description": "Invalid Access Token" Generate a new token from the } Access Token API, ] add the new value, } and resend. Expired access 401 Unauthorized { Generate a new token "errors": [ token from the { Access Token API, add the new value, "code": 401, and resend. "description": "Access token expired" } ] } Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 34
Card Risk Mitigation—Travel Exemptions API Exception Scenarios Request Body Errors The following responses are examples of situations that occur if parameters or attributes within a schema are incorrect in the request body of an API call. $client.id Fiserv-assigned client company ID is a required parameter for a request call. The following examples are server responses if the clientID is missing or incorrect. HTTP Response Error Scenario Response Example Solution Code Missing client Id 400 Bad Request { Client Id is missing "errors": [ from the request { body. Add and resend. "code": "WS999", "description": "Sorry, but our systems are currently experiencing technical difficulties. Please try your request again at a later time." } ] } Incorrect client Id 400 Bad Request { Client Id entered in "errors": [ request body is { incorrect. Check for a correct value, enter "code": "WS100", in the request body, "description": "Information entered is and resend. invalid-please revise and try again." } ] } Wrong client Id with 400 Bad Request { Client Id entered in 8 digits "errors": [ request body is { incorrect. Check for a correct value, enter "code": "WS201", in the request body, "description": "Card record not found." and resend. } ] } Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 35
Card Risk Mitigation—Travel Exemptions API Exception Scenarios $client.applicationName HTTP Response Error Scenario Response Example Solution Code Missing client 400 Bad Request { Client application application name "errors": [ name is missing { from the request body. "code": "100" "description": "Error Validating FiAPIRequest." } ] } Client application 400 Bad Request { Check the client name with "errors": [ application name and special character { resend. "code": "WS100", "description": "Information entered is invalid-please revise and try again." } ] } Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 36
Card Risk Mitigation—Travel Exemptions API Exception Scenarios $client.vendorName HTTP Response Error Scenario Response Example Solution Code Missing Vendor 400 Bad Request { Client vendor name Name "errors": [ is missing from the { request body. "code": "100" "description": "Error Validating FiAPIRequest." } ] } Special Character in 400 Bad Request { Check the vendor Vendor Name "errors": [ name and resend. { "code": "100" "description": "Error Validating FiAPIRequest." } ] } $client.auditId HTTP Response Error Scenario Response Example Solution Code Missing client Audit 400 Bad Request { Client Audit Id is Id "errors": [ missing from the { request body. Add and resend. "code": "100", "description": " Error Validating FiAPIRequest." } ] } Special character in 400 Bad Request { Correct the audit client Audit Id "errors": [ ID value and resend. { "code": "WS100", "description": "Information entered is invalid-please revise and try again." } ] } Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 37
Card Risk Mitigation—Travel Exemptions API Exception Scenarios $cardholder.zip and middleInitial Error Scenario HTTP Response Response Example Solution Code With missing 400 Bad Request { Enter the correct zipCode and wrong "errors": [ values and resend. MiddleInitial { "code": "WS102", "description": "Card record not found." } ] } Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 38
Card Risk Mitigation—Travel Exemptions API Exception Scenarios $cardholder.pan Error Scenario HTTP Response Code Response Example Solution Missing PAN number 400 Bad Request { Enter the value "errors": [ and send the { request again. "code": "WS104", "description": "Card record not found." } ] } Wrong PAN number 400 Bad Request { Enter the "errors": [ correct value { and resend. "code": "WS201", "description": "Card record not found." } ] } Inactive PAN number 400 Bad Request { Enter the "errors": [ correct value { and resend. "code": "W208", "description": "Card status validation failed." } ] } Buisness Rule Validation 400 Bad Request { Enter the Failed "errors": [ correct value { and resend. "code": "W207", "description": "Business rules validation failed." } ] } Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 39
Card Risk Mitigation—Travel Exemptions API Exception Scenarios $cardholder.pan and name and zip Error Scenario HTTP Response Response Example Solution Code With valid PAN and 400 Bad Request { Enter the correct invalid zipCode and "errors": [ values and resend. missing cardholder { Name "code": "WS103", "description": "Card record not found." } ] } With valid PAN and 400 Bad Request { Enter the correct invalid cardholder "errors": [ values and resend. Name and missing { zipCode "code": "WS102", "description": "Card record not found." } ] } $travelExemptions.exemptionNumber Error Scenario HTTP Response Code Response Example Solution Missing Exemptions or 400 Bad Request { Enter the Exemptions number other "errors": [ value and than 1 and 2 { resend. "code": "WS106", "description": "Travel Exemption not found." } ] } Update an expired 400 Bad Request { Enter the exemption number "errors": [ correct { value and resend. "code": "WS107", "description": "Expired Exemption cannot be updated." } ] } Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 40
Card Risk Mitigation—Travel Exemptions API Exception Scenarios $travelExemptions.startDateTime Error Scenario HTTP Response Code Response Example Solution Missing start date 400 Bad Request { Enter the "errors": [ value and { resend. "code": "WS202", "description": "Invalid Start date." } ] } Start Date greater than 400 Bad Request { Enter the End date. "errors": [ value and { resend. "code": "WS203", "description": "Invalid End date." } ] } $travelExemptions.endDateTime Error Scenario HTTP Response Code Response Example Solution Missing end date 400 Bad Request { Enter the "errors": [ value and { resend. "code": "WS203", "description": "Invalid End date." } ] } Invalid end date 400 Bad Request { Enter the "errors": [ correct { value and resend. "code": "WS203", "description": "Invalid End date." } ] } Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 41
Card Risk Mitigation—Travel Exemptions API Exception Scenarios $exemptionCodes.stateCountryCodes Error Scenario HTTP Response Code Response Example Solution Missing country code 400 Bad Request { Enter the "errors": [ value and { resend. "code": "WS204", "description": "State/Country code validation failed." } ] } Invalid country code 400 Bad Request { Enter the "errors": [ value and { resend. "code": "WS204", "description": "State/Country code validation failed." } ] } Exclusion State code is 400 Bad Request { Enter the used to update Travel "errors": [ value and Exemptions { resend. "code": "WS204", "description": "State/Country code validation failed." } ] } Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 42
Reference Error Condition Codes Error Condition codes are received in the Standard Status, csStatus. RetrieveTravel Exemptions—Error Codes Error Condition Error Message Code WS102 Cardholder name validation failed Card record not found. WS103 Zip Code validation failed Card record not found. WS104 PAN validation failed Card record not found. WS105 memberNum validation failed Card record not found. WS201 PAN Lookup failed Card record not found. WS207 Business rules validation failed. Minimum criteria Business rules validation failed. for System, permissions and Risk systems participation not met. WS208 Card status does not allow Travel Card status validation failed. Exemption requests. WS210 Invalid character found; especially for String {0} cannot contain an invalid character. formatted fields. {0} = Field Name Values: • Cardholder First Name • a-z •* • Cardholder Last Name • A-Z •& • Cardholder Middle Initial • 0-9 •@ • Zip Code • . (period) •( • StateCountryCode • . (comma) •) •$ •# WS999 Unrecoverable system error Sorry, but our systems are currently experiencing technical difficulties. Please try your request again at a later time. Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 43
Card Risk Mitigation—Travel Exemptions API Reference Add Travel Exemptions—Error Codes Error Condition Error Message Code WS102 Cardholder name validation failed Card record not found. WS103 Zip Code validation failed Card record not found. WS104 PAN validation failed Card record not found. WS105 memberNum validation failed Card record not found. WS106 If there are two Travel Exemptions in the DAF and Only two Travel Exemptions can be in place both are active or in the future (or a combination of at any given time. active and future) WS201 PAN Lookup failed Card record not found. WS202 Start Date validation failed Invalid Start date. WS203 End Date validation failed Invalid End date. WS204 State/Country Code validation failed. State/Country code validation failed. Note: If a country value is provided incorrectly in a 2- character format and there is a state that matches this value; this error condition will not be sent and a state exemption will be created. WS205 Exclusion list validation failed Location validation failed. WS207 Business rules validation failed. Minimum criteria for Business rules validation failed. System, permissions and Risk systems participation not met. WS208 Card status does not allow Travel Card status validation failed. Exemption requests. WS210 Invalid character found; especially for String {0} cannot contain an invalid character. formatted fields. {0} = Field Name Values: • Cardholder First Name • Cardholder Last Name • a-z • ,(comma) •@ • Cardholder Middle Initial • A-Z •$ •( • Zip Code • 0-9 •* •) • StateCountryCode • . (period) •& •# WS999 Unrecoverable system error Sorry, but our systems are currently experiencing technical difficulties. Please try your request again at a later time. Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 44
Card Risk Mitigation—Travel Exemptions API Reference Update Travel Exemptions—Error Codes Error Condition Error Message Code WS102 Cardholder name validation failed Card record not found. WS103 Zip Code validation failed Card record not found. WS104 PAN validation failed Card record not found. WS105 memberNum validation failed Card record not found. WS106 If the Travel Exemption occurrence (arrayNum) is Travel Exemptions not found. not 1 or 2 WS107 Exemption exists at provided arrayNum but that Expired Exemption cannot is not active(i.e. endDTM is in past). be updated. WS201 PAN Lookup failed Card record not found. WS202 Start Date validation failed Invalid Start date. WS203 End Date validation failed Invalid End date. WS204 State/Country Code validation failed State/Country code validation failed. Note: If a country value is provided incorrectly in a 2-character format and there is a state that matches this value; this error condition will not be sent and a state exemption will be created. WS205 Exclusion list validation failed Location validation failed. WS206 If there is not an existing Travel Exemption for the Travel Exemption not found. occurrence (arrayNum) passed WS207 Business rules validation failed. Minimum criteria Business rules validation failed. for System, permissions and Risk systems participation not met. WS208 Card status does not allow Travel Card status validation failed. Exemption requests. WS210 Invalid character found; especially for String {0} cannot contain an invalid character. formatted fields. {0} = Field Name Values: • Cardholder First Name • a-z • . (comma) •@ • Cardholder Last Name • A-Z •$ •( • Cardholder Middle Initial • 0-9 •* •) • Zip Code • . (period) •& •# • StateCountryCode Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 45
Card Risk Mitigation—Travel Exemptions API Reference Error Condition Error Message Code WS999 Unrecoverable system error Sorry, but our systems are currently experiencing technical difficulties. Please try your request again at a later time. Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 46
Card Risk Mitigation—Travel Exemptions API Reference Expire Travel Exemptions—Error Codes Error Condition Error Message Code WS102 Cardholder name validation failed Card record not found. WS103 Zip Code validation failed Card record not found. WS104 PAN validation failed Card record not found. WS105 memberNum validation failed Card record not found. WS106 If the Travel Exemption occurrence (arrayNum) is not 1 Travel Exemptions not found. or 2 WS201 PAN Lookup failed Card record not found. WS202 Start Date validation failed Invalid Start date. WS203 End Date validation failed Invalid End date. WS204 State/Country Code validation failed State/Country code validation failed. Note: If a country value is provided incorrectly in a 2- character format and there is a state that matches this value; this error condition will not be sent and a state exemption will be created. WS205 Exclusion list validation failed Location validation failed. WS206 If there is not an active or future travel exemption for Travel Exemptions not found the occurrence (arrayNum) passed (meaning it is either non-existent or expired) WS207 Business rules validation failed. Minimum criteria for Business rules validation failed. System, permissions and Risk systems participation not met. WS208 Card status does not allow Travel Exemption requests. Card status validation failed. WS210 Invalid character found; especially for String formatted {0} cannot contain an invalid character. fields. {0} = Field Name Values: • Cardholder First Name • a-z • . (comma) •@ • Cardholder Last Name • A-Z •$ •( • Cardholder Middle Initial • 0-9 •* •) • Zip Code • . (period) •& •# • StateCountryCode WS999 Unrecoverable system error Sorry, but our systems are currently experiencing technical difficulties. Please try your request again at a later time. Fiserv Confidential August 2021 Distribution restricted to clients of Fiserv 47
You can also read