통신사 승인을 받은 일부 고객사에 한해 사용하실 수 있으며, 현재 다날, kcp(신모듈)을 통해서만 서비스되고 있습니다.\n
본인인증 대상자의 성명, 생년월일 + 주민등록 뒷부분 첫 자리, 휴대폰번호, 통신사 정보를 고객사에서 직접 입력받아 API요청하면 됩니다. 전달된 개인정보가 올바를 경우 해당 휴대폰으로 인증번호 SMS가 전송됩니다.\n
200응답 시 imp_uid 가 응답데이터로 전달되며, SMS전송된 인증번호를 본인인증 완료 API 로 요청주시면 최종 본인인증 프로세스가 완료됩니다.",
"operationId": "requestOTP",
"consumes": [
"application/json",
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "name",
"in": "formData",
"description": "본인인증 대상자 성명",
"required": true,
"type": "string",
"x-portone-name": "성명",
"x-portone-description": "본인인증 대상자 성명"
},
{
"name": "phone",
"in": "formData",
"description": "본인인증 대상자 전화번호 (- 또는 . 과 같은 기호가 포함되어도 무방 - 포트원 내에서 숫자 외에는 정규식으로 모두 제거처리)",
"required": true,
"type": "string",
"x-portone-name": "휴대폰번호",
"x-portone-summary": "본인인증 대상자 전화번호",
"x-portone-description": "- 또는 . 과 같은 기호가 포함되어도 무방 - 포트원 내에서 숫자 외에는 정규식으로 모두 제거처리"
},
{
"name": "birth",
"in": "formData",
"description": "본인인증 대상자 생년월일 YYMMDD 6자리(연/월/일 사이에 - 또는 . 과 같은 기호가 포함되어도 무방 - 포트원 내에서 숫자 외에는 정규식으로 모두 제거처리함)",
"required": true,
"type": "string",
"x-portone-name": "생년월일",
"x-portone-summary": "본인인증 대상자 생년월일",
"x-portone-description": "`YYMMDD` 6자리(연/월/일 사이에 - 또는 . 과 같은 기호가 포함되어도 무방 - 포트원 내에서 숫자 외에는 정규식으로 모두 제거처리함)"
},
{
"name": "gender_digit",
"in": "formData",
"description": "본인인증 대상자 주민등록번호 뒷부분 첫자리(주민등록번호 13자리 중 7번째 자리 2000년 이전 출생자는 1 또는 2, 2000년 이후 출생자는 3 또는 4)\n
외국인 고객은 다음 기준에 따라 입력해주세요:\n- 남성: ~1999년생은 5, 2000년 이후 출생자는 7\n- 여성: ~1999년생은 6, 2000년 이후 출생자는 8",
"required": true,
"type": "string",
"x-portone-name": "성별구분코드",
"x-portone-summary": "본인인증 대상자 주민등록번호 뒷부분 첫자리",
"x-portone-description": "주민등록번호 13자리 중 7번째 자리\n\n2000년 이전 출생자는 1 또는 2, 2000년 이후 출생자는 3 또는 4\n
kcp(신모듈)의 경우 외국인 고객은 다음 기준에 따라 입력해주세요:\n- 남성: ~1999년생은 5, 2000년 이후 출생자는 7\n- 여성: ~1999년생은 6, 2000년 이후 출생자는 8"
},
{
"name": "carrier",
"in": "formData",
"description": "본인인증 대상자 통신사 코드 (알뜰폰 사용자의 경우, carrier파라메터 SKT, KT, LGT 중 하나를 지정한 후 is_mvno : true 로 설정)\n
SKT
\n
KT
\n
LGT
",
"required": true,
"type": "string",
"enum": [
"SKT",
"KT",
"LGT"
],
"x-portone-name": "통신사구분코드",
"x-portone-summary": "본인인증 대상자 통신자 코드",
"x-portone-description": "알뜰폰 사용자의 경우, carrier파라메터 SKT, KT, LGT 중 하나를 지정한 후 **is_mvno : true** 로 설정\n- SKT\n- KT\n- LGT"
},
{
"name": "is_mvno",
"in": "formData",
"description": "본인인증 대상자 알뜰폰 사용 여부",
"required": false,
"type": "boolean",
"default": "false",
"x-portone-name": "알뜰폰 사용 여부",
"x-portone-description": "본인인증 대상자 알뜰폰 사용 여부"
},
{
"name": "company",
"in": "formData",
"description": "고객사 서비스명칭 또는 domain URL. KISA에서 대상자에게 발송하는 SMS에 안내될 서비스 명칭",
"required": false,
"type": "string",
"x-portone-name": "고객사 서비스명칭",
"x-portone-summary": "고객사 서비스명칭 또는 domain URL",
"x-portone-description": "KISA에서 대상자에게 발송하는 SMS에 안내될 서비스 명칭"
},
{
"name": "merchant_uid",
"in": "formData",
"description": "본인인증 요청건을 식별하기 위한 고객사 주문번호",
"required": false,
"type": "string",
"x-portone-name": "고객사 주문번호",
"x-portone-description": "본인인증 요청건을 식별하기 위한 고객사 주문번호"
},
{
"name": "pg",
"in": "formData",
"description": "PG사 구분자 다날 상점아이디를 2개 이상 동시에 사용하시려는 경우 설정하시면 됩니다. danal.{상점아이디} 형태로 지정. Deprecated 되었으므로 channel_key 파라미터를 사용해주세요.",
"required": false,
"type": "string",
"x-portone-name": "PG사 구분코드(deprecated)",
"x-portone-summary": "본인인증을 요청하고자 하는 PG사 구분자",
"x-portone-description": "다날 상점아이디를 2개 이상 동시에 사용하시려는 경우 설정하시면 됩니다. **danal.{상점아이디}** 형태로 지정. Deprecated 되었으므로 channel_key 파라미터를 사용해주세요."
},
{
"name": "channel_key",
"in": "formData",
"description": "본인인증을 요청하고자 하는 PG사의 채널키로 kcp(신모듈) 본인인증을 사용하시려는 경우 반드시 channel_key를 입력해야합니다.",
"required": true,
"type": "string",
"x-portone-name": "채널키",
"x-portone-summary": "본인인증을 요청하고자 하는 PG사의 채널키",
"x-portone-description": "kcp(신모듈) 본인인증을 사용하시려는 경우 반드시 channel_key를 입력해야합니다."
},
{
"name": "verification_method",
"in": "formData",
"description": "본인인증을 진행하고자 하는 방식.\n - SMS\n - APP\n\n지원하는 pg사\n- kcp(신모듈)",
"required": false,
"type": "string",
"enum": [
"SMS",
"APP"
],
"x-portone-name": "본인인증 방식",
"x-portone-summary": "본인인증을 진행하고자 하는 방식",
"x-portone-description": "본인인증을 진행하고자 하는 방식. (현재 kcp(신모듈)만 지원)\n- SMS\n- APP",
"x-portone-supported-pgs": [
"kcp_v2"
]
},
{
"name": "bypass",
"in": "formData",
"description": "JSON string 형식의 PG사별로 특화된 파라미터. 전달 한 값은 가공 없이 그대로 PG사로 전달 됩니다. 각 PG사별 스펙은 PG사별 연동 문서 참고해주세요",
"required": false,
"type": "string",
"x-portone-name": "bypass 데이터",
"x-portone-summary": "JSON string 형식의 PG사별로 특화된 파라미터",
"x-portone-description": "전달 한 값은 가공 없이 그대로 PG사로 전달 됩니다. 각 PG사별 스펙은 PG사별 연동 문서 참고해주세요",
"x-portone-supported-pgs": [
"kcp_v2"
]
}
],
"responses": {
"200": {
"description": "본인인증을 위한 대상자 정보 검증 완료(인증번호 SMS전송요청 중)",
"schema": {
"$ref": "#/definitions/CertificationOTPResponse"
}
},
"401": {
"description": "인증 Token이 전달되지 않았거나 유효하지 않은 경우"
},
"400": {
"description": "대상자 개인정보 중 일부가 누락되었거나 올바르지 않은 경우"
},
"500": {
"description": "처리 중 다날서버 응답오류 등 오류가 발생한 경우"
}
},
"x-portone-supported-pgs": [
"danal",
"kcp_v2"
],
"x-portone-category": "certification"
}
},
"/certifications/otp/confirm/{imp_uid}": {
"post": {
"tags": [
"certifications"
],
"summary": "본인인증 완료 API",
"description": "본인인증 요청 API를 통해 SMS/APP로 전송된 인증번호를 전달하여 본인인증을 완료합니다. \n 본인인증이 완료되면 대상자의 이름, 전화번호, 통신사, 성별, 외국인 여부, 생년월일, CI, DI 값을 응답받을 수 있습니다.",
"operationId": "confirmOTP",
"consumes": [
"application/json",
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "imp_uid",
"in": "path",
"description": "본인인증 요청 API 요청 후 응답된 인증 고유번호",
"required": true,
"type": "string",
"x-portone-name": "포트원 인증 고유번호",
"x-portone-description": "본인인증 요청 API 요청 후 응답된 인증 고유번호"
},
{
"name": "otp",
"in": "formData",
"description": "SMS로 전송된 본인인증 번호. KCP (신모듈) APP 방식의 경우에는 해당 값을 전달하지 않습니다.",
"required": false,
"type": "string",
"x-portone-name": "본인인증 번호",
"x-portone-description": "SMS로 전송된 본인인증 번호. KCP (신모듈) APP 방식의 경우에는 해당 값을 전달하지 않습니다."
}
],
"responses": {
"200": {
"description": "본인인증완료",
"schema": {
"$ref": "#/definitions/CertificationResponse"
}
},
"401": {
"description": "인증 Token이 전달되지 않았거나 유효하지 않은 경우"
},
"400": {
"description": "인증번호를 누락하였거나 이미 인증처리가 완료된 건에 대해 재요청하는 경우"
},
"404": {
"description": "imp_uid 에 해당되는 요청건이 없는 경우"
},
"500": {
"description": "처리 중 다날서버 응답오류 등 오류가 발생한 경우"
}
},
"x-portone-supported-pgs": [
"danal",
"kcp_v2"
],
"x-portone-category": "certification"
}
},
"/subscribe/customers": {
"get": {
"tags": [
"subscribe.customer"
],
"summary": "빌링키 정보 복수조회 API",
"description": "여러 개의 빌링키를 한 번에 조회하는 API입니다.
등록된 카드마다 1개의 customer_uid가 매핑되므로,\n 고객사 시스템 내에 1명의 고객이 여러 장의 카드를 등록할 수 있는 경우 여러 개의 customer_uid를 가지게 됩니다. 해당 고객이 등록해놓은 카드정보 목록을 한 번에 조회하는데 사용하면 편리합니다.\n
예시) /subscribe/customers?customer_uid[]=hong_1234_a&customer_uid[]=hong_1234_b",
"operationId": "customer_view_multiple",
"consumes": [
"application/json",
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "customer_uid[]",
"in": "query",
"description": "빌링키와 매핑되며 고객사에서 채번하는 구매자의 결제 수단 식별 고유번호",
"required": true,
"type": "array",
"items": {
"type": "string"
},
"collectionFormat": "multi",
"default": "customer_1234",
"x-portone-name": "구매자의 결제 수단 식별 고유번호",
"x-portone-description": "빌링키와 매핑되며 고객사에서 채번하는 구매자의 결제 수단 식별 고유번호"
}
],
"responses": {
"200": {
"description": "요청된 모든 customer_uid 에 대한 빌키정보 응답완료. 조회된 빌링키에 따라 일반 빌링키(CustomerAnnotation)와 슈퍼 빌링키(SuperBillingKeyAnnotation)를 포함할 수 있습니다.",
"schema": {
"$ref": "#/definitions/MultipleCustomersResponse"
}
},
"207": {
"description": "요청된 customer_uid 중 일부 빌키정보 조회 실패(ex. 접근권한없음 또는 존재하지 않는 customer_uid). 조회된 빌링키에 따라 일반 빌링키(CustomerAnnotation)와 슈퍼 빌링키(SuperBillingKeyAnnotation)를 포함할 수 있습니다.",
"schema": {
"$ref": "#/definitions/MultipleCustomersResponse"
}
},
"401": {
"description": "인증 Token이 전달되지 않았거나 유효하지 않은 경우"
},
"404": {
"description": "유효하지 않은 customer_uid"
}
},
"x-portone-supported-pgs": [
"chai",
"danal",
"danal_tpay",
"daou",
"html5_inicis",
"inicis",
"kakaopay",
"kcp",
"kcp_billing",
"kicc",
"ksnet",
"mobilians",
"naverpay",
"nice",
"payco",
"paymentwall",
"settle",
"settle_acc",
"settle_firm",
"smartro_v2",
"tosspayments",
"paypal_v2",
"welcome",
"tosspay_v2"
],
"x-portone-category": "billingkey",
"x-portone-per-pg": {
"paypal_v2": {
"description": "연동 유의사항\n\n빌링키 발급 수단 및 정보를 알 수 없음\n\n페이팔을 통해 다양한 수단으로 빌링키 발급이 가능하지만, 페이팔이 승인 된 빌링키 발급 수단 및 정보를 알려주지 않습니다.\n따라서 페이팔 빌링키 발급 건의 결제 수단(pay_method)은 모두 **paypal**로 일괄 저장되며 발급 된 빌링키 정보 조회시 카드 정보는 모두 **null**로 내려갑니다.\n```json\n\\\\ GET /subscribe/customers/{customer_uid}\n{\n ...중략\n pg_provider: 'paypal_v2',\n customer_uid: '{customer_uid}'\n card_name: null,\n card_code: null,\n card_number: null,\n card_type: null,\n}\n```\n "
}
}
}
},
"/subscribe/customers/{customer_uid}": {
"get": {
"tags": [
"subscribe.customer"
],
"summary": "빌링키 정보 단건조회 API",
"description": "구매자의 빌링키 정보 조회",
"operationId": "customer_view",
"consumes": [
"application/json",
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "customer_uid",
"in": "path",
"description": "빌링키와 매핑되며 고객사에서 채번하는 구매자의 결제 수단 식별 고유번호",
"required": true,
"type": "string",
"default": "customer_1234",
"x-portone-name": "구매자의 결제 수단 식별 고유번호",
"x-portone-description": "빌링키와 매핑되며 고객사에서 채번하는 구매자의 결제 수단 식별 고유번호"
}
],
"responses": {
"200": {
"description": "정상 조회 시, 일반 빌링키 조회는 CustomerResponse를 반환하며, 슈퍼 빌링키 조회는 SuperBillingKeyResponse를 반환합니다.",
"schema": {
"properties": {
"CustomerResponse": {
"$ref": "#/definitions/CustomerResponse"
},
"SuperBillingKeyResponse": {
"$ref": "#/definitions/SuperBillingKeyResponse"
}
}
}
},
"401": {
"description": "인증 Token이 전달되지 않았거나 유효하지 않은 경우"
},
"404": {
"description": "유효하지 않은 customer_uid"
}
},
"x-portone-supported-pgs": [
"chai",
"danal",
"danal_tpay",
"daou",
"html5_inicis",
"inicis",
"kakaopay",
"kcp",
"kcp_billing",
"kicc",
"ksnet",
"mobilians",
"naverpay",
"nice",
"payco",
"paymentwall",
"settle",
"settle_acc",
"settle_firm",
"smartro_v2",
"tosspayments",
"paypal_v2",
"nice_v2",
"welcome",
"tosspay_v2"
],
"x-portone-category": "billingkey",
"x-portone-per-pg": {
"paypal_v2": {
"description": "연동 유의사항\n\n빌링키 발급 수단 및 정보를 알 수 없음\n\n페이팔을 통해 다양한 수단으로 빌링키 발급이 가능하지만, 페이팔이 승인 된 빌링키 발급 수단 및 정보를 알려주지 않습니다.\n따라서 페이팔 빌링키 발급 건의 결제 수단(pay_method)은 모두 **paypal**로 일괄 저장되며 발급 된 빌링키 정보 조회시 카드 정보는 모두 **null**로 내려갑니다.\n```json\n\\\\ GET /subscribe/customers/{customer_uid}\n{\n ...중략\n pg_provider: 'paypal_v2',\n customer_uid: '{customer_uid}'\n card_name: null,\n card_code: null,\n card_number: null,\n card_type: null,\n}\n```\n "
}
}
},
"post": {
"tags": [
"subscribe.customer"
],
"summary": "빌링키 발급 API",
"description": "구매자에 대해 빌링키 발급 및 저장 해당 빌링키 발급 API는 PG사와 협의가 완료된 경우 이용 가능한 서비스입니다.\n
PG사 협의를 통해 카드정보 필수 조건 값 조정이 가능합니다.
\n
민감한 카드정보를 이용하기 때문에 보안에 특히 유의하셔야 합니다.
\n
customer_uid 값은 고객 & 카드번호 단위별로 고유하게 발급 관리되어야 합니다
\n
",
"operationId": "customer_save",
"consumes": [
"application/json",
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "customer_uid",
"in": "path",
"description": "빌링키와 매핑되며 고객사에서 채번하는 구매자의 결제 수단 식별 고유번호",
"required": true,
"type": "string",
"default": "customer_1234",
"maxLength": 80,
"x-portone-name": "구매자의 결제 수단 식별 고유번호",
"x-portone-description": "빌링키와 매핑되며 고객사에서 채번하는 구매자의 결제 수단 식별 고유번호"
},
{
"name": "pg",
"in": "formData",
"description": "API 방식 비인증 PG설정이 2개 이상인 경우, 결제가 진행되길 원하는 PG사를 지정하실 수 있습니다. pg 파라메터는 {PG사} 혹은 {PG사}.{PG상점아이디} 형태의 문자열입니다. 지정하지 않거나 유효하지 않은 값이 전달되면 기본PG설정된 값을 이용해 결제하게 됩니다.
나이스페이먼츠, KCP 2가지 PG설정이 되어있다면, pg 파라메터로 nice 또는 kcp로 구분 가능
나이스페이먼츠로부터 2개 이상의 상점아이디를 발급받았다면, nice.MID1 또는 nice.MID2로 구분 가능
",
"required": false,
"type": "string",
"enum": [
"CJGLS",
"KGB",
"DONGBU",
"EPOST",
"REGISTPOST",
"HANJIN",
"HYUNDAI",
"KGBLS",
"INNOGIS",
"DAESIN",
"ILYANG",
"KDEXP",
"CHUNIL",
"CH1",
"HDEXP",
"CVSNET",
"DHL",
"FEDEX",
"GSMNTON",
"WARPEX",
"WIZWA",
"EMS",
"DHLDE",
"ACIEXPRESS",
"EZUSA",
"PANTOS",
"UPS",
"HLCGLOBAL",
"KOREXG",
"TNT",
"SWGEXP",
"DAEWOON",
"USPS",
"IPARCEL",
"KUNYOUNG",
"HPL",
"DADREAM",
"SLX",
"SFEXPRESS",
"HONAM"
],
"x-portone-name": "택배사 코드",
"x-portone-description": "택배사 코드(delivery_method == `RETURN_DELIVERY` 인 경우 필수로 입력해야하는 파라메터)"
},
{
"name": "tracking_number",
"in": "formData",
"description": "송장번호(delivery_method == 'RETURN_DELIVERY' 인 경우 필수 파라메터)",
"required": false,
"type": "string",
"x-portone-name": "송장번호",
"x-portone-description": "송장번호(delivery_method == `RETURN_DELIVERY` 인 경우 필수로 입력해야하는 파라메터)"
}
],
"responses": {
"200": {
"description": "모든 상품주문 반품요청 성공",
"schema": {
"$ref": "#/definitions/NaverProductOrderArrayResponse"
}
},
"207": {
"description": "일부 상품주문 반품요청성공 & 일부주문 반품요청실패 \n 포트원에서 네이버페이에 반품요청시 product_order_id 개별로 반품요청이 진행되어야 합니다. 일부 건만 성공하는 경우 207 응답이 내려갑니다. (모두 성공인 경우 200응답 / 모두 실패인 경우 500응답)",
"schema": {
"$ref": "#/definitions/NaverProductOrderArrayResponse"
}
},
"400": {
"description": "delivery_method 파라메터가 누락되거나 올바르지 않은 경우"
},
"401": {
"description": "인증 Token이 전달되지 않았거나 유효하지 않은 경우"
},
"404": {
"description": "imp_uid에 해당되는 거래건을 찾을 수 없거나 접근 권한이 없는 계정인 경우"
},
"500": {
"description": "모든 상품주문 반품요청실패"
}
},
"x-portone-supported-pgs": [
"naverco"
],
"x-portone-category": "pg.naverpay"
}
},
"/payments/{imp_uid}/naver/approve-return": {
"post": {
"tags": [
"naver"
],
"summary": "(주문형-네이버페이) 상품 반품승인 처리 API",
"description": "(주문형-네이버페이) 네이버페이 상품주문들을 반품승인처리합니다. \n 주문상품의 종류가 여러 개인 경우, 한 건의 포트원 거래건(imp_uid)에 여러 개의 네이버페이 상품주문이 존재하며 일부 또는 전체를 반품승인 처리할 수 있습니다.\n 반품시 배송비 제외, 혹은 추가 청구액이 필요한 경우 반품보류 처리(POST 반품요청상품 반품보류 처리 API) 사용합니다.\n 시도된 상품주문 중 반품승인 처리에 성공한 상품주문에 대한 최종 정보만 제공됩니다.",
"operationId": "naverApproveReturnProductOrder",
"consumes": [
"application/json",
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "imp_uid",
"in": "path",
"description": "네이버페이 반품승인 처리할 거래건의 포트원 거래고유번호",
"required": true,
"type": "string",
"x-portone-name": "포트원 거래고유번호",
"x-portone-description": "네이버페이 반품승인 처리할 거래건의 포트원 거래고유번호"
},
{
"name": "product_order_id",
"in": "formData",
"description": "반품승인 처리할 거래건의 네이버페이 상품주문번호. 생략되면 imp_uid 에 해당되는 모든 상품주문을 반품승인 처리합니다.",
"required": false,
"type": "array",
"items": "string",
"x-portone-name": "네이버페이 상품주문번호",
"x-portone-description": "반품승인 처리할 거래건의 네이버페이 상품주문번호로 생략되면 imp_uid 에 해당되는 모든 상품주문을 반품승인 처리합니다."
},
{
"name": "memo",
"in": "formData",
"description": "반품승인 후 구매자에게 전달하는 메모",
"required": false,
"type": "string",
"x-portone-name": "메모",
"x-portone-description": "반품승인 후 구매자에게 전달하는 메모"
}
],
"responses": {
"200": {
"description": "모든 상품주문 반품승인 처리 성공",
"schema": {
"$ref": "#/definitions/NaverProductOrderArrayResponse"
}
},
"207": {
"description": "일부 상품주문 반품승인 처리성공 & 일부주문 반품승인 처리실패 \n 포트원에서 네이버페이에 반품승인 처리시 product_order_id 개별로 반품승인 처리이 진행되어야 합니다. 일부 건만 성공하는 경우 207 응답이 내려갑니다.\n (모두 성공인 경우 200응답 / 모두 실패인 경우 500응답)",
"schema": {
"$ref": "#/definitions/NaverProductOrderArrayResponse"
}
},
"401": {
"description": "인증 Token이 전달되지 않았거나 유효하지 않은 경우"
},
"404": {
"description": "imp_uid에 해당되는 거래건을 찾을 수 없거나 접근 권한이 없는 계정인 경우"
},
"500": {
"description": "모든 상품주문 반품승인 처리실패"
}
},
"x-portone-supported-pgs": [
"naverco"
],
"x-portone-category": "pg.naverpay"
}
},
"/payments/{imp_uid}/naver/reject-return": {
"post": {
"tags": [
"naver"
],
"summary": "(주문형-네이버페이) 상품 반품거절 처리 API",
"description": "(주문형-네이버페이) 네이버페이 반품요청 상품주문들을 반품거절처리합니다. \n 주문상품의 종류가 여러 개인 경우, 한 건의 포트원 거래건(imp_uid)에 여러 개의 네이버페이 상품주문이 존재하며 일부 또는 전체를 반품거절 처리할 수 있습니다.\n 시도된 상품주문 중 반품거절 처리에 성공한 상품주문에 대한 최종 정보만 제공됩니다.",
"operationId": "naverRejectReturnProductOrder",
"consumes": [
"application/json",
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "imp_uid",
"in": "path",
"description": "네이버페이 반품거절 처리할 거래건의 포트원 거래고유번호",
"required": true,
"type": "string",
"x-portone-name": "포트원의 거래고유번호",
"x-portone-description": "네이버페이 반품거절 처리할 거래건의 포트원 거래고유번호"
},
{
"name": "product_order_id",
"in": "formData",
"description": "네이버페이 반품거절 처리할 거래건의 네이버페이 상품주문번호. 생략되면 imp_uid 에 해당되는 모든 상품주문을 반품거절 처리합니다.",
"required": false,
"type": "array",
"items": "string",
"x-portone-name": "네이버페이 상품주문번호",
"x-portone-description": "네이버페이 반품거절 처리할 거래건의 네이버페이 상품주문번호로 생략되면 imp_uid 에 해당되는 모든 상품주문을 반품거절 처리합니다."
},
{
"name": "memo",
"in": "formData",
"description": "반품거절 후 구매자에게 전달하는 메모",
"required": true,
"type": "string",
"x-portone-name": "메모",
"x-portone-description": "반품거절 후 구매자에게 전달하는 메모"
}
],
"responses": {
"200": {
"description": "모든 상품주문 반품거절 처리 성공",
"schema": {
"$ref": "#/definitions/NaverProductOrderArrayResponse"
}
},
"207": {
"description": "일부 상품주문 반품거절 처리성공 & 일부주문 반품거절 처리실패 \n 포트원에서 네이버페이에 반품거절 처리시 product_order_id 개별로 반품거절 처리이 진행되어야 합니다. 일부 건만 성공하는 경우 207 응답이 내려갑니다.\n (모두 성공인 경우 200응답 / 모두 실패인 경우 500응답)",
"schema": {
"$ref": "#/definitions/NaverProductOrderArrayResponse"
}
},
"400": {
"description": "memo 파라미터가 누락되거나 올바르지 않은 경우"
},
"401": {
"description": "인증 Token이 전달되지 않았거나 유효하지 않은 경우"
},
"404": {
"description": "imp_uid에 해당되는 거래건을 찾을 수 없거나 접근 권한이 없는 계정인 경우"
},
"500": {
"description": "모든 상품주문 반품거절 처리실패"
}
},
"x-portone-supported-pgs": [
"naverco"
],
"x-portone-category": "pg.naverpay"
}
},
"/payments/{imp_uid}/naver/withhold-return": {
"post": {
"tags": [
"naver"
],
"summary": "(주문형-네이버페이) 상품 반품보류 처리 API",
"description": "(주문형-네이버페이) 반품요청 상품주문들을 반품보류처리합니다. \n 주문상품의 종류가 여러 개인 경우, 한 건의 포트원 거래건(imp_uid)에 여러 개의 네이버페이 상품주문이 존재하며 일부 또는 전체를 반품보류 처리할 수 있습니다.\n 시도된 상품주문 중 반품보류 처리에 성공한 상품주문에 대한 최종 정보만 제공됩니다.",
"operationId": "naverWithholdReturnProductOrder",
"consumes": [
"application/json",
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "imp_uid",
"in": "path",
"description": "네이버페이 반품보류 처리할 거래건의 포트원 거래고유번호",
"required": true,
"type": "string",
"x-portone-name": "포트원 거래고유번호",
"x-portone-description": "네이버페이 반품보류 처리할 거래건의 포트원 거래고유번호"
},
{
"name": "product_order_id",
"in": "formData",
"description": "반품보류 처리할 거래건의 네이버페이 상품주문번호. 생략되면 imp_uid 에 해당되는 모든 상품주문을 반품보류 처리합니다.",
"required": false,
"type": "array",
"items": "string",
"x-portone-name": "네이버페이 상품주문번호",
"x-portone-description": "반품보류 처리할 거래건의 네이버페이 상품주문번호로 생략되면 imp_uid 에 해당되는 모든 상품주문을 반품보류 처리합니다."
},
{
"name": "reason",
"in": "formData",
"description": "반품보류사유 코드. 올바르지 않은 보류사유코드인 경우 기본값(ETC)를 적용합니다.\n
\n
RETURN_DELIVERYFEE : 반품 배송비 청구
\n
EXTRAFEEE : 기타 반품 비용 청구
\n
RETURN_DELIVERYFEE_AND_EXTRAFEEE : 반품 배송비 및 기타 반품 비용 청구
\n
RETURN_PRODUCT_NOT_DELIVERED : 반품 상품 미입고
\n
ETC : 기타 사유
\n
",
"required": false,
"type": "string",
"default": "ETC",
"enum": [
"RETURN_DELIVERYFEE",
"EXTRAFEEE",
"RETURN_DELIVERYFEE_AND_EXTRAFEEE",
"RETURN_PRODUCT_NOT_DELIVERED",
"ETC"
],
"x-portone-name": "반품보류사유 코드",
"x-portone-description": "반품보류사유 코드로 올바르지 않은 보류사유코드인 경우 기본값(`ETC`)를 적용합니다."
},
{
"name": "memo",
"in": "formData",
"description": "반품보류에 대하여 구매자에게 전달하는 메모",
"required": true,
"type": "string",
"x-portone-name": "메모",
"x-portone-description": "반품보류에 대하여 구매자에게 전달하는 메모"
},
{
"name": "extra_charge",
"in": "formData",
"description": "기타 비용 청구액(기본값 : 0원)",
"required": false,
"type": "integer",
"x-portone-name": "기타 비용 청구액",
"x-portone-description": "기타 비용 청구액으로 기본값은 **0원**입니다."
}
],
"responses": {
"200": {
"description": "모든 상품주문 반품보류 처리 성공",
"schema": {
"$ref": "#/definitions/NaverProductOrderArrayResponse"
}
},
"207": {
"description": "일부 상품주문 반품보류 처리성공 & 일부주문 반품보류 처리실패 \n 포트원에서 네이버페이에 반품보류 처리시 product_order_id 개별로 반품보류 처리이 진행되어야 합니다. 일부 건만 성공하는 경우 207 응답이 내려갑니다.\n (모두 성공인 경우 200응답 / 모두 실패인 경우 500응답)",
"schema": {
"$ref": "#/definitions/NaverProductOrderArrayResponse"
}
},
"400": {
"description": "memo 파라미터가 누락되거나 올바르지 않은 경우"
},
"401": {
"description": "인증 Token이 전달되지 않았거나 유효하지 않은 경우"
},
"404": {
"description": "imp_uid에 해당되는 거래건을 찾을 수 없거나 접근 권한이 없는 계정인 경우"
},
"500": {
"description": "모든 상품주문 반품보류 처리실패"
}
},
"x-portone-supported-pgs": [
"naverco"
],
"x-portone-category": "pg.naverpay"
}
},
"/payments/{imp_uid}/naver/resolve-return": {
"post": {
"tags": [
"naver"
],
"summary": "(주문형-네이버페이) 반품보류상품 반품보류해제 처리 API",
"description": "(주문형-네이버페이) 반품보류 상품주문들을 반품보류해제처리합니다. \n 주문상품의 종류가 여러 개인 경우, 한 건의 포트원 거래건(imp_uid)에 여러 개의 네이버페이 상품주문이 존재하며 일부 또는 전체를 반품보류해제 처리할 수 있습니다.\n 시도된 상품주문 중 반품보류해제 처리에 성공한 상품주문에 대한 최종 정보만 제공됩니다.",
"operationId": "naverResolveReturnProductOrder",
"consumes": [
"application/json",
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "imp_uid",
"in": "path",
"description": "네이버페이 반품보류해제 처리할 거래건의 포트원 거래고유번호",
"required": true,
"type": "string",
"x-portone-name": "포트원 거래고유번호",
"x-portone-description": "네이버페이 반품보류해제 처리할 거래건의 포트원 거래고유번호"
},
{
"name": "product_order_id",
"in": "formData",
"description": "반품보류해제 처리할 거래건의 네이버페이 상품주문번호. 생략되면 imp_uid 에 해당되는 모든 상품주문을 반품보류해제 처리합니다.",
"required": false,
"type": "array",
"items": "string",
"x-portone-name": "네이버페이 상품주문번호",
"x-portone-description": "반품보류해제 처리할 거래건의 네이버페이 상품주문번호로 생략되면 imp_uid 에 해당되는 모든 상품주문을 반품보류해제 처리합니다."
}
],
"responses": {
"200": {
"description": "모든 상품주문 반품보류해제 처리 성공",
"schema": {
"$ref": "#/definitions/NaverProductOrderArrayResponse"
}
},
"207": {
"description": "일부 상품주문 반품보류해제 처리성공 & 일부주문 반품보류해제 처리실패 \n 포트원에서 네이버페이에 반품보류해제 처리시 product_order_id 개별로 반품보류해제 처리이 진행되어야 합니다. 일부 건만 성공하는 경우 207 응답이 내려갑니다.\n (모두 성공인 경우 200응답 / 모두 실패인 경우 500응답)",
"schema": {
"$ref": "#/definitions/NaverProductOrderArrayResponse"
}
},
"401": {
"description": "인증 Token이 전달되지 않았거나 유효하지 않은 경우"
},
"404": {
"description": "imp_uid에 해당되는 거래건을 찾을 수 없거나 접근 권한이 없는 계정인 경우"
},
"500": {
"description": "모든 상품주문 반품보류해제 처리실패"
}
},
"x-portone-supported-pgs": [
"naverco"
],
"x-portone-category": "pg.naverpay"
}
},
"/payments/{imp_uid}/naver/point": {
"post": {
"tags": [
"naver"
],
"summary": "(결제형-네이버페이) 네이버페이 포인트 적립 API",
"description": "(결제형-네이버페이) 네이버페이 포인트 적립 API",
"operationId": "naverDepositPoint",
"consumes": [
"application/json",
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "imp_uid",
"in": "path",
"description": "네이버페이 포인트 적립할 거래건의 포트원 거래고유번호",
"required": true,
"type": "string",
"x-portone-name": "포트원 거래고유번호",
"x-portone-description": "네이버페이 포인트 적립할 거래건의 포트원 거래고유번호"
}
],
"responses": {
"200": {
"description": "네이버페이 포인트 적립 성공",
"schema": {
"$ref": "#/definitions/ResponseAnnotation"
}
},
"401": {
"description": "인증 Token이 전달되지 않았거나 유효하지 않은 경우"
},
"404": {
"description": "imp_uid에 해당되는 거래건을 찾을 수 없거나 접근 권한이 없는 계정인 경우"
},
"500": {
"description": "네이버페이 포인트 적립 실패. 응답 BODY의 message 확인 필요"
}
},
"x-portone-supported-pgs": [
"naverpay"
],
"x-portone-category": "pg.naverpay"
}
},
"/payments/{imp_uid}/naver/confirm": {
"post": {
"tags": [
"naver"
],
"summary": "(결제형-네이버페이) 에스크로 주문 확정 API",
"description": "(결제형-네이버페이) 에스크로 주문 확정",
"operationId": "naverConfirmPayment",
"consumes": [
"application/json",
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "imp_uid",
"in": "path",
"description": "네이버페이 구매확정할 거래건의 포트원 거래고유번호",
"required": true,
"type": "string",
"x-portone-name": "포트원 거래고유번호",
"x-portone-description": "네이버페이 구매확정할 거래건의 포트원 거래고유번호"
},
{
"name": "requester",
"in": "formData",
"description": "구매확정 요청자 (admin : 고객사 관리자 (기본값), customer : 구매자)",
"required": false,
"type": "string",
"x-portone-name": "구매확정 요청자",
"x-portone-description": "구매확정 요청자 (admin : 고객사 관리자 (기본값), customer : 구매자)"
}
],
"responses": {
"200": {
"description": "네이버페이 구매확정 성공",
"schema": {
"$ref": "#/definitions/ResponseAnnotation"
}
},
"401": {
"description": "인증 Token이 전달되지 않았거나 유효하지 않은 경우"
},
"404": {
"description": "imp_uid에 해당되는 거래건을 찾을 수 없거나 접근 권한이 없는 계정인 경우"
},
"500": {
"description": "네이버페이 구매확정 실패. 응답 BODY의 message 확인 필요"
}
},
"x-portone-supported-pgs": [
"naverpay"
],
"x-portone-category": "pg.naverpay"
}
},
"/payments/{imp_uid}/naver/product-orders": {
"get": {
"tags": [
"naver"
],
"summary": "(주문형-네이버페이) 포트원 거래고유번호 기준 네이버페이 상품주문 조회 API",
"description": "(주문형-네이버페이) 포트원 거래번호 기준으로 네이버페이 상품주문 목록을 조회합니다. (배열 반환)
\n 네이버페이의 경우 주문하는 상품의 종류별로 주문번호(product_order_id)를 관리합니다. 포트원 거래건 당 1개 이상의 네이버페이 상품주문이 연결되므로,\n 포트원 거래고유번호(imp_uid)에 매핑된 1개 이상의 네이버페이 상품주문번호(product_order_id) 및 상세 내역을 조회할 수 있습니다.
\n
응답 안내
\n
product_order_status
\n
PAYMENT_WAITING : 입금 대기
\n
PAYED : 결제 완료
\n
DELIVERING : 배송 중
\n
DELIVERED : 배송 완료
\n
PURCHASE_DECIDED : 구매 확정
\n
EXCHANGED : 교환 완료
\n
CANCELED : 취소 완료
\n
RETURNED : 반품 완료
\n
CANCELED_BY_NOPAYMENT : 미입금 취소
\n
claim_type
\n
CANCEL : 취소
\n
RETURN : 반품
\n
EXCHANGE : 교환
\n
PURCHASE_DECISION_HOLDBACK : 구매 확정 보류
\n
ADMIN_CANCEL : 직권 취소
\n
claim_status
[ claim_type : CANCEL 일 때 ]
\n
CANCEL_REQUEST : 취소 요청
CANCELING : 취소 처리 중
\n
CANCEL_DONE : 취소 처리 완료
CANCEL_REJECT : 취소 철회
\n
[ claim_type : RETURN 일 때 ]
\n
RETURN_REQUEST : 반품 요청
COLLECTING : 수거 처리 중
COLLECT_DONE : 수거 완료
RETURN_DONE : 반품 완료
RETURN_REJECT : 반품 철회
\n
[ claim_type : EXCHANGE 일 때 ]
\n
EXCHANGE_REQUEST : 교환 요청
\n
COLLECTING : 수거 처리 중
\n
COLLECT_DONE : 수거 완료(교환)
\n
EXCHANGE_REDELIVERING : 교환 재배송 중
\n
EXCHANGE_DONE : 교환 완료
\n
EXCHANGE_REJECT : 교환 거부
\n
[ claim_type : PURCHASE_DECISION_HOLDBACK 일 때 ]
\n
PURCHASE_DECISION_HOLDBACK : 구매 확정 보류
\n
PURCHASE_DECISION_HOLDBACK_REDELIVERING : 구매 확정 보류 재배송 중
\n
PURCHASE_DECISION_REQUEST : 구매 확정 요청
\n
PURCHASE_DECISION_HOLDBACK_RELEASE : 구매 확정 보류 해제
\n
[ claim_type : ADMIN_CANCEL 일 때 ]
\n
ADMIN_CANCELING : 직권 취소 중
ADMIN_CANCEL_DONE : 직권 취소 완료
",
"operationId": "getProductOrders",
"consumes": [
"application/json",
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "imp_uid",
"in": "path",
"description": "네이버페이 상품주문 조회를 위한 포트원 거래 고유번호",
"required": true,
"type": "string",
"x-portone-name": "포트원 거래고유번호",
"x-portone-description": "네이버페이 상품주문 조회를 위한 포트원 거래 고유번호"
}
],
"responses": {
"200": {
"description": "네이버페이 상품주문 조회 성공",
"schema": {
"$ref": "#/definitions/NaverProductOrderArrayResponse"
}
},
"401": {
"description": "인증 Token이 전달되지 않았거나 유효하지 않은 경우"
},
"404": {
"description": "imp_uid에 해당되는 거래건을 찾을 수 없거나 접근 권한이 없는 계정인 경우"
}
},
"x-portone-supported-pgs": [
"naverco"
],
"x-portone-category": "pg.naverpay"
}
},
"/naver/product-orders/{product_order_id}": {
"get": {
"tags": [
"naver"
],
"summary": "(주문형-네이버페이) 네이버페이 상품주문번호로 상품주문 상세 조회 API",
"description": "(주문형-네이버페이) 네이버페이 상품주문번호 기준 네이버페이 상품주문을 조회합니다. (단건 반환)
\n 네이버페이 상품주문번호(product_order_id)를 통해 해당되는 상품주문정보 단건을 조회할 수 있습니다. \n
product_order_status
\n
PAYMENT_WAITING : 입금 대기
\n
PAYED : 결제 완료
DELIVERING : 배송 중
\n
DELIVERED : 배송 완료
PURCHASE_DECIDED : 구매 확정
\n
EXCHANGED : 교환 완료
CANCELED : 취소 완료
\n
RETURNED : 반품 완료
CANCELED_BY_NOPAYMENT : 미입금 취소
\n
claim_type
\n
CANCEL : 취소
RETURN : 반품
EXCHANGE : 교환
\n
PURCHASE_DECISION_HOLDBACK : 구매 확정 보류
\n
ADMIN_CANCEL : 직권 취소
\n
claim_status
[ claim_type : CANCEL 일 때 ]
\n
CANCEL_REQUEST : 취소 요청
\n
CANCELING : 취소 처리 중
\n
CANCEL_DONE : 취소 처리 완료
\n
CANCEL_REJECT : 취소 철회
\n
[ claim_type : RETURN 일 때 ]
\n
RETURN_REQUEST : 반품 요청
\n
COLLECTING : 수거 처리 중
\n
COLLECT_DONE : 수거 완료
\n
RETURN_DONE : 반품 완료
\n
RETURN_REJECT : 반품 철회
\n
[ claim_type : EXCHANGE 일 때 ]
\n
EXCHANGE_REQUEST : 교환 요청
\n
COLLECTING : 수거 처리 중
\n
COLLECT_DONE : 수거 완료(교환)
\n
EXCHANGE_REDELIVERING : 교환 재배송 중
\n
EXCHANGE_DONE : 교환 완료
\n
EXCHANGE_REJECT : 교환 거부
\n
[ claim_type : PURCHASE_DECISION_HOLDBACK 일 때 ]
\n
PURCHASE_DECISION_HOLDBACK : 구매 확정 보류
\n
PURCHASE_DECISION_HOLDBACK_REDELIVERING : 구매 확정 보류 재배송 중
",
"operationId": "partner",
"consumes": [
"application/json",
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "imp_uid",
"in": "path",
"description": "포트원 거래고유번호",
"required": true,
"type": "string",
"x-portone-name": "포트원 거래고유번호",
"x-portone-description": "하위 상점 거래를 등록할 결제건의 포트원 거래고유번호"
},
{
"name": "data",
"in": "formData",
"description": "등록할 하위 상점 및 하위 상점 별 거래 금액 정보 배열 [ 필수항목 ] business_registration_number : 하위 상점 사업자 등록 번호 company_name : 하위 상점 명 amount : 하위 상점 거래 금액 [ 선택항목 ] tax_free : 하위 상점 거래 금액 중 면세 금액 (기본값 : 0) vat_amount : 하위 상점 거래 금액 중 부가세 금액 (기본값 : amount / 11)",
"required": true,
"type": "array",
"items": {
"$ref": "#/definitions/PartnerReceiptsAnnotation"
},
"default": "[
{
"business_registration_number": "하위 상점 사업자 등록 번호1",
"company_name": "하위 상점 명1",
"amount": 1000
},
{
"business_registration_number": "하위 상점 사업자 등록 번호2",
"company_name": "하위 상점 명2",
"amount": 2000
}
]",
"x-portone-name": "등록할 하위 상점 및 하위 상점 별 거래 금액 정보",
"x-portone-description": "imp_uid에 매핑되는 거래 하위를 구성하는 하위 상점 및 하위 상점 별 거래 금액 정보의 배열"
}
],
"responses": {
"200": {
"description": "정상적으로 하위 상점 거래 등록이 완료되었습니다.",
"schema": {
"$ref": "#/definitions/PartnerReceiptResponse"
}
},
"400": {
"description": "필수 파라미터 누락, 결제 미승인, PG사로부터 요청 실패 응답을 받은 경우"
},
"401": {
"description": "인증 Token이 전달되지 않았거나 유효하지 않은 경우"
},
"404": {
"description": "결제내역 검색 실패, 결제건에 등록되어있는 결제연동 내역이 확인 불가한 경우"
},
"500": {
"description": "포트원 내부 이슈로 인한 API 호출 실패"
},
"501": {
"description": "지원하지 않는 PG사"
}
},
"x-portone-supported-pgs": [
"html5_inicis"
],
"x-portone-category": "partner"
}
},
"/payco/orders/status/{imp_uid}": {
"post": {
"tags": [
"payco"
],
"summary": "(페이코) 주문상태 단건 수정 API",
"description": "페이코 주문상품의 상태를 변경합니다",
"operationId": "changeOrderStatus",
"consumes": [
"application/json",
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "imp_uid",
"in": "path",
"description": "포트원 거래고유번호",
"required": true,
"type": "string",
"x-portone-name": "포트원 거래고유번호",
"x-portone-description": "주문상태를 변경할 결제건의 포트원 거래고유번호"
},
{
"name": "status",
"in": "formData",
"description": "주문상품 변경될 상태\n
DELIVERY_START : 배송시작-출고지시
\n
PURCHASE_DECISION : 구매확정
\n
CANCELED : 취소
",
"required": true,
"type": "string",
"enum": [
"DELIVERY_START",
"PURCHASE_DECISION",
"CANCELED"
],
"x-portone-name": "주문상태코드",
"x-portone-description": "변경될 주문상태"
}
],
"responses": {
"200": {
"description": "주문상품 상태 변경 완료",
"schema": {
"$ref": "#/definitions/PaycoStatusResponse"
}
},
"401": {
"description": "인증 Token이 전달되지 않았거나 유효하지 않은 경우"
}
},
"x-portone-supported-pgs": [
"payco"
],
"x-portone-category": "pg.payco"
}
},
"/payments/{imp_uid}/balance": {
"get": {
"tags": [
"payments"
],
"summary": "결제 상세내역 조회 API",
"description": "포트원 거래고유번호로 결제수단별 금액 상세정보를 확인합니다.(현재, PAYCO결제수단에 한해 제공되고 있습니다. 타 PG사의 경우 파라메터 검증 등 검토/협의 단계에 있습니다.",
"operationId": "balanceByImpUid",
"consumes": [
"application/json",
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "imp_uid",
"in": "path",
"description": "포트원 거래고유번호",
"required": true,
"type": "string",
"default": "imp_448280090638",
"x-portone-name": "포트원 거래고유번호",
"x-portone-description": "상세정보를 조회할 결제건의 포트원 거래고유번호"
}
],
"responses": {
"200": {
"description": "정상 조회",
"schema": {
"$ref": "#/definitions/PaymentBalanceResponse"
}
},
"401": {
"description": "인증 Token이 전달되지 않았거나 유효하지 않은 경우"
},
"404": {
"description": "유효하지 않은 imp_uid"
},
"405": {
"description": "허용되지 않는 HTTP METHOD"
}
},
"x-portone-supported-pgs": [
"payco"
],
"x-portone-category": "payment"
}
},
"/payments/{imp_uid}": {
"get": {
"tags": [
"payments"
],
"summary": "결제내역 단건조회 API",
"description": "포트원 거래고유번호로 결제내역을 확인합니다",
"operationId": "getPaymentByImpUid",
"consumes": [
"application/json",
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "imp_uid",
"in": "path",
"description": "포트원 거래고유번호",
"required": true,
"type": "string",
"default": "imp_448280090638",
"x-portone-name": "포트원 거래고유번호",
"x-portone-description": "결제내역을 확인할 결제건의 포트원 거래고유번호"
},
{
"name": "include_sandbox",
"in": "query",
"description": "테스트 채널을 통해 발생한 결제건을 조회 결과에 포함할지 여부 (default: false)",
"required": false,
"type": "boolean",
"x-portone-name": "테스트 결제건 포함 여부",
"x-portone-description": "테스트 채널을 통해 발생한 결제건을 조회 결과에 포함할지 여부 (기본값: `false`)"
}
],
"responses": {
"200": {
"description": "정상 조회",
"schema": {
"$ref": "#/definitions/PaymentResponse"
}
},
"401": {
"description": "인증 Token이 전달되지 않았거나 유효하지 않은 경우"
},
"404": {
"description": "유효하지 않은 imp_uid"
}
},
"x-portone-category": "payment",
"x-portone-per-pg": {
"daou": {
"description": "키움페이(구 다우, 페이조아)는 (발급된) 가상계좌에 입금 완료시, 송금자의 정보(은행명, 계좌번호, 송금인) 중 **송금자 이름**만 알려줍니다.\n 따라서 송금자의 은행코드(`bank_code`)과 은행명(`bank_name`)은 모두 **NULL**로 내려가며, 송금자 이름을 확인하기 위해서는 아래 예시와 같이 별도의 쿼리 파라미터(`extension`)를 **true**로 설정해주셔야 합니다.\n ```text\n GET http://api.iamport.kr/payments/{포트원 거래고유번호}?**extension=true**\n ```\n\n ```json\n {\n // ... 중략\n \"bank_code\": null, // 송금자 은행 코드 알 수 없음\n \"bank_name\": null, // 송금자 은행 이름 알 수 없음\n \"extension\": {\n // ... 중략\n \"REMITTER\": \"홍길동\" // 송금자 이름\n }\n }\n ```\n "
},
"paypal_v2": {
"description": "페이팔 결제 건은 승인 요청 시 바로 승인 되지 않고 일정 시간 후 처리되는 승인 대기(`pending`) 상태가 존재합니다.\n 따라서 고객사는 트랜잭션 종료시 결제 내역을 조회(GET /payments/{imp_uid})한 후 응답 되는 status를 보고 각 상황에 맞는 후 처리 로직을 작성해야 합니다.\n 승인 대기 상태에서는 최종적으로 승인(`paid`)이 될 수도 있고 승인이 되지 않을 수도(`failed`) 있기 때문에 고객사는 반드시\n (가상계좌나 정기결제와 같이 결제가 비동기로 승인되는 경우 포트원 → 고객사로 결제 결과를 통보해주는) 웹훅 기능을 연동해야 합니다."
}
}
}
},
"/payments": {
"get": {
"tags": [
"payments"
],
"summary": "결제내역 복수조회 API",
"description": "여러 개의 포트원 거래고유번호 또는 고객사 주문번호로 결제내역을 한 번에 조회합니다.(최대 100개)\n (예시) /payments?imp_uid[]=imp_448280090638&imp_uid[]=imp_448280090639&merchant_uid[]=merchant_143434085216",
"operationId": "getPaymentListByImpUid",
"consumes": [
"application/json",
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "imp_uid[]",
"in": "query",
"description": "포트원 거래고유번호",
"required": false,
"type": "array",
"items": {
"type": "string"
},
"collectionFormat": "multi",
"default": "imp_448280090638",
"x-portone-name": "포트원 거래고유번호",
"x-portone-description": "조회할 결제건의 포트원 거래고유번호 리스트"
},
{
"name": "merchant_uid[]",
"in": "query",
"description": "결제요청 시 고객사에서 요청한 merchant_uid",
"required": false,
"type": "array",
"items": {
"type": "string"
},
"collectionFormat": "multi",
"default": "merchant_143434085216",
"x-portone-name": "고객사 주문번호",
"x-portone-description": "결제요청 시 고객사에서 요청한 고객사 주문번호"
}
],
"responses": {
"200": {
"description": "요청된 모든 imp_uid 에 대한 결제정보 응답완료",
"schema": {
"$ref": "#/definitions/MultiplePaymentsResponse"
}
},
"207": {
"description": "요청된 imp_uid 중 일부 거래 조회 실패(ex. 접근권한없음 또는 존재하지 않는 imp_uid)",
"schema": {
"$ref": "#/definitions/MultiplePaymentsResponse"
}
},
"401": {
"description": "인증 Token이 전달되지 않았거나 유효하지 않은 경우"
},
"404": {
"description": "해당되는 결제건을 찾지 못하였습니다."
}
},
"x-portone-category": "payment"
}
},
"/payments/find/{merchant_uid}/{payment_status}": {
"get": {
"tags": [
"payments"
],
"summary": "결제 단건조회(고유 고객사 주문번호 조회) API",
"description": "고객사지정 고유번호로 결제내역을 확인합니다 \n 동일한 merchant_uid가 여러 건 존재하는 경우, 정렬 기준에 따라 가장 첫 번째 해당되는 건을 반환합니다.\n (모든 내역에 대한 조회가 필요하시면 GET 결제 복수조회(고객사 주문번호 중복 포함) API를 사용해주세요.)
\n payment_status를 추가로 지정하시면, 해당 status에 해당하는 가장 최신 데이터를 반환합니다.",
"operationId": "getPaymentByMerchantUid",
"consumes": [
"application/json",
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "merchant_uid",
"in": "path",
"description": "결제요청 시 고객사에서 요청한 merchant_uid",
"required": true,
"type": "string",
"default": "merchant_1448280088556",
"x-portone-name": "고객사 주문번호",
"x-portone-description": "결제요청 시 고객사에서 요청한 고객사 주문번호"
},
{
"name": "payment_status",
"in": "path",
"description": "특정 status상태의 값만 필터링하고 싶은 경우에 사용. 지정하지 않으면 모든 상태를 대상으로 조회합니다.
ready(미결제)
paid(결제완료)
failed(결제실패)
cancelled(환불취소)
",
"required": false,
"type": "string",
"default": "",
"x-portone-name": "거래상태 구분코드",
"x-portone-description": "특정 status상태의 값만 필터링하고 싶은 경우에 사용하는 파라미터로 지정하지 않으면 **모든 상태**를 대상으로 조회합니다"
},
{
"name": "sorting",
"in": "query",
"description": "기본값은 -started 마이너스(-) 기호가 앞에 붙으면 내림차순 정렬을 의미합니다. \n
-started : 결제시작시각(결제창오픈시각) 기준 내림차순(DESC) 정렬\n
started : 결제시작시각(결제창오픈시각) 기준 오름차순(ASC) 정렬\n
-paid : 결제완료시각 기준 내림차순(DESC) 정렬\n
paid : 결제완료시각 기준 오름차순(ASC) 정렬\n
-updated : 최종수정시각(결제건 상태변화마다 수정시각 변경됨) 기준 내림차순(DESC) 정렬\n
updated : 최종수정시각(결제건 상태변화마다 수정시각 변경됨) 기준 오름차순(ASC) 정렬
",
"required": false,
"type": "string",
"default": "-started",
"enum": [
"-started",
"started",
"-paid",
"paid",
"-updated",
"updated"
],
"x-portone-name": "정렬구분코드",
"x-portone-description": "정렬 기준을 설정하는 파라미터로 기본값은 `-started`입니다."
}
],
"responses": {
"200": {
"description": "정상 조회",
"schema": {
"$ref": "#/definitions/PaymentResponse"
}
},
"401": {
"description": "인증 Token이 전달되지 않았거나 유효하지 않은 경우"
},
"404": {
"description": "거래건이 존재하지 않는 경우"
}
},
"x-portone-category": "payment"
}
},
"/payments/findAll/{merchant_uid}/{payment_status}": {
"get": {
"tags": [
"payments"
],
"summary": "결제 복수조회(고객사 주문번호 중복 포함) API",
"description": "고객사지정 고유번호 및 상태기준으로 결제내역을 확인합니다 동일한 merchant_uid가 여러 건 존재하는 경우, 존재하는 모든 거래가 조회됩니다.\n
payment_status를 추가로 지정하시면, 해당 status에 해당하는 가장 최신 데이터를 반환합니다.",
"operationId": "getAllPaymentsByMerchantUid",
"consumes": [
"application/json",
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "merchant_uid",
"in": "path",
"description": "결제요청 시 고객사에서 요청한 merchant_uid",
"required": true,
"type": "string",
"default": "merchant_1448280088556",
"x-portone-name": "고객사 주문번호",
"x-portone-description": "결제요청 시 고객사에서 요청한 고객사 주문번호"
},
{
"name": "payment_status",
"in": "path",
"description": "특정 status상태의 값만 필터링하고 싶은 경우에 사용. 지정하지 않으면 모든 상태를 조회합니다.
-updated : 최종수정시각(결제건 상태변화마다 수정시각 변경됨) 기준 내림차순(DESC) 정렬\n
updated : 최종수정시각(결제건 상태변화마다 수정시각 변경됨) 기준 오름차순(ASC) 정렬
",
"required": false,
"type": "string",
"default": "-started",
"enum": [
"-started",
"started",
"-paid",
"paid",
"-updated",
"updated"
],
"x-portone-name": "정렬기준",
"x-portone-description": "정렬기준을 나타내는 파라미터로 기본값은 `-started`입니다."
}
],
"responses": {
"200": {
"description": "정상 조회",
"schema": {
"$ref": "#/definitions/PaymentListResponse"
}
},
"400": {
"description": "merchant_uid누락, 올바르지 않은 status 등 파라메터가 잘못된 경우"
},
"401": {
"description": "인증 Token이 전달되지 않았거나 유효하지 않은 경우"
},
"404": {
"description": "유효하지 않은 merchant_uid"
}
},
"x-portone-category": "payment"
}
},
"/payments/status/{payment_status}": {
"get": {
"tags": [
"payments"
],
"summary": "결제상태기준 복수조회 API",
"description": "미결제/결제완료/결제취소/결제실패 상태 별로 검색할 수 있습니다.(20건씩 최신순 페이징)
\n 검색기간은 최대 90일까지이며 to파라메터의 기본값은 현재 unix timestamp이고 from파라메터의 기본값은 to파라메터 기준으로 90일 전입니다.\n 때문에, from/to 파라메터가 없이 호출되면 현재 시점 기준으로 최근 90일 구간에 대한 데이터를 검색하게 됩니다. \n from, to 파라메터를 지정하여 90일 단위로 과거 데이터 조회는 가능합니다. ",
"operationId": "getPaymentsByStatus",
"consumes": [
"application/json",
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "payment_status",
"in": "path",
"description": "
시간별 검색 시작 시각(>=) UNIX TIMESTAMP. 결제건의 최종 status에 따라 다른 검색기준이 적용됩니다. ready : 결제시작 시각 기준 paid : 결제완료 시각 기준 cancelled : 결제취소 시각 기준 failed : 결제실패 시각 기준",
"required": false,
"type": "integer",
"x-portone-name": "검색 시작 시각",
"x-portone-description": "기본값은 to 파라메터 기준으로 **90일** 전 unix timestamp입니다. (시간별 검색 시작 시각(>=) UNIX TIMESTAMP)"
},
{
"name": "to",
"in": "query",
"description": "기본값 : 현재 unix timestamp
시간별 검색 종료 시각(<=) UNIX TIMESTAMP. 결제건의 최종 status에 따라 다른 검색기준이 적용됩니다. ready : 결제시작 시각 기준 paid : 결제완료 시각 기준 cancelled : 결제취소 시각 기준 failed : 결제실패 시각 기준",
"required": false,
"type": "integer",
"x-portone-name": "검색 종료 시각",
"x-portone-description": "기본값은 현재 unix timestamp입니다. (시간별 검색 종료 시각(<=) UNIX TIMESTAMP)"
},
{
"name": "sorting",
"in": "query",
"description": "기본값은 -started 마이너스(-) 기호가 앞에 붙으면 내림차순 정렬을 의미합니다. \n
-started : 결제시작시각(결제창오픈시각) 기준 내림차순(DESC) 정렬\n
started : 결제시작시각(결제창오픈시각) 기준 오름차순(ASC) 정렬\n
-paid : 결제완료시각 기준 내림차순(DESC) 정렬\n
paid : 결제완료시각 기준 오름차순(ASC) 정렬\n
-updated : 최종수정시각(결제건 상태변화마다 수정시각 변경됨) 기준 내림차순(DESC) 정렬\n
updated : 최종수정시각(결제건 상태변화마다 수정시각 변경됨) 기준 오름차순(ASC) 정렬
",
"required": false,
"type": "string",
"default": "-started",
"enum": [
"-started",
"started",
"-paid",
"paid",
"-updated",
"updated"
],
"x-portone-name": "정렬기준",
"x-portone-description": "정렬기준을 나타내는 파라미터로 기본값은 `-started`입니다."
}
],
"responses": {
"200": {
"description": "정상 조회",
"schema": {
"$ref": "#/definitions/PaymentListResponse"
}
},
"401": {
"description": "인증 Token이 전달되지 않았거나 유효하지 않은 경우"
},
"400": {
"description": "유효하지 않은 payment_status인 경우, 데이터 범위를 넘어선 page인 경우"
}
},
"x-portone-category": "payment"
}
},
"/payments/cancel": {
"post": {
"tags": [
"payments"
],
"summary": "결제취소 API",
"description": "승인된 결제를 취소합니다. 신용카드/실시간계좌이체/휴대폰소액결제의 경우 즉시 취소처리가 이뤄지게 되며,\n 가상계좌와 휴대폰소액결제 익월 환불(KCP)의 경우는 환불받으실 계좌정보를 같이 전달해주시면 환불정보가 PG사에 등록되어 익영업일에 처리됩니다.\n (가상계좌 환불, 휴대폰소액결제 익월 환불(KCP)의 경우 관련 특약계약 필요)",
"operationId": "cancelPayment",
"consumes": [
"application/json",
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "imp_uid",
"in": "formData",
"description": "취소할 거래의 포트원 거래고유번호",
"required": false,
"type": "string",
"x-portone-name": "포트원 거래고유번호",
"x-portone-description": "취소할 거래의 포트원 거래고유번호"
},
{
"name": "merchant_uid",
"in": "formData",
"description": "고객사에서 전달한 거래 고유번호. imp_uid, merchant_uid 중 하나는 필수이어야 합니다. 두 값이 모두 넘어오면 imp_uid를 우선 적용합니다.",
"required": false,
"type": "string",
"x-portone-name": "고객사 주문번호",
"x-portone-description": "고객사에서 전달한 거래 고유번호로 imp_uid, merchant_uid 중 하나는 필수이어야 합니다. (두 값이 모두 넘어오면 **imp_uid를 우선 적용**합니다.)"
},
{
"name": "amount",
"in": "formData",
"description": "(부분)취소요청 금액
누락하거나 0을 입력하는 경우 전액 취소 요청합니다.
",
"required": false,
"type": "number",
"x-portone-name": "(부분)취소 요청금액",
"x-portone-summary": "(부분)취소요청금액으로 누락하거나 0을 입력 시 전액취소를 요청합니다.",
"x-portone-description": "(부분)취소요청 금액으로 **(누락하거나 0을 입력하는 경우 전액 취소 요청합니다.)**"
},
{
"name": "tax_free",
"in": "formData",
"description": "(부분)취소요청금액 중 면세금액(누락되면 0원처리)
단, 아래 PG사의 경우 자동으로 0원 처리 되지 않으므로 면세 결제에 한하여 필수 입력 바랍니다.
kcp
kcp_quick
kicc
nice
payco
",
"required": false,
"type": "number",
"x-portone-name": "(부분)취소요청 금액 중 면세금액",
"x-portone-summary": "(부분)취소요청금액 중 면세금액으로 누락되면 0원처리합니다.",
"x-portone-description": "단, 아래 PG사의 경우 자동으로 0원 처리 되지 않으므로 면세 결제에 한하여 **필수 입력** 바랍니다.",
"x-portone-per-pg": {
"kcp": {
"description": "누락시 자동으로 0원 처리 되지 않으므로 면세 결제에 한하여 필수 입력 바랍니다."
},
"kcp_quick": {
"description": "누락시 자동으로 0원 처리 되지 않으므로 면세 결제에 한하여 필수 입력 바랍니다."
},
"kicc": {
"description": "누락시 자동으로 0원 처리 되지 않으므로 면세 결제에 한하여 필수 입력 바랍니다."
},
"nice": {
"description": "누락시 자동으로 0원 처리 되지 않으므로 면세 결제에 한하여 필수 입력 바랍니다."
},
"payco": {
"description": "누락시 자동으로 0원 처리 되지 않으므로 면세 결제에 한하여 필수 입력 바랍니다."
},
"smartro_v2": {
"description": "부분취소시 면세 금액이 포함된 경우 반드시 취소 면세금액(tax_free)을 필수 입력 바랍니다"
},
"welcome": {
"description": "**`부가세업체정함` 설정 고객사에 한해 결제 시 면세금액을 지정했던 경우 필수** 입력 바라며, 입력한 면세금액이 그대로 취소 승인되기 때문에 정확한 금액을 입력해 주시길 바랍니다."
}
}
},
{
"name": "vat_amount",
"in": "formData",
"description": "(부분)취소요청금액 중 부가세 금액(기본값: null). 단, 결제 시 부가세를 지정했던 경우 필수 입력 바랍니다.
지원되는 PG사
나이스페이먼츠(nice)
이니시스(html5_inicis)
웰컴페이먼츠
(신) 나이스페이먼츠(nice_v2)
",
"required": false,
"type": "number",
"x-portone-name": "(부분)취소요청금액 중 부가세 금액",
"x-portone-summary": "(부분)취소요청금액 중 부가세 금액으로 기본값은 `null`입니다.",
"x-portone-description": "단, **결제 시 부가세를 지정했던 경우 필수** 입력 바랍니다.",
"x-portone-supported-pgs": [
"nice",
"html5_inicis",
"welcome",
"nice_v2"
],
"x-portone-per-pg": {
"nice": {
"description": "**결제 시 부가세를 지정했던 경우 필수** 입력 바랍니다."
},
"html5_inicis": {
"description": "**결제 시 부가세를 지정했던 경우 필수** 입력 바랍니다."
},
"welcome": {
"description": "**`부가세업체정함` 설정 고객사에 한해 결제 시 부가세를 지정했던 경우 필수** 입력이 필요하며, 입력한 부가세가 그대로 취소 승인되기 때문에 정확한 금액을 입력해 주시길 바랍니다."
}
}
},
{
"name": "checksum",
"in": "formData",
"description": "취소 트랜잭션 수행 전, 현재시점의 취소 가능한 잔액.
빌링키 저장 시, buyer_email, buyer_name 등의 정보는 customer 부가정보인 customer_email, customer_name 등으로 함께 저장됩니다. 빌링키 발급 API참조",
"operationId": "onetime",
"consumes": [
"application/json",
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "merchant_uid",
"in": "formData",
"description": "고객사 거래 고유번호 매 결제요청 시 고유값으로 요청해야 합니다.",
"required": true,
"type": "string",
"maxLength": 40,
"x-portone-name": "고객사 주문번호",
"x-portone-description": "고객사 거래 고유번호로 매 결제요청 시 고유값으로 요청해야 합니다."
},
{
"name": "currency",
"in": "formData",
"description": "(Paymentwall 전용) 통화 e.g.) KRW, USD, VND, ... Default: KRW",
"required": false,
"type": "string",
"x-portone-name": "결제통화 구분코드",
"x-portone-description": "통화 e.g.) KRW, USD, VND, ... Default: KRW",
"x-portone-per-pg": {
"ksnet": {
"description": "USD 결제는 순수 해외카드로만 결제 가능합니다."
}
}
},
{
"name": "amount",
"in": "formData",
"description": "결제금액",
"required": true,
"type": "number",
"x-portone-name": "결제금액",
"x-portone-description": "결제요청 할 금액"
},
{
"name": "tax_free",
"in": "formData",
"description": "amount 중 면세공급가액. 기본값은 0이므로(amount 모두 과세대상이므로) amount의 1/11 이 부가세로 처리됩니다.",
"required": false,
"type": "number",
"x-portone-name": "면세금액",
"x-portone-description": "amount 중 면세공급가액",
"x-portone-per-pg": {
"ksnet": {
"description": "면세 설정 상점아이디에서 면세처리를 위해 결제 금액과 동일한 면세 금액을 반드시 입력해야 합니다. 그렇지 않은 경우 매출전표에 전액 면세가 아닌 것으로 표시되고 실제 처리 내역이 다를 수 있습니다.\n\n과세 설정 상점아이디에서 면세 금액을 전달하지 않아야 합니다. 면세 금액을 전달하는 경우 매출전표에 면세 처리된 것으로 표시되지만 실제 처리 내역과 다를 수 있습니다."
},
"welcome": {
"description": "`부가세업체정함` 설정 고객사에 한해 사용 가능합니다."
}
}
},
{
"name": "vat_amount",
"in": "formData",
"description": "amount 중 부가세 금액. 부가세를 지정할 수 있으며, tax_free=0, vat_amount=0으로 영세율로 결제 가능합니다.(기본값: null)
지원되는 PG사
나이스페이먼츠
이니시스
(신) 나이스페이
웰컴페이먼츠
",
"required": false,
"type": "number",
"x-portone-name": "부가세",
"x-portone-summary": "amount 중 부가세 금액",
"x-portone-description": "부가세를 지정할 수 있으며, `tax_free=0, vat_amount=0`으로 영세율로 결제 가능합니다.\nPG사와의 사전 협의 후 사용가능합니다. (기본값: **null**)",
"x-portone-supported-pgs": [
"nice",
"html5_inicis",
"nice_v2",
"welcome"
],
"x-portone-per-pg": {
"welcome": {
"description": "`부가세업체정함` 설정 고객사에 한해 사용 가능하며 전체금액의 10% 이하로 설정해야 합니다. vat_amount가 총 상품가격의 10%를 초과할 경우는 결제가 거절됩니다."
}
}
},
{
"name": "vat",
"in": "formData",
"description": "Deprecated 되었습니다. tax_free 파라메터를 사용해주세요. 결제금액 중 부가세 금액(파라메터가 누락되면 10%로 자동 계산됨)",
"required": false,
"type": "number",
"deprecated": true
},
{
"name": "card_number",
"in": "formData",
"description": "카드번호(dddd-dddd-dddd-dddd) 기재 양식을 유의하세요.",
"required": true,
"type": "string",
"x-portone-name": "카드번호",
"x-portone-description": "카드번호(`dddd-dddd-dddd-dddd`) 기재 양식을 유의하세요."
},
{
"name": "expiry",
"in": "formData",
"description": "카드 유효기간(YYYY-MM) 기재 양식을 유의하세요.",
"required": true,
"type": "string",
"x-portone-name": "카드 유효기간",
"x-portone-description": "카드 유효기간(`YYYY-MM`) 기재 양식을 유의하세요."
},
{
"name": "birth",
"in": "formData",
"description": "생년월일6자리(YYMMDD) (법인카드의 경우 사업자등록번호10자리) (생년월일기재가 필요없는 해외 PG사 결제 요청의 경우 000000으로 고정 기재하도 무방)",
"required": false,
"type": "string",
"x-portone-name": "생년월일 6자리",
"x-portone-summary": "생년월일6자리(`YYMMDD`) (법인카드의 경우 사업자등록번호10자리)",
"x-portone-description": "PG사별로 혹은 계약상황에 따라 필수값 여부가 상이합니다.\n\n생년월일 기재가 필요없는 해외 PG사 결제 요청의 경우 `000000`으로 고정 기재하도 무방합니다.",
"x-portone-per-pg": {
"ksnet": {
"description": "카드번호와 유효기간만으로 결제를 요청하는 비인증 승인 API만 연동되어 있어\n `birth`(생년월일 6자리 혹은 사업자 등록번호 10자리)는 검증하지 않습니다."
}
}
},
{
"name": "pwd_2digit",
"in": "formData",
"description": "카드비밀번호 앞 2자리 PG사별로 혹은 계약상황에따라 필수값 여부가 상이합니다.",
"required": false,
"type": "string",
"x-portone-name": "카드비밀번호 앞 2자리",
"x-portone-summary": "결제 요청할 카드의 비밀번호 앞 2자리",
"x-portone-description": "PG사별로 혹은 계약상황에 따라 필수값 여부가 상이합니다.",
"x-portone-per-pg": {
"ksnet": {
"description": "카드번호와 유효기간만으로 결제를 요청하는 비인증 승인 API만 연동되어 있어\n `pwd_2digit`(생년월일 6자리 혹은 사업자 등록번호 10자리)는 검증하지 않습니다."
}
}
},
{
"name": "cvc",
"in": "formData",
"description": "카드 인증번호 (카드 뒷면 3자리, AMEX의 경우 4자리). Paymentwall에서만 사용",
"required": false,
"type": "string",
"x-portone-name": "카드 인증번호",
"x-portone-description": "결제 요청할 카드의 인증번호 (카드 뒷면 3자리, AMEX의 경우 4자리)",
"x-portone-supported-pgs": [
"paymentwall"
],
"x-portone-per-pg": {
"paymentwall": {
"required": true
}
}
},
{
"name": "customer_uid",
"in": "formData",
"description": "빌링키와 매핑되며 고객사에서 채번하는 구매자의 결제 수단 식별 고유번호.
(결제에 사용된 카드정보를 빌링키 형태로 저장해두고 결제에 사용하시려면 customer_uid를 지정해주세요. 비 인증 결제(빌링키) API, 결제 예약 API로 결제를 진행하실 수 있습니다. customer_uid가 없는 경우 저장되지 않습니다.)",
"required": false,
"type": "string",
"maxLength": 80,
"x-portone-name": "구매자의 결제 수단 식별 고유번호",
"x-portone-description": "빌링키와 매핑되며 고객사에서 채번하는 구매자의 결제 수단 식별 고유번호",
"x-portone-unsupported-pgs": [
"ksnet",
"tosspayments"
]
},
{
"name": "pg",
"in": "formData",
"description": "API 방식 비인증 PG설정이 2개 이상인 경우, 결제가 진행되길 원하는 PG사를 지정하실 수 있습니다. pg 파라메터는 {PG사} 혹은 {PG사}.{PG상점아이디} 형태의 문자열입니다. 지정하지 않거나 유효하지 않은 값이 전달되면 기본PG설정된 값을 이용해 결제하게 됩니다.
나이스페이먼츠, KCP 2가지 PG설정이 되어있다면, pg 파라메터로 nice 또는 kcp로 구분 가능
나이스페이먼츠로부터 2개 이상의 상점아이디를 발급받았다면, nice.MID1 또는 nice.MID2로 구분 가능
스마트 라우팅 그룹 ID를 지정하여 결제를 요청하면, 스마트 라우팅 그룹 내 설정된 채널 비율에 따라 확률 기반으로 하나의 결제대행사로 결제 요청을 합니다. 이때, pg 파라메터는 무시됩니다.
",
"required": false,
"type": "string",
"maxLength": 55,
"x-portone-name": "스마트 라우팅 그룹 ID",
"x-portone-description": "스마트 라우팅 그룹 내 설정된 채널 비율에 따라 확률 기반으로 하나의 결제대행사로 결제 요청을 합니다."
},
{
"name": "name",
"in": "formData",
"description": "제품명",
"required": false,
"type": "string",
"maxLength": 40,
"x-portone-name": "주문명",
"x-portone-description": "결제요청 할 결제건의 주문명",
"x-portone-per-pg": {
"html5_inicis": {
"required": true
}
}
},
{
"name": "buyer_name",
"in": "formData",
"description": "주문자명 (필수 : KSNET, 웰컴페이먼츠) 페이먼트월 PG를 이용하는 경우 구매자명은 first name 과 last name이 한칸 띄어쓰기 형태로 구분되서 유입되어야 합니다. 예시) Michael Jackson",
"required": false,
"type": "string",
"maxLength": 16,
"x-portone-name": "구매자명",
"x-portone-description": "결제건의 구매자명",
"x-portone-per-pg": {
"html5_inicis": {
"required": true
},
"ksnet": {
"required": true
},
"welcome": {
"required": true
},
"paymentwall": {
"description": "구매자명은 first name 과 last name이 **한칸 띄어쓰기** 형태로 구분되서 유입되어야 합니다. 예시) Michael Jackson"
}
}
},
{
"name": "buyer_email",
"in": "formData",
"description": "주문자 E-mail주소",
"required": false,
"type": "string",
"maxLength": 64,
"x-portone-name": "주문자 E-mail 주소",
"x-portone-description": "결제건의 주문자 E-mail주소",
"x-portone-per-pg": {
"html5_inicis": {
"required": true
}
}
},
{
"name": "buyer_tel",
"in": "formData",
"description": "주문자 전화번호",
"required": false,
"type": "string",
"maxLength": 16,
"x-portone-name": "주문자 전화번호",
"x-portone-description": "결제건의 주문자 전화번호",
"x-portone-per-pg": {
"html5_inicis": {
"required": true
}
}
},
{
"name": "buyer_addr",
"in": "formData",
"description": "주문자 주소",
"required": false,
"type": "string",
"maxLength": 128,
"x-portone-name": "주문자 주소",
"x-portone-description": "결제건의 주문자 주소"
},
{
"name": "buyer_postcode",
"in": "formData",
"description": "주문자 우편번호",
"required": false,
"type": "string",
"maxLength": 8,
"x-portone-name": "주문자 우편번호",
"x-portone-description": "결제건의 주문자 우편번호"
},
{
"name": "card_quota",
"in": "formData",
"description": "카드할부개월수. 2 이상의 integer 할부개월수 적용 (결제금액 50,000원 이상 한정, default = 0(일시불)) ",
"required": false,
"type": "integer",
"x-portone-name": "카드할부개월수",
"x-portone-summary": "결제건의 카드할부개월수으로 기본값은 **0(일시불)**입니다.",
"x-portone-description": "결제금액 50,000원 이상 한정으로 2 이상의 integer 할부개월수가 적용가능합니다."
},
{
"name": "interest_free_by_merchant",
"in": "formData",
"description": "카드할부처리할 때, 할부이자가 발생하는 경우(카드사 무이자 프로모션 제외) 부과되는 할부이자를 고객대신 고객사가 지불하고자 PG사와 계약된 경우 (현재, 나이스페이먼츠, (신) 나이스페이만 지원됨)",
"required": false,
"type": "boolean",
"default": false,
"x-portone-name": "고객사 부담 무이자 할부여부",
"x-portone-description": "카드할부처리할 때, 할부이자가 발생하는 경우(카드사 무이자 프로모션 제외) 부과되는 할부이자를 고객대신 고객사가 지불하는지에 대한 여부 (**PG사와 사전 계약이 필요**)",
"x-portone-supported-pgs": [
"nice_v2",
"nice"
]
},
{
"name": "use_card_point",
"in": "formData",
"description": "승인요청시 카드사 포인트 차감하며 결제승인처리할지 여부 flag. PG사 영업담당자와 계약 당시 사전 협의 필요 (현재, (신) 나이스페이만 지원됨)",
"required": false,
"type": "boolean",
"default": false,
"x-portone-name": "카드포인트 사용여부",
"x-portone-description": "승인요청시 카드사 포인트 차감하며 결제승인처리할지 여부 flag. **PG사 영업담당자와 계약 당시 사전 협의 필요**",
"x-portone-supported-pgs": [
"ksnet",
"nice",
"nice_v2"
]
},
{
"name": "custom_data",
"in": "formData",
"description": "거래정보와 함께 저장할 추가 정보",
"required": false,
"type": "string",
"x-portone-name": "추가 정보",
"x-portone-description": "거래정보와 함께 저장할 추가 정보"
},
{
"name": "notice_url",
"in": "formData",
"description": "결제성공 시 통지될 Notification URL(Webhook URL)",
"required": false,
"type": "string",
"x-portone-name": "Notification URL(Webhook URL)",
"x-portone-description": "결제성공 시 통지될 Notification URL(Webhook URL)"
},
{
"name": "browser_ip",
"in": "formData",
"description": "구매자 브라우저(PC)의 IP (입력하지 않은 경우 API를 호출한 클라이언트 IP로 설정됩니다.)",
"required": false,
"type": "string",
"x-portone-name": "브라우저 IP",
"x-portone-description": "구매자 브라우저(PC)의 IP",
"x-portone-per-pg": {
"paymentwall": {
"required": true
}
}
},
{
"name": "secure_3d_charge_id",
"in": "formData",
"description": "(해외PG 전용) 3D secure 인증 후 결제시 PG사에서 부여한 결제 ID",
"required": false,
"type": "string",
"x-portone-name": "결제 ID",
"x-portone-description": "해외PG 전용 파라미터로 3D secure 인증 후 결제시 PG사에서 부여한 결제 ID",
"x-portone-supported-pgs": [
"paymentwall"
]
},
{
"name": "secure_3d_token",
"in": "formData",
"description": "(해외PG 전용) 3D secure 인증 후 결제시 PG사에서 부여한 토큰",
"required": false,
"type": "string",
"x-portone-name": "토큰",
"x-portone-description": "해외PG 전용 파라미터로 3D secure 인증 후 결제시 PG사에서 부여한 토큰",
"x-portone-supported-pgs": [
"paymentwall"
]
},
{
"name": "product_type",
"in": "formData",
"description": "판매 상품에 대한 구분 값 real : 실물상품 digital : 디지털 컨텐츠 (필수 : KSNET)",
"required": false,
"type": "string",
"enum": [
"real",
"digital"
],
"x-portone-name": "주문 상품구분",
"x-portone-description": "결제 요청할 판매 상품에 대한 구분 값",
"x-portone-supported-pgs": [
"ksnet"
],
"x-portone-per-pg": {
"ksnet": {
"required": true
}
}
},
{
"name": "promotion_id",
"in": "formData",
"description": "`promotion-id-`로 시작하며, 프로모션 아이디에 설정된 할인 내용을 적용하여 결제합니다. 비인증 결제 경우 빌링키 발급시 저장된 마스킹된 카드번호를 통해 프로모션 적용 여부가 결정됩니다.",
"required": false,
"type": "string",
"x-portone-name": "프로모션 아이디",
"x-portone-description": "`promotion-id-`로 시작하며, 프로모션 아이디에 설정된 할인 내용을 적용하여 결제합니다. 비인증 결제 경우 빌링키 발급시 저장된 마스킹된 카드번호를 통해 프로모션 적용 여부가 결정됩니다."
},
{
"name": "bypass",
"in": "formData",
"description": "JSON string 형식의 PG사별로 특화된 파라미터. 전달 한 값은 가공 없이 그대로 PG사로 전달 됩니다. 각 PG사별 스펙은 PG사별 연동 문서 참고해주세요",
"required": false,
"type": "string",
"x-portone-name": "bypass 데이터",
"x-portone-summary": "JSON string 형식의 PG사별로 특화된 파라미터",
"x-portone-description": "전달 한 값은 가공 없이 그대로 PG사로 전달 됩니다. 각 PG사별 스펙은 PG사별 연동 문서 참고해주세요"
}
],
"responses": {
"200": {
"description": "정상 결제",
"schema": {
"$ref": "#/definitions/PaymentResponse"
}
},
"401": {
"description": "인증 Token이 전달되지 않았거나 유효하지 않은 경우"
}
},
"x-portone-supported-pgs": [
"daou",
"kcp",
"nice",
"nice_v2",
"html5_inicis",
"paymentwall",
"settle",
"tosspayments",
"ksnet",
"welcome"
],
"x-portone-category": "nonAuthPayment"
}
},
"/subscribe/payments/again": {
"post": {
"tags": [
"subscribe"
],
"summary": "비 인증 결제(빌링키) API",
"description": "저장된 빌링키로 결제를 하는 경우 사용됩니다. PG사 결제창, 비 인증 결제(일회성)API 또는 빌링키 발급 API로 등록된 빌링키가 있을 때 매칭되는 customer_uid로 결제를 진행할 수 있습니다.",
"operationId": "again",
"consumes": [
"application/json",
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "customer_uid",
"in": "formData",
"description": "빌링키와 매핑되며 고객사에서 채번하는 구매자의 결제 수단 식별 고유번호 PG사가 발급한 빌링키와 1:1로 맵핑되는 고객사가 지정한 고유값입니다. customer_uid는 카드번호 단위로 구분되서 저장되어야 합니다.",
"required": true,
"type": "string",
"maxLength": 80,
"x-portone-name": "구매자의 결제 수단 식별 고유번호",
"x-portone-description": "빌링키와 매핑되며 고객사에서 채번하는 구매자의 결제 수단 식별 고유번호"
},
{
"name": "merchant_uid",
"in": "formData",
"description": "고객사 거래 고유번호 (스마트로 - 신모듈의 경우, 특수문자 포함이 불가능합니다.)",
"required": true,
"type": "string",
"maxLength": 40,
"x-portone-name": "고객사 주문번호",
"x-portone-description": "결제 요청할 결제건의 고객사 거래 고유번호",
"x-portone-per-pg": {
"smartro_v2": {
"description": "스마트로는 주문 번호(merchant_uid)에 **특수문자를 허용하고 있지 않습니다.**\n\n따라서 결제창에서 일반결제를 할때와 발급 된 빌링키로 API를 통해 결제를 하는 경우 숫자, 문자(알파벳 소문자와 대문자) 또는 그 조합으로 이루어진 주문 번호를 사용해주세요.\n또한, 주문번호(merchant_uid)가 **최대 40자**를 넘을 수 없습니다. 40자가 넘을 경우 40자까지 잘려서 저장되기 때문에 유의 바랍니다."
}
}
},
{
"name": "currency",
"in": "formData",
"description": "(Paymentwall 전용) 통화 e.g.) KRW, USD, VND, ... Default: KRW",
"required": false,
"type": "string",
"x-portone-name": "결제 통화 코드",
"x-portone-description": "통화 e.g.) KRW, USD, VND, ... Default: KRW",
"x-portone-per-pg": {
"ksnet": {
"description": "USD 결제는 순수 해외카드로만 결제 가능합니다."
},
"paypal_v2": {
"required": true,
"description": "KRW은 불가능합니다."
}
}
},
{
"name": "amount",
"in": "formData",
"description": "결제금액",
"required": true,
"type": "number",
"x-portone-name": "결제금액",
"x-portone-description": "결제 요청할 금액"
},
{
"name": "tax_free",
"in": "formData",
"description": "amount 중 면세공급가액. 기본값은 0이므로(amount 모두 과세대상이므로) amount의 1/11 이 부가세로 처리됩니다.",
"required": false,
"type": "number",
"x-portone-name": "면세금액",
"x-portone-description": "amount 중 면세공급가액",
"x-portone-per-pg": {
"ksnet": {
"description": "면세 설정 상점아이디에서 면세처리를 위해 결제 금액과 동일한 면세 금액을 반드시 입력해야 합니다. 그렇지 않은 경우 매출전표에 전액 면세가 아닌 것으로 표시되고 실제 처리 내역이 다를 수 있습니다.\n\n과세 설정 상점아이디에서 면세 금액을 전달하지 않아야 합니다. 면세 금액을 전달하는 경우 매출전표에 면세 처리된 것으로 표시되지만 실제 처리 내역과 다를 수 있습니다."
},
"welcome": {
"description": "`부가세업체정함` 설정 고객사에 한해 사용 가능합니다."
}
}
},
{
"name": "vat_amount",
"in": "formData",
"description": "amount 중 부가세 금액. 부가세를 지정할 수 있으며, tax_free=0, vat_amount=0으로 영세율로 결제 가능합니다.(기본값: null)
지원되는 PG사
나이스페이먼츠
이니시스
(신) 나이스페이
웰컴페이먼츠
(신) 토스페이
",
"required": false,
"type": "number",
"x-portone-name": "부가세",
"x-portone-summary": "amount 중 부가세 금액",
"x-portone-description": "부가세를 지정할 수 있으며, `tax_free=0, vat_amount=0`으로 영세율로 결제 가능합니다.(기본값: **null**)",
"x-portone-supported-pgs": [
"nice",
"html5_inicis",
"nice_v2",
"welcome",
"tosspay_v2"
],
"x-portone-per-pg": {
"welcome": {
"description": "`부가세업체정함` 설정 고객사에 한해 사용 가능하며 전체금액의 10% 이하로 설정해야 합니다. vat_amount가 총 상품가격의 10%를 초과할 경우는 결제가 거절됩니다."
}
}
},
{
"name": "vat",
"in": "formData",
"description": "Deprecated 되었습니다. tax_free 파라메터를 사용해주세요. 결제금액 중 부가세 금액(파라메터가 누락되면 10%로 자동 계산됨)",
"required": false,
"type": "number",
"deprecated": true
},
{
"name": "name",
"in": "formData",
"description": "제품명",
"required": true,
"type": "string",
"maxLength": 40,
"x-portone-name": "제품명",
"x-portone-description": "결제 요청할 결제건의 제품명",
"x-portone-per-pg": {
"html5_inicis": {
"required": true
},
"danal_tpay": {
"required": true
}
}
},
{
"name": "buyer_name",
"in": "formData",
"description": "주문자명 (필수 KSNET, 스마트로 - 신모듈, 웰컴페이먼츠) 페이먼트월 PG사인 경우 first name, last name 한칸 띄어쓰기로 구분되어 유입되어야 합니다.",
"required": false,
"type": "string",
"maxLength": 16,
"x-portone-name": "주문자명",
"x-portone-description": "결제건의 주문자명",
"x-portone-per-pg": {
"smartro_v2": {
"required": true
},
"ksnet": {
"required": true
},
"welcome": {
"required": true
},
"paymentwall": {
"description": "first name, last name 한칸 띄어쓰기로 구분되어 유입되어야 합니다. 예시) Michael Jackson"
}
}
},
{
"name": "buyer_email",
"in": "formData",
"description": "주문자 E-mail주소 (필수 : 페이먼트월, 스마트로 - 신모듈)",
"required": false,
"type": "string",
"maxLength": 64,
"x-portone-name": "주문자 E-mail 주소",
"x-portone-description": "결제건의 주문자 E-mail주소",
"x-portone-per-pg": {
"smartro_v2": {
"required": true
},
"paymentwall": {
"required": true,
"description": "빌링키 발급시 기재한 이메일주소와 발급된 빌링키로 결제시 기입한 이메일주소가 일치해야 합니다."
}
}
},
{
"name": "buyer_tel",
"in": "formData",
"description": "주문자 전화번호 (필수 :스마트로 - 신모듈)",
"required": false,
"type": "string",
"maxLength": 16,
"x-portone-name": "주문자 전화번호",
"x-portone-description": "결제건의 주문자 전화번호",
"x-portone-per-pg": {
"smartro_v2": {
"required": true
}
}
},
{
"name": "buyer_addr",
"in": "formData",
"description": "주문자 주소",
"required": false,
"type": "string",
"maxLength": 128,
"x-portone-name": "주문자 주소",
"x-portone-description": "결제건의 주문자 주소"
},
{
"name": "buyer_postcode",
"in": "formData",
"description": "주문자 우편번호",
"required": false,
"type": "string",
"maxLength": 8,
"x-portone-name": "주문자 우편번호",
"x-portone-description": "결제건의 주문자 우편번호"
},
{
"name": "card_quota",
"in": "formData",
"description": "카드할부개월수. 2 이상의 integer 할부개월수 적용 (결제금액 50,000원 이상 한정, default = 0(일시불))",
"required": false,
"type": "integer",
"x-portone-name": "카드 할부 개월수",
"x-portone-description": "결제건의 카드 할부 개월 수로 기본값은 **0(일시불)**입니다."
},
{
"name": "interest_free_by_merchant",
"in": "formData",
"description": "카드할부처리할 때, 할부이자가 발생하는 경우(카드사 무이자 프로모션 제외) 부과되는 할부이자를 고객대신 고객사가 지불하고자 PG사와 계약된 경우 (현재, 나이스페이먼츠, (신) 나이스페이만 지원됨)",
"required": false,
"type": "boolean",
"default": false,
"x-portone-name": "상점분담 무이자 할부여부",
"x-portone-description": "카드할부처리할 때, 할부이자가 발생하는 경우(카드사 무이자 프로모션 제외) 부과되는 할부이자를 고객대신 고객사가 지불하는지에 대한 여부 (**PG사와 사전 계약이 필요**)",
"x-portone-supported-pgs": [
"nice",
"ksnet",
"nice_v2"
]
},
{
"name": "use_card_point",
"in": "formData",
"description": "승인요청시 카드사 포인트 차감하며 결제승인처리할지 flag. PG사 영업담당자와 계약 당시 사전 협의 필요 (현재, 나이스페이먼츠, 스마트로 - 신모듈, (신) 나이스페이만 지원됨)",
"required": false,
"type": "boolean",
"default": false,
"x-portone-name": "카드포인트 사용여부",
"x-portone-description": "승인요청시 카드사 포인트 차감하며 결제승인처리할지 여부 flag. **PG사 영업담당자와 계약 당시 사전 협의 필요**",
"x-portone-supported-pgs": [
"nice",
"smartro_v2",
"nice_v2"
]
},
{
"name": "custom_data",
"in": "formData",
"description": "거래정보와 함께 저장할 추가 정보",
"required": false,
"type": "string",
"x-portone-name": "빌링키 발급 시 같이 저장할 고객사 custom 데이터",
"x-portone-description": "거래정보와 함께 저장할 추가 정보"
},
{
"name": "notice_url",
"in": "formData",
"description": "결제성공 시 통지될 Notification URL(Webhook URL)",
"required": false,
"type": "string",
"x-portone-name": "Notification URL(Webhook URL)",
"x-portone-description": "결제성공 시 통지될 Notification URL(Webhook URL)"
},
{
"name": "browser_ip",
"in": "formData",
"description": "구매자 브라우저(PC)의 IP (입력하지 않은 경우 API를 호출한 클라이언트 IP로 설정됩니다.)",
"required": false,
"type": "string",
"x-portone-name": "브라우저의 IP",
"x-portone-description": "구매자 브라우저(PC)의 IP (입력하지 않은 경우 API를 호출한 클라이언트 IP로 설정됩니다.)",
"x-portone-per-pg": {
"paymentwall": {
"required": true
}
}
},
{
"name": "product_type",
"in": "formData",
"description": "판매 상품에 대한 구분 값 (real : 실물상품, digital : 디지털 컨텐츠) (필수:KSNET)",
"required": false,
"type": "string",
"enum": [
"real",
"digital"
],
"x-portone-name": "주문 상품구분",
"x-portone-description": "결제 요청할 판매 상품에 대한 구분 값",
"x-portone-supported-pgs": [
"ksnet",
"paypal_v2"
],
"x-portone-per-pg": {
"ksnet": {
"required": true
}
}
},
{
"name": "product_count",
"in": "formData",
"description": "결제 상품의 개수 (Default : 1)",
"required": false,
"type": "integer",
"x-portone-name": "결제 상품의 개수",
"x-portone-description": "결제 상품의 개수로 기본값은 1입니다."
},
{
"name": "cash_receipt_type",
"in": "formData",
"description": "현금영수증 발행할 대상
지원되는 PG사
(신) 토스페이
(신) 토스페이 경우 anonymous 전달 시 현금영수증 미발행 그 외의 값을 전달한 경우 현금영수증 자동 발행으로 동작합니다.",
"required": false,
"type": "string",
"enum": [
"person",
"company",
"anonymous"
],
"x-portone-name": "현금영수증 발행대상 타입",
"x-portone-description": "현금영수증 발행대상의 구분 값",
"x-portone-supported-pgs": [
"tosspay_v2"
],
"x-portone-per-pg": {
"tosspay_v2": {
"description": "(신) 토스페이 경우 anonymous 전달 시 현금영수증 미발행 그 외의 값을 전달한 경우 현금영수증 자동 발행으로 동작합니다."
}
}
},
{
"name": "bypass",
"in": "formData",
"description": "JSON string 형식의 PG사별로 특화된 파라미터. 전달 한 값은 가공 없이 그대로 PG사로 전달 됩니다. 각 PG사별 스펙은 PG사별 연동 문서 참고해주세요",
"required": false,
"type": "string",
"x-portone-name": "bypass 데이터",
"x-portone-summary": "JSON string 형식의 PG사별로 특화된 파라미터",
"x-portone-description": "전달 한 값은 가공 없이 그대로 PG사로 전달 됩니다. 각 PG사별 스펙은 PG사별 연동 문서 참고해주세요"
},
{
"name": "extra",
"in": "formData",
"description": "추가 파라미터",
"required": false,
"schema": {
"$ref": "#/definitions/SubscribePaymentExtra"
},
"x-portone-name": "추가 파라미터",
"x-portone-description": "비인증 결제 요청 시 추가 파라미터"
},
{
"name": "promotion_id",
"in": "formData",
"description": "`promotion-id-`로 시작하며, 프로모션 아이디에 설정된 할인 내용을 적용하여 결제합니다. 비인증 결제 경우 빌링키 발급시 저장된 마스킹된 카드번호를 통해 프로모션 적용 여부가 결정됩니다.",
"required": false,
"type": "string",
"x-portone-name": "프로모션 아이디",
"x-portone-description": "`promotion-id-`로 시작하며, 프로모션 아이디에 설정된 할인 내용을 적용하여 결제합니다. 비인증 결제 경우 빌링키 발급시 저장된 마스킹된 카드번호를 통해 프로모션 적용 여부가 결정됩니다."
},
{
"name": "channel_key",
"in": "formData",
"description": "
관리자 콘솔의 [연동관리] -> [연동 정보] 메뉴에서 확인할 수 있습니다.
슈퍼 빌링키 결제시, 결제 채널을 특정하고 싶을 때 명시할 수 있습니다.
",
"required": false,
"type": "string",
"maxLength": 55,
"x-portone-name": "채널 키",
"x-portone-description": "다수 채널에 대해 발급된 빌링키에 대해, 결제 채널을 특정하고 싶을 때 명시"
}
],
"responses": {
"200": {
"description": "정상 결제",
"schema": {
"$ref": "#/definitions/PaymentResponse"
}
},
"401": {
"description": "인증 Token이 전달되지 않았거나 유효하지 않은 경우"
}
},
"x-portone-supported-pgs": [
"chai",
"danal",
"danal_tpay",
"daou",
"html5_inicis",
"inicis",
"kakaopay",
"kcp",
"kcp_billing",
"kicc",
"ksnet",
"mobilians",
"naverpay",
"nice",
"nice_v2",
"payco",
"paymentwall",
"settle",
"settle_acc",
"smartro_v2",
"tosspayments",
"paypal_v2",
"welcome",
"tosspay_v2"
],
"x-portone-category": "nonAuthPayment",
"x-portone-per-pg": {
"paypal_v2": {
"description": "### Manges & Fraudnet 이상 거래 대응 필요\n\n페이팔은 이상 거래를 줄이기 위해 Risk Data Acquisition 정책을 시행하고 있습니다. 일반 결제나 빌링키 발급은 페이팔 버튼을 통해 진행되기 때문에 페이팔이 이상 거래 판단을 위한 구매자 접속 정보를 얻을 수 있지만, 발급 된 빌링키로 결제 (again API 호출) 할때는 고객사 서버에서 포트원 API를 통해 페이팔 API가 호출되는 구조이기 때문에 이상 거래 판단을 위한 구매자 접속 정보를 얻을 수 없습니다.\n따라서 발급 된 빌링키로 결제를 할때는 구매자의 브라우저/디바이스 접속 정보를 페이팔에 전달할 수 있도록 again API가 호출되는 **고객사 클라이언트 페이지에 반드시 페이팔 Fraudnet 스크립트/Manges SDK를 아래와 같이 추가**해야 합니다.\n\n**페이팔 RT를 통한 again API 호출시에는 Manges & Fraudnet 조치가 필수적으로 요구됩니다.**\n브라우저/앱에 페이팔 Fraudnet Script/Manges SDK를 추가한 후 again API를 호출할때 진행되는 플로우는 아래와 같습니다.\n\n\n\n#### 브라우저\n```html\n\n\n{\n \"f\": \"RISK_SESSION_CORRELATION_ID\",\n \"s\": \"SOURCE_IDENTIFIER\",\n \"sandbox\": true\n}\n\n\n\n```\n\n| 파라미터 | 의미 | 예시 |\n| -------- | --------------------------------------------------------- | --------------------------------------------- |\n| fncls | fnparams-dede7cc5-15fd-4c75-a9f4-36c430ee3a99로 항상 고정 | fnparams-dede7cc5-15fd-4c75-a9f4-36c430ee3a99 |\n| f | 주문번호(merchant_uid) 전달 | mid_1683690731602 |\n| s | string | 7WBB3CKT63FRG_checkout-page |\n| sandbox | 페이팔 Account ID가 테스트 용인지 운영 용인지 여부 | true |\n\n#### 앱\n\n##### 안드로이드\n\n[**Android Integration of Magnes**](https://developer.paypal.com/limited-release/magnes/integrate/android/) 가이드 문서에 따라 아래와 같이 collectAndSubmit 메소드 호출을 통해 페이팔로 디바이스 정보를 보내야합니다. 이때 두번째 파라미터(`paypalClientMetaDataId`)로는 주문번호(`merchant_uid`)를 전달해주시면 됩니다.\n\n```java\nMagnesResult magnesResult = MagnesSDK.getInstance()\n.collectAndSubmit(Context context, String paypalClientMetaDataId,\nHashMap\nadditionalData)\n```\n\n##### IOS Swift\n\n[**iOS Swift SDK Integration**](https://developer.paypal.com/limited-release/magnes/integrate/ios-swift/) 가이드 문서에 따라 아래와 같이 collectAndSubmit 메소드 호출을 통해 페이팔로 디바이스 정보를 보내야합니다. 이때 첫번째 파라미터(`withPayPalClientMetadataId`)로는 주문번호(`merchant_uid`)를 전달해주시면 됩니다.\n\n```swift\nlet magnesResult:MagnesResult =\nMagnesSDK.shared().collectAndSubmit(withPayPalClientMetadataId:\n\"YOUR-PAYPAL-CLIENT-METADATA-ID\", withAdditionalData: [String: String])\n```\n\n##### IOS Objective-C\n\n[**iOS Objective-C SDK Integration of Magnes**](https://developer.paypal.com/limited-release/magnes/integrate/ios-objective-c/) 가이드 문서에 따라 아래와 같이 collectAndSubmitWithPayPalClientMetadataId 메소드 호출을 통해 페이팔로 디바이스 정보를 보내야합니다. 이때 첫번째 파라미터(`YOUR-PAYPAL-CLIENT-METADATA-ID`)로는 주문번호(`merchant_uid`)를 전달해주시면 됩니다.\n\n```objective-c\n//PPRMOCMagnesSDK *magnesSDK = [PPRMOCMagnesSDK shared];\nPPRMOCMagnesSDKResult *magnesResult =\n[magnesSDK\ncollectAndSubmitWithPayPalClientMetadataId:@\"YOUR-PAYPAL-CLIENT-METADATA-ID\"\nwithAdditionalData:@{}];\n```\n\n### 고위험 결제 처리\n페이팔은 판매자 보호 정책을 통해 고객사 거래에서 이상 거래나 사기 등이 발생 시, 판매자 보호 정책을 통해 고객사가 손해 입을 수 있는 부분을 보존하는 판매자 보호 프로그램을 가지고 있습니다. 이 판매자 보호 정책을 적용하기 위해서는 페이팔 측에서 제공하는 **STC 기능**을 사용해야 합니다.\n\nSTC 기능을 사용하시기 위해 다음 정보를 확인하셔야 합니다.\n 1. 페이팔 Business 계정 가입시 산업 종류(Industry)를 결정하는데, 계정의 산업 종류를 확인해야 합니다.\n 2. 계정의 산업 종류를 확인하신 뒤, loadUI 호출 해 빌링키를 발급 받을때 그리고 발급 된 빌링키로 결제(again API 호출)할때 모두 bypass.paypal_v2 객체에 아래와 같은 형식으로 전달해주셔야 합니다.\n\n#### 발급 된 빌링키로 단건 결제(again API 호출)시 STC 적용하기\n ``` javascript\nawait fetch(\n \"https://api.iamport.kr/subscribe/payments/again\",\n {\n method: \"POST\",\n headers: {\n Authorization: `Basic ${ACCESS_TOKEN}`,\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n customer_uid, // [필수 입력] 빌링키 발급시 전달 한 빌링키와 1:1 매핑되는 UUID\n merchant_uid, // [필수 입력] 주문 번호\n currency, // [필수 입력] 결제 통화 (페이팔은 KRW 불가능)\n amount, // [필수 입력] 결제 금액\n name, // 주문명\n bypass: JSON.stringify({\n paypal_v2: {\n additional_data: [{\n key: \"sender_account_id\", // 고객사 account ID(merchant-id)\n value: \"A12345N343\"\n }, {\n key: \"sender_first_name\", // 고객사의 account에 등록 된 구매자의 이름\n value: \"John\"\n }, {\n key: \"sender_last_name\", // 고객사의 account에 등록 된 구매자의 이름\n value: \"Doe\"\n }, {\n key: \"sender_email\", // 고객사의 account에 등록 된 구매자의 이메일 주소\n value: \"example@example.com\"\n }, {\n key: \"sender_phone\", // 고객사의 account에 등록 된 구매자의 연락처\n value: \"(02)16705176\"\n }, {\n key: \"sender_country_code\", // 고객사의 account에 등록 된 국가 코드\n value: \"KR\" // ISO Alpha-2 형식 국가 코드\n }, {\n key: \"sender_create_date\", // 고객사의 account에 등록 된 국가 코드\n value: \"2023-10-10T23:59:59+09:00\" // IOS8601 형식\n }]\n }\n }) // end of bypass string\n }) // end of body\n }\n)\n ```\n "
}
}
}
},
"/subscribe/payments/schedule": {
"get": {
"tags": [
"subscribe"
],
"summary": "결제예약 복수조회 API",
"description": "기간범위를 지정하여 결제예약목록을 조회할 수 있습니다. 결제예약정보가 (페이징된)목록으로 전달되며, 최대 3개월 단위로 조회가 가능합니다.",
"operationId": "findSchedulesByRange",
"consumes": [
"application/json",
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "schedule_from",
"in": "query",
"description": "조회 시작시각 unix timestamp(결제예약건의 '예약시각'기준으로 조회합니다. from <= '예약시각')",
"required": true,
"type": "integer",
"x-portone-name": "조회 시작시각",
"x-portone-description": "조회 시작시각 unix timestamp(결제예약건의 '예약시각'기준으로 조회합니다. from <= '예약시각')"
},
{
"name": "schedule_to",
"in": "query",
"description": "조회 종료시각 unix timestamp(결제예약건의 '예약시각'기준으로 조회합니다. '예약시각' < to)",
"required": true,
"type": "integer",
"x-portone-name": "조회 종료시각",
"x-portone-description": "조회 종료시각 unix timestamp(결제예약건의 '예약시각'기준으로 조회합니다. '예약시각' < to)"
},
{
"name": "schedule_status",
"in": "query",
"description": "예약상태. 누락되면 모든 상태의 예약내역 조회\n
\n **웰컴페이먼츠**의 경우, `현금영수증 부가세업체정함` 설정 고객사에 한해 사용이 가능합니다. \n **나이스페이먼츠, (신) 나이스페이 **의 경우, 상점아이디의 과세설정이 **지정금액방식**(복합과세)으로 설정되어 있는 경우 **필수값** 입니다.\n 과세 혹은 면세로 설정된 상점아이디에서 파라미터 전달 시 가상계좌 생성이 불가능합니다.",
"required": false,
"type": "integer",
"x-portone-name": "면세금액",
"x-portone-description": "가상계좌 발급을 위한 결제건의 면세금액",
"x-portone-supported-pgs": [
"nice",
"nice_v2",
"welcome"
],
"x-portone-per-pg": {
"nice": {
"description": "상점아이디의 과세설정이 **지정금액방식**(복합과세)으로 설정되어 있는 경우 **필수값** 입니다.\n\n* 과세 혹은 면세로 설정된 상점아이디에서 파라미터 전달 시 가상계좌 생성이 불가능합니다."
},
"nice_v2": {
"description": "상점아이디의 과세설정이 **지정금액방식**(복합과세)으로 설정되어 있는 경우 **필수값** 입니다.\n\n* 과세 혹은 면세로 설정된 상점아이디에서 파라미터 전달 시 가상계좌 생성이 불가능합니다."
},
"welcome": {
"description": "`현금영수증 부가세업체정함` 설정 고객사에 한해 사용이 가능합니다"
}
}
},
{
"name": "vat_amount",
"in": "formData",
"description": "amount 중 부가세 금액. \n 부가세를 지정할 수 있으며, tax_free=0, vat_amount=0으로 영세율로 결제 가능합니다.(기본값: null) \n
지원되는 PG사
나이스페이먼츠
(신) 나이스페이
웰컴페이먼츠
",
"required": false,
"type": "number",
"x-portone-name": "부가세",
"x-portone-description": "가상계좌 발급을 위한 결제건의 부가세 금액",
"x-portone-supported-pgs": [
"nice",
"nice_v2",
"welcome"
],
"x-portone-per-pg": {
"welcome": {
"description": "`부가세업체정함` 설정 고객사에 한해 사용 가능하며 전체금액의 10% 이하로 설정해야 합니다. vat_amount가 총 상품가격의 10%를 초과할 경우는 결제가 거절됩니다."
}
}
},
{
"name": "pg_api_key",
"in": "query",
"description": "이니시스의 가맹점 관리자 페이지에서 확인하셔야 하는 API Key 값으로 가상계좌 발급 및 말소 신청에 사용됩니다. 누락하거나 잘못된 키 입력 시 hashData 불일치 오류가 발생합니다. \n (**이니시스 전용 필수 파라미터로 Query parameter입니다.**)",
"required": false,
"type": "string",
"x-portone-name": "Api Key",
"x-portone-summary": "이니시스의 가맹점 관리자 페이지에서 확인하셔야 하는 API Key 값",
"x-portone-description": "가상계좌 발급 및 말소 신청에 사용됩니다. 누락하거나 잘못된 키 입력 시 hashData 불일치 오류가 발생합니다. (**이니시스 전용 필수 파라미터로 Query parameter입니다.**)",
"x-portone-supported-pgs": [
"html5_inicis"
],
"x-portone-per-pg": {
"html5_inicis": {
"required": true,
"description": "Query parameter로 입력 바랍니다."
}
}
},
{
"name": "product_count",
"in": "formData",
"description": "결제 상품의 개수 (Default : 1)",
"required": false,
"type": "integer",
"x-portone-name": "결제 상품의 개수",
"x-portone-description": "가상계좌 발급을 위한 결제 상품의 개수로 기본값은 1입니다"
},
{
"name": "escrow_password",
"in": "formData",
"description": "헥토파이낸셜 고정식 가상계좌 에스크로 결제 시 필수로 입력해야합니다.",
"required": false,
"type": "string",
"x-portone-name": "에스크로 비밀번호",
"x-portone-description": "헥토파이낸셜 고정식 가상계좌 에스크로 결제 시 필수로 입력해야합니다."
},
{
"name": "fixed_unlimited_vbank",
"in": "formData",
"description": "헥토파이낸셜 고정식 무제한 가상계좌 발급 시 필수로 입력해야합니다.",
"required": false,
"type": "boolean",
"default": false,
"x-portone-name": "고정식 무제한 가상계좌 여부",
"x-portone-description": "헥토파이낸셜 고정식 무제한 가상계좌 발급시 필수로 입력해야합니다."
}
],
"responses": {
"200": {
"description": "가상계좌 생성 완료",
"schema": {
"$ref": "#/definitions/PaymentResponse"
}
},
"401": {
"description": "인증 Token이 전달되지 않았거나 유효하지 않은 경우"
}
},
"x-portone-supported-pgs": [
"settle",
"nice",
"nice_v2",
"html5_inicis",
"ksnet",
"smartro_v2",
"tosspayments",
"welcome"
],
"x-portone-category": "vbank"
}
},
"/vbanks/{imp_uid}": {
"put": {
"tags": [
"vbanks"
],
"summary": "가상계좌 발급정보 수정 API",
"description": "API요청으로 발급된 가상계좌(입금이 되기 전)의 정보를 수정합니다 \n 아직 입금이 되지 않은 가상계좌의 입금기한 또는 입금금액을 수정할 수 있습니다. (헥토파이낸셜(구 세틀뱅크)만 사용 가능) \n imp_uid가 지정되어야 합니다.(포트원 기획 의도상 동일한 merchant_uid의 입금대기 중인 가상계좌가 N개 존재할 수 있으므로 imp_uid로만 가상계좌 수정이 가능합니다)",
"operationId": "modifyVbank",
"consumes": [
"application/json",
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "imp_uid",
"in": "path",
"description": "포트원 거래고유번호",
"required": true,
"type": "string",
"default": "imp_448280090638",
"x-portone-name": "포트원 거래고유번호",
"x-portone-description": "가상계봐 발급 정보를 수정할 결제건의 포트원 거래고유번호"
},
{
"name": "amount",
"in": "formData",
"description": "수정할 결제금액",
"required": false,
"type": "integer",
"x-portone-name": "발급금액",
"x-portone-description": "수정할 결제금액"
},
{
"name": "vbank_due",
"in": "formData",
"description": "수정할 가상계좌 입금기한 UNIX TIMESTAMP",
"required": false,
"type": "integer",
"x-portone-name": "입금기한",
"x-portone-description": "수정할 가상계좌 입금기한 UNIX TIMESTAMP"
}
],
"responses": {
"200": {
"description": "가상계좌 수정 완료",
"schema": {
"$ref": "#/definitions/PaymentResponse"
}
},
"400": {
"description": "imp_uid가 누락된 경우/ 가상계좌 결제 건이 아닌 경우/ 가상계좌가 입금대기 상태(ready)가 아닌 경우"
},
"401": {
"description": "인증 Token이 전달되지 않았거나 유효하지 않은 경우"
},
"404": {
"description": "유효하지 않은 imp_uid"
}
},
"x-portone-supported-pgs": [
"settle"
],
"x-portone-category": "vbank"
},
"delete": {
"tags": [
"vbanks"
],
"summary": "가상계좌 발급취소 API",
"description": "발급된 가상계좌(입금이 되기 전)를 말소합니다. \n 아직 입금이 되지 않은 가상계좌를 말소시킴으로써 구매자가 실수로 입금하는 경우를 방지하도록 합니다. \n imp_uid가 지정되어야 합니다.(포트원 기획 의도상 동일한 merchant_uid의 입금대기 중인 가상계좌가 N개 존재할 수 있으므로 imp_uid로만 가상계좌 말소가 가능합니다)\n
지원되는 PG사
\n
KG이니시스\n
NHN KCP\n
토스페이먼츠 - 구모듈\n
다날\n
나이스페이먼츠\n
KICC\n
헥토파이낸셜(구 세틀뱅크)\n
스마트로 - 구모듈\n
토스페이먼츠 - 신모듈\n
KSNET\n
스마트로 - 신모듈\n
(신) 나이스페이\n
웰컴페이먼츠
",
"operationId": "revokeVbank",
"consumes": [
"application/json",
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "imp_uid",
"in": "path",
"description": "포트원 거래고유번호",
"required": true,
"type": "string",
"default": "imp_448280090638",
"x-portone-name": "포트원 거래고유번호",
"x-portone-description": "가상계좌 발급 취소할 결제건의 포트원 거래고유번호"
},
{
"name": "pg_api_key",
"in": "query",
"description": "이니시스의 가맹점 관리자 페이지에서 확인하셔야 하는 API Key 값으로 가상계좌 발급 및 말소 신청에 사용됩니다. 누락하거나 잘못된 키 입력 시 hashData 불일치 오류가 발생합니다. \n POST 가상계좌 발급 API요청의 `pg_api_key`와 동일한 값입니다. \n (**이니시스 전용 필수 파라미터로 Query parameter입니다.**)",
"required": false,
"type": "string",
"x-portone-name": "API Key",
"x-portone-summary": "이니시스의 가맹점 관리자 페이지에서 확인하셔야 하는 API Key 값",
"x-portone-description": "가상계좌 발급 및 말소 신청에 사용됩니다. 누락하거나 잘못된 키 입력 시 hashData 불일치 오류가 발생합니다. (**이니시스 전용 필수 파라미터로 Query parameter입니다.**)",
"x-portone-supported-pgs": [
"html5_inicis"
],
"x-portone-per-pg": {
"html5_inicis": {
"required": true,
"description": "Query parameter로 입력 바랍니다."
}
}
}
],
"responses": {
"200": {
"description": "가상계좌 말소 완료",
"schema": {
"$ref": "#/definitions/PaymentResponse"
}
},
"400": {
"description": "imp_uid가 누락된 경우/ 가상계좌 결제 건이 아닌 경우 / 가상계좌가 입금대기 상태(ready)가 아닌 경우"
},
"401": {
"description": "인증 Token이 전달되지 않았거나 유효하지 않은 경우"
},
"404": {
"description": "유효하지 않은 imp_uid"
}
},
"x-portone-supported-pgs": [
"html5_inicis",
"uplus",
"danal",
"nice",
"kicc",
"settle",
"smartro",
"tosspayments",
"ksnet",
"smartro_v2",
"nice_v2",
"welcome"
],
"x-portone-category": "vbank"
}
},
"/vbanks/holder": {
"get": {
"tags": [
"vbanks"
],
"summary": "예금주 조회 API",
"description": "가상계좌 환불 전, 확인차원에서 예금주를 조회하는 API \n 은행코드, 계좌번호를 이용해 해당 계좌의 예금주 명을 조회합니다. \n
",
"type": "string",
"x-portone-name": "성별",
"x-portone-description": "- male : 남성\n- female : 여성"
},
"birthday": {
"description": "인증결과-생년월일 ISO8601 형식의 문자열. YYYY-MM-DD 10자리 문자열",
"type": "string",
"x-portone-name": "생년월일",
"x-portone-description": "ISO8601 형식의 문자열. YYYY-MM-DD 10자리 문자열"
},
"foreigner": {
"description": "인증결과-외국인 여부. 다날 본인인증서비스 계약시외국인 구분기능을 추가 요청하지 않은 경우 항상 false를 응답합니다.\n
true:외국인
false:내국인
",
"type": "boolean",
"x-portone-name": "외국인 여부",
"x-portone-summary": "인증된 사용자의 외국인 여부",
"x-portone-description": "**다날 본인인증서비스 계약시** 외국인 구분기능을 추가 요청하지 않은 경우 항상 **false**를 응답합니다.\n- true : 외국인\n- false : 내국인"
},
"phone": {
"description": "인증결과-사용된 휴대폰번호(신용카드 본인인증의 경우 해당사항없음). 특수기호없이 숫자로만 구성된 휴대폰번호가 전달됨. 통신사 사전승인이 이뤄지지 않으면 phone 속성은 존재하지 않습니다. 통신사 사전승인이 필요하므로 cs@portone.io 로 다날 CPID 와 함께 사용승인 요청주시면 안내도와드리겠습니다.",
"type": "string",
"x-portone-name": "휴대폰번호",
"x-portone-summary": "인증에 사용된 휴대폰 번호 (신용카드 본인인증의 경우 해당사항 없음)",
"x-portone-description": "특수 기호없이 숫자로만 구성된 휴대폰번호가 전달되며 통신사 사전승인이 이뤄지지 않으면 phone 속성은 존재하지 않습니다.\n\n통신사 사전승인이 필요하므로 cs@portone.io 로 다날 CPID 와 함께 사용승인 요청주시면 안내도와드리겠습니다."
},
"carrier": {
"description": "인증결과-사용된 휴대폰번호의 통신사(신용카드 본인인증의 경우 해당사항없음). 통신사 사전승인이 이뤄지지 않으면 carrier 속성은 존재하지 않습니다. 통신사 사전승인이 필요하므로 cs@portone.io 로 다날 CPID 와 함께 사용승인 요청주시면 안내도와드리겠습니다.\n
SKT
\n
KT
\n
LGT
\n
SKT_MVNO
\n
KT_MVNO
\n
LGT_MVNO
",
"type": "string",
"x-portone-name": "통신사",
"x-portone-summary": "인증에 사용된 휴대폰번호의 통신사 (신용카드 본인인증의 경우 해당사항없음)",
"x-portone-description": "사용된 휴대폰번호의 통신사(신용카드 본인인증의 경우 해당사항없음). 통신사 사전승인이 이뤄지지 않으면 carrier 속성은 존재하지 않습니다. 통신사 사전승인이 필요하므로 cs@portone.io 로 다날 CPID 와 함께 사용승인 요청주시면 안내도와드리겠습니다.\n- SKT\n- KT\n- LGT\n- SKT_MVNO\n- KT_MVNO\n- LGT_MVNO"
},
"certified": {
"description": "인증성공여부",
"type": "boolean",
"x-portone-name": "인증성공여부",
"x-portone-description": "본인인증 성공여부"
},
"certified_at": {
"description": "인증처리시각 UNIX timestamp",
"type": "integer",
"x-portone-name": "인증처리시각",
"x-portone-description": "본인인증 처리시각 UNIX timestamp"
},
"unique_key": {
"description": "개인 고유구분 식별키(CI)",
"type": "string",
"maxLength": "88",
"x-portone-name": "개인 고유구분 식별키",
"x-portone-description": "개인별로 고유하게 부여하는 개인 식별키(CI)"
},
"unique_in_site": {
"description": "고객사 내 개인 고유구분 식별키(DI). 본인인증 PG MID별로 할당되는 개인 식별키",
"type": "string",
"maxLength": "64",
"x-portone-name": "고객사 내 개인 고유구분 식별키",
"x-portone-summary": "고객사 내 개인별로 고유하게 부여하는 개인 식별키(DI)",
"x-portone-description": "본인인증 PG MID별로 할당되는 개인 식별키"
},
"origin": {
"description": "본인인증 프로세스가 진행된 웹 페이지의 URL",
"type": "string",
"x-portone-name": "웹 페이지 URL",
"x-portone-description": "본인인증 프로세스가 진행된 웹 페이지의 URL"
},
"foreigner_v2": {
"description": "인증결과-외국인 여부(nullable)\n
true:외국인
\n
false:내국인
\n 다날 본인인증서비스 계약시외국인 구분기능 추가 요청을 해주셔야 사용이 가능합니다. 요청을 하지 않은 경우 null을 응답합니다.",
"type": "boolean",
"x-portone-name": "외국인 여부(nullable)",
"x-portone-summary": "본인인증 결과 외국인 여부(nullable)",
"x-portone-description": "- true : 외국인\n- false : 내국인\n\n**다날 본인인증서비스 계약시** 외국인 구분기능 추가 요청을 해주셔야 사용이 가능합니다. 요청을 하지 않은 경우 **null**을 응답합니다."
}
}
},
"CertificationResponse": {
"allOf": [
{
"$ref": "#/definitions/ResponseAnnotation"
},
{
"description": "본인인증 결과 객체. 바로 아래 Certification structure를 확인하세요",
"properties": {
"response": {
"$ref": "#/definitions/CertificationAnnotation"
}
}
}
]
},
"CertificationOTPAnnotation": {
"required": [
"imp_uid"
],
"properties": {
"imp_uid": {
"description": "포트원 인증 고유번호",
"type": "string",
"x-portone-name": "포트원 인증 고유번호",
"x-portone-description": "본인인증 결과건의 포트원 인증 고유번호"
}
}
},
"CertificationOTPResponse": {
"allOf": [
{
"$ref": "#/definitions/ResponseAnnotation"
},
{
"description": "본인인증 결과 객체. 바로 아래 Certification structure를 확인하세요",
"properties": {
"response": {
"$ref": "#/definitions/CertificationOTPAnnotation"
}
}
}
]
},
"CustomerAnnotation": {
"required": [
"customer_uid",
"pg_provider",
"pg_id",
"card_name",
"inserted",
"updated",
"sandbox"
],
"properties": {
"customer_uid": {
"description": "빌링키와 매핑되며 고객사에서 채번하는 구매자의 결제 수단 식별 고유번호",
"type": "string",
"maxLength": "80",
"x-portone-name": "구매자의 결제 수단 식별 고유번호",
"x-portone-description": "빌링키와 매핑되며 고객사에서 채번하는 구매자의 결제 수단 식별 고유번호"
},
"pg_provider": {
"description": "빌링키가 등록된 PG사 구분코드",
"type": "string",
"maxLength": "16",
"x-portone-name": "PG사 구분코드",
"x-portone-description": "빌링키가 등록된 PG사 구분코드"
},
"pg_id": {
"description": "빌링키가 등록된 PG사 상점아이디(MID)",
"type": "string",
"maxLength": "80",
"x-portone-name": "상점아이디(MID)",
"x-portone-description": "빌링키가 등록된 PG사 상점아이디(MID)"
},
"sandbox": {
"description": "빌링키 발급 시 이용한 포트원 채널의 테스트 채널 여부",
"type": "boolean",
"x-portone-name": "테스트 빌링키 여부",
"x-portone-description": "빌링키 발급 시 이용한 포트원 채널의 테스트 채널 여부"
},
"customer_id": {
"description": "구매자 ID",
"type": "string",
"x-portone-name": "구매자 ID",
"x-portone-description": "구매자 식별 고유 번호"
},
"card_name": {
"description": "카드사명",
"type": "string",
"x-portone-name": "카드명",
"x-portone-description": "빌링키 발급 한 카드명"
},
"card_code": {
"description": "카드사 코드(금융결제원 표준코드번호)\n 링크보기",
"type": "string",
"x-portone-name": "카드사 코드",
"x-portone-description": "카드사 코드(금융결제원 표준코드번호)\n\n[링크보기](https://developers.portone.io/opi/ko/support/code-info/card-code?v=v1)"
},
"card_issuer_code": {
"description": "카드 발급사 코드(금융결제원 표준코드번호) \n 발급사 코드 지원 pg사\n
(신) 토스페이먼츠\n
KSNET\n
페이팔 RT\n
(신) 스마트로\n
(신) 나이스페이먼츠\n
웰컴페이먼츠\n
(신) 토스페이",
"type": "string",
"x-portone-name": "카드 발급사 코드",
"x-portone-description": "카드 발급사 코드(금융결제원 표준코드번호)\n\n발급사 코드 지원 pg사\n- (신) 토스페이먼츠\n- KSNET\n- 페이팔 RT\n- (신) 스마트로\n- (신) 나이스페이먼츠\n- 웰컴페이먼츠\n- (신) 토스페이",
"x-portone-supported-pgs": [
"tosspayments",
"ksnet",
"paypal_v2",
"smartro_v2",
"nice_v2",
"welcome",
"tosspay_v2"
]
},
"card_issuer_name": {
"description": "카드 발급사명으로 발급사 코드를 지원하는 pg사에 한해 제공됩니다.",
"type": "string",
"x-portone-name": "카드 발급사명",
"x-portone-description": "빌링키 발급 한 카드의 발급사명\n\n 발급사 코드를 지원하는 pg사에 한해 제공됩니다."
},
"card_publisher_code": {
"description": "카드 발행사 코드(금융결제원 표준코드번호) \n 발행사 코드 지원 pg사\n
(신) 토스페이먼츠\n
KSNET\n
페이팔 RT\n
(신) 스마트로\n
(신) 나이스페이먼츠\n
웰컴페이먼츠\n
(신) 토스페이",
"type": "string",
"x-portone-name": "카드 발행사 코드",
"x-portone-description": "카드 발행사 코드(금융결제원 표준코드번호)\n\n발행사 코드 지원 pg사\n- (신) 토스페이먼츠\n- KSNET\n- 페이팔 RT\n- (신) 스마트로\n- (신) 나이스페이먼츠\n- 웰컴페이먼츠\n- (신) 토스페이",
"x-portone-supported-pgs": [
"tosspayments",
"ksnet",
"paypal_v2",
"smartro_v2",
"nice_v2",
"welcome",
"tosspay_v2"
]
},
"card_publisher_name": {
"description": "카드 발행사명으로 발행사 코드를 지원하는 pg사에 한해 제공됩니다.",
"type": "string",
"x-portone-name": "카드 발행사명",
"x-portone-description": "빌링키 발급 한 카드의 발행사명\n\n 발행사 코드를 지원하는 pg사에 한해 제공됩니다."
},
"card_number": {
"description": "마스킹 카드번호",
"type": "string",
"x-portone-name": "마스킹 카드번호",
"x-portone-description": "빌링키 발급 한 카드의 마스킹된 카드번호"
},
"card_type": {
"description": "카드유형 \n (주의)해당 정보를 제공하지 않는 일부 PG사의 경우 null 로 응답됨(ex. 이니시스-빌링)\n
(신) 토스페이",
"type": "string",
"x-portone-name": "카드 발급사 코드",
"x-portone-description": "결제건의 카드 발급사 코드번호(금융결제원 표준코드번호) - 카드 결제 건의 경우\n\n발급사 코드 지원 pg사\n- (신) 토스페이먼츠\n- KSNET\n- 페이팔 RT\n- (신) 스마트로\n- (신) 나이스페이먼츠\n- 웰컴페이먼츠\n- 토스페이먼츠 브랜드페이\n- (신) 토스페이",
"x-portone-supported-pgs": [
"tosspayments",
"ksnet",
"paypal_v2",
"smartro_v2",
"nice_v2",
"toss_brandpay",
"welcome",
"tosspay_v2"
]
},
"card_issuer_name": {
"description": "결제한 카드의 발급사명으로 발급사 코드를 지원하는 pg사에 한해 제공됩니다. - (카드 결제 건의 경우)",
"type": "string",
"x-portone-name": "카드 발급사명",
"x-portone-description": "결제한 카드의 발급사명 - 카드 결제 건의 경우\n\n 발급사 코드를 지원하는 pg사에 한해 제공됩니다."
},
"card_publisher_code": {
"description": "결제건의 카드 발행사 코드번호(금융결제원 표준코드번호) - (카드 결제 건의 경우) \n 발행사 코드 지원 pg사\n
(신) 토스페이먼츠\n
KSNET\n
페이팔 RT\n
(신) 스마트로\n
(신) 나이스페이먼츠\n
웰컴페이먼츠\n
토스페이먼츠 브랜드페이\n
(신) 토스페이",
"type": "string",
"x-portone-name": "카드 발행사 코드",
"x-portone-description": "결제건의 카드 발행사 코드번호(금융결제원 표준코드번호) - 카드 결제 건의 경우\n\n발행사 코드 지원 pg사\n- (신) 토스페이먼츠\n- KSNET\n- 페이팔 RT\n- (신) 스마트로\n- (신) 나이스페이먼츠\n- 웰컴페이먼츠\n- 토스페이먼츠 브랜드페이\n- (신) 토스페이",
"x-portone-supported-pgs": [
"tosspayments",
"ksnet",
"paypal_v2",
"smartro_v2",
"nice_v2",
"welcome",
"toss_brandpay",
"tosspay_v2"
]
},
"card_publisher_name": {
"description": "카드 발행사명으로 발행사 코드를 지원하는 pg사에 한해 제공됩니다. - (카드 결제 건의 경우)",
"type": "string",
"x-portone-name": "카드 발행사명",
"x-portone-description": "결제 한 카드의 발행사명 - 카드 결제 건의 경우\n\n 발행사 코드를 지원하는 pg사에 한해 제공됩니다."
},
"card_quota": {
"description": "할부개월 수(0이면 일시불)",
"type": "integer",
"x-portone-name": "할부개월 수",
"x-portone-description": "결제건의 할부개월 수(일시불은 0으로 표기) - 신용카드 결제 건의 경우",
"x-portone-per-pg": {
"paypal_v2": "Pay Later를 이용하면 할부 결제가 가능합니다. 하지만 **페이팔이 승인 된 할부 정보를 알려주지 않기 때문에**\n실제로 할부로 결제가 됐는지, 됐다면 몇 개월 할부로 결제 됐는지 알 수 없습니다."
}
},
"card_number": {
"description": "결제에 사용된 마스킹된 카드번호. 7~12번째 자리를 마스킹하는 것이 일반적이지만, PG사의 정책/설정에 따라 다소 차이가 있을 수 있습니다.",
"type": "string",
"x-portone-name": "카드번호",
"x-portone-summary": "결제에 사용된 마스킹된 카드번호",
"x-portone-description": "결제에 사용된 마스킹된 카드번호. 7~12번째 자리를 마스킹하는 것이 일반적이지만, PG사의 정책/설정에 따라 다소 차이가 있을 수 있습니다."
},
"card_type": {
"description": "카드 구분코드 (주의)해당 정보를 제공하지 않는 일부 PG사의 경우 null 로 응답됨(ex. 이니시스-빌링)\n