개발자
세 번의 호출, 하나의 웹훅.
Gateway는 호스팅형 checkout이라 연동 범위를 의도적으로 작게 유지했습니다. 주문을 생성하고, 고객을 결제 페이지로 보내고, 서명된 결과를 검증하면 됩니다. 아래가 연동의 전부입니다. 결제 UI, 결제수단 로직, 3-D Secure, 월렛, 영수증은 저희가 구축하고 최신 상태로 관리합니다.
구조
연동 대상의 구조.
- HTTPS 기반 REST
- JSON 요청, JSON 응답
- Bearer API 키
- 멱등성 키
- 서명된 웹훅
- 리플레이 방지
- 테스트 모드와 라이브 모드
- iOS 및 Android SDK
- 스토어 플러그인
- 임베디드 필드
퀵스타트
처음부터 결제 완료까지.
정상 흐름 전체입니다. 금액은 최소 통화 단위이고, reference는 직접 지정하며, 고객은 checkout URL로 리디렉션합니다. API 기본 URL은 샌드박스 키와 함께 발급됩니다. PROTOCORE_API_BASE로 export하면 아래 호출을 그대로 실행할 수 있습니다.
주문 생성
금액, 통화, 자체 reference를 담아 한 번 호출합니다. 멱등성 키는 직접 생성하며, 같은 요청을 재시도해도 두 번째 주문이 만들어지지 않고 기존 주문이 반환됩니다.
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"
}'고객을 checkout으로 보내기
응답에는 고객사 checkout 호스트의 checkout URL이 담겨 있습니다. 샌드박스와 함께 발급된 호스트이거나, 도메인을 연결한 뒤에는 고객사 도메인입니다. 이 URL로 리디렉션하거나 SDK에서 열면 됩니다. 결제수단, 월렛, 3-D Secure는 모두 이 페이지에서 처리되므로 직접 구현할 부분이 없습니다.
{
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}서명된 결과 검증
결제가 완료되면 서명된 이벤트가 엔드포인트로 전송됩니다. 무엇이든 신뢰하기 전에 웹훅 시크릿으로 서명을 검증하고, 이미 알고 있는 reference를 기준으로 처리합니다.
{
"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" }
}
}레퍼런스
실제로 사용하게 될 엔드포인트.
문서에 더 많은 내용이 있지만, 대부분의 연동은 이 범위를 넘지 않습니다.
웹훅
백엔드가 전달받는 이벤트.
모든 이벤트에는 직접 생성한 주문 reference가 포함되므로, 핸들러는 type에 따른 분기와 자체 시스템의 조회만으로 구성할 수 있습니다.
본문을 신뢰하기 전에 서명을 확인하세요.
모든 전송에는 타임스탬프와 원본 본문에 대한 HMAC 서명이 포함됩니다. 상수 시간으로 비교하고, 허용 시간 범위를 벗어난 요청은 거부하며, 중복된 이벤트 id는 이미 처리된 것으로 간주합니다. 2xx가 아닌 응답에는 재시도하므로 핸들러도 멱등하게 작성해야 합니다.
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;
}보장 사항
안심하고 설계할 수 있는 특성.
멱등한 생성
모든 주문 생성에는 멱등성 키가 사용됩니다. 타임아웃, 배포, 큐 재전달 후 재시도하더라도 이중 청구 없이 기존 주문이 반환됩니다.
서명과 리플레이 방지가 적용된 이벤트
웹훅에는 타임스탬프 기반 HMAC 서명과 고정된 이벤트 id가 포함됩니다. 엔드포인트가 2xx로 응답할 때까지 백오프를 적용해 재전송하므로, 배포 중에도 결제가 유실되지 않습니다.
처음부터 끝까지 하나의 reference
생성 시 지정한 reference는 checkout, 영수증, 웹훅, 정산, 이후의 환불에 동일하게 나타납니다. 시스템 간에 매핑할 별도의 식별자가 없습니다.
테스트 모드도 동일한 코드 경로
테스트 키는 테스트 세션에서 동일한 플로우를 실행합니다. 테스트에서 통과한 것이 그대로 배포됩니다. 달라지는 것은 호출하는 엔드포인트가 아니라 사용하는 키입니다.
테스트 데이터
중요한 경로를 검증하는 방법.
각 경로마다 테스트 카드가 준비되어 있으며, 샌드박스 발급 시 키와 함께 안내해 드립니다. 카드 번호는 카드 브랜드의 테스트 범위가 바뀌어도 항상 정확하도록 이 페이지에 공개하지 않고 샌드박스별로 제공합니다. 어느 경우든 동작은 결정적이므로, 테스트에서 승인뿐 아니라 거절도 동일하게 검증할 수 있습니다.
키를 받고 시작하세요.
API 키, 웹훅 시크릿, 모든 결제 수단이 활성화된 샌드박스 가맹점과 전체 레퍼런스를 제공합니다. 계약 전에 팀에서 먼저 연동을 진행할 수 있습니다.