Checkout

Checkout Session을 발급하면 구매자를 결제 페이지로 보낼 URL을 받을 수 있어요.

세션 생성

상품 식별자로 test 또는 live 결제 세션을 만들어요.
공개 연락처 인증이 끝나지 않은 스토어는 409 응답을 돌려줘요.
Idempotency-Key는 24시간 보관해요.

권한 checkout:write·Idempotency-Key 헤더 필수

알아둘 점

successUrl·cancelUrl 호스트는 리디렉트 허용 목록에 등록해요.
결제가 끝나면 successUrl에 order_id와 session_id가 붙어 돌아와요. 이 값만으로 확정하지 말고 세션을 조회하거나 order.paid 웹훅을 확인해요.
구매자가 결제를 취소하거나 PG 결제가 실패하면 cancelUrl에 session_id가 붙어 돌아와요.
metadata는 문자열 값만 받고 키 50개, 키 40자, 값 500자까지예요.
같은 구매자가 같은 상품을 다시 구독 결제하면 구독이 하나 더 생겨요. 중복을 막으려면 세션을 만들기 전에 확인해요.

헤더

Idempotency-Keystring필수

POST 요청의 중복 실행을 막는 키예요. 24시간 보관하며 본문이 다른 요청에는 같은 키를 쓸 수 없어요.

제약 1~255자

요청 본문

productIdstring필수

결제할 상품 식별자예요.

예 prod_123

cancelUrlstring

결제가 취소된 뒤 구매자를 돌려보낼 URL이에요.

예 https://shop.example.com/cancel

customerobject

구매자 사전 입력 정보예요.

하위 필드 3개

emailstring

결제 구매자의 이메일 주소예요.

예 buyer@example.com

namestring

결제 구매자의 이름이에요.

예 홍길동

phonestring

결제 구매자의 연락처예요.

예 01012345678

intervalstring

구독 상품의 결제 주기예요.

허용 값 monthly, yearly

metadataobject

결제 후 웹훅과 조회 응답에서 받을 문자열 메타데이터예요.

planIdstring

구독 상품의 플랜 식별자예요.

예 plan_basic

successUrlstring

결제 완료 후 구매자를 돌려보낼 URL이에요.

예 https://shop.example.com/complete

응답

성공하면 HTTP 201과 결제 세션 객체를 돌려줘요.

오류

코드	HTTP	의미
`PRODUCT_NOT_FOUND`	`404`	상품이 없거나 키의 상품 범위 밖이에요.
`PRODUCT_ARCHIVED`	`409`	보관된 상품은 결제할 수 없어요.
`SOLD_OUT`	`409`	이 상품은 품절되어 결제할 수 없어요.
`NOT_STARTED`	`409`	아직 판매가 시작되지 않은 상품이에요.
`ENDED`	`409`	판매가 종료된 상품이에요.
`PUBLIC_CONTACT_VERIFICATION_REQUIRED`	`409`	Checkout 세션을 만들기 전에 공개 연락처를 인증해 주세요.
`CHECKOUT_URL_INVALID`	`400`	Checkout 또는 포털 복귀 URL 형식이 올바르지 않아요.
`RETURN_URL_NOT_ALLOWED`	`400`	복귀 URL 도메인이 결제 모드별 허용 목록에 없어요.
`METADATA_INVALID`	`400`	메타데이터가 평면 문자열 맵이 아니거나 허용된 크기를 벗어났어요.
`CHECKOUT_NOT_CONFIGURED`	`500`	스토어의 결제 설정이 완료되지 않아 Checkout 세션을 만들 수 없어요.

표에 없는 공통 오류(인증·권한, 호출 한도, 입력 검증, 멱등 키, 서버 오류)는 에러 코드에서 확인해요.

curl -X POST https://api.payri.kr/v1/checkout/sessions \
  -H "Authorization: Bearer $PAYRI_API_KEY" \
  -H "Idempotency-Key: checkout-prod-123-001" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "prod_123",
    "successUrl": "https://shop.example.com/complete",
    "customer": { "email": "buyer@example.com" }
  }'

{
  "cancelUrl": "https://shop.example.com/cancel",
  "createdAt": "2026-10-15T00:00:00.000Z",
  "customer": {
    "email": "buyer@example.com",
    "name": "홍길동",
    "phone": null
  },
  "expiresAt": "2026-10-15T00:30:00.000Z",
  "id": "cs_123",
  "metadata": {
    "campaign": "fall"
  },
  "mode": "test",
  "orderId": null,
  "productId": "prod_123",
  "status": "open",
  "successUrl": "https://shop.example.com/complete",
  "url": "https://payri.kr/checkout/cs_123"
}

세션 조회

세션 식별자로 만료 시각과 결제 상태를 조회해요.

권한 checkout:read

경로 파라미터

idstring필수

조회할 결제 세션 식별자예요.

예 cs_123

응답

성공하면 HTTP 200과 결제 세션 객체를 돌려줘요.

오류

코드	HTTP	의미
`CHECKOUT_SESSION_NOT_FOUND`	`404`	Checkout 세션이 없거나 키의 범위 밖이에요.

표에 없는 공통 오류(인증·권한, 호출 한도, 서버 오류)는 에러 코드에서 확인해요.

curl https://api.payri.kr/v1/checkout/sessions/cs_123 \
  -H "Authorization: Bearer $PAYRI_API_KEY"

{
  "cancelUrl": "https://shop.example.com/cancel",
  "createdAt": "2026-10-15T00:00:00.000Z",
  "customer": {
    "email": "buyer@example.com",
    "name": "홍길동",
    "phone": null
  },
  "expiresAt": "2026-10-15T00:30:00.000Z",
  "id": "cs_123",
  "metadata": {
    "campaign": "fall"
  },
  "mode": "test",
  "orderId": null,
  "productId": "prod_123",
  "status": "open",
  "successUrl": "https://shop.example.com/complete",
  "url": "https://payri.kr/checkout/cs_123"
}

결제 세션 객체

필드

cancelUrlstringnull 가능

결제 취소 후 이동할 URL이에요.

createdAtstring

세션이 생성된 시각이에요.

customerobject

세션에 사전 입력한 구매자 정보예요.

하위 필드 3개

emailstringnull 가능

결제 구매자의 이메일 주소예요.

namestringnull 가능

결제 구매자의 이름이에요.

phonestringnull 가능

결제 구매자의 연락처예요.

expiresAtstring

세션 생성 후 30분이 되는 만료 시각이에요.

idstring

결제 세션 식별자예요.

metadataobjectnull 가능

요청 때 전달한 메타데이터예요.

modestring

test 또는 live 결제 환경을 알려줘요.

허용 값 live, test

orderIdstringnull 가능

결제가 완료된 주문 식별자예요.

productIdstring

상품 식별자예요.

statusstring

결제 세션 상태예요.

허용 값 open, completed, expired

successUrlstringnull 가능

결제 완료 후 이동할 URL이에요.

urlstring

구매자가 열 결제 페이지 URL이에요.

{
  "cancelUrl": "https://shop.example.com/cancel",
  "createdAt": "2026-10-15T00:00:00.000Z",
  "customer": {
    "email": "buyer@example.com",
    "name": "홍길동",
    "phone": null
  },
  "expiresAt": "2026-10-15T00:30:00.000Z",
  "id": "cs_123",
  "metadata": {
    "campaign": "fall"
  },
  "mode": "test",
  "orderId": null,
  "productId": "prod_123",
  "status": "open",
  "successUrl": "https://shop.example.com/complete",
  "url": "https://payri.kr/checkout/cs_123"
}