Google Wallet API

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

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

URL พื้นฐาน

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

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

การรับรองความถูกต้อง

ทุกคำขอต้องมี header 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 ดึงข้อมูลมา ไม่ใช่ไฟล์ที่อัปโหลด
สไตล์บัตร: ต้องตั้งค่า object สไตล์เพียงหนึ่งอย่าง (generic, offer, loyalty, eventTicket, giftCard, flight หรือ transit) บนบัตร ไม่สามารถเปลี่ยนสไตล์ได้หลังจากการสร้าง

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

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

Endpoints

Method	Path	Description
`POST`	`/api/google/pass/validate`	ตรวจสอบการกำหนดค่าบัตร
`POST`	`/api/google/pass/create`	สร้าง object บัตรใหม่และรับลิงก์บันทึก
`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}`	รับเทมเพลตเดียว

สร้างบัตร

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

POST /api/google/pass/create

เนื้อหาคำขอ

Parameter	Type	Required	Description
`pass`	object	Yes	object บัตร ที่อธิบายบัตร ต้องตั้งค่าสไตล์เพียงหนึ่งอย่างเท่านั้น
`userId`	string	Yes	Pushwoosh User ID ที่บัตรถูกออกให้
`applicationCode`	string	Yes	รหัสแอปพลิเคชัน 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"
    }
  }
}

การตอบกลับ

Field	Type	Description
`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

เนื้อหาคำขอ

Parameter	Type	Required	Description
`pass`	object	Yes	object บัตร ที่จะตรวจสอบ

การตอบกลับ

Field	Type	Description
`valid`	boolean	บัตรผ่านการตรวจสอบหรือไม่
`errors`	array of strings	ปัญหาที่ขัดขวางซึ่งต้องได้รับการแก้ไข
`warnings`	array of strings	คำแนะนำที่ไม่ขัดขวาง

อัปเดตบัตร

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

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

พารามิเตอร์ของ Path

Parameter	Type	Description
`serialNumber`	string	หมายเลขซีเรียลที่ส่งคืนเมื่อบัตรถูกสร้างขึ้น

เนื้อหาคำขอ

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

การตอบกลับ

Field	Type	Description
`success`	boolean	การอัปเดตสำเร็จหรือไม่
`message`	string	ข้อความผลลัพธ์

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

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

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

การตอบกลับ

Field	Type	Description
`saveLink`	string	`https://pay.google.com/gp/v/save/{jwt}`

รับบัตร

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

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

การตอบกลับ

ส่งคืน { "pass": { ... } } ซึ่งเป็น บันทึกบัตร เดียว

แสดงรายการบัตร

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

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

พารามิเตอร์ของ Query

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

การตอบกลับ

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

ตั้งค่าสถานะบัตร

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

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

เนื้อหาคำขอ

Parameter	Type	Required	Description
`active`	boolean	Yes	`true` ตั้งค่าบัตรเป็น `ACTIVE`; `false` ทำให้บัตรใช้งานไม่ได้ (`INACTIVE`)

การตอบกลับ

ส่งคืน object ว่าง {} เมื่อสำเร็จ

ลบบัตร

ทำให้บัตรใช้งานไม่ได้ใน Google และลบบันทึกที่จัดเก็บไว้ใน Pushwoosh

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

การตอบกลับ

ส่งคืน object ว่าง {} เมื่อสำเร็จ

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

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

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

การตอบกลับ

Field	Type	Description
`hasServiceAccount`	boolean	มีการกำหนดค่า service account key หรือไม่
`issuerId`	string	Issuer ID ของ Google Pay & Wallet Console ที่กำหนดค่าไว้
`serviceAccountEmail`	string	`client_email` ของ service account ที่กำหนดค่าไว้

เทมเพลต

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

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

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

การอ้างอิง Object

Object บัตร

Field	Type	Description
`serialNumber`	string	กำหนดโดยเซิร์ฟเวอร์เมื่อสร้าง; ใช้ระบุบัตร
`generic` / `offer` / `loyalty` / `eventTicket` / `giftCard` / `flight` / `transit`	object	สไตล์บัตร ต้องตั้งค่า เพียงหนึ่งอย่างเท่านั้น ดู object สไตล์ด้านล่าง
`hexBackgroundColor`	string	สีพื้นหลังของบัตร, `#rrggbb`
`logoUrl`	string	URL HTTPS สาธารณะของรูปภาพโลโก้ จำเป็นสำหรับบัตรสะสมคะแนนและบัตรเดินทาง
`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`

Object ทั่วไป

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

Object ข้อเสนอ

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

Object สะสมคะแนน

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

Object ตั๋วงานอีเวนต์

Field	Type	Description
`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`

Object บัตรของขวัญ

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

Object เที่ยวบิน

Field	Type	Description
`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` จากนั้นเป็นรหัสสายการบิน

Object การเดินทาง

Field	Type	Description
`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`

Object ช่วงการเดินทาง

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

Object บาร์โค้ด

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

Object โมดูลข้อความ

Field	Type	Description
`id`	string	ตัวระบุของโมดูล
`header`	string	หัวข้อของโมดูล
`body`	string	ข้อความของโมดูล

Object โมดูลลิงก์

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

Object ลิงก์แอป

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

Object ตำแหน่ง

Field	Type	Description
`latitude`	number	`-90.0` ถึง `+90.0`
`longitude`	number	`-180.0` ถึง `+180.0`

Object บันทึกบัตร

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

Field	Type	Description
`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	object บัตร แบบเต็ม สำหรับการแก้ไข