Protocore
ติดต่อเรา

นักพัฒนา

สามคำสั่งกับหนึ่ง webhook

Gateway เป็นหน้า checkout แบบโฮสต์ การเชื่อมต่อจึงเล็กโดยตั้งใจ: สร้างออเดอร์ ส่งลูกค้าไปยังหน้าชำระเงิน แล้วตรวจสอบผลลัพธ์ที่ลงลายเซ็น ทั้งหมดที่เห็นด้านล่างคือส่วนที่คุณต้องดูแล ส่วน UI การชำระเงิน ตรรกะของแต่ละวิธีชำระ 3-D Secure วอลเล็ต และใบเสร็จ เราเป็นผู้สร้างและอัปเดตให้ทันสมัยเสมอ

ขอสิทธิ์เข้าใช้ sandboxลอง checkout

ภาพรวม

สิ่งที่คุณจะเชื่อมต่อด้วย

  • REST over HTTPS
  • JSON เข้า JSON ออก
  • Bearer API key
  • Idempotency key
  • Webhook ที่ลงลายเซ็น
  • ป้องกัน replay
  • โหมดทดสอบและโหมดใช้งานจริง
  • iOS & Android SDK
  • ปลั๊กอินสำหรับร้านค้า
  • ช่องกรอกแบบฝัง

เริ่มต้นใช้งาน

จากศูนย์ถึงออเดอร์ที่ชำระแล้ว

เส้นทางหลักตั้งแต่ต้นจนจบ จำนวนเงินเป็นหน่วยย่อย (minor unit) reference เป็นของคุณ และ checkout URL คือปลายทางที่คุณ redirect ลูกค้าไป API base URL จะออกให้พร้อมคีย์ sandbox — export เป็น PROTOCORE_API_BASE แล้วรันคำสั่งด้านล่างได้ตามที่เขียนไว้ทุกบรรทัด

01

สร้างออเดอร์

เรียกครั้งเดียวพร้อมจำนวนเงิน สกุลเงิน และ reference ของคุณเอง Idempotency key คุณเป็นผู้สร้างเอง — หากส่งคำขอซ้ำ ระบบจะคืนออเดอร์เดิมแทนการสร้างใบที่สอง

POST /v1/orders
curl -X POST "$PROTOCORE_API_BASE/v1/orders" \
  -H "Authorization: Bearer $PROTOCORE_API_KEY" \
  -H "Idempotency-Key: 9F21-0716" \
  -H "Content-Type: application/json" \
  -d '{
        "amount": 4900,
        "currency": "EUR",
        "reference": "9F21-0716",
        "line_items": [
          { "name": "Brand identity sprint", "amount": 3850 },
          { "name": "Typeface licensing",   "amount": 600 },
          { "name": "Rush delivery",        "amount": 400 }
        ],
        "return_url": "https://arcstudio.ro/thanks"
      }'
02

ส่งลูกค้าไปยังหน้า checkout

ผลลัพธ์ที่ได้มี checkout URL บนโฮสต์ checkout ของคุณเอง ทั้งโฮสต์ที่ออกให้พร้อม sandbox หรือโดเมนของคุณเองเมื่อชี้มาที่เราแล้ว ให้ redirect ไปที่ URL นั้น หรือเปิดผ่าน SDK หน้านี้รวมวิธีชำระเงิน วอลเล็ต และ 3-D Secure ไว้ครบ ฝั่งคุณจึงไม่ต้องสร้างอะไรเพิ่ม

201 Created
{
  "id": "ord_2h4Kq9wRz",
  "reference": "9F21-0716",
  "amount": 4900,
  "currency": "EUR",
  "status": "pending",
  "checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}
03

ตรวจสอบผลลัพธ์ที่ลงลายเซ็น

เมื่อการชำระเงินเสร็จสมบูรณ์ อีเวนต์ที่ลงลายเซ็นจะถูกส่งมายัง endpoint ของคุณ ตรวจสอบลายเซ็นกับ webhook secret ก่อนเชื่อถือข้อมูลใดๆ แล้วจึงดำเนินการตาม reference ที่คุณมีอยู่แล้ว

POST /your/webhook — order.paid
{
  "type": "order.paid",
  "id": "evt_7Ka2Lm",
  "created": "2026-07-23T09:41:02Z",
  "data": {
    "id": "ord_2h4Kq9wRz",
    "reference": "9F21-0716",
    "amount": 4900,
    "currency": "EUR",
    "method": "usdc",
    "settlement": { "currency": "EUR", "amount": 4900, "rate": "0.9184" }
  }
}

เอกสารอ้างอิง

endpoint ที่คุณจะใช้จริง

ในเอกสารยังมีอีกมาก แต่ชุดนี้คือสิ่งที่การเชื่อมต่อส่วนใหญ่ไม่เคยต้องใช้เกินไปกว่านี้

POST /v1/orders
สร้างออเดอร์และรับ checkout URL ของออเดอร์นั้น ต้องระบุ idempotency key
GET /v1/orders/:id
สถานะปัจจุบันของออเดอร์ — สถานะ วิธีชำระ การชำระบัญชี และการคืนเงิน
POST /v1/orders/:id/refunds
คืนเงินตามออเดอร์ ทั้งจำนวนเต็มหรือบางส่วน โดยต้องระบุเหตุผล
POST /v1/orders/:id/void
ยกเลิก authorization ก่อนการชำระบัญชี จึงไม่มีเงินเคลื่อนย้ายเลย
POST /v1/links
สร้างลิงก์ชำระเงิน — แบบใช้ครั้งเดียวหรือแบบรับชำระต่อเนื่อง พร้อมกำหนดวันหมดอายุได้
GET /v1/payouts/:id
รอบการชำระบัญชีและออเดอร์ที่เป็นที่มาของยอด พร้อมรายการค่าธรรมเนียมแยกบรรทัด
POST /v1/customers/:id/cards
เก็บบัตรไว้ใน vault สำหรับการชำระแบบคลิกเดียวและการเรียกเก็บประจำ คืนค่าเป็น token reference
POST /v1/subscriptions
เรียกเก็บจากบัตรใน vault ตามกำหนดเวลา แต่ละรอบจะสร้างออเดอร์ของตัวเอง

Webhook

สิ่งที่แบ็กเอนด์ของคุณจะได้รับแจ้ง

ทุกอีเวนต์มี reference ของออเดอร์ที่คุณสร้างไว้ ตัวจัดการของคุณจึงทำได้เพียง switch ตาม type แล้วค้นหาในระบบของคุณเอง

order.paid
Authorization และ capture สำเร็จ — ดำเนินการต่อตาม reference
order.failed
การชำระเงินไม่สำเร็จ พร้อมสาเหตุที่เจ้าหน้าที่นำไปแก้ไขต่อได้
order.refunded
มีการคืนเงิน ทั้งจำนวนเต็มหรือบางส่วน พร้อมเหตุผลและหมายเหตุ
order.disputed
มีการเปิด chargeback พร้อมหลักฐานที่แนบกับออเดอร์ไว้แล้ว
payout.settled
รอบการชำระบัญชีถูกส่งเข้าบัญชีของคุณแล้ว พร้อมรายการออเดอร์ที่เป็นที่มา
subscription.charged
รอบการเรียกเก็บประจำสร้างออเดอร์และใบเสร็จของตัวเอง
ตรวจสอบ

ตรวจสอบลายเซ็นก่อนเชื่อถือเนื้อหา

ทุกการส่งมี timestamp และลายเซ็น HMAC ของ raw body ให้เปรียบเทียบแบบ constant time ปฏิเสธรายการที่เก่ากว่าช่วงเวลาที่คุณกำหนด และถือว่าอีเวนต์ที่ id ซ้ำถูกจัดการไปแล้ว — เราจะส่งซ้ำเมื่อได้รับการตอบกลับที่ไม่ใช่ 2xx ตัวจัดการของคุณจึงควรเป็น idempotent ด้วย

Node — การตรวจสอบลายเซ็น
import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(rawBody, header, secret) {
  const [ts, sig] = header.split(",").map((p) => p.split("=")[1]);
  const expected = createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(sig, "hex");
  const b = Buffer.from(expected, "hex");
  if (a.length !== b.length || !timingSafeEqual(a, b)) return false;

  // Reject replays outside a five-minute window.
  return Math.abs(Date.now() / 1000 - Number(ts)) < 300;
}

การรับประกัน

คุณสมบัติที่คุณวางใจและสร้างระบบบนนั้นได้

01

การสร้างแบบ idempotent

ทุกการสร้างออเดอร์ใช้ idempotency key หากส่งคำขอซ้ำ ไม่ว่าจะหลัง timeout, การ deploy หรือคิวส่งซ้ำ ระบบจะคืนออเดอร์เดิมแทนการเรียกเก็บเงินสองครั้ง

02

อีเวนต์ที่ลงลายเซ็นและป้องกัน replay

Webhook มีลายเซ็น HMAC พร้อม timestamp และ event id ที่คงที่ ระบบจะส่งซ้ำแบบ backoff จนกว่า endpoint ของคุณจะตอบ 2xx ช่วง deploy จึงไม่ทำให้การชำระเงินหาย

03

หนึ่ง reference ตลอดทาง

reference ที่คุณระบุตอนสร้างจะปรากฏบน checkout ใบเสร็จ webhook payout และการคืนเงินในภายหลังทุกรายการ ไม่มีรหัสอีกชุดที่ต้องจับคู่ข้ามระบบ

04

โหมดทดสอบใช้โค้ดเส้นทางเดียวกัน

คีย์ทดสอบรันโฟลว์เดียวกันทุกประการกับเซสชันทดสอบ สิ่งที่ผ่านในโหมดทดสอบคือสิ่งที่ใช้งานจริง ต่างกันที่คีย์ที่คุณส่ง ไม่ใช่ endpoint ที่คุณเรียก

ลอง checkout

ข้อมูลทดสอบ

วิธีทดสอบเส้นทางที่สำคัญ

แต่ละเส้นทางด้านล่างมีบัตรทดสอบรองรับ โดยจะแสดงไว้พร้อมคีย์ของคุณเมื่อออก sandbox ให้ — หมายเลขบัตรแยกตาม sandbox และไม่เผยแพร่ไว้ที่นี่ เพื่อให้ถูกต้องอยู่เสมอแม้ช่วงหมายเลขทดสอบของ scheme จะเปลี่ยนไป พฤติกรรมของระบบเป็นแบบกำหนดผลได้แน่นอนเสมอ: เทสต์ตรวจสอบกรณีถูกปฏิเสธได้ง่ายพอ ๆ กับกรณีสำเร็จ

อนุมัติทันที
อนุมัติและ capture โดยไม่มีการยืนยัน 3-D Secure — เส้นทางปกติที่ราบรื่น
การยืนยัน 3-D Secure
บังคับให้มีขั้นตอนยืนยันที่คุณทดลองทำตามได้ เพื่อทดสอบขากลับ (return leg)
Soft decline
ปฏิเสธเพราะยอดเงินไม่เพียงพอ แล้วลองใหม่ผ่านเส้นทางสำรอง
Hard decline
ปฏิเสธถาวรเพราะบัตรหมดอายุ และไม่มีการลองใหม่
เครือข่ายทดสอบ USDC
USDC บน test-net ของ Ethereum, Base และ Solana ในอัตราคงที่
จำลองการโอนเงิน
ทำเครื่องหมายว่าการโอนทดสอบผ่าน vIBAN มาถึงแล้ว เพื่อเปลี่ยนสถานะออเดอร์เป็นชำระแล้ว

รับคีย์แล้วเริ่มเลย

merchant ใน sandbox พร้อม API key, webhook secret และเปิดใช้ทุกวิธีชำระเงิน — พร้อมเอกสารอ้างอิงฉบับเต็ม ทีมของคุณจึงเริ่มเชื่อมต่อได้ก่อนเซ็นสัญญาใด ๆ

ขอสิทธิ์เข้าใช้ sandboxcontact@protocore.io