지원국가와 결제통화

CROSS Pay 는 현재 53개국을 지원합니다. 각 국가는 하나 이상의 fiat 통화 또는 crypto 통화(USDT / CROSSD) 로 결제할 수 있습니다. 체인 메타데이터· 토큰 컨트랙트 정보는 체인·토큰 컨트랙트 를 참고하세요.

아래 표는 reference 용 스냅샷입니다. 머천트별 실시간 매핑(소수점 자릿수 포함)은 GET /v1/catalog 로 조회하세요. 활성 crypto 제한이 걸린 국가에서는 crypto 통화가 숨겨집니다.

결제수단이 아닌 통화 기준

본 페이지는 국가별로 사용할 수 있는 결제통화 를 정리합니다. 통화 뒤에 있는 결제수단 브랜드나 제공사는 다루지 않습니다. 결제수단 브랜드는 자주 바뀌지만, 국가가 결제할 수 있는 통화는 안정적이기 때문입니다.

미등록 국가는 거부됩니다

본 페이지의 53개 화이트리스트에 없는 country code 가 country 파라미터로 들어오면 POST /v1/payments 단계에서 422 UNSUPPORTED_COUNTRY 로 떨어집니다.

곧 지원 예정

공개 Sandbox 환경 (테스트 키, 테스트 카드/토큰)
Tron 체인 (tron-nile 등)
USDC 토큰

그룹	국가 수	결제통화
Global (crypto 전용)	1	USDT / CROSSD
로컬 통화 + crypto	5	THB / JPY / TWD / IDR / PHP (+ USDT / CROSSD)
USD + crypto	47	USD (+ USDT / CROSSD)

국가별 카탈로그

🌐 Global — 암호화폐 통화 (GL)

국가	코드	결제통화
Global	`GL`	USDT / CROSSD

로컬 통화 + crypto

각 국가는 로컬 fiat 통화와 crypto 통화(USDT / CROSSD) 를 함께 지원합니다.

국가	코드	로컬 통화	Crypto
Thailand	`TH`	THB	USDT / CROSSD
Japan	`JP`	JPY	USDT / CROSSD
Taiwan	`TW`	TWD	USDT / CROSSD
Indonesia	`ID`	IDR	USDT / CROSSD
Philippines	`PH`	PHP	USDT / CROSSD

🌍 USD + crypto (47국)

fiat 통화로 USD 를, 그리고 crypto 통화(USDT / CROSSD) 를 지원하는 국가입니다.

국가코드	국가명	국가코드	국가명
`US`	United States	`KW`	Kuwait
`GU`	Guam	`PY`	Paraguay
`KH`	Cambodia	`BH`	Bahrain
`AU`	Australia	`DO`	Dominican Republic
`GB`	United Kingdom	`PL`	Poland
`CA`	Canada	`CO`	Colombia
`FR`	France	`NZ`	New Zealand
`MP`	Northern Mariana Islands	`IN`	India
`AR`	Argentina	`IE`	Ireland
`VN`	Vietnam	`EG`	Egypt
`UY`	Uruguay	`PA`	Panama
`DE`	Germany	`EC`	Ecuador
`ES`	Spain	`CH`	Switzerland
`LK`	Sri Lanka	`HU`	Hungary
`MX`	Mexico	`BG`	Bulgaria
`PT`	Portugal	`BE`	Belgium
`SA`	Saudi Arabia	`SE`	Sweden
`UA`	Ukraine	`SG`	Singapore
`PE`	Peru	`BR`	Brazil
`QA`	Qatar	`MY`	Malaysia
`AM`	Armenia	`HK`	Hong Kong
`CL`	Chile
`NO`	Norway
`IT`	Italy
`NL`	Netherlands
`SV`	El Salvador

통화

통화별 소수점

amount 는 항상 decimal 문자열 로 전달합니다 (JS Number 정밀도 손실 방지). 소수점 자리수는 ISO 4217 을 따르며, 잘못된 자릿수는 422 INVALID_AMOUNT 로 거부됩니다.

통화	종류	소수점 (`decimals`)	비고
`USD`	FIAT	2	`'9.99'`
`THB`	FIAT	2	Thai Baht
`JPY`	FIAT	0	정수만 (`'500'`)
`TWD`	FIAT	2	New Taiwan Dollar
`IDR`	FIAT	2	Indonesian Rupiah
`PHP`	FIAT	2	Philippine Peso
`USDT`	CRYPTO	체인별 (6 또는 18)	Ethereum=6, BSC=18, CROSS=18
`CROSSD`	CRYPTO	18	Native CROSS Dollar (CROSS chain)

JPY 와 IDR 주의

JPY 는 소수점이 없는 통화입니다. '500.50' 같은 값은 거부됩니다. IDR 처럼 소수점이 명목상 2 이지만 실무에서 반올림되는 통화는 머천트 측에서 사전 반올림 후 전달하세요.

`country` 파라미터 사용

지원 국가 조회

GET /v1/countries 는 public API 입니다.

GET /v1/countries HTTP/1.1
Host: api.crosspay.io

응답은 name 오름차순으로 정렬되며, 각 항목의 metadata 는 항상 객체 입니다. 현재 UI 에서 사용할 수 있는 key 는 metadata.image_url 입니다.

{
  "countries": [
    {
      "country_code": "US",
      "name": "United States",
      "metadata": {
        "image_url": "https://static.crosspay.ai/flags/us.svg"
      }
    }
  ]
}

운영 데이터가 아직 주입되지 않은 국가는 metadata: {} 로 내려올 수 있습니다. 클라이언트는 null 분기를 추가할 필요가 없습니다.

결제 카탈로그 API

GET /v1/catalog (merchant API 키 필요) 는 지원 국가별로 내 머천트에 프로비저닝된 결제수단을 통해 결제 가능한 재화와 각 재화의 표시 소수점 자릿수를 반환합니다. 내 머천트가 결제할 수 없는 국가는 생략됩니다.

GET /v1/catalog HTTP/1.1
Host: api.crosspay.io
Authorization: Bearer sk_live_...

{
  "updated_at": "2026-06-01T09:00:00Z",
  "countries": [
    {
      "country_code": "JP",
      "name": "Japan",
      "currencies": [
        { "currency": "JPY", "decimals": 0 },
        { "currency": "USDT", "decimals": 4 },
        { "currency": "CROSSD", "decimals": 4 }
      ]
    }
  ]
}

decimals 는 결제/표시 정밀도입니다 (fiat 은 ISO 4217, crypto 심볼은 프로젝트 컨벤션 4) — 체인별 온체인 토큰 decimals 가 아닙니다. 최소 단위 변환에는 체인·토큰 컨트랙트 의 chain/token 메타데이터를 사용하세요.
활성 CRYPTO 제한이 걸린 국가에서는 crypto 재화가 제외됩니다 (아래 참고).
응답에는 ETag 와 Cache-Control: private, max-age=300 이 실립니다. If-None-Match 로 재검증하면 저렴한 304 Not Modified 를 받습니다.

암호화폐 결제의 국가별 제한

admin 이 관리하는 제한 리스트가 국가 단위로 crypto 기능을 선택적으로 제한합니다 (결제 진입 자체를 전면 차단하는 FDS country blocklist 와는 독립적입니다):

타입	제한 대상	판정에 쓰이는 국가 신호
`CRYPTO`	hosted checkout 의 crypto 결제수단, 그리고 `GET /v1/catalog` 의 crypto 재화	buyer 의 요청 IP (CloudFront-Viewer-Country — 위변조 불가)
`ONRAMP`	fiat→crypto 온램프(AlchemyPay) 주문	요청 본문의 `country` 파라미터

대한민국(KR)은 기본적으로 ONRAMP 제한이 걸려 있습니다 (종전 온램프 country blacklist 에서 이관). 리스트는 CROSS Pay admin 서비스가 운영하며 머천트용 토글은 없습니다. 제한이 적용되어도 응답 필드 구조는 그대로이며 반환 집합만 좁아집니다.

결제 생성의 `country`

POST /v1/payments 요청 body 에 optional country 를 넣을 수 있습니다.

{
  "currency": "USD",
  "amount": "9.99",
  "payer_uid": "user-456",
  "country": "US"
}

길이 2 의 ISO 3166-1 alpha-2 형태만 허용합니다.
응답의 checkout_url 에만 ?country=US 로 전달됩니다.
DB 에는 저장되지 않습니다.
이후 GET /v1/payments/{payment_id} 또는 GET /v1/checkout/{checkout_id} 응답의 checkout URL 에는 유지되지 않습니다.

Checkout API 의 `country`

GET /v1/checkout/{checkout_id} 응답은 suggested_country 를 포함할 수 있습니다. 이 값은 geo-resolution 기반 UI hint 입니다.

GET /v1/checkout/{checkout_id}/quotes 는 optional query country 를 받습니다. 미지정 시 backend 가 geo-resolution 결과를 사용하고, 실패하면 fallback country 를 사용합니다.

GET /v1/checkout/cs_abc123/quotes?currency=USD&country=US

hint 를 권한 판단에 사용하지 마세요

country 와 suggested_country 는 billing country 기본값이나 드롭다운 초기 선택에만 사용합니다. 세금, 라우팅, 인증, 접근 권한은 서버 응답과 FDS 결과를 기준으로 처리하세요.

머천트 활성화

신규 머천트 활성화 또는 결제통화 노출 변경은 다음과 같이 진행됩니다 (셀프-서비스 UI 미제공).

PG 계약 및 KYC 완료
CROSS Pay 측에 활성화 요청 (활성화하려는 국가 / 통화 명시)
운영팀이 활성화 반영
동일 흐름 검증
운영 활성화

문의: support@crosspay.ai

다음 단계

체인·토큰 컨트랙트 — 온체인 레일의 체인 메타데이터, PayGateway 주소, 토큰 매핑.

국가별 카탈로그​

🌐 Global — 암호화폐 통화 (GL)​

로컬 통화 + crypto​

🌍 USD + crypto (47국)​

통화​

통화별 소수점​

country 파라미터 사용​

지원 국가 조회​

결제 카탈로그 API​

암호화폐 결제의 국가별 제한​

결제 생성의 country​

Checkout API 의 country​

머천트 활성화​

다음 단계​