รายการ IP ที่อนุญาตสำหรับ Merchant API

รายการนี้เก็บ public egress IP ของเซิร์ฟเวอร์ที่เรียก API ของคุณ ไม่ใช่ IP ลูกค้า, browser, ปลายทาง webhook หรือ allowlist ของผู้ให้บริการตรวจสลิป ยังต้องใช้ API key และลายเซ็น HMAC ตามเดิม การเพิ่มกติกา IP ไม่เปลี่ยน canonical request ที่เซ็น

ค่าเริ่มต้นและ CIDR

• LIVE และ TEST มี policy ของ Merchant self แยกกัน ไม่คัดลอกรายการจาก LIVE ไป TEST และแก้โหมดหนึ่งแล้วไม่กระทบอีกโหมด
• ค่าเริ่มต้นคือ disabled, version 0, cidrs: [], updated_at: null
• enforced ต้องมี IPv4/IPv6 CIDR รูป canonical 1–32 รายการ เรียงตามสตริงและไม่ซ้ำ ส่วน disabled ต้องเป็นรายการว่าง ใช้ /32 สำหรับ IPv4 host และ /128 สำหรับ IPv6 host; IP ที่ไม่มี prefix ไม่ใช่ CIDR ที่รับได้
• ตัวอย่าง ["198.51.100.0/24", "2001:db 8::/32"] เป็นช่วงสำหรับเอกสารเท่านั้น ต้องแทนด้วย network ขาออกจริงของเซิร์ฟเวอร์คุณ
• ปฏิเสธ /0, host bits เช่น 198.51.100.1/24, IPv4 มีเลขศูนย์นำหน้า, IPv6 ตัวพิมพ์ใหญ่หรือเขียนแบบขยาย, zone และ dotted IPv6 โปรไฟล์นี้ไม่รองรับ source ใน compatible ::/96 และ mapped ::ffff/96 รวม ::/::1; CIDR ที่อยู่ทั้งช่วง ภายในสอง network นี้ใช้ไม่ได้ แต่ IPv6 canonical ที่กว้างกว่า เช่น ::/64 ยังใช้ได้

จังหวะตรวจ policy และความน่าเชื่อถือของ IP

ระบบอ่าน policy จริงตอน รับ request ใหม่เข้าใช้งาน (admission) และ consume HMAC nonce ใน transaction เดียวกันเมื่อผ่านเท่านั้น error ของ policy ทั้งสองชนิด ด้านล่างไม่ consume nonce และไม่เกิดผลทางธุรกิจ ยังคงใช้ PG-Nonce ใหม่ทุก HTTP attempt และเก็บ idempotency key เดิมสำหรับ mutation เจตนาเดิม

การแก้ policy มีผลกับ admission ถัดไป request ที่รับผ่านก่อนแก้อาจทำงานจนจบ การตั้งค่านี้ไม่ยกเลิกคำสั่งโอนที่ออกไปแล้วหรือ slip capability ที่ออกแล้ว endpoint อัปสลิปใช้ capability ของตัวเอง จึงไม่ใช้กติกา HMAC IP นี้

ต้องเป็น direct Cloudflare ingress ของ API host ที่ตรวจยืนยันแล้ว ระบบไม่ใช้ X-Forwarded-For, X-Real-IP, IP ใน JSON หรือ Cloudflare header ที่ผู้เรียกใส่มา เป็นหลักฐาน request ที่ส่งต่อจาก Cloudflare Worker อื่น หรือไม่มี ingress context ที่พิสูจน์ได้ จะไม่มี source ที่ใช้ได้ในโปรไฟล์นี้ และได้ 503 source_ip_unavailable เมื่อบังคับ policy ส่วน disabled ยังรับ context ที่ไม่มี IP ได้ อย่าเปิดบังคับใช้ กับ integration ที่มาจาก Worker โดยคาดว่าการส่งต่อ header จะยืนยัน IP ต้นทางเดิมได้

Code	HTTP	Retryable	สิ่งที่ควรทำ
source_ip_not_allowed	403	false	แก้รายการ network หรือ IP ขาออกของเซิร์ฟเวอร์
source_ip_unavailable	503	true	ตรวจ direct ingress/ความพร้อมของแพลตฟอร์ม; retry ไม่ทำให้ provenance จาก Worker ที่ไม่รองรับกลายเป็นหลักฐานที่ใช้ได้

คง error envelope ของแต่ละ route ตามเดิม LIVE unavailable มี Retry-After: 1 แต่ IP-policy error ใน TEST ไม่มี Retry-After

อ่านและแก้ policy

เป็น Back Office session บน origin เดียวกัน แยกจาก Merchant API key/HMAC ทั้งอ่าน และเขียนต้องเป็น Merchant self ในโหมดปัจจุบัน มี contract api_ip_allowlist และ capability ครบสามตัว: api_keys:read_metadata, api_keys:create, api_keys:revoke โดย WL/Agent เลือก Merchant ลูกเพื่อสวมสิทธิ์ไม่ได้ API-key metadata และ flow ของ Owner/WL คง contract เดิม

GET /v1/bo/api-ip-allowlist
X-PG-BO-Client: 1

GET ไม่มี query parameter; cookie principal ปัจจุบันเลือก scope/mode ตอบ { "data": <policy> } พร้อม ETag เป็น version ในเครื่องหมายคำพูด และ Cache-Control: private, no-store, no-transform

PUT /v1/bo/api-ip-allowlist
Content-Type: application/json
X-PG-BO-Client: 1
If-Match: "0"
Idempotency-Key: merchant-network-change-001
X-PG-Step-Up-Token: <dedicated-request-bound-assertion>

{
  "scope_id": "11110000-0000-4000-8000-000000000004",
  "state": "enforced",
  "cidrs": ["198.51.100.0/24", "2001:db 8::/32"],
  "reason_code": "API_EGRESS_UPDATE"
}

body มีสี่ field นี้เท่านั้นและไม่เกิน8192 UTF-8 bytes ต้องมี If-Match: "0" สำหรับสร้างครั้งแรก และ version ปัจจุบันสำหรับแก้ (0..2147483646) idempotency key ยาว8–200 printable non-space ASCII ตัวอักษร success ตอบ {data:{status,replayed,http_status:200,policy,request_digest}} พร้อม ETag ใหม่ แต่ละการแก้ใหม่เพิ่ม version ส่วน exact retained replay คืน receipt เดิมหลังตรวจ สิทธิ์ปัจจุบันและ proof ใหม่ โดยไม่สร้าง revision เพิ่ม

เมื่อขอ enforced server ต้องยืนยัน enrolled API host และ trusted ingress profile ก่อนตรวจ proof หรือแก้ข้อมูล หากไม่พร้อม ตอบ503 api_ip_allowlist_enforcement_unavailable โดยไม่มี mutation ส่วนการบันทึก disabled ยังทำได้แม้ ingress ไม่พร้อม แต่ต้องมีสิทธิ์, CAS และ fresh proof ตามเดิม

Fresh authentication แยก family

เริ่มที่ POST /v1/bo/auth/step-up/api-ip-allowlist proof ผูก api_ip_allowlist.replace, PUT, canonical path ตรงตัว, resource type merchant_api_ip_allowlist, UUID Merchant, expected version, mode, raw body digest, idempotency-key digest และ canonical request digest server ตรวจ session ซ้ำและ OIDC บังคับยืนยันตัวตนใหม่ภายใน5 นาที

เป็น family แยก: state pgsit1., assertion pgsia1., callback message paygate:api-ip-allowlist-step-up browser ต้องตรวจ popup และ origin ตรงตัว ใช้ API-key/approval/step-up family อื่นแทนไม่ได้ เปลี่ยน body/version/mode ต้องขอ proof ใหม่

หาก version ชน ให้อ่าน policy ล่าสุดและทบทวนก่อนสร้าง mutation ใหม่ หากผล request เดิมยังไม่แน่ชัด ให้เก็บ raw body และ idempotency identity เดิมสำหรับ retry พร้อมยืนยันตัวตนใหม่ตามที่ต้องใช้