Protocore
Liên hệ

Dành cho nhà phát triển

Ba lệnh gọi và một webhook.

Gateway là trang checkout được lưu trữ sẵn, nên việc tích hợp được giữ ở mức tối giản: tạo đơn hàng, chuyển khách đến trang thanh toán, xác minh kết quả đã ký. Toàn bộ phạm vi chỉ có vậy — giao diện thanh toán, logic phương thức, 3-D Secure, ví và biên lai đều do chúng tôi xây dựng và cập nhật.

Yêu cầu quyền truy cập sandboxDùng thử checkout

Cấu trúc

Bạn tích hợp với những gì.

  • REST qua HTTPS
  • JSON vào, JSON ra
  • API key dạng Bearer
  • Idempotency key
  • Webhook có chữ ký
  • Chống replay
  • Chế độ test và live
  • SDK iOS & Android
  • Plugin cho cửa hàng
  • Trường nhập liệu nhúng

Bắt đầu nhanh

Từ con số không đến đơn hàng đã thanh toán.

Toàn bộ luồng thành công. Số tiền tính theo đơn vị nhỏ nhất, mã tham chiếu do bạn đặt, còn URL checkout là nơi bạn chuyển hướng khách. URL gốc của API được cấp cùng khóa sandbox — hãy export thành PROTOCORE_API_BASE và các lệnh gọi dưới đây sẽ chạy đúng như đã viết.

01

Tạo đơn hàng

Một lệnh gọi với số tiền, loại tiền tệ và mã tham chiếu của bạn. Idempotency key do bạn tự tạo — yêu cầu gửi lại sẽ trả về đơn hàng ban đầu thay vì tạo đơn thứ hai.

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

Chuyển khách đến trang checkout

Phản hồi chứa URL checkout trên checkout host của riêng bạn — host được cấp cùng sandbox, hoặc tên miền của bạn sau khi trỏ về chúng tôi. Hãy chuyển hướng đến đó, hoặc mở trong SDK; trang này chứa các phương thức thanh toán, ví và 3-D Secure, nên bạn không phải xây dựng gì thêm.

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

Xác minh kết quả đã ký

Khi thanh toán hoàn tất, một sự kiện có chữ ký được gửi đến endpoint của bạn. Hãy xác minh chữ ký bằng webhook secret trước khi tin bất kỳ dữ liệu nào, rồi xử lý đơn hàng theo mã tham chiếu bạn đã biết.

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" }
  }
}

Tham chiếu

Những endpoint bạn thực sự dùng.

Tài liệu còn nhiều hơn thế, nhưng đây là bộ mà đa số tích hợp không cần vượt quá.

POST /v1/orders
Tạo đơn hàng và nhận URL checkout. Cần có idempotency key.
GET /v1/orders/:id
Trạng thái hiện tại của đơn hàng — trạng thái, phương thức, quyết toán và hoàn tiền.
POST /v1/orders/:id/refunds
Hoàn tiền cho đơn hàng, toàn phần hoặc một phần, bắt buộc nêu lý do.
POST /v1/orders/:id/void
Hủy ủy quyền trước khi quyết toán, để không có khoản tiền nào di chuyển.
POST /v1/links
Tạo liên kết thanh toán — dùng một lần hoặc thu nhiều lần, có thể đặt thời hạn.
GET /v1/payouts/:id
Một đợt quyết toán và các đơn hàng hình thành nên nó, kèm chi tiết từng khoản phí.
POST /v1/customers/:id/cards
Lưu thẻ vào vault để thanh toán một chạm và định kỳ; trả về token tham chiếu.
POST /v1/subscriptions
Tính phí thẻ đã lưu theo lịch; mỗi chu kỳ tạo ra một đơn hàng riêng.

Webhook

Những gì backend của bạn được thông báo.

Mỗi sự kiện đều mang mã tham chiếu đơn hàng bạn đã tạo, nên handler chỉ cần rẽ nhánh theo loại sự kiện và tra cứu phía bạn.

order.paid
Ủy quyền và thu tiền thành công — xử lý đơn hàng theo mã tham chiếu.
order.failed
Thanh toán không hoàn tất, kèm lý do để vận hành viên có thể xử lý.
order.refunded
Một khoản hoàn tiền đã được thực hiện, toàn phần hoặc một phần, kèm lý do và ghi chú.
order.disputed
Một yêu cầu chargeback được mở, với bằng chứng đã đính kèm vào đơn hàng.
payout.settled
Một đợt quyết toán đã chuyển về tài khoản của bạn, kèm danh sách các đơn hàng liên quan.
subscription.charged
Một chu kỳ định kỳ đã tạo đơn hàng và biên lai riêng.
Xác minh

Kiểm tra chữ ký trước khi tin nội dung.

Mỗi lần gửi đều có timestamp và chữ ký HMAC trên raw body. Hãy so sánh trong thời gian hằng định, từ chối mọi yêu cầu cũ hơn cửa sổ dung sai của bạn, và coi event id trùng lặp là đã xử lý — chúng tôi gửi lại khi nhận phản hồi không phải 2xx, nên handler của bạn cũng cần có tính idempotent.

Node — xác minh chữ ký
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;
}

Cam kết

Những đặc tính bạn có thể dựa vào.

01

Tạo idempotent

Mọi lần tạo đơn hàng đều nhận một idempotency key. Yêu cầu gửi lại — sau timeout, sau khi deploy hoặc khi queue gửi lại — sẽ trả về đơn hàng ban đầu thay vì tính tiền hai lần.

02

Sự kiện có chữ ký, chống replay

Webhook mang chữ ký HMAC có timestamp và event id ổn định. Việc gửi được thử lại với backoff cho đến khi endpoint của bạn trả về 2xx, nên thời gian deploy không làm mất giao dịch.

03

Một mã tham chiếu, xuyên suốt

Mã tham chiếu bạn cung cấp khi tạo đơn xuất hiện trên checkout, biên lai, webhook, payout và mọi khoản hoàn tiền sau đó. Không cần ánh xạ thêm mã định danh thứ hai giữa các hệ thống.

04

Chế độ test dùng cùng luồng mã

Khóa test chạy các luồng y hệt trên phiên test. Cái gì qua được ở test thì chạy được ở live — khác biệt chỉ là khóa bạn gửi, không phải endpoint bạn gọi.

Dùng thử checkout

Dữ liệu test

Cách kiểm thử những luồng quan trọng.

Mỗi trường hợp bên dưới đều có một thẻ test đi kèm, được liệt kê cùng các khóa khi sandbox được cấp — số thẻ được cấp riêng cho từng sandbox thay vì công bố tại đây, nên luôn đúng khi dải thẻ test của scheme thay đổi. Dù vậy, hành vi luôn mang tính xác định: test có thể kiểm tra một giao dịch bị từ chối dễ dàng như một giao dịch thành công.

Duyệt ngay
Cấp phép và ghi nhận giao dịch mà không có bước xác thực 3-D Secure — luồng thành công.
Xác thực 3-D Secure
Buộc phải xác thực để bạn đi qua từng bước và kiểm thử luồng quay lại.
Từ chối mềm
Từ chối do không đủ số dư, sau đó thử lại trên một tuyến thay thế.
Từ chối cứng
Từ chối vĩnh viễn do thẻ hết hạn, không thử lại.
Mạng test USDC
USDC test-net trên Ethereum, Base và Solana, quy đổi theo tỷ giá cố định.
Mô phỏng chuyển khoản
Đánh dấu một giao dịch chuyển khoản vIBAN thử nghiệm là đã nhận để chuyển đơn hàng sang trạng thái đã thanh toán.

Lấy khóa và bắt đầu.

Một merchant sandbox với khóa API, webhook secret và mọi phương thức được bật sẵn — kèm tài liệu tham chiếu đầy đủ, để đội ngũ của bạn có thể tích hợp trước khi ký bất kỳ thỏa thuận nào.

Yêu cầu quyền truy cập sandboxcontact@protocore.io