요청·응답 본문

요청 본문

요청 본문은 클라이언트가 API를 요청할 때 보내는 데이터입니다. 캔디페이 API에 요청할 때는 JSON 형식을 사용하세요.

URL 인코딩

전체 요청 본문을 인코딩할 필요는 없습니다. 특수 문자가 요청 본문이나 쿼리 파라미터 값에 포함되어 있다면 URL 인코딩을 해야 합니다. 데이터를 안전하게 전송하고, 서버에서 정확하게 해석되도록 하는 중요한 단계입니다.

URL 인코딩은 웹에서 안전하게 데이터를 전송하기 위해 특정 문자를 % 기호와 두 개의 16진수 숫자로 변환하는 과정입니다. 인코딩은 데이터가 전달되는 과정에서 오류나 변조 없이 완전하고 믿을 수 있는 상태로 유지해서 웹 서버가 요청을 정확하게 해석하도록 도와줍니다.

// 원본 데이터
name=John Doe&age=30

// 인코딩 후
name=John%20Doe&age=30

API 요청을 할 때 데이터 전송의 정확성과 안전성을 보장하려면 URL 인코딩을 하세요. 대부분의 프로그래밍 언어 및 플랫폼에서는 URL 인코딩을 위한 내장 함수나 라이브러리를 제공합니다. 사용하는 언어에 맞는 인코딩 방법을 참조하여 API 요청을 준비하세요.

멱등성 키

아래 API는 선택 헤더 Idempotency-Key를 지원합니다. 하나의 작업을 식별하는 고유한 키를 최초 요청부터 보내고, 통신 오류로 같은 작업을 재요청할 때 같은 키를 사용하세요.

작업	API
빌링키 발급	POST /px/billing/billkeys/issue
빌링 승인	POST /px/billing
intentKey로 취소	POST /px/intents/{intentKey}/cancel
orderId로 취소	POST /px/intents/orders/{orderId}/cancel

Idempotency-Key: 173b48f9-623b-4ef3-a210-2a4fb8ca7436

동일한 인증 주체와 API에서 키와 요청 내용이 같으면 저장된 성공 또는 실패 응답의 HTTP 상태 코드와 본문을 반환합니다. 응답 재사용 기간은 최초 요청 시점부터 24시간이며, 재요청 시 연장되지 않습니다. 최신 결제 상태가 필요하면 별도로 결제 조회 API를 호출하세요.

조건	응답
동일 키의 최초 요청이 처리 중	425 IDEMPOTENCY_IN_PROGRESS
같은 키로 경로 파라미터·쿼리·본문 또는 Candypay-Sdk-Test 헤더를 변경	409 IDEMPOTENCY_KEY_REUSED
빈 키를 전송	400 IDEMPOTENCY_KEY_REQUIRED

헤더를 생략하면 응답 재사용이 적용되지 않습니다. 다른 청구나 추가 부분취소에는 새 키를 사용하세요. 같은 작업을 재시도할 때는 인증 주체·엔드포인트·요청 내용을 유지하세요. 처리 중인 요청은 24시간이 지나도 자동으로 재실행하지 않으므로, 425가 계속되면 캔디페이 담당자에게 확인해주세요.

일반 승인 API인 POST /px/intents/confirm과 결제 링크 생성 API인 POST /px/payfront/sessions에는 이 응답 재사용이 적용되지 않습니다. 각각 승인 재요청과 타임아웃, 링크 유효기간과 재발급을 확인하세요.

응답 본문

응답 본문은 서버가 클라이언트에 보내는 데이터입니다. 캔디페이 API의 성공 여부는 HTTP 상태 코드로 전달합니다. 돌아온 HTTP 상태 코드에 따라 요청이나 에러를 처리하는 로직을 구축하세요.

모든 API 응답, 요청 본문은 JSON 형식입니다. 따라서 응답 헤더에는 다음과 같이 Content-Type이 포함됩니다.

Content-Type: application/json

에러 객체

요청이 정상적으로 처리되지 않으면 응답으로 HTTP 상태 코드와 함께 아래와 같은 에러 객체가 돌아옵니다. API 별 에러 코드와 메시지는 에러 코드 페이지에서 살펴보세요.

{
  "code": "NOT_FOUND_PAYMENT",
  "message": "존재하지 않는 결제입니다."
}

interface ErrorObject {
  code: string
  message: string
  details?: Record<string, unknown>
}

결제 승인·취소 오류를 집계한 응답에는 details.errors를 포함해드립니다. 각 항목의 index는 처리 대상의 0부터 시작하는 순서, code와 message는 해당 오류의 CandyPay 표준 코드와 메시지이며, 최상위 code와 message는 첫 번째 오류를 나타냅니다. 빌링결제 승인 실패의 billing은 해당 결제수단에 요청한 instruments[].billing 값입니다. 빌링 식별자가 없는 경우에는 null입니다.

일부 결제수단만 취소되었거나 승인 보상 취소에 실패한 경우 등에는 대표 오류 대신 PAYMENT_RECONCILIATION_REQUIRED가 반환될 수 있습니다. 이 경우 details.stage 등과 함께 캔디페이에 거래 확인을 요청하세요.

{
  "code": "INVALID_CARD",
  "message": "카드 입력정보가 올바르지 않습니다.",
  "details": {
    "stage": "APPROVE_PAYMENT_METHODS",
    "errors": [
      { "index": 0, "billing": "billing-example-1", "code": "INVALID_CARD", "message": "카드 입력정보가 올바르지 않습니다." },
      { "index": 1, "billing": "billing-example-2", "code": "EXCEED_MAX_AMOUNT", "message": "거래금액 한도를 초과했습니다." }
    ]
  }
}