Skip to Content
개발자REST APIOrders

Orders

주문(Order)은 결제 한 건이에요.
목록과 단건을 조회할 수 있어요.
환불 발행은 Refunds에서 다뤄요.

주문 목록

GEThttps://api.payri.kr/v1/ordersscope orders:read
curl "https://api.payri.kr/v1/orders?page=1&limit=20" \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

페이지네이션 형식으로 응답해요.
키가 특정 상품으로 제한돼 있으면 해당 상품의 주문만 담겨요.

{
  "data": [
    {
      "id": "ord_3kf9a2",
      "productId": "prod_88x",
      "productName": "MeetNote Solo",
      "amount": 19000,
      "currency": "KRW",
      "buyerName": "김구매",
      "buyerEmail": "buyer@example.com",
      "buyerPhone": "010-0000-0000",
      "method": "card",
      "status": "paid",
      "createdAt": "2026-06-16T03:20:00.000Z",
      "paidAt": "2026-06-16T03:20:05.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

주문 단건

GEThttps://api.payri.kr/v1/orders/:idscope orders:read
curl https://api.payri.kr/v1/orders/ord_3kf9a2 \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

환불·쿠폰·구독 관련 필드는 해당될 때만 포함돼요.

{
  "id": "ord_3kf9a2",
  "productId": "prod_88x",
  "productName": "MeetNote Solo",
  "amount": 19000,
  "currency": "KRW",
  "buyerName": "김구매",
  "buyerEmail": "buyer@example.com",
  "buyerPhone": "010-0000-0000",
  "method": "card",
  "status": "refunded",
  "createdAt": "2026-06-16T03:20:00.000Z",
  "paidAt": "2026-06-16T03:20:05.000Z",
  "refundedAt": "2026-06-17T09:00:00.000Z",
  "refundedAmount": 19000,
  "refunds": [
    { "amount": 19000, "at": "2026-06-17T09:00:00.000Z", "reason": "구매자 요청" }
  ]
}

주요 필드

필드타입설명
idstring주문 ID
amountint최종 결제 금액 (KRW)
methodenumcard · kakao_pay · naver_pay · toss
statusenumpending · paid · failed · refunded
refundedAmountint누적 환불 금액 (부분환불 누적)
refundsarray환불 이력 { amount, at, reason? }
couponobject적용된 쿠폰 (있을 때만)
subscriptionIdstring구독 결제면 구독 ID (있을 때만)
metadataobjectCheckout Session에 담았던 메타데이터 (있을 때만)

범위 밖 상품의 주문을 단건 조회하면 404 NOT_FOUND로 응답해요.
키의 상품 범위는 IP · 상품 제한에서 설정해요.

Last updated on
CheckoutRefunds