API & SDK

링크페이 API

링크페이 API로 결제 링크를 생성하고 관리할 수 있습니다. 링크페이는 별도 계약 후 사용할 수 있습니다.

목차
인증 및 기타 헤더 설정
요청·응답 본문

링크 복사상품

상품 API로 결제 링크에 사용할 상품을 생성하고 관리할 수 있습니다. Basic 인증 방식을 사용합니다.

링크 복사Product 객체

상품 정보를 담고 있는 객체입니다.

링크 복사객체 상세

  • productKey string

    상품의 고유 ID입니다.

  • name string

    상품명입니다.

  • amount number

    상품 가격입니다.

  • currency string

    통화 정보입니다.

  • description nullable · string

    상품 설명입니다.

  • exchangeRefundPolicy nullable · string

    환불 정책입니다.

  • status string

    상품 상태입니다. ON_SALE, SOLD_OUT 중 하나입니다.

  • url nullable · string

    결제 링크 URL입니다. 이 URL을 구매자에게 공유하면 결제를 진행할 수 있습니다.

  • useMemo boolean

    구매자의 요청사항 입력란 사용 여부입니다.

  • validThrough nullable · string

    상품 유효기간입니다.

  • mainImage nullable · object

    메인 이미지 정보입니다.

    • productImageKey string

      이미지의 고유 ID입니다.

    • path string

      이미지 URL입니다.

  • images array

    상세 이미지 리스트입니다.

    • productImageKey string

      이미지의 고유 ID입니다.

    • path string

      이미지 URL입니다.

  • optionDetail object

    상품의 옵션 구성 정보입니다.

    • groups array

      옵션의 분류 기준 리스트입니다. 예를 들어 사이즈, 색상 등입니다.

      • id string

        옵션 그룹 ID입니다.

      • name string

        옵션 그룹 이름입니다. 예를 들어 사이즈, 색상 등입니다.

      • values array

        옵션 그룹 값 리스트입니다. 예를 들어 ["S", "M", "L"] 등입니다.

    • options array

      groups에서 정의한 값을 조합한 항목 리스트입니다. 예를 들어 사이즈와 색상을 조합한 ["M", "블랙"]이 하나의 항목입니다. 각 항목별로 가격, 재고, 판매 가능 여부를 담고 있습니다.

      • id string

        항목의 고유 ID입니다.

      • names array

        조합된 옵션 그룹 값 리스트입니다. 예를 들어 ["M", "블랙"]입니다.

      • amount number

        항목의 가격입니다.

      • currency string

        통화 정보입니다.

      • available boolean

        항목의 이용 가능 여부입니다.

      • stock nullable · object

        항목의 재고 정보입니다.

        • totalQuantity integer

          전체 재고 수량입니다.

        • remainQuantity integer

          남은 재고 수량입니다.

  • stock nullable · object

    상품 재고 정보입니다.

    • totalQuantity integer

      전체 재고 수량입니다.

    • remainQuantity integer

      남은 재고 수량입니다.

  • deliveryPolicy nullable · object

    상품 배송 정보입니다.

    • amount number

      배송비입니다.

    • currency string

      통화 정보입니다.

    • period string

      배송 기간입니다. 예를 들어 3일 이내입니다.

  • createdAt string

    상품 생성 일시입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.

링크 복사상품(링크) 생성

POST /v1/products

결제 링크에 사용할 상품을 생성합니다.

링크 복사Request Body 파라미터

  • name 필수 · string

    상품명입니다.

  • amount 필수 · number

    상품 가격입니다.

  • description string

    상품 설명입니다.

  • stock object

    상품 재고 정보입니다. 옵션 항목 재고와는 동시에 설정할 수 없습니다.

    • quantity 필수 · integer

      전체 재고 수량입니다.

  • optionDetail object

    상품의 옵션 구성 정보입니다.

    • groups 필수 · array

      옵션의 분류 기준 리스트입니다. 예를 들어 사이즈, 색상 등입니다.

      • name 필수 · string

        옵션 그룹 이름입니다.

      • values 필수 · array

        옵션 그룹 값 리스트입니다.

    • options 필수 · array

      groups에서 정의한 값을 조합한 항목 리스트입니다. 예를 들어 사이즈와 색상을 조합한 ["M", "블랙"]이 하나의 항목입니다.

      • names 필수 · array

        조합된 옵션 그룹 값 리스트입니다. groups의 값에 포함된 값이어야 합니다.

      • amount 필수 · number

        항목의 가격입니다.

      • available 필수 · boolean

        항목의 이용 가능 여부입니다.

      • stock object

        항목의 재고 정보입니다.

        • quantity 필수 · integer

          전체 재고 수량입니다.

  • useMemo boolean

    구매자의 요청사항 입력란 사용 여부입니다.

  • validThrough string

    상품 유효기간입니다.

  • exchangeRefundPolicy string

    환불 정책입니다.

  • deliveryPolicy object

    상품 배송 정보입니다.

    • amount 필수 · number

      배송비입니다.

    • period 필수 · string

      배송 기간입니다.

링크 복사Response

성공

상품 생성에 성공했다면 Product 객체가 돌아옵니다.

실패

상품 생성에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

상품(링크) 생성 API에서 발생할 수 있는 에러를 살펴보세요.

링크 복사상품(링크) SMS 발송

POST /v1/products/{productKey}/sms

상품의 결제 링크를 SMS로 발송합니다. 발신번호는 수정 불가합니다.

테스트 환경에서는 문자가 실제로 발송되지 않습니다.

링크 복사Path 파라미터

  • productKey 필수 · string

    상품의 고유 ID입니다.

링크 복사Request Body 파라미터

  • recipients 필수 · array

    문자를 수신할 핸드폰 번호 리스트입니다.

  • queryParams object

    상품 결제 링크에 추가할 커스텀 쿼리 파라미터입니다. key-value 형태로 객체로 보내세요. 설정한 값은 주문 완료 후 Order 객체의 metaFields에 포함되어 돌아옵니다. JSON 변환 시 500자를 초과할 수 없습니다.

링크 복사Response

성공

문자 발송에 성공했다면 HTTP 200 상태 코드가 돌아옵니다.

실패

문자 발송에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

상품(링크) SMS 발송 API에서 발생할 수 있는 에러를 살펴보세요.

링크 복사상품 단건 조회

GET /v1/products/{productKey}

상품 하나의 정보를 조회합니다.

링크 복사Path 파라미터

  • productKey 필수 · string

    상품의 고유 ID입니다.

링크 복사Response

성공

상품 조회에 성공했다면 Product 객체가 돌아옵니다.

실패

상품 조회에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

상품 단건 조회 API에서 발생할 수 있는 에러를 살펴보세요.

링크 복사상품 목록 조회

GET /v1/products

상품 목록을 조회합니다.

링크 복사Query 파라미터

  • limit integer

    한 번에 조회할 상품 수입니다. 최대 100까지 설정할 수 있으며 기본값은 20입니다.

  • startingAfter string

    페이지네이션에 사용합니다. 이전 조회 결과의 마지막 productKey를 넣으면 그 다음 상품부터 조회합니다.

링크 복사Response

성공

상품 목록 조회에 성공했다면 Product 객체 배열이 돌아옵니다.

실패

상품 목록 조회에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

상품 목록 조회 API에서 발생할 수 있는 에러를 살펴보세요.

링크 복사상품 수정

POST /v1/products/{productKey}

상품 정보를 수정합니다. 수정할 필드만 요청 본문에 포함하면 됩니다.

링크 복사Path 파라미터

  • productKey 필수 · string

    상품의 고유 ID입니다.

링크 복사Request Body 파라미터

  • name string

    상품명입니다.

  • amount number

    상품 가격입니다.

  • description string

    상품 설명입니다.

  • stock object

    상품 재고 정보입니다. 옵션 항목 재고와는 동시에 설정할 수 없습니다.

    • quantity 필수 · integer

      전체 재고 수량입니다.

  • optionDetail object

    상품의 옵션 구성 정보입니다.

    • groups 필수 · array

      옵션의 분류 기준 리스트입니다. 예를 들어 사이즈, 색상 등입니다.

      • name 필수 · string

        옵션 그룹 이름입니다.

      • values 필수 · array

        옵션 그룹 값 리스트입니다.

    • options 필수 · array

      groups에서 정의한 값을 조합한 항목 리스트입니다. 예를 들어 사이즈와 색상을 조합한 ["M", "블랙"]이 하나의 항목입니다.

      • names 필수 · array

        조합된 옵션 그룹 값 리스트입니다. groups의 값에 포함된 값이어야 합니다.

      • amount 필수 · number

        항목의 가격입니다.

      • available 필수 · boolean

        항목의 이용 가능 여부입니다.

      • stock object

        항목의 재고 정보입니다.

        • quantity 필수 · integer

          전체 재고 수량입니다.

  • useMemo boolean

    구매자의 요청사항 입력란 사용 여부입니다.

  • validThrough string

    상품 유효기간입니다.

  • exchangeRefundPolicy string

    환불 정책입니다.

  • deliveryPolicy object

    상품 배송 정보입니다.

    • amount 필수 · number

      배송비입니다.

    • period 필수 · string

      배송 기간입니다.

링크 복사Response

성공

상품 수정에 성공했다면 Product 객체가 돌아옵니다.

실패

상품 수정에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

상품 수정 API에서 발생할 수 있는 에러를 살펴보세요.

링크 복사상품 삭제

DELETE /v1/products/{productKey}

상품을 삭제합니다.

링크 복사Path 파라미터

  • productKey 필수 · string

    상품의 고유 ID입니다.

링크 복사Response

성공

상품 삭제에 성공했다면 삭제된 상품의 productKey가 돌아옵니다.

실패

상품 삭제에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

상품 삭제 API에서 발생할 수 있는 에러를 살펴보세요.

링크 복사상품 이미지 업로드

POST /v1/products/{productKey}/images

상품에 이미지를 업로드합니다. multipart/form-data 형식으로 files 필드에 이미지 파일을 담아 요청합니다. 최대 10개까지 업로드할 수 있으며, 파일당 최대 10MB까지 가능합니다.

링크 복사Path 파라미터

  • productKey 필수 · string

    상품의 고유 ID입니다.

링크 복사Query 파라미터

  • imageType 필수 · string

    이미지 타입입니다. MAIN, DETAIL 중 하나입니다.

링크 복사Response

성공

이미지 업로드에 성공했다면 ProductImage 객체 배열이 돌아옵니다.

실패

이미지 업로드에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

이미지 업로드 API에서 발생할 수 있는 에러를 살펴보세요.

링크 복사주문

주문 API로 결제 링크를 통해 발생한 주문을 조회하고 관리할 수 있습니다. Basic 인증 방식을 사용합니다.

링크 복사Order 객체

주문 정보를 담고 있는 객체입니다.

링크 복사객체 상세

  • orderKey string

    주문의 고유 ID입니다.

  • amount number

    주문 금액입니다.

  • currency string

    통화 정보입니다.

  • metaFields object

    결제 링크의 queryParams로 전달된 데이터가 담긴 필드입니다.

  • orderItems array

    주문 아이템 리스트입니다.

    • product object

      상품 정보입니다. Product 객체를 참고하세요.

    • quantity integer

      상품 수량입니다.

    • orderOptions array

      주문 옵션 리스트입니다.

      • names array

        옵션 이름 리스트입니다.

      • amount number

        옵션 가격입니다.

      • currency string

        통화 정보입니다.

  • customerName nullable · string

    구매자 이름입니다.

  • customerPhoneNumber nullable · string

    구매자 핸드폰 번호입니다.

  • memo nullable · string

    구매자의 요청사항입니다.

  • shipping nullable · object

    구매자 배송 정보입니다.

    • receiver string

      수취인입니다.

    • postalCode string

      우편번호입니다.

    • address string

      기본주소입니다.

    • detailAddress string

      상세주소입니다.

    • fullAddress string

      전체 주소입니다.

  • payment nullable · object

    결제 정보입니다. 결제 승인이 완료되면 값이 들어옵니다. Payment 객체를 참고하세요.

  • createdAt string

    주문 생성 일시입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.

링크 복사주문 목록 조회

GET /v1/orders

주문 목록을 조회합니다.

링크 복사Query 파라미터

  • limit integer

    한 번에 조회할 주문 수입니다. 최대 100까지 설정할 수 있으며 기본값은 20입니다.

  • startingAfter string

    페이지네이션에 사용합니다. 이전 조회 결과의 마지막 orderKey를 넣으면 그 다음 주문부터 조회합니다.

링크 복사Response

성공

주문 목록 조회에 성공했다면 Order 객체 배열이 돌아옵니다.

실패

주문 목록 조회에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

주문 목록 조회 API에서 발생할 수 있는 에러를 살펴보세요.

링크 복사주문 단건 조회

GET /v1/orders/{orderKey}

주문 하나의 정보를 조회합니다.

링크 복사Path 파라미터

  • orderKey 필수 · string

    주문의 고유 ID입니다.

링크 복사Response

성공

주문 조회에 성공했다면 Order 객체가 돌아옵니다.

실패

주문 조회에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

주문 단건 조회 API에서 발생할 수 있는 에러를 살펴보세요.

링크 복사주문 취소

POST /v1/orders/{orderKey}/cancel

주문을 취소합니다.

링크 복사Path 파라미터

  • orderKey 필수 · string

    취소할 주문의 고유 ID입니다.

링크 복사Request Body 파라미터

  • cancelReason 필수 · string

    취소 사유입니다.

  • cancelAmount number

    취소 금액입니다. 부분 취소 시 사용합니다.

  • currency string

    통화 정보입니다.

  • taxFreeAmount number

    면세 금액입니다.

  • refundReceiveAccount object

    가상계좌 결제 취소 시 환불 계좌 정보입니다.

    • bank 필수 · string

      은행 한글명입니다.

    • accountNumber 필수 · string

      계좌번호입니다.

    • holderName 필수 · string

      예금주명입니다.

링크 복사Response

성공

주문 취소에 성공했다면 Order 객체가 돌아옵니다.

실패

주문 취소에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

주문 취소 API에서 발생할 수 있는 에러를 살펴보세요.