결제 생성 (Create Intent)

POST /payments

PaymentIntent 를 생성한다. Merchant 는 반환된 checkout_url 을 buyer 에게 전달(redirect 또는 링크)하여 결제를 진행한다. checkout_id 는 동일 페이지의 식별자로, 직접 URL 을 조립할 일은 없다.

Idempotency-Key 헤더로 중복 생성을 방지한다 (24h TTL, Redis 캐시).
metadata 는 opaque JSON 으로 저장/반환만 하며, CROSS Pay 는 해석하지 않는다.
amount 는 문자열로 전달한다 (shopspring/decimal 정밀도 보장).
expires_in 은 초 단위이며, 0 또는 미지정 시 기본 30분.
checkout_url 은 {checkout.base_url}/{checkout_id} 형식이며, dev 환경에서 checkout.base_url 이 비어 있으면 응답에서 생략된다.
country(ISO 3166-1 alpha-2, optional)가 제공되면 응답 checkout_url 에 ?country=XX 쿼리로 forward 되어 hosted checkout 페이지가 청구 국가를 초기 선택한다. DB 미저장 — POST 응답에만 흐르며 이후 GET 응답의 checkout_url 에는 쿼리가 따라붙지 않는다.
include_pegged_assets (optional, v0.7.55 부터 기본 true — 이전에는 false) 는 법정통화 결제 시 해당 통화에 peg 된 stablecoin(예: USD → USDT / USDC / CROSSD)을 hosted checkout 의 결제 옵션으로 함께 노출할지 결정한다. fiat 전용 체크아웃을 유지하려면 명시적으로 false 를 보낸다. currency 자체가 토큰 심볼(USDT)인 결제는 이 플래그의 영향을 받지 않는다.

Request

FDS 가 요청을 거부했다. HTTP 상태는 200 으로 유지되며(이것은 transport 레벨 에러가 아니라 비즈니스 결과다) 본문은 { fds: ... } envelope 다. 모든 /v1/payments 엔드포인트가 이 응답을 반환할 수 있다.