API 레퍼런스

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

이 페이지는 가맹점 연동용 엔드포인트를 나열합니다. 자체 페이지가 없는 엔드포인트는 관련 개념 페이지에 설명되어 있습니다.

/b2b/v1/* 아래의 엔드포인트는 시크릿 키(sk_…)로 HMAC 서명합니다. 가맹점 백엔드가 호출하는 표면입니다. 가맹점 대시보드와 호스팅 결제 페이지는 자체 엔드포인트를 사용하며, 이는 연동 API에 포함되지 않습니다.

체크아웃

메서드	경로	용도	비고
`POST`	`/b2b/v1/checkout-sessions/quick`	한 번의 호출로 세션 생성 — 주문 + 체크아웃 세션을 함께 발급.	요청 본문과 샘플은 빠른 시작을 참조하세요.
`POST`	`/b2b/v1/checkout-sessions`	기존 주문에 대해 세션 생성. 플랫폼에 자체 주문 모델이 있고 시도당 하나의 세션을 원할 때 사용.	2단계 흐름.
`GET`	`/b2b/v1/checkout-sessions/by-order/{order_id}`	한 주문에 대해 발급된 모든 세션 목록.	구매자가 세션을 포기했고 대시보드에 이전 시도를 표시하고 싶을 때 유용합니다.

주문

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

메서드	경로	용도	비고
`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을 전달하기만 하면 됩니다. 백엔드(아래)에서 또는 가맹점 대시보드에서 토큰을 발급할 수 있습니다. 갱신과 취소는 대시보드에서 처리합니다.

메서드	경로	인증	용도
`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`)를 발생시킵니다.

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

두 흐름 모두에 적용됩니다. 아래 엔드포인트는 요청 토큰이 아닌 환불 자체 (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 Pay가 정산할 수 있는 모든 체인(메인넷 + 테스트넷, env로 필터링됨).
`GET`	`/v1/supported/tokens`	해당 체인의 모든 스테이블코인.
`GET`	`/v1/supported/currencies`	`order.currency`에 허용되는 통화.

헬스

메서드	경로	인증	용도
`GET`	`/health`	없음 (공개)	라이브니스 확인. `{"status":"ok"}`를 반환합니다. 업타임 모니터를 여기에 지정하세요.

커서 페이지네이션

모든 목록 엔드포인트는 동일한 쿼리 매개변수를 받고 동일한 envelope를 반환합니다. 커서는 불투명하며 오프셋 대신 사용되므로, 페이지를 넘기는 동안 새 행이 도착해도 페이지가 이동하지 않습니다.

쿼리 매개변수	타입	기본값	비고
`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일 때 생략됩니다. 커서는 불투명한 문자열로 다루세요.

이 페이지에서 누락된 항목

이 페이지는 가맹점 연동용 엔드포인트를 다룹니다. 나열되지 않은 엔드포인트나 OpenAPI 스펙이 필요하면 지원팀에 문의하세요.