PAYCO Developer

1. 주문 예약(payco_reserve)

• 바로구매 주문서를 띄우기 전에 주문예약 API를 통해 필요한 정보를 전달합니다.
• 가맹점에서는 주문 예약 응답으로 받은 주문서 URL 을 팝업으로 띄웁니다.
• 외부가맹점의 주문번호(sellerOrderReferenceKey)는 중복되지 않는 고유한 key이어야 합니다.
• 외부가맹점에서 관리하는 주문상품 연동 키(sellerOrderProductReferenceKey)는 주문 별로 고유한 key이어야 합니다.
• 배송비 상품 설명(바로구매형인 경우에만 전달필요)
  • - 배송비를 상품으로 간주하고 상품금액은 총 배송비로 하여 주문 상품 List(orderProducts)에 하나의 상품으로 추가해야 합니다.
  • 배송비가 없는 경우에도 금액을 0으로 셋팅하여 주문 상품 List(orderProducts)에 추가해야 합니다.
  • 추가 배송비가 발생 한 경우 배송비 상품의 productPaymentAmt 에 추가 배송비가 합산 됩니다.
  • 위 배송비 상품의 cpId, productId는 서비스 별로 고정된 값을 발급합니다.
• PAYCO 주문예약 후 결제팝업 오픈시 팝업차단을 위한 개발 TIP!!
  • - orderSheetUrl로 PAYCO 팝업오픈시엔
  • 가맹점페이지 오픈 후 피드백받은 orderSheetUrl을 redirect처리하도록 합니다.
  • -팝업 오픈은 POST방식의 submit은 지양하도록 한다. ( IE11 관리자모드 about:blank 새창 오픈 )
• METHOD : POST
• URL : /outseller/order/reserve

주문 예약 API > INPUT

▷ 21번 컬럼 orderProducts 주문상품 List

▷ 22번 컬럼 extraData

▷ 22번 컬럼 extraData의 viewOptions 화면UI 옵션

▷ 23번 컬럼 sellerOptions

					
{ 
	"sellerKey": "S0FSJE", 
	"sellerOrderReferenceKey":"TESTORDERKEY00000001", 
	"totalOrderAmt": "3000", 
	"totalDeliveryFeeAmt": "0", 
	"totalPaymentAmt": "3000", 
	"returnUrl": "https://alpha-api-bill.payco.com/return", 
	"returnUrlParam" : "{\"returnUrlParam1\":\"data1\",\"returnUrlParam2\":300}", 
	"orderMethod": "CHECKOUT", \
	"orderProducts": [ 
		{ 
			"cpId": "PARTNERTEST", 
			"productId": "PROD_CHK", 
			"productAmt": "1500", 
			"productPaymentAmt": "1500", 
			"sortOrdering": 1, 
			"productName": "BAG", 
			"orderQuantity": 1, 
			"sellerOrderProductReferenceKey": "TESTPRODKEY00000001" 
		}
	],

	"extraData": "{\"payExpiryYmdt\": \"20181231000000\"}"
}  
					
					

주문 예약 API > OUTPUT

					
{
     "result":{ 
         "reserveOrderNo": "201503172000525479", 
         "orderSheetUrl":"https://alpha-bill.payco.com/easyLogin/201503172000525479" 
     }, 
     "code": 0, 
     "message": "success" 
 }
					
					

2. 추가배송비 조회(payco_deliveryfee)

외부 가맹점 API 상세

• 외부가맹점은 아래 API를 제공해야 합니다.
• API 스펙은 PAYCO에서 정의한 대로 개발되어 있어야 합니다.

추가 배송비 조회

• API URL은 PAYCO 쪽에 미리 등록 요청이 필요 합니다.
• 해당 API 는 바로구매 형의 경우 배송지 정보 입력 시 호출 됩니다.
• 우편번호 기준으로 주문의 추가 배송비를 조회합니다.
• 요청 정보는 "response"라는 이름의 parameter로 제공되며, parameter value를 UTF-8 urldecode하면 Json형태의 값을 받아 볼 수 있습니다.
• 결과는 Json으로 전달합니다.
• ［추가배송비 과세처리방법]
  • - 주문예약정보 100% 과세금액인 경우 추가배송비도 과세처리
  • - 주문예약정보 100% 과세금액인 경우 추가배송비도 과세처리
  • - 주문예약정보 100% 과세금액인 경우 추가배송비도 과세처리

추가 배송비 조회 > INPUT

					
https://alpha-api-bill.payco.com/sample/outseller/
getRemoteAreaDeliveryFee?
response=%7B%22zipcode%22%3A%22463-400%22%2C%22
sellerOrderenceReferenceKey%
22%3A%22201408212212505952%22%2C%
22sellerOrderProductReferenceKeys%22%3A%5B
%221918597%22%5D%7D
					
					

추가 배송비 조회 > OUTPUT

					
{ 
    "resultCode": 0, 
    "resultMessage": "success", 
    "totalRemoteAreaDeliveryFeeAmt": 1000 
}
					
					

3. 결제인증 완료(payco_return)

• 주문예약 API 연동 시 파라미터로 'returnUrl'을 전달하게 됩니다.
• 'returnUrl'은 결제인증완료URL로 외부가맹점이 제공하는 페이지입니다.
• 결제인증 성공시점 또는 사용자취소시 외부가맹점의 returnUrl로 이동합니다.
• 캐릭터셋은 UTF-8이며, GET으로 전달합니다. (option POST)
• 예약시 returnUrlParam 값에 셋팅된 정보가 존재시 해당값을 추가하여 returnUrl을 호출합니다.
• - 예] 예약API 호출시 전달된 정보

  "returnUrl": "https://alpha-api-bill.payco.com/test/surl/ok",

  "returnUrlParam" : "{\"returnUrlParam1\":\"data1\", \"returnUrlParam2\":300}",

• - 예] 결제인증완료 호출 페이지

  http://alpha-api-bill.payco.com/test/surl/ok?returnParam1=data1&returnParam2=300

• 자세한 항목은 아래 'returnUrl 로 전달되는 정보'를 참고합니다.
• returnUrl에서는 결제팝업창을 close한 다음 주문이 가능할 경우 결제승인처리API를 호출하여 주문이 완료 (결제완료) 될 수 있도록 합니다.
• 가맹점에서는 총 결제금액 (totalPaymentAmt)과 외부가맹점번호가 일치하는지 확인합니다.

returnUrl 로 전달되는 정보

4. 결제승인 요청(payco_return)

• 결제인증 후 실제 결제완료 처리가 되는 API 입니다.
• 외부가맹점에서 주문 가능한 조건이 되는 경우 결제승인 API를 호출합니다. ( ex. 재고확인 )
• 승인처리 성공시 PAYCO 회원에게 PAYCO앱에 주문완료 push알림 및 email을 발송합니다.
• 결제인증 후 5분내 승인처리가 이루어져야 합니다.
• 중복 승인 요청이 일어나지 않도록 방어코드 작성 필요합니다.
• timeout 최대 30초 설정
• URL : /outseller/payment/approval
• totalOrderAmt(총 주문금액) + totalDeliveryFeeAmt(총 배송비) + totalRemoteAreaDeliveryFeeAmt(총 도서산간비용)
  = 총 결제금액 (totalPaymentAmt)

결제승인 API > INPUT

					
{
    "sellerKey" : "S0FSJE", 
    "reserveOrderNo" : "201503302000530385",
    "sellerOrderReferenceKey": "201503301", 
    "paymentCertifyToken" : "IBbBLWLH9Eoiwyr5RQASbyIqXe1P3373OHt2_6FlTLUS840rys0h2e1SSJoMWuhc",
    "totalPaymentAmt": 1000 
}
					
					

결제승인 API > OUTPUT

▷ deliveryPlace (배송지)

▷ orderProducts (주문상품List)

▷ paymentDetails (결제내역 List)

▷ cardSettleInfo (카드결제정보)

▷ cellphoneSettleInfo(핸드폰 결제 정보)

▷ realtimeAccountTransferSettleInfo(실시간계좌이체 결제정보)

▷ nonBankbookSettleInfo (무통장입금 결제정보)

▷ couponSettleInfo (쿠폰정보)

					
{ 
"result": { 
    "sellerOrderReferenceKey": "201503301",
    "reserveOrderNo": "201503302000530385",
    "orderNo": "201503302000162863",
    "memberName": "이윤*",
    "memberEmail": "tan**@naver.com",
    "orderChannel": "PC",
    "totalOrderAmt": 1000,
    "totalDeliveryFeeAmt": 0,
    "totalRemoteAreaDeliveryFeeAmt": 0,
    "totalPaymentAmt": 1000,
    "orderProducts": [ 
        {
        "orderProductNo": "201503302000310008",
        "sellerOrderProductReferenceKey": "1", 
        "orderProductStatusCode": "OPSPAED",
        "orderProductStatusName": "결제완료",
        "cpId": "PARTNERTEST ",
        "productId": "PROD_CHK",
        "productKindCode": "GENERAL_PRODUCT",
        "productPaymentAmt": 1000,
        "originalProductPaymentAmt": 1000 
        }
    ],
    "paymentDetails": [ 
        { 
        "cardSettleInfo":{ 
            "cardCompanyName": "삼성카드",
            "cardCompanyCode": "CCSS",
            "cardInstallmentMonthNumber": "00",
            "cardAdmissionNo" : 52451124 
            },
        "paymentTradeNo": "201503302000465174",
        "paymentMethodCode": "31",
        "paymentMethodName": "신용카드",
        "paymentAmt": 1000,
        "tradeYmdt": "20150330111047",
        "pgAdmissionNo": "20150330992623",
        "pgAdmissionYmdt": "20150330111051",
        "easyPaymentYn": "Y" 
        } 
    ],
    "serviceUrlParam": "{\"serviceUrlParam1\":\"data1\", \"serviceUrlParam2\":300}",
    "orderCertifyKey": "A7CZSz9A489nkOUWSMM3NZ1OAHPdhKnpG2BBMh3D458YCC",
    "paymentCompletionYn": "Y" 
    },
"message": "success",
"code": 0 
}
					
					

5. 주문 결제 취소 처리(payco_cancel)

• 기존에 생성된 주문 및 결제내역을 취소 처리하는 경우 사용합니다.
• PG취소가 가능한 금액으로 요청 했을 때만 취소됩니다.
• 취소 할 배송비가 있는 경우 (부분 취소의 경우만 해당)
  • - 취소 배송비를 취소할 상품 List에 추가해야 합니다.
  • - 추가 배송비도 함께 취소해야 하는 경우 배송비 상품의 productAmt에 추가 배송비를 합산한 금액으로 넘겨야 합니다.
  • - 주문예약 시 전달했던 배송비 상품의 sellerOrderProductReferenceKey, cpId, productId 가 동일해야 합니다.
  • - 쿠폰사용시에는 결제 부분취소가 불가능한 케이스가 존재 함.
    • ( 부분취소금액 <= 쿠폰사용금액 조건인 경우 부분취소 불가 )
  • - 계좌(결제/송금)의 경우 11월 5일부터 전체취소 지원
    • 단, 부분취소는 지원이 안되며
    • 주문상태가 배송시작이거나 구매확정인 경우 또는 주문일시가 120일이 지난 건의 경우는 취소 불가.
• METHOD : POST
• URL : /outseller/order/cancel

주문 결제 취소 처리 API > INPUT

▷ orderProducts

					
{
    "sellerKey" : "S0FSJE", 
    "orderNo" :	"201510232002005194", 
    "cancelTotalAmt" : 40000, 
    "orderCertifyKey" : "tGYCvfgsiG1DDnsnyIXY/JwFCN1JQdH9JGnseXX0RNc=",
    "orderProducts" : [ 
        { 
            "sellerOrderProductReferenceKey" : "1171997", 
            "cpId" : "PARTNERTEST", 
            "productId" : "PROD_CHK", 
            "productAmt" : 40000, 
            "cancelDetailContent" : "TEST" 
        } 
    ] 
}
					
					

▷ 주문 결제 취소 처리 API > OUTPUT

▷ cancelPaymentDetails

					
{ 
    "result": { 
        "orderNo": "201510232002005194", 
        "cancelTradeSeq": 2000000270, 
        "totalCancelPaymentAmt": 40000, 
        "remainCancelPossibleAmt": 0, 
        "cancelPaymentDetails": [ 
            { 
                "paymentTradeNo": "201412262000003384", 
                "paymentMethodCode": "98", 
                "cancelPaymentAmt": 40000, 
                "tradeYmdt": "20141226152604" 
            } 
        ] 
        "cancelYmdt": "20151019172418"
    }, 
    "message": "success", 
    "code": 0 
}