帳戶資訊 API

帳戶資訊 API 包含了每位旅客的詳細資料。您的範本網站會在單一登入 (SSO) 通訊協定中使用這些資訊,以驗證使用者帳戶。消費、會員計畫兌換等都會用到這個 API。

Expedia 客服專員也可以在要求取得使用者帳戶詳細資料時,使用這個 API 驗證旅客的唯一識別碼,像是信用卡號碼。在繼續為旅客處理訂單和預訂之前,客服專員會先以收到的詳細資料驗證通話的旅客身分。

如需其他資訊,請參閱通用資料和回應頁面。

信用卡加密與解密

Expedia 採用業界標準的 JWE (JSON Web 加密) 技術來加密及解密信用卡的詳細資料,也就是使用公開和私密金鑰組的非對稱式加密。

加密使用案例

下列項目應進行加密:

  • 要求:cardNumber
  • 回應:cardDetails

在要求參數中,您應設定一個 2048 位元的 CA (憑證授權中心) 簽署 RSA (Rivest Shamir Adleman) 私密金鑰憑證,並將其提供給 Expedia。接著,我們會透過 JWE 和 RSA,使用您的公開金鑰來加密 cardNumber 欄位。

在回應參數中,我們會設定一個 2048 位元的 CA 簽署 RSA 私密金鑰,並將對應的公開金鑰憑證提供給您。接著您便可透過 JWE 和 RSA,使用 Expedia 公開金鑰加密 cardDetails 的各項元素。

以下詳列加密流程的步驟。

加密逐步指引

**步驟 1:**擷取公開憑證,並取得 RSA 2048 公開金鑰。

  1. 產生隨機對稱金鑰 (RSK),長度為 256 位元。
  2. 透過演算法 RSA-OAEP-256,使用 RSA 2048 公開金鑰加密 RSK。

**步驟 2:**產生隨機的初始向量 (IV),長度為 96 位元。

**步驟 3:**使用 RSK、IV 和演算法 A256GCM 加密純文字資料,以形成加密文字及驗證標記資料。

**步驟 4:**以 Base64URL 對加密文字進行編碼,以產生 Base64URL (JWE 加密文字)。

**步驟 5:**以 Base64URL 對驗證標記、IV、RSK 及 JWE 標頭 JSON 進行編碼,以產生下列項目:

  • 驗證標記資料:Base64URL (JWE 驗證標記)。
  • IV:Base64URL (JWE 初始向量)
  • RSK:Base64URL (JWE 加密後的金鑰)
  • JWE 標頭 JSON:Base64URL (UTF8 (JWE 標頭))

接著將 JWE 物件序列化為精簡格式,其中包含的 Base64URL 編碼部分以句號 ('.') 分隔,藉此產生:

Base64URL (UTF8) (JWE 標頭) || '.' || Base64URL (JWE 加密後的金鑰) || '.' || Base64URL (JWE 初始向量) || '.' || Base64URL (JWE 加密文字) || '.' || Base64URL (JWE 驗證標記)

程式碼範例

用於加密的 Java 範例

您可以借助第三方 JWE 資料庫,有效率地快速執行 JWE 加密。舉例來說,這段用於加密的 java 程式碼便是利用 Nimbus JOSE+JWT 資料庫建立而成。

public String encryptWithJWE(String plainText){
    X509Certificate publicCertificate = <fetch public cert>
    //get RSA public key
    final X509EncodedKeySpec publicKeySpec = new 
    X509EncodedKeySpec(publicCertificate.getPublicKey().getEncoded());
    final KeyFactory keyFactory = KeyFactory.getInstance("RSA");
    RSAPublicKey rsaPublicKey = (RSAPublicKey) keyFactory.generatePublic(publicKeySpec);
    //get keyID
    String keyID = certificateManager.getKid(publicCertificate);
    // Create JWE Header containing the needed metadata for encryption and decryption
    JWEHeader jweHeader = new JWEHeader.Builder(JWEAlgorithm.RSA_OAEP_256, EncryptionMethod.A256GCM)
        .type(JOSEObjectType.JWT)
        .customParam(IAT, System.currentTimeMillis())
        .keyID(keyID)
        .build();
/*

JWE 標頭範例

{
"alg":"RSA-OAEP-256",
"typ":"JWT",
"enc":"A256GCM",
"iat":<Time (in UTC) when JWE was issued, expressed in UNIX epoch time (seconds since 1 January, 1970)>,
"kid":<Key ID or subject key Identifier from the public key certificate>
}
*/
    JWEObject jweObject = new JWEObject(jweHeader, new Payload(plainText));
    RSAEncrypter encrypter = new RSAEncrypter(rsaPublicKey);
    jweObject.encrypt(encrypter);
    return jweObject.serialize();
    }

解密要求中的卡號

Expedia 會加密要求中的 cardNumber。解密路徑則與加密路徑相反:

  1. 收到加密的 JWE 時,您應對 JWE 的第一個部分和 JOSE 標頭進行解碼,以判斷演算法、加密方式及 keyId (alg、enc、kid)。
  2. 接著請驗證 iat (issued-at:JWT 的簽發時間),確保其距目前時間未超過 5 分鐘。(標記 5 分鐘後就會過期。)
  3. 接下來,請擷取私密金鑰,並對 JWE 加密金鑰進行解密。
  4. 接下來,您可以使用解密的 RSK、JWE 初始向量及 JWE 驗證標記,對 JWE 加密文字參數進行解密並加以驗證。

程式碼範例

用於加密的 Java 範例

您可以借助第三方 JWE 資料庫,有效率地快速執行 JWE 加密。舉例來說,這段用於加密的 java 程式碼便是利用 Nimbus JOSE+JWT 資料庫建立而成。

public String decryptJWE(String jweString) {
    PrivateKey privateKey = <fetch private key>;
    RSAPrivateKey rsaPrivateKey = (RSAPrivateKey) privateKey;
    JWEObject jweObject = JWEObject.parse(jweString);
    JWEHeader jweHeader = jweObject.getHeader();validateJweHeader(jweHeader);
    RSADecrypter rsaDecrypter = new RSADecrypter(rsaPrivateKey);
    jweObject.decrypt(rsaDecrypter);
    return jweObject.getPayload().toString();
}

取得帳戶資訊

您將使用 POST /user/v1/account,透過這組欄位擷取會員或持卡人的帳戶資訊。

標頭

欄位詳情範例值欄位類型是否為必要?
partnerIdExpedia 提供的企業唯一識別碼您的品牌字串,最多 20 個字元
AuthorizationExpedia 從您授權伺服器收到的存取標記,將由您的團隊進行驗證標準 JSON Web 標記 (JWT)字串,標準 JWT 長度
Authorization2由 Expedia 傳送的 JSON Web 標記 (JWT);要在您這一端驗證的簽章和宣告標準 JWT字串,標準 JWT 長度

要求

欄位詳情欄位類型是否為必要?
requestId交易要求的唯一識別碼字串
membershipId旅客唯一識別碼字串
loyaltyAccountNumber旅客的會員帳號 (也稱為 programAccountNumber);只有在會員計畫作業需要 membershipId 以外的識別碼時,才應填入字串
programId旅客所屬會員計畫的識別碼,或與會員計畫相關聯的等級名稱字串
cardNumber旅客的信用卡號碼 (經過加密)字串
email旅客電子郵件地址字串

回應

欄位詳情欄位類型是否為必要?
status交易狀態 (值:核准、拒絕)字串
requestId交易要求 (來自要求有效負載) 的唯一識別碼字串
ProgramAccount計畫帳戶詳細資料;請參閱 ProgramAccount 資料表了解嵌入欄位  
languageId用於檢視網站的語言字串
channelType網站最佳化的目標平台 (值:WEB、MOBILE、TABLET) 

ProgramAccount

欄位詳情範例值是否為必要?
programId旅客所屬會員計畫的識別碼,或與會員計畫相關聯的等級名稱Aventura Gold
accountName計畫名稱 (如與 programId 不同)Aventura
loyaltyAccountNumber旅客的會員帳號 (也稱為 programAccountNumber);只有在會員計畫作業需要 membershipId 以外的識別碼時,才應填入1234567
lastFourDigitsOfCreditCard旅客預訂時所用信用卡的末 4 碼0000
loyaltyConversionRatio付款轉換為賺取點數的比率 (例如 $1 = 1 點) 
loyaltyAccountBalance旅客所賺取會員點數的目前餘額2003

使用者資訊

欄位詳情範例值是否為必要?
userId旅客的唯一識別碼;與 membershipId 相同 
name旅客的名字、中間名和姓氏  
firstName旅客的名字;嵌入至 name 下方Bob
middleName旅客的中間名;嵌入至 name 下方Robert
lastName旅客的姓氏;嵌入至 name 下方Jones
contactInfo旅客的聯絡資訊,包含地址、電子郵件和電話號碼 
address旅客的地址,包含街道地址、城市、州或省,以及郵遞區號;嵌入至 contactInfo 下方  
streetAddress旅客的街道地址,嵌入至 address 下方123 Main St.
city旅客街道地址所在的城市;嵌入至 address 下方波士頓
state旅客街道地址所在的州;嵌入至 address 下方MA
country旅客街道地址所在的國家/地區,嵌入至 address 下方美國
postalCode旅客街道地址的郵遞區號;嵌入至 address 下方02112
taxProvince旅客納稅的州或省;嵌入至 address 下方MA
email旅客的電子郵件地址;嵌入至 contactInfo 下方brjones@somewhere.com
contactNumber旅客的電話號碼;嵌入至 contactInfo 下方555-555-5555
userType旅客是否為單一 (主要) 使用者,或與組織相關聯 
dateOfBirth旅客的出生日期 
cardDetails交易所用信用卡的詳細資料;如填入這項資訊,則必須加密部分嵌入項目 
cardNumber *交易所用的信用卡號碼 (經過加密);嵌入至 cardDetails 下方 
cardType所用的信用卡類型 (經過加密);嵌入至 cardDetails 下方 
expirationDate *信用卡的有效期限,格式為 MM/YYYY (經過加密);嵌入至 cardDetails 下方 
billingAddress交易所用信用卡的帳單地址;嵌入至 cardDetails 下方  
firstAddressLine *帳單地址的第一行 (經過加密);嵌入至 billingAddress 下方 
secondAddressLine帳單地址的第二行;嵌入至 billingAddress 下方 
thirdAddressLine帳單地址的第三行;嵌入至 billingAddress 下方 
city帳單地址的城市元素;嵌入至 billingAddress 下方 
province帳單地址的州或省元素;嵌入至 billingAddress 下方 
countryCode帳單地址的國家/地區元素;嵌入至 billingAddress 下方 
postalCode *帳單地址的郵遞區號元素 (經過加密);嵌入至 billingAddress 下方 

注意:如填入任一 cardDetails 欄位,則必須以 * 標示該欄位。這些欄位中的所有資料均已經過加密。

API 詳細資料

不含信用卡資訊

包含信用卡資訊

這個頁面有幫助嗎?
我們能如何改善內容?
感謝您協助我們進行改善!