본문으로 건너뛰기

CROSS Pay API

Version 0.9.9

CROSS Pay v1 REST API. Merchant 서버는 PaymentIntent를 생성하고, merchant API 키를 사용해 서버-투-서버 컨텍스트에서 그 라이프사이클을 구동한다.

이 사이트의 Try it out 은 샌드박스(/v1)로 프록시되며 샌드박스 API 키가 서버 측에서 주입된다. 프로덕션 키는 브라우저에 절대 노출되지 않는다.

스펙 다운로드​

Postman, SDK 제너레이터, IDE 등에서 사용하도록 전체 스펙을 내려받을 수 있다. 이 페이지에 문서화된 merchant 서버 엔드포인트만 정확히 포함한다:

인증​

모든 /payments/** 엔드포인트와 GET /catalog 는 merchant API 키 (Authorization: Bearer <API_KEY>)를 요구한다. Buyer 대상 hosted checkout, wallet 클라이언트용 온체인 세션 조회, 공개 countries / chains 조회, 프로바이더 측 webhook 은 CROSS Pay hosted checkout, wallet SDK, 그리고 플랫폼 자체가 소비하는 것으로 — 본 merchant 연동 레퍼런스의 범위가 아니다.

환경​

CROSS Pay 는 현재 Production 환경(https://api.crosspay.io)만 노출한다: 53개국 카탈로그, chain slug ethereum / bsc / cross, 크립토 통화 USDT / CROSSD, 그리고 sk_live_… 프리픽스의 API 키.

공개 Sandbox 환경(셀프서브 테스트 키, 테스트 카드, 테스트 토큰 포함)은 다음 릴리스에 예정되어 있다.

전체 국가별 매핑은 지원 국가 & 결제수단 카탈로그를 참고한다.

PaymentStatus 개요​

상태의미 / 진입 경로
PENDINGPOST /payments 직후. 아직 quote 미선택.
PROCESSINGBuyer 가 hosted checkout 에서 결제수단을 선택한 이후. 외부 PG 인계 구간 — PG/chain 의 종결 webhook(PAID/FAILED) 또는 expiry 워커(EXPIRED)를 기다린다.
PAID / FAILEDPG/chain webhook 이 PROCESSING 을 종결한다. 종단 상태.
EXPIREDTTL expiry 워커. PENDING 과 PROCESSING 양쪽에서 도달 가능. 종단 상태.
CANCELLEDMerchant 취소 호출 또는 buyer-cancel webhook. PENDING 에서만 도달 가능 — PROCESSING 취소는 PG race 때문에 409 INVALID_PAYMENT_STATE 으로 거부된다. 종단 상태.
PARTIALLY_REFUNDED / REFUNDED환불 결과. PAID 에서 도달. 종단 상태.

PENDING → PAID/FAILED 직접 전이는 더 이상 허용되지 않는다. 모든 webhook 기반 종단 전이는 PROCESSING 을 거친다. 전체 상태 머신과 webhook 매핑은 Webhooks Overview를 참고한다.

최근 변경사항​

  • 신규 PG: MyCard (v0.9.9, additive): TW/HK/SEA fiat hosted-page PG MyCard 가 PG 레지스트리에 추가됐다. buyer-facing wire shape 변경은 없다 — Payment 의 provider enum 에 mycard 값만 추가됐고, MyCard 로 처리된 결제는 provider 가 mycard 로 내려온다. MyCard ops 콜백은 이 merchant 레퍼런스의 범위 밖(webhook 그룹)이다.
  • GET /catalog 인증 필요로 전환 (v0.9.3, BREAKING): 종전 공개(인증 불필요) 카탈로그가 Merchant API Key 인증을 요구한다. Authorization: Bearer <API_KEY> 없이 호출하면 401. Cache-Control 도 public → private 로 바뀌어 공유 캐시(CDN/프록시)에 저장되지 않는다. ETag / If-None-Match 304 재검증은 그대로다.
  • GET /catalog 머천트별 스코핑 (v0.9.5): 카탈로그가 인증된 머천트 단위로 필터링된다 — 머천트에 프로비저닝된 결제수단(merchant_payment_method)으로 결제 가능한 재화만 노출하고, 결제 가능한 재화가 하나도 없는 국가는 응답에서 제외한다. 응답 wire shape 은 동일하며 반환 집합만 좁아진다. ETag 는 이제 머천트별 신선도에서 파생된다.
  • include_pegged_assets 기본값이 true 로 반전 (v0.7.55, BREAKING): POST /payments 에서 v0.7.51 에 도입된 opt-in 플래그가 opt-out 으로 뒤집혔다. 플래그 없이 생성한 법정통화 결제도 이제 해당 통화에 peg 된 stablecoin(USDT / USDC / …)이 hosted checkout 의 결제 옵션으로 노출된다. stablecoin 을 계속 숨겨야 하는 merchant 는 명시적으로 include_pegged_assets: false 를 보내야 한다. 그 외 wire shape / DB 변경은 없다. before/after 동작은 CreatePaymentRequest 의 필드 설명을 참고한다.
  • GET /catalog 추가 (v0.7.55, additive): 지원 국가별로, 호출한 merchant 에게 프로비저닝된 결제수단을 통해 결제 가능한 재화(통화/자산)와 각 재화의 표시 소수점 자릿수를 반환한다. 캐시에서 서빙되며 ETag / If-None-Match 재검증을 지원한다.
  • 암호화폐 결제의 국가별 제한 (v0.7.55): admin 이 관리하는 제한 리스트(타입 CRYPTO / ONRAMP)가 crypto 결제 노출 지역을 통제한다. Buyer 의 IP 기반 국가(CloudFront-Viewer-Country — 위변조 불가한 권위 신호)가 CRYPTO 제한국이면 체크아웃 견적에서 crypto 결제수단이 숨겨지고, GET /catalog 도 해당 국가의 crypto 재화를 제외한다. 응답 필드 구조는 불변 — 반환 집합만 좁아진다. 종전 온램프 country_blacklist config (기본 KR)는 이 리스트의 ONRAMP 행으로 이관됐다.
  • PROCESSING 상태 추가 (v0.7.34, additive): PROCESSING 가 PaymentStatus enum 에 추가됐다. PG webhook 이 PROCESSING → PAID/FAILED 를 종결한다. 기존 클라이언트는 그대로 동작하지만, default / unknown 경로 없이 status 로 분기하던 소비자는 PROCESSING 을 명시적으로 처리해야 한다 ("PG 처리 중 — 결과 대기" 상태 표시를 권장).
  • POST /payments/{payment_id}/cancel 재오픈 (v0.7.34): v0.7.27 에서 제거됐던 cancel 라우트가 동일 wire 포맷으로 merchant 에게 다시 노출된다. PROCESSING 결제를 취소하면 409 INVALID_PAYMENT_STATE 을 반환한다 — PG 와의 race 를 피하기 위함이다. PENDING 동안에만 취소하거나, 종단 결과를 기다린 뒤 환불 API 를 사용한다.
  • POST /payments: optional country 필드는 checkout URL 에 ?country=XX hint 로만 forward 되며 데이터베이스에 저장되지 않는다.

Authentication​

MerchantApiKey — http (bearer)

Merchant API Key

Contact​

Cross Pay Team