Google Wallet API

Google Wallet API ช่วยให้คุณสามารถสร้าง อัปเดต แสดงรายการ และจัดการ Google Wallet pass ผ่านโปรแกรมได้ รองรับการทำงานเช่นเดียวกับที่ pass builder ใน Control Panel ทำ

ใช้เพื่อออกบัตรสะสมคะแนน ข้อเสนอ บัตรของขวัญ ตั๋วงานอีเวนต์ บอร์ดดิ้งพาสเที่ยวบิน ตั๋วเดินทาง และพาสทั่วไป และเพื่อพุชการอัปเดตสดไปยังพาสที่บันทึกไว้ในอุปกรณ์ของผู้ใช้ของคุณแล้ว

URL พื้นฐาน

https://apple-passkit.svc-nue.pushwoosh.com

endpoint ทั้งหมดให้บริการผ่าน HTTPS คำขอและการตอบกลับใช้ application/json เว้นแต่จะระบุไว้เป็นอย่างอื่น

การยืนยันตัวตน

ทุกคำขอต้องมีเฮดเดอร์ Authorization พร้อมกับ โทเค็นการเข้าถึง Pushwoosh API ของคุณ:

Authorization: Token <api-token>

บัญชีที่เป็นเจ้าของโทเค็นจะต้องเป็นเจ้าของแอปพลิเคชันที่อ้างอิงโดย applicationCode คำขอสำหรับแอปพลิเคชันที่เป็นของบัญชีอื่นจะส่งคืน 403 Forbidden

ข้อตกลงทั่วไป

การตั้งชื่อฟิลด์: ฟิลด์ JSON ใช้ lowerCamelCase (ตัวอย่างเช่น serialNumber, hexBackgroundColor, logoUrl)
ฟิลด์ที่ไม่มีข้อมูล: การตอบกลับจะรวมทุกฟิลด์ แม้ว่าจะว่างเปล่าหรือมีค่าเป็นศูนย์ก็ตาม
ข้อมูลระบุตัวตน: serialNumber จะถูกกำหนดโดยเซิร์ฟเวอร์เสมอเมื่อมีการสร้างพาส ค่าใดๆ ที่คุณส่งเมื่อสร้างจะถูกละเว้น object id แบบเต็มของ Google Wallet คือ {issuerId}.{serialNumber}
รูปภาพ: logoUrl และ heroImageUrl คือ URL HTTPS สาธารณะไปยังรูปภาพที่ Google ดึงข้อมูลมา—ไม่ใช่ไฟล์ที่อัปโหลด
สไตล์ของพาส: ต้องตั้งค่าอ็อบเจกต์สไตล์เพียงหนึ่งอย่าง (generic, offer, loyalty, eventTicket, giftCard, flight หรือ transit) บนพาส สไตล์ไม่สามารถเปลี่ยนแปลงได้หลังจากการสร้าง

การตอบกลับข้อผิดพลาด

สถานะ HTTP	ความหมาย
`400 Bad Request`	อาร์กิวเมนต์ไม่ถูกต้อง—ฟิลด์ที่จำเป็นขาดหายไปหรือมีรูปแบบไม่ถูกต้อง
`401 Unauthorized`	เฮดเดอร์ `Authorization` ขาดหายไปหรือไม่ถูกต้อง
`403 Forbidden`	แอปพลิเคชันไม่ได้เป็นของบัญชีของผู้เรียก
`404 Not Found`	ไม่พบพาส เทมเพลต หรือแอปพลิเคชัน
`503 Service Unavailable`	บริการเต็มความจุหรือใช้งานไม่ได้ชั่วคราว

Endpoints

เมธอด	เส้นทาง	คำอธิบาย
`POST`	`/api/google/pass/validate`	ตรวจสอบการกำหนดค่าพาส
`POST`	`/api/google/pass/create`	สร้างอ็อบเจกต์พาสใหม่และรับลิงก์บันทึก
`POST`	`/api/google/pass/update/{serialNumber}`	อัปเดตพาสที่มีอยู่ Google จะส่งการเปลี่ยนแปลง
`GET`	`/api/google/pass/{applicationCode}/{serialNumber}/save-link`	รับลิงก์บันทึก “Add to Google Wallet”
`GET`	`/api/google/pass/{applicationCode}/{serialNumber}`	รับพาสเดียว
`GET`	`/api/google/passes`	แสดงรายการพาสทั้งหมดสำหรับแอปพลิเคชัน
`POST`	`/api/google/pass/{applicationCode}/{serialNumber}/state`	เปิดใช้งานหรือทำให้พาสไม่ถูกต้อง
`DELETE`	`/api/google/pass/{applicationCode}/{serialNumber}`	ลบพาส
`GET`	`/api/google/config`	รับการกำหนดค่า Google Wallet ของแอปพลิเคชัน
`GET`	`/api/google/templates`	แสดงรายการเทมเพลตพาสที่มีอยู่
`GET`	`/api/google/templates/{filename}`	รับเทมเพลตเดียว

สร้างพาส

สร้างคลาสและอ็อบเจกต์ของพาสใน Google Wallet จากนั้นส่งคืนหมายเลขซีเรียลที่เซิร์ฟเวอร์กำหนด, object id แบบเต็ม และลิงก์บันทึก “Add to Google Wallet”

POST /api/google/pass/create

เนื้อหาคำขอ

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
`pass`	object	ใช่	อ็อบเจกต์พาส ที่อธิบายพาส ต้องตั้งค่าสไตล์เพียงหนึ่งอย่าง
`userId`	string	ใช่	Pushwoosh User ID ที่พาสถูกออกให้
`applicationCode`	string	ใช่	รหัสแอปพลิเคชัน Pushwoosh

ตัวอย่างคำขอ

{
  "applicationCode": "XXXXX-XXXXX",
  "userId": "user-123",
  "pass": {
    "hexBackgroundColor": "#3c414c",
    "logoUrl": "https://cdn.acme.com/logo.png",
    "loyalty": {
      "programName": "Acme Rewards",
      "accountName": "Jane Doe",
      "accountId": "1234567890",
      "pointsLabel": "Points",
      "pointsBalance": "1200",
      "rewardsTier": "Gold"
    },
    "barcode": {
      "format": "QR_CODE",
      "value": "1234567890"
    }
  }
}

การตอบกลับ

ฟิลด์	ประเภท	คำอธิบาย
`serialNumber`	string	ข้อมูลระบุตัวตนเฉพาะของพาสที่สร้างขึ้นซึ่งกำหนดโดยเซิร์ฟเวอร์
`objectId`	string	object id แบบเต็มของ Google Wallet: `{issuerId}.{serialNumber}`
`saveLink`	string	ลิงก์ “Add to Google Wallet”: `https://pay.google.com/gp/v/save/{jwt}`
`message`	string	ข้อความผลลัพธ์

ตัวอย่างการตอบกลับ

{
  "serialNumber": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "objectId": "XXXXXXXXXXXXXXX.XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "saveLink": "https://pay.google.com/gp/v/save/{jwt}",
  "message": "Pass created successfully"
}

ตรวจสอบพาส

ตรวจสอบการกำหนดค่าพาสเทียบกับข้อกำหนดของ Google โดยไม่ต้องสร้างพาส มีประโยชน์ก่อนที่จะเรียกใช้ create

POST /api/google/pass/validate

เนื้อหาคำขอ

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
`pass`	object	ใช่	อ็อบเจกต์พาส ที่จะตรวจสอบ

การตอบกลับ

ฟิลด์	ประเภท	คำอธิบาย
`valid`	boolean	พาสผ่านการตรวจสอบหรือไม่
`errors`	array of strings	ปัญหาที่บล็อกซึ่งต้องได้รับการแก้ไข
`warnings`	array of strings	คำแนะนำที่ไม่ใช่การบล็อก

อัปเดตพาส

แก้ไขอ็อบเจกต์พาสด้วยเนื้อหาใหม่ จากนั้น Google จะส่งเวอร์ชันที่อัปเดตไปยังทุกอุปกรณ์ที่บันทึกพาสไว้ สามารถเลือกส่งการแจ้งเตือน Android พร้อมกับการอัปเดตได้

POST /api/google/pass/update/{serialNumber}

พารามิเตอร์เส้นทาง

พารามิเตอร์	ประเภท	คำอธิบาย
`serialNumber`	string	หมายเลขซีเรียลที่ส่งคืนเมื่อพาสถูกสร้างขึ้น

เนื้อหาคำขอ

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
`updates`	object	ใช่	อ็อบเจกต์พาส ที่มีเนื้อหาใหม่ สไตล์ไม่สามารถเปลี่ยนแปลงได้
`applicationCode`	string	ใช่	รหัสแอปพลิเคชัน Pushwoosh
`notifyMessage`	string	ไม่	เมื่อไม่ว่างเปล่า ให้พุชการแจ้งเตือน Android พร้อมข้อความนี้ไปยังทุกคนที่บันทึกพาสไว้ ค่าว่างหมายถึงการอัปเดตแบบเงียบ
`notifyOnUpdate`	boolean	ไม่	ขอการแจ้งเตือนการอัปเดตฟิลด์ เฉพาะพาสประเภท `loyalty`, `eventTicket` และ `flight` เท่านั้นที่จะแจ้งเตือนจริง สไตล์อื่นๆ จะยอมรับแฟล็กแต่จะไม่ส่งการแจ้งเตือน การแจ้งเตือนจะทำงานเฉพาะภายใน 3 ชั่วโมงของเวลาเริ่มต้นที่เกี่ยวข้อง และ Google จำกัดไว้ที่ 3 การแจ้งเตือนต่อพาสต่อ 24 ชั่วโมง

การตอบกลับ

ฟิลด์	ประเภท	คำอธิบาย
`success`	boolean	การอัปเดตสำเร็จหรือไม่
`message`	string	ข้อความผลลัพธ์

รับลิงก์บันทึก

ส่งคืนลิงก์บันทึก “Add to Google Wallet” สำหรับพาสที่สร้างไว้แล้ว อ็อบเจกต์พาสต้องมีอยู่แล้ว (สร้างผ่าน สร้างพาส)

GET /api/google/pass/{applicationCode}/{serialNumber}/save-link

การตอบกลับ

ฟิลด์	ประเภท	คำอธิบาย
`saveLink`	string	`https://pay.google.com/gp/v/save/{jwt}`

รับพาส

ส่งคืนพาสที่จัดเก็บไว้เดียว รวมถึงอ็อบเจกต์พาสแบบเต็ม

GET /api/google/pass/{applicationCode}/{serialNumber}

การตอบกลับ

ส่งคืน { "pass": { ... } } ซึ่งเป็น ระเบียนพาส เดียว

แสดงรายการพาส

ส่งคืนรายการพาสที่จัดเก็บไว้สำหรับแอปพลิเคชันแบบแบ่งหน้าและจัดเรียง

GET /api/google/passes?applicationCode=XXXXX-XXXXX&page=0&perPage=20

พารามิเตอร์คิวรี

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
`applicationCode`	string	ใช่	รหัสแอปพลิเคชัน Pushwoosh
`orderBy`	string	ไม่	ฟิลด์การจัดเรียง: `UPDATED` (ค่าเริ่มต้น) หรือ `CREATED`
`orderDirection`	string	ไม่	ทิศทางการจัดเรียง: `DESC` (ค่าเริ่มต้น, ใหม่สุดก่อน) หรือ `ASC`
`page`	integer	ไม่	ดัชนีหน้าแบบศูนย์ เริ่มต้นที่ `0`
`perPage`	integer	ไม่	ขนาดหน้า `0` หรือละเว้นจะใช้ค่าเริ่มต้นของเซิร์ฟเวอร์

การตอบกลับ

ฟิลด์	ประเภท	คำอธิบาย
`passes`	array of objects	หน้าปัจจุบันของ ระเบียนพาส
`page`	integer	ดัชนีหน้าที่ส่งคืน
`perPage`	integer	ขนาดหน้าที่ใช้สำหรับการตอบกลับนี้
`total`	integer	จำนวนพาสทั้งหมดสำหรับแอปพลิเคชันในทุกหน้า

ตั้งค่าสถานะพาส

เปิดใช้งานหรือทำให้พาสไม่ถูกต้อง พาสที่ไม่ถูกต้อง (inactive) จะถูกย้ายไปยังส่วน Expired passes ของผู้ใช้ใน Google Wallet ระเบียนจะถูกเก็บไว้เพื่อให้สามารถเปิดใช้งานใหม่ได้

POST /api/google/pass/{applicationCode}/{serialNumber}/state

เนื้อหาคำขอ

พารามิเตอร์	ประเภท	จำเป็น	คำอธิบาย
`active`	boolean	ใช่	`true` ตั้งค่าพาสเป็น `ACTIVE`; `false` ทำให้ไม่ถูกต้อง (`INACTIVE`)

การตอบกลับ

ส่งคืนอ็อบเจกต์ว่าง {} เมื่อสำเร็จ

ลบพาส

ทำให้พาสใน Google ไม่ถูกต้องและลบระเบียนที่จัดเก็บไว้ใน Pushwoosh

DELETE /api/google/pass/{applicationCode}/{serialNumber}

การตอบกลับ

ส่งคืนอ็อบเจกต์ว่าง {} เมื่อสำเร็จ

รับการกำหนดค่า

ส่งคืนสถานะการกำหนดค่า Google Wallet สำหรับแอปพลิเคชัน

GET /api/google/config?applicationCode=XXXXX-XXXXX

การตอบกลับ

ฟิลด์	ประเภท	คำอธิบาย
`hasServiceAccount`	boolean	มีการกำหนดค่า service account key หรือไม่
`issuerId`	string	Issuer ID ของ Google Pay & Wallet Console ที่กำหนดค่าไว้
`serviceAccountEmail`	string	`client_email` ของ service account ที่กำหนดค่าไว้

เทมเพลต

แสดงรายการเทมเพลตพาสตัวอย่างที่มีอยู่ หรือดึงข้อมูลหนึ่งรายการเป็น อ็อบเจกต์พาส ที่คุณสามารถใช้เป็นจุดเริ่มต้นได้

GET /api/google/templates — ส่งคืน { "templates": [ { "filename", "name", "description", "style" } ] }

GET /api/google/templates/{filename} — ส่งคืน { "template": { ...pass object... } }

การอ้างอิงอ็อบเจกต์

อ็อบเจกต์พาส

ฟิลด์	ประเภท	คำอธิบาย
`serialNumber`	string	กำหนดโดยเซิร์ฟเวอร์เมื่อสร้าง ใช้ระบุพาส
`generic` / `offer` / `loyalty` / `eventTicket` / `giftCard` / `flight` / `transit`	object	สไตล์ของพาส ต้องตั้งค่า เพียงหนึ่งอย่าง ดูอ็อบเจกต์สไตล์ด้านล่าง
`hexBackgroundColor`	string	สีพื้นหลังของการ์ด `#rrggbb`
`logoUrl`	string	URL HTTPS สาธารณะของรูปภาพโลโก้ จำเป็นสำหรับ loyalty และ transit
`heroImageUrl`	string	URL HTTPS สาธารณะของรูปภาพแบนเนอร์กว้าง
`barcode`	object	บาร์โค้ด ที่แสดงบนพาส
`textModules`	array	โมดูลข้อความ ที่แสดงในมุมมองรายละเอียด
`links`	array	โมดูลลิงก์ ที่แสดงในมุมมองรายละเอียด
`expirationTime`	string	เวลา ISO 8601 ที่ Google จะทำให้พาสหมดอายุโดยอัตโนมัติ ค่าว่างหมายถึงไม่มีวันหมดอายุ
`appLink`	object	ลิงก์แอป: ปุ่ม CTA ที่ด้านหน้าของพาส
`locations`	array	ตำแหน่ง ที่ทริกเกอร์การแจ้งเตือนตามตำแหน่งทางภูมิศาสตร์ (สูงสุด 10)
`holdersPolicy`	string	ใครสามารถบันทึกพาสได้: `ONE_USER_ALL_DEVICES` (ค่าเริ่มต้น), `ONE_USER_ONE_DEVICE` หรือ `MULTIPLE_HOLDERS`

อ็อบเจกต์ Generic

ฟิลด์	ประเภท	คำอธิบาย
`cardTitle`	string	จำเป็น ชื่อผู้ออก/โปรแกรมที่ด้านบนของการ์ด
`header`	string	จำเป็น ชื่อหลักของการ์ด
`subheader`	string	ชื่อรอง
`cardFields`	array	สูงสุด 6 โมดูลข้อความ ที่ปักหมุดไว้ที่ด้านหน้า (สูงสุด 3 แถว แถวละ 2)

อ็อบเจกต์ Offer

ฟิลด์	ประเภท	คำอธิบาย
`title`	string	จำเป็น ตัวอย่างเช่น `ลด 20% ทุกอย่าง`
`provider`	string	จำเป็น ชื่อร้านค้า
`details`	string	รายละเอียดข้อเสนอ
`finePrint`	string	ข้อกำหนดและเงื่อนไข
`redemptionChannel`	string	`ONLINE`, `INSTORE`, `BOTH` (ค่าเริ่มต้น) หรือ `TEMPORARY_PRICE_REDUCTION`
`issuerName`	string	แสดงบนพื้นผิว “issued by” ของ Google ค่าเริ่มต้นคือ `provider`

อ็อบเจกต์ Loyalty

ฟิลด์	ประเภท	คำอธิบาย
`programName`	string	จำเป็น ต้องมี `logoUrl` บนพาส
`accountName`	string	ชื่อสมาชิกที่แสดงบนการ์ด
`accountId`	string	ID สมาชิกที่แสดงบนการ์ด
`pointsLabel`	string	ตัวอย่างเช่น `Points` แสดงเฉพาะเมื่อมียอดคงเหลือ
`pointsBalance`	string	ยอดคะแนนสะสม
`rewardsTier`	string	ตัวอย่างเช่น `Gold`
`rewardsTierLabel`	string	ป้ายกำกับถัดจากระดับ ค่าเริ่มต้นคือ `Tier`
`issuerName`	string	ค่าเริ่มต้นคือ `programName`

อ็อบเจกต์ Event ticket

ฟิลด์	ประเภท	คำอธิบาย
`eventName`	string	จำเป็น
`venueName` / `venueAddress`	string	รายละเอียดสถานที่จัดงาน
`startDateTime` / `endDateTime`	string	ISO 8601 พร้อม offset (ตัวอย่างเช่น `2026-07-01T19:30:00+02:00`)
`ticketHolderName` / `ticketNumber` / `ticketType`	string	รายละเอียดผู้ถือตั๋วและตั๋ว
`section` / `row` / `seat` / `gate`	string	รายละเอียดที่นั่ง
`issuerName`	string	ค่าเริ่มต้นคือ `eventName`

อ็อบเจกต์ Gift card

ฟิลด์	ประเภท	คำอธิบาย
`merchantName`	string	จำเป็น
`cardNumber`	string	จำเป็น
`pin`	string	PIN ของการ์ด
`balance`	string	จำนวนทศนิยม ตัวอย่างเช่น `25.00` ต้องมี `balanceCurrency`
`balanceCurrency`	string	รหัสสกุลเงิน ISO 4217 ตัวอย่างเช่น `USD`
`issuerName`	string	ค่าเริ่มต้นคือ `merchantName`

อ็อบเจกต์ Flight

ฟิลด์	ประเภท	คำอธิบาย
`carrierIataCode`	string	จำเป็น รหัส IATA 2 ตัวอักษร ตัวอย่างเช่น `LX`
`airlineName`	string	ชื่อที่แสดงของสายการบิน
`flightNumber`	string	จำเป็น เฉพาะตัวเลข ตัวอย่างเช่น `113`
`originAirportCode` / `destinationAirportCode`	string	จำเป็น รหัส IATA 3 ตัวอักษร
`originTerminal` / `originGate` / `destinationTerminal`	string	รายละเอียดเทอร์มินัลและประตู
`departureDateTime`	string	จำเป็น เวลา ท้องถิ่น ของสนามบินต้นทาง, ISO 8601 ไม่มี offset (ตัวอย่างเช่น `2026-09-01T06:30:00`)
`boardingTime` / `arrivalDateTime`	string	รูปแบบท้องถิ่นเดียวกัน `arrivalDateTime` คือเวลาท้องถิ่นของปลายทาง
`passengerName`	string	จำเป็น
`confirmationCode` / `seatNumber` / `seatClass` / `boardingGroup`	string	รายละเอียดผู้โดยสาร
`issuerName`	string	ค่าเริ่มต้นคือ `airlineName` จากนั้นคือรหัสสายการบิน

อ็อบเจกต์ Transit

ฟิลด์	ประเภท	คำอธิบาย
`transitType`	string	จำเป็น `BUS`, `RAIL`, `TRAM`, `FERRY` หรือ `OTHER`
`transitOperatorName`	string	จำเป็น ต้องมี `logoUrl` บนพาส
`passengerName`	string	จำเป็น
`ticketNumber`	string	หมายเลขตั๋ว
`tripType`	string	`ONE_WAY` (ค่าเริ่มต้น) หรือ `ROUND_TRIP`
`legs`	array	หนึ่งหรือมากกว่า ช่วงการเดินทาง ตามลำดับการเดินทาง
`issuerName`	string	ค่าเริ่มต้นคือ `transitOperatorName`

อ็อบเจกต์ Transit leg

ฟิลด์	ประเภท	คำอธิบาย
`originName` / `destinationName`	string	จำเป็น
`departureDateTime` / `arrivalDateTime`	string	ISO 8601; offset เป็นทางเลือก (เวลาท้องถิ่นเมื่อละเว้น)
`platform` / `coach` / `seat`	string	รายละเอียดการขึ้นยานพาหนะ
`fareName`	string	ตัวอย่างเช่น `Anytime Single`

อ็อบเจกต์ Barcode

ฟิลด์	ประเภท	คำอธิบาย
`format`	string	`QR_CODE`, `PDF_417`, `AZTEC`, `CODE_128`, `EAN_13` และประเภทบาร์โค้ดอื่นๆ ของ Google Wallet
`value`	string	ข้อมูลที่เข้ารหัสในบาร์โค้ด
`altText`	string	ข้อความที่แสดงใต้บาร์โค้ด

อ็อบเจกต์ Text module

ฟิลด์	ประเภท	คำอธิบาย
`id`	string	ตัวระบุของโมดูล
`header`	string	หัวข้อโมดูล
`body`	string	ข้อความโมดูล

อ็อบเจกต์ Link module

ฟิลด์	ประเภท	คำอธิบาย
`uri`	string	URL ลิงก์ภายนอก
`description`	string	ป้ายกำกับลิงก์ที่แสดงในมุมมองรายละเอียด

อ็อบเจกต์ App link

ฟิลด์	ประเภท	คำอธิบาย
`uri`	string	URL เว็บหรือ URI เป้าหมายของ deep-link
`androidPackageName`	string	ทางเลือก เมื่อตั้งค่า จะเปิดแอป Android
`description`	string	คำอธิบายภายในของ URI เป้าหมาย (ไม่ใช่ป้ายกำกับปุ่มที่มองเห็นได้) ค่าเริ่มต้นคือ URI

อ็อบเจกต์ Location

ฟิลด์	ประเภท	คำอธิบาย
`latitude`	number	`-90.0` ถึง `+90.0`
`longitude`	number	`-180.0` ถึง `+180.0`

อ็อบเจกต์ Pass record

ส่งคืนโดย endpoints list/get

ฟิลด์	ประเภท	คำอธิบาย
`serialNumber`	string	หมายเลขซีเรียลของพาส
`objectId`	string	object id แบบเต็มของ Google Wallet `{issuerId}.{serialNumber}`
`cardTitle`	string	ชื่อ/หัวข้อที่แสดงสำหรับพาส
`header`	string	ชื่อที่แสดงรอง
`userId`	string	Pushwoosh User ID ที่พาสถูกออกให้
`createdAt` / `updatedAt`	string	การประทับเวลาของการสร้างและการอัปเดตล่าสุด
`state`	string	`ACTIVE` หรือ `INACTIVE`
`style`	string	`generic`, `offer`, `loyalty`, `eventTicket`, `giftCard`, `flight` หรือ `transit`
`pass`	object	อ็อบเจกต์พาส แบบเต็ม สำหรับการแก้ไข