Spanish Resident Fares (CKIN SSR)
Spain offers fare discounts for residents of the Balearic Islands, Canary Islands, and Ceuta. To be eligible for a resident discount, passengers must be either Spanish citizens, citizens of other member states of the European Union, or citizens of other States that are members of the European Economic Area who can prove that they are resident in the Balearic or Canary Islands. Residents from the Balearic or Canary Islands must be travelling between their place of residence to any other part of Spain. Residents from Ceuta must be travelling between Seville, Malaga, or Jerez to any other part of Spain.
Residents must provide:
- A Certificate of Residence or Parliamentary/Senatorial credentials
- A valid passport or national identity card
Residency is required to validate the rules of some air fares such as Government State fares (Passenger Type GST). In addition, the residency validates Check-In Information (CKIN) SSR data, which is required for Spanish Resident fares in Galileo (1G).
Notes:
- Spanish Resident fares are supported on Galileo™ (1G). These fares are also supported for Apollo™ (1V), but are unlikely to be requested, as most fare requests within Europe are routed through Galileo.
- Personal Geography is not supported for Universal Record Import, Universal Record Retrieve, Universal Record History, Saved Trips, or Passive SDK segments.
- Spanish resident child (CHR) and infant (INR) passengers, both with and without a valid ID, are supported to reduce debit memos due to improper handling of these passenger types. See Spanish resident infant remarks.Release 23.1
-
Prior to release 24.1.1, Spanish Resident CHR tickets were not saved in the Sistema de Acreditación de Residencia Automático (SARA) database when tickets were issued. Universal API Release 24.1.1 allows the attribute for CHR passenger at the time of ticketing to transmit the CHR ticket number to the SARA database. Release 24.1
Request
Personal Geography
PersonalGeography within the typePassengerType complex type is used to support location-specific fares. This complex type is used by the SearchPassenger element.
The PersonalGeography element supports discounts in Low Fare Shopping (synchronous and asynchronous), Air Pricing, Air Booking, and Universal Record (UR) Modify transactions. CountryCode, StateProvinceCode, or CityCode child elements can be used to specify required location details. These child elements are mutually exclusive; only one PersonalGeography child element can be used per BookingTraveler in a request, but at least one of these fields must be submitted per booking traveler.
Some carriers do not file Personal Geography data for Spanish Resident Discounts. For these carriers, applicable Spanish Resident fares are determined solely by the Passenger Type, such as Adult Resident (ADR). For these carriers, Personal Geography data is optional in the request, whereas it is required for carriers that do file Personal Geography data with the fare.
The following requests support the PersonalGeography element and Spanish Resident Fares:
- Low Fare Shopping (LowFareSearchReq)
- Asynchronous Low Fare Shopping (LowFareSearchAsynchReq (v49.0 and earlier))
- Air Pricing (AirPriceReq)
- Air Booking (AirCreateReservationReq)
- Universal Record Modify (UniversalRecordModifyReq/UniversalModifyCmd/AirAdd)
Booking with CKIN SSRs
In addition to the PersonalGeography values used for pricing in Low Fare Shopping and Air Pricing, a booking with Spanish Resident fares also requires a CKIN SSR that contains a text format for the residency data. This SSR is required for initial bookings that use AirCreateReservationReq and updated bookings that use UniversalRecordModifyReq. Multiple CKIN SSRs are supported within a PNR, as a single CKIN SSR is associated to each traveler (BookingTraveler).
The CKIN SSRs used for Spanish Resident Fares have two basic formats: Resident and Family, for use by extended family members traveling with the Resident passenger.
The following example shows a CKIN SSR with residency data for a Spanish Resident traveler:
< SSR Key="1" Status="HK" Carrier="IB" Type="CKIN" FreeText=" RESIDENT BPDN/12345678Z/070027/SF12.00" SegmentRef="1T" />
As of 27 February 2013, Spain will permit pre-verification of residency in the Spanish government system, Sistema de Acreditación de Residencia Automático (SARA). This pre-verification allows Resident passengers to bypass providing a Spanish resident card to the airline representative at check-in. To support pre-verification, three additional fields are added to the SSR text string. For example:
< SSR Key="1" Status="HK" Carrier="IB" Type="CKIN" FreeText=" RESIDENT BPDN/12345678Z/070027/VERIFICADO/001/B8EE5AB2197EA867E6301B42EA2B35FB/SF12.00" SegmentRef="1T" />
Pre-verified residency data is optional. After 27 February 2013, either the new pre-verified or the original unverified CKIN SSR format will be accepted.
Show tableThe following table identifies the components of the text string for a Resident CKIN SSR.
RESIDENT BPDN/12345678Z/070027/VERIFICADO/001/B8EE5AB2197EA867E6301B42EA2B35FB/SF12.00
RESIDENT identifies the Resident passenger discount. Followed by a mandatory space.
RESIDENT BPDN/12345678Z/070027/VERIFICADO/001/B8EE5AB2197EA867E6301B42EA2B35FB/SF12.00
Resident geographical area.
- BP: Residents in the Balearic Islands flying from/to this area from/to the rest of the country except for to/from this area.
- BI: Residents in the Balearic Islands flying within the archipelago.
- RC: Residents in the Canary Islands flying from/to this area from/to the rest of the country except for to/from this area.
- DC: Residents in the Canary Islands flying within the archipelago.
- RM: Residents in Melilla flying from/to Melilla to/from the rest of the country and residents in Ceuta flying from/to Malaga, Jerez de la Frontera, or Seville to/from the rest of the country.
RESIDENT BPDN/12345678Z/070027/VERIFICADO/001/B8EE5AB2197EA867E6301B42EA2B35FB/SF12.00
Document/passenger type code.
- DN: Spanish Citizens with own national ID (DNI).
- TR: EU or EFTA citizens with own passport and resident foreigner card (NIE).
- MR: Spanish minors under 14 years without own national ID (DNI).
- GR: Member of the Spanish Parliament with own national ID (DNI).
RESIDENT BPDN/12345678Z/070027/VERIFICADO/001/B8EE5AB2197EA867E6301B42EA2B35FB/SF12.00
ID number.
- Spanish national ID (DNI) number when the document/passenger type code is ‘DN’.
- Resident foreigner card (NIE) number when the document/passenger type code is ‘TR’.
For both of the ‘DN’ and ‘TR’ values, the last letter must be validated
- A date of birth (DDMMYYYY) must be inserted instead of a national ID when the document/passenger type code is ‘MR’.
- No date indicates that a person of 14 years or older must be permitted.
Known Issue: Case “MR” does not accept the mandatory date of birth of the minor but a national ID instead when inserting this data in the present NI field.
RESIDENT BPDN/12345678Z/070027/VERIFICADO/001/B8EE5AB2197EA867E6301B42EA2B35FB/SF12.00
Code for the Spanish Autonomous Community (state) that has issued the certificate for the passenger.
This code can be the Municipal Residence Code Number or the Resident Certificate Number (optional for document/passenger type codes ‘MR’ and ‘GR’). The code used must be valid for the specific issuing locale.
Known Issue: Case “MR” does not accept the mandatory date of birth of the minor but a national ID instead when inserting this data in the present NI field.
RESIDENT BPDN/12345678Z/070027/VERIFICADO/001/B8EE5AB2197EA867E6301B42EA2B35FB/SF12.00
The pre-verification status. Optional pre-verification data (valid after 27 February 2013).
- VERIFICADO indicates that the Spanish Resident passenger is in the official database of the Spanish Police under this eligibility. Under this condition, the passenger will not have to show an official resident certificate at the time of check-in and boarding at the airport.
- NO VERIFICADO indicates that the Spanish Resident passenger is not present in the database. Under this condition, the passenger must show an official resident certificate at the time of check-in and boarding at the airport.
RESIDENT BPDN/12345678Z/070027/VERIFICADO/001/B8EE5AB2197EA867E6301B42EA2B35FB/SF12.00
Numeric identifier of the verification status. Optional pre-verification data (valid after 27 February 2013).
- 001 indicates a verified (VERIFICADO) status.
- 000 indicates an unverified (NO VERIFICADO) status.
RESIDENT BPDN/12345678Z/070027/VERIFICADO/001/B8EE5AB2197EA867E6301B42EA2B35FB/SF12.00
Hash code for each response to the automated verification consultation. Optional pre-verification data (valid after 27 February 2013).
This data is optional for pre-verified travelers because some carriers do not require it for check-in purposes. Contains 32 alphanumeric characters.
RESIDENT BPDN/12345678Z/070027/VERIFICADO/001/B8EE5AB2197EA867E6301B42EA2B35FB/SF12.00
The discounted amount of service fee charged. Optional for all Spanish Resident SSRs.
No currency code is indicated (EUR is assumed).
Pre-verification data is not used for Family SSRs, as pre-verification is applied to the primary Spanish Resident passenger. The following table identifies the components of the text string for a Family CKIN SSR.
FAMILY F1DN/12345678Z/410917/123412341234
FAMILY identifies the Extended Family discount. Followed by a mandatory space.
FAMILY F1DN/12345678Z/410917/123412341234
Extended family category/discount.
- F1: General category, additional 5% discount added to the resident discount.
- F2: Special category, additional 10% discount added to the resident discount.
FAMILY F1DN/12345678Z/410917/123412341234
Document/passenger type code.
- DN: Spanish Citizens with own national ID (DNI).
- TR: EU or EFTA citizens with own passport and resident foreigner card (NIE).
- MR: Spanish minors under 14 years without own national ID (DNI).
- GR: Member of the Spanish Parliament with own national ID (DNI).
FAMILY F1DN/12345678Z/410917/123412341234
ID number.
- Spanish national ID (DNI) number when the document/passenger type code is ‘DN’.
- Resident foreigner card (NIE) number when the document/passenger type code is ‘TR’.
- For both of the ‘DN’ and ‘TR’ values, the last letter must be validated
- A date of birth (DDMMYYYY) must be inserted instead of a national ID when the document/passenger type code is ‘MR’.
- No date indicates that a person of 14 years or older must be permitted.
Known Issue: Case “MR” does not accept the mandatory date of birth of the minor but a national ID instead when inserting this data in the present NI field.
FAMILY F1DN/12345678Z/410917/123412341234
Code for the Spanish Autonomous Community (state) that has issued the official extended family certificate for the passenger.
This code can be the Municipal Residence Code Number or the Resident Certificate Number (optional for document/passenger type codes ‘MR’ and ‘GR’). The code used must be valid for the specific issuing locale.
Known Issue: Case “GR” does not accept the optional resident certificate number when inserting this data in the present NI field.
FAMILY F1DN/12345678Z/410917/123412341234
Extended family certificate number (maximum 20 characters).
Spanish resident infant remarks
Spanish resident child (CHR) and infant (INR) passengers, both with and without a valid ID, are supported to reduce debit memos due to improper handling of these passenger types. For Spanish resident infant remarks, in the request, if the date of birth is included in the <RemarkData>, it should not be populated in the DOB field. The system automatically appends the DOB in the Response based on the Remarks Data.
Note: When including the date of birth in the remarks field it must precede all other data and it must be in DDMMMYY format.
For example:
Request:
<BookingTraveler TravelerType="INR" Key="3" xmlns=http://www.travelport.com/schema/common_v51_0>
<BookingTravelerName First="TEST" Last="MARPINEZ " Prefix="INF"/>
<SSR Key="2MDAwMDAwMDAwMDAwMDAwMA==" Type="CTCE" FreeText="iremola//*****.com" Carrier="UX"/>
<SSR Key="2MDAwMDAwMDAwMDAwMDAwMQ==" Type="CTCM" FreeText="XXXXXXXXX" Carrier="UX"/>
<SSR Key="22" Type="FOID" FreeText="NI11111111h" Carrier="UX" Status="HK"/>
<NameRemark Key="3">
<RemarkData>12APR22 P-INRLPMI</RemarkData>
</NameRemark>
</BookingTraveler>
Response:
<common_v51_0:BookingTraveler Key="JffxZ0SqWDKAltQbBAAAAA==" TravelerType="INR" DOB="2022-04-12" ElStat="A">
<common_v51_0:BookingTravelerName Prefix="INF" First="TEST" Last="MARPINEZ "/>
<common_v51_0:NameRemark Key="JffxZ0SqWDKAptQbBAAAAA==" ElStat="A">
<common_v51_0:RemarkData>12APR22 P-INRLPMI</common_v51_0:RemarkData>
<common_v51_0:ProviderReservationInfoRef Key="JffxZ0SqWDKAlwQbBAAAAA=="/>
</common_v51_0:NameRemark>
</common_v51_0:BookingTraveler>
In the request if the date of birth is included in the DOB field, it should not be included in the remarks data. The system will automatically append the date of birth in the <RemarkData> in the response.
For example:
Request:
<BookingTraveler TravelerType="INR" DOB="2022-04-12 Key="3" xmlns=http://www.travelport.com/schema/common_v51_0>
<BookingTravelerName First="TEST" Last="MARPINEZ " Prefix="INF"/>
<SSR Key="2MDAwMDAwMDAwMDAwMDAwMA==" Type="CTCE" FreeText="iremola//*****.com" Carrier="UX"/>
<SSR Key="2MDAwMDAwMDAwMDAwMDAwMQ==" Type="CTCM" FreeText="XXXXXXXXX" Carrier="UX"/>
<SSR Key="22" Type="FOID" FreeText="NI11111111h" Carrier="UX" Status="HK"/>
<NameRemark Key="3">
<RemarkData>P-INRLPMI</RemarkData>
</NameRemark>
</BookingTraveler>
Response:
<common_v51_0:BookingTraveler Key="JffxZ0SqWDKAltQbBAAAAA==" TravelerType="INR" DOB="2022-04-12" ElStat="A">
<common_v51_0:BookingTravelerName Prefix="INF" First="TEST" Last="MARPINEZ "/>
<common_v51_0:NameRemark Key="JffxZ0SqWDKAptQbBAAAAA==" ElStat="A">
<common_v51_0:RemarkData>12APR22 P-INRLPMI</common_v51_0:RemarkData>
<common_v51_0:ProviderReservationInfoRef Key="JffxZ0SqWDKAlwQbBAAAAA=="/>
</common_v51_0:NameRemark>
</common_v51_0:BookingTraveler>
SARA Validation
As of Universal API Release 19.1.4 Release 19.1, and enhanced with Release 19.1.8 and 20.4.1 Release 20.4, a new framework was implemented to verify the eligibility of passengers wanting to fly using a Spanish Residency discount. This validation is done when the ticket is issued. The Spanish government has provided access to a database called SARA (Sistema de Acreditación de Residencia Automático, or Automatic Residency Accreditation System) which can validate if the passenger is eligible for that discount. If the passenger has a Resident discount, the provider must call SARA to validate the passenger. The default Boolean @ValidateSpanishResidency value is false, and if set to 'true' a SARA validation is executed.
These are the possible responses from that Validation call:
- VERIFICADO (verified) Case number: 001: this passenger's eligibility has been validated by the Spanish Police database, so he/she does not need to show his/her resident certificate at the time of check-in and/or boarding at the airport.
- The SSR CKIN will be sent to the Airline with “VERIFICADO”.
- The passenger will be able to check in and go to the gate.
- NO VERIFICADO (not verified) Case number 000: The Spanish Police database has processed the request but find the passenger no eligible.
- An SSR CKIN “NO VERIFICADO” is sent to the airline.
- The passenger will need to show his/her resident certificate at the time of check-in in order to board at the airport.
- NO VERIFICADO Case Number 003 with Hash Code:
- An SSR CKIN “NO VERIFICADO” is sent to the airline.
- The passenger will need to show their resident certificate at the time of check-in in order to board at the airport.
- NO VERIFICADO Case Number 003 PLATAFORMA NO DISPONIBLE (Platform not available).
- An SSR CKIN “NO VERIFICADO” is sent to the airline.
- The passenger will need to show his/her resident certificate at the time of check-in to board at the airport.
When 003 No Verificado, with no hashcode, is returned by Spanish Police Department, Universal API provides a configurable resend validation to re-request up to five times, or until you get valid response. Each re-request automatically voids the previous ETKT issued with case 003 if an additional permitted SARA attempt occurs.
Prior to Universal API release 24.1.3, when residency was not validated, due to a timeout or processing issue, when issuing a PNR for Spanish resident fares, a ticket was issued, but no failed validation message was being added to the booking. After 24.1.3, a ticket is still issued, and new endpoints are called to update the passenger information in the SARA database. Following the update, a response message returns, Release 24.1
<common_v53_0:ResponseMessage Code="0" Type="Info" ProviderCode="1G">SaveResidence/MR LASTNAME FIRSTNAME/007-RESIDENT DATA CORRECTLY INSERTED IN DDBB</common_v53_0:ResponseMessage>
A successful response is:
Case 000 No Verificado with HASH code
- Case 001 Verificado
All carriers, in addition to the SSR CKIN information, also require the transmission of all resident, numerous family details and the SARA validation results via the RET FILE FRCA IT/07, when the BSP reports take place. Consequently, all these details are present in the fare construction of the electronic ticket in order to properly populate and transmit.
After the ticket is issued the Web Service “Ticket” is called.
- Ticket - store the details of the issued ticket and the related validation data. That data is used to generate a nightly report to the airline and SARA.
- Void - used in two scenarios:
- Void an issued ticket.
- When it has not been possible to issue a ticket after making a call to the SARA validation service (example: credit card has no balance and the ticket has not been issued).
- In both scenarios a service call is made to let to civil aviation that there will be no ticket associated to the validation call.
Response
Personal Geography data is not included in responses. Therefore, there is no change to the Travelport Universal API responses for transactions that include Personal Geography data in the request.
Applied residency data are returned in booking and ticketing retrieve responses, so that the nationality from the applied residency type by passenger line or data can be applied in a future exchange.
/AirPricingInfo/PassengerType @ResidencyType Release 23.1
Airlines may return Fare Basis codes (FareInfo @FareBasis) in the response that indicate a geographic fare, such as a code that ends with the two characters of the Spanish geographic area of the trip. However, the format of the Fare Basis code varies by carrier.
Error and Warning Messages
While CKIN SSR data is not a new function for Travelport Universal API, new validation errors may be returned in Travelport Universal API directly from Galileo.
Note: When the error, "003 PLATAFORMA SARA NO DISPONIBLE (Platform not available)." when requesting Spanish resident fares and the residency cannot be validated against the Spanish Government residency database, SARA. However, a ticket is still issued, and new endpoints are called to update the passenger information in the SARA database. Following the update, a response message returns,
<common_v53_0:ResponseMessage Code="0" Type="Info" ProviderCode="1G">SaveResidence/MR LASTNAME FIRSTNAME/007-RESIDENT DATA CORRECTLY INSERTED IN DDBB</common_v53_0:ResponseMessage> Release 24.1
Error Text | Reason for Error | |||
---|---|---|---|---|
VERIFY PASSENGER DESCRIPTION AND DISCOUNT CODE |
|
|||
ITINERARY NOT VALID FOR REQUESTED DISCOUNT TYPE |
SSR has wrong discount code for itinerary booked. |
|||
INVALID PASSENGER DESCRIPTION |
Invalid PTC and/or geography. |
Carrier-Specific Errors
Following Release 20.4.1, Universal API adds the following logic for SARA resident fares when a ticket is issued on carrier NT (Binter Canarias): Release 20.4
-
If the validation response includes NO VERIFICADO, the SSR CKIN is appended to the booking.
-
If the validation response includes VERIFICADO, then a CKIN SSR is not appended to the booking.
Travelport can process the requests from carriers to exclude tariffs, rules, and fare classes from the Spanish Resident and Family discounts. When updates, changes, and/or deletions are necessary for carrier-specific changes to Spanish Resident fares, those requests should be sent to: ManualTableRequest@Travelport.com. The email subject line should include: ‘SDE Table Changes for Exemptions from the Spanish Resident & Family Discounts’.
Exceptions
Apollo (1V), Worldspan (1P), and Airline Content Hub (ACH) do not currently support Spanish Resident Discount functionality through Universal API. While CKIN SSRs with locale data were previously supported in Universal API, the validation functionality for Spanish resident fares is new to Universal API in release 4.1.