API 레퍼런스

아래의 모든 엔드포인트는 JSON으로 통신하며, https://api.infraio.xyz(프로덕션) 또는 https://api-dev.infraio.xyz(테스트) 아래에 존재하고, HMAC-SHA256으로 인증합니다 — 서명 절차는 인증을, 오류 envelope 형식은 오류를 참조하세요.

이 페이지는 인덱스입니다. 각 행은 가장 깊은 기존 작성 문서에 연결됩니다. 행이 경로만 참조하는 경우, 해당 엔드포인트는 현재 존재하지만 자체 레퍼런스 페이지가 아닌 관련 개념 페이지에 인라인으로 문서화되어 있습니다.

게이트웨이 경로 프리픽스와 인증 모델:

/b2b/v1/* — 시크릿 키(sk_…)로 HMAC 서명. 가맹점 백엔드 표면.
/payment/v1/* — Bearer JWT(대시보드 세션). 가맹점 대시보드 프론트엔드에서 사용되며, 서드파티 연동자용이 아닙니다.
/pub/v1/* — 경로 내 진실의 베어러(환불 요청을 위한 rfqt_… 토큰). 자격증명 없음. 브라우저에서 호출하기에 안전합니다.
/checkout/:key/* — 호스팅 체크아웃 흐름을 위한 공개 프리픽스. key는 생성 시 반환된 cst_… 세션 키이며, 구매자 브라우저만 호출자입니다. 자격증명 없음.

체크아웃

메서드	경로	용도	비고
`POST`	`/b2b/v1/checkout-sessions/quick`	한 번의 호출로 세션 생성 — 주문 + 체크아웃 세션을 함께 발급.	요청 본문과 샘플은 빠른 시작을 참조하세요.
`POST`	`/b2b/v1/checkout-sessions`	기존 주문에 대해 세션 생성. 플랫폼에 자체 주문 모델이 있고 시도당 하나의 세션을 원할 때 사용.	2단계 흐름.
`GET`	`/b2b/v1/checkout-sessions/by-order/{order_id}`	한 주문에 대해 발급된 모든 세션 목록.	구매자가 세션을 포기했고 대시보드에 이전 시도를 표시하고 싶을 때 유용합니다.
`GET`	`/checkout/{session_key}`	공개 — 호스팅 체크아웃 페이지가 가져옵니다. 구매자 영역 필드만 포함(내부 참조 없음).	서명 없음. 진실의 베어러로 `session_key`를 사용합니다.
`POST`	`/checkout/{session_key}/intent`	공개 — 호스팅 페이지에서 결제 방법 선택. 입금 주소가 있는 `PaymentIntent`를 발생시킵니다.	사용자 메서드 선택 시 checkout-web이 호출합니다.
`POST`	`/checkout/{session_key}/verify`	공개 — 구매자가 tx 해시를 붙여넣어 확인 대기를 단락시킬 수 있게 합니다.	해시가 잘못된 경우 체인 워처로 폴스루됩니다.

주문

주문은 시간을 초월하는 청구 가능한 엔티티입니다. 하나의 주문이 여러 체크아웃 세션을 지원할 수 있습니다(예: 구매자 포기, 재시도).

메서드	경로	용도	비고
`POST`	`/b2b/v1/orders`	세션 없이 주문 생성.	즉시 리디렉션하는 대신 나중에 구매자에게 결제 링크를 보내려는 경우 사용합니다.
`GET`	`/b2b/v1/orders/{id}`	라인 아이템 + 상태가 포함된 단일 주문 읽기.	상태: `PENDING` → `PAID` \| `PARTIAL_PAID` \| `CANCELED`. 환불 후: `PARTIALLY_REFUNDED` \| `REFUNDED`.
`GET`	`/b2b/v1/orders/by-merchant/{merchant_id}`	가맹점의 주문 목록. 커서 페이지네이션.	커서 프로토콜은 커서 페이지네이션을 참조하세요.
`PATCH`	`/b2b/v1/orders/{id}/cancel`	미결제 주문을 취소로 표시. `order.canceled`를 발생시킵니다.	주문이 이미 결제된 경우 실패합니다.
`PATCH`	`/b2b/v1/orders/{id}/reopen`	자동 취소(`canceled_reason=payment_timeout`)를 되돌립니다.	TTL 만료 후 구매자가 돌아오는 경우 유용합니다.

환불

saga 흐름과 토큰 라이프사이클은 환불 개념 페이지를 참조하세요.

가맹점 시작

메서드	경로	용도	비고
`POST`	`/b2b/v1/merchants/{merchant_id}/refunds`	가맹점 시작 환불. 자동 승인(`PENDING` 건너뜀).	`payment.refund.approved`를 즉시 발생시킵니다.

고객 시작 — 환불 요청 토큰

구매자는 저희 호스팅 페이지에서 환불 양식을 작성합니다. 가맹점은 토큰을 발급하고 URL을 전달하기만 하면 됩니다. 두 가지 발급 경로(백엔드용 HMAC, 대시보드용 JWT), 세 가지 공개 토큰 경로(컨텍스트 읽기, 제출, 갱신 요청), 그리고 갱신 처리를 위한 두 가지 대시보드 전용 경로가 있습니다.

메서드	경로	인증	용도
`POST`	`/b2b/v1/merchants/{merchant_id}/refund-requests`	HMAC (`sk_…`)	백엔드에서 토큰 발급. 본문: `{ref_type, ref_value, amount, ttl_seconds?, metadata?, hide_summary?, hide_header?}`. `ref_type`은 `order_id` / `order_number` / `session_id` / `session_key` 중 하나. `ref_value`는 매칭되는 식별자. `amount`는 필수이며 구매자가 제출할 수 있는 최대값을 잠급니다. 기본 TTL 30분. `refund_request.created`(`source: b2b`)를 발생시킵니다.
`POST`	`/payment/v1/merchants/{merchant_id}/refund-requests`	JWT (대시보드)	가맹점 대시보드의 Issue Refund 모달에서 토큰 발급. B2B 변형과 동일한 본문 형식. 기본 TTL 24시간. `refund_request.created`(`source: dashboard`)를 발생시킵니다.
`GET`	`/pub/v1/refund-requests/{token}`	경로 내 토큰	공개 — checkout-web이 양식 컨텍스트(주문 요약, 잠긴 금액, 현재 유효 상태)를 읽습니다.
`POST`	`/pub/v1/refund-requests/{token}/submit`	경로 내 토큰	공개 — 구매자가 양식 제출. 본문: `{reason, refund_to_address, amount?, metadata?}`. `amount`는 선택 — 생략되면 가맹점이 잠근 링크 금액이 사용되고, 존재하면 서버가 `amount ≤ 잠긴 금액`을 강제합니다. `Refund` 행을 생성하고, `payment.refund.requested`를 발생시키며, 영수증 페이지를 위한 `{link_token, refund_id}`를 반환합니다.
`POST`	`/pub/v1/refund-requests/{token}/request-renewal`	경로 내 토큰	공개 — 만료 후 구매자가 새 링크를 요청. 본문: `{customer_note?}`. `refund_request.renewal_requested`를 발생시킵니다.
`GET`	`/payment/v1/merchants/{merchant_id}/refund-requests/renewals`	JWT (대시보드)	가맹점의 갱신 위젯을 위한 대기 중 `RENEWAL_REQUESTED` 토큰 목록. 커서 페이지네이션.
`POST`	`/payment/v1/merchants/{merchant_id}/refund-requests/renewals/{token}/issue-new`	JWT (대시보드)	갱신 승인 — 새 `ACTIVE` 토큰을 발급하고 이전 토큰을 폐기. `refund_request.renewed` + `refund_request.created`(`source: renewal`)를 발생시킵니다.
`GET`	`/payment/v1/merchants/{merchant_id}/refund-requests/by-order/{order_id}`	JWT (대시보드)	한 주문에 대해 발급된 모든 환불 요청 토큰을 유효 상태와 함께 목록화. 최신순.
`POST`	`/payment/v1/merchants/{merchant_id}/refund-requests/{token}/send-email`	JWT (대시보드)	고객에게 환불 요청 링크 이메일 전달 큐잉. 본문: `{to}`. `refund_request.email_send_requested`를 발생시킵니다.
`POST`	`/payment/v1/merchants/{merchant_id}/refund-requests/{token}/cancel`	JWT (대시보드)	가맹점 킬 스위치 — `ACTIVE` 또는 `RENEWAL_REQUESTED`를 `CANCELED`로 전환. 본문: `{reason?}`. 멱등성: 상태가 이미 이동한 후 두 번째 호출은 재발생 없이 성공을 반환합니다. 첫 번째 전이 시 `refund_request.canceled`를 발생시킵니다.

환불 라이프사이클 (생성 후)

두 흐름 모두에 적용됩니다. 아래 엔드포인트는 요청 토큰이 아닌 Refund 행 (id가 rfn_…로 시작)에 작동합니다.

메서드	경로	용도	비고
`GET`	`/b2b/v1/refunds/{id}`	단일 환불 읽기.	상태: `PENDING` → `APPROVED` → `EXECUTED` \| `REJECTED`.
`GET`	`/b2b/v1/refunds/by-merchant/{merchant_id}`	환불 목록. 커서 페이지네이션.	—
`POST`	`/b2b/v1/refunds/{id}/approve`	`PENDING` 환불 승인(고객 시작만 — 가맹점 시작은 이미 `APPROVED` 상태).	암호화폐: `APPROVED`로 도착하면 다음 `/submit-tx`를 호출합니다.
`POST`	`/b2b/v1/refunds/{id}/reject`	`PENDING` 환불 거부.	`payment.refund.rejected`를 발생시킵니다.
`POST`	`/b2b/v1/refunds/{id}/submit-tx`	암호화폐 전용 — 브로드캐스트한 온체인 tx 해시를 스탬프.	본문: `{tx_hash, network, token_address}` — 세 개 모두 필수.

카탈로그 (읽기 전용)

메서드	경로	용도
`GET`	`/v1/supported/networks`	InfraIO가 정산할 수 있는 모든 체인(메인넷 + 테스트넷, env로 필터링됨).
`GET`	`/v1/supported/tokens`	해당 체인의 모든 스테이블코인.
`GET`	`/v1/supported/currencies`	`order.currency`에 허용되는 법정화폐.
`GET`	`/v1/merchants/payment-methods`	THIS 가맹점이 활성화한 방법 — 플랫폼 카탈로그 + 가맹점별 토글의 조합. checkout-web이 사용합니다.
`GET`	`/v1/public/merchants/{merchant_id}/branding`	공개 — 체크아웃 페이지가 자체 스킨을 위해 읽습니다.

헬스

메서드	경로	인증	용도
`GET`	`/health`	없음 (공개)	일반 라이브니스 프로브 — `{"status":"ok"}`를 반환합니다. 이(접두사 `/v1` 없음)가 유일한 비인증 헬스 엔드포인트입니다 — 여기에 k8s/uptime 모니터를 가리키세요.
`GET`	`/payment/v1/merchants/{merchant_id}/health`	대시보드 JWT	가맹점별 헬스 뷰 — 최근 인텐트 정산률, 스윕 백로그. 자체 상태 페이지에 유용합니다. B2B API 키가 아닌 대시보드 세션 토큰이 필요합니다. `/payment/` 게이트웨이 접두사 아래에서만 접근 가능합니다 — 접두사 없는 `/v1/...` 경로는 공개적으로 라우팅되지 않습니다.
`GET`	`/payment/v1/stats/health`	대시보드 JWT	가맹점 워크스페이스 트리 전반의 집계 헬스. 공개 라이브니스 프로브가 아닙니다 — `/payment/` 게이트웨이 접두사 아래에서 나머지 `/v1/*`와 동일한 JWT 인증 뒤에 있습니다.

커서 페이지네이션

모든 목록 엔드포인트는 동일한 쿼리 매개변수를 받고 동일한 envelope를 반환합니다. 행이 스크롤 중에 도착해도 페이지가 이동하지 않도록 오프셋이 아닌 불투명 커서((created_at, id)를 base64url 인코딩)를 사용합니다.

쿼리 매개변수	타입	기본값	비고
`cursor`	`string`	—	불투명 — 이전 응답의 `next_cursor`를 그대로 복사합니다.
`limit`	`int`	`20`	`1..100`.
`sort_dir`	`'asc' \| 'desc'`	`desc`	`(created_at, id)` 기준 정렬.
`from` / `to`	`RFC3339`	—	선택적 시간 윈도우 필터.
`search`	`string`	—	지원되는 경우 자유 텍스트 필터.

응답 envelope:


{
  "orders": [ /* page rows */ ],
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0...",
  "has_next": true
}

has_next는 항상 존재합니다. next_cursor는 has_next가 false일 때 생략됩니다. 커서를 파싱하려고 하지 마세요 — 형식은 내부적이며 변경될 것입니다.

이 페이지에서 누락된 항목

이 인덱스는 가맹점 영역 표면을 다룹니다 — /admin/* 아래의 엔드포인트 (대시보드 도구, KYB 리뷰, 네트워크 관리)와 내부 gRPC 경로는 의도적으로 나열되지 않았습니다. swag가 생성하는 OpenAPI 스펙은 전체 표면을 다룹니다 — 필요한 경우 지원팀에 문의하면 최신 스냅샷을 공유해 드립니다.