CookiePay API 매뉴얼

인증 결제

인증결제 요청전문

URL
https://www.cookiepayments.com/pay/ready [POST]
JAVASCRIPT

쿠키페이 라이브러리 추가

jQuery 1.0 이상이 설치되어 있어야 합니다

<script type="text/javascript" src="https://www.cookiepayments.com/js/cookiepayments-1.1.3.js"></script>

결제 준비하기

cookiepayments.init({
    api_id : 'abcde12345', //쿠키페이 결제 연동 id
    api_key : '4229dd5550455ab34c876c0b751982b601198f621234567890', //쿠키페이 결제 연동 key
});

결제 요청하기

cookiepayments.payrequest({
    ORDERNO: $("#ORDERNO").val(), //주문번호 (필수)
    PRODUCTNAME: $("#PRODUCTNAME").val(), //상품명 (필수)
    AMOUNT: $("#AMOUNT").val(), //결제 금액 (필수)
    BUYERNAME: $("#BUYERNAME").val(), //고객명 (필수)
    BUYEREMAIL: $("#BUYEREMAIL").val(), //고객 e-mail (필수)
    PAYMETHOD: $("#PAYMETHOD").val(), //결제 수단 (선택, 미입력시 CARD)
    PRODUCTCODE : $("#PRODUCTCODE").val(), //상품 코드 (선택)
    BUYERID : $("#BUYERID").val(), //고객 아이디 (선택)
    BUYERADDRESS : $("#BUYERADDRESS").val(), //고객 주소 (선택)
    BUYERPHONE : $("#BUYERPHONE").val(), //고객 휴대폰번호 (선택, 웰컴페이는 필수)
    RETURNURL : $("#RETURNURL").val(), //결제 완료 후 리다이렉트 url (필수)
    ETC1 : $("#ETC1").val(), //사용자 추가필드1 (선택)
    ETC2 : $("#ETC2").val(), //사용자 추가필드2 (선택)
    ETC3 : $("#ETC3").val(), //사용자 추가필드3 (선택)
    ETC4 : $("#ETC4").val(), //사용자 추가필드4 (선택)
    ETC5 : $("#ETC5").val(), //사용자 추가필드5 (선택)
});

샘플 예제

<!DOCTYPE html>
<html>
<head></head>
<body>
<script src="https://code.jquery.com/jquery-1.12.4.min.js"></script>
<script src="https://www.cookiepayments.com/js/cookiepayments-1.1.3.js"></script>
<script>
cookiepayments.init({
    api_id: 'abcde12345', //쿠키페이 결제 연동 id
    api_key: '4229dd5550455ab34c876c0b751982b601198f621234567890', //쿠키페이 결제 연동 key
});

function pay() {
    cookiepayments.payrequest({
        ORDERNO: $("#ORDERNO").val(), //주문번호 (필수)
        PRODUCTNAME: $("#PRODUCTNAME").val(), //상품명 (필수)
        AMOUNT: $("#AMOUNT").val(), //결제 금액 (필수)
        BUYERNAME: $("#BUYERNAME").val(), //고객명 (필수)
        BUYEREMAIL: $("#BUYEREMAIL").val(), //고객 e-mail (필수)
        PAYMETHOD: $("#PAYMETHOD").val(), //결제 수단 (선택)
        PRODUCTCODE: $("#PRODUCTCODE").val(), //상품 코드 (선택)
        BUYERID: $("#BUYERID").val(), //고객 아이디 (선택)
        BUYERADDRESS: $("#BUYERADDRESS").val(), //고객 주소 (선택)
        BUYERPHONE : $("#BUYERPHONE").val(), //고객 휴대폰번호 (선택, 웰컴페이는 필수)
        RETURNURL: $("#RETURNURL").val(), //결제 완료 후 리다이렉트 url (필수)
        ETC1 : $("#ETC1").val(), //사용자 추가필드1 (선택)
        ETC2 : $("#ETC2").val(), //사용자 추가필드2 (선택)
        ETC3 : $("#ETC3").val(), //사용자 추가필드3 (선택)
        ETC4 : $("#ETC4").val(), //사용자 추가필드4 (선택)
        ETC5 : $("#ETC5").val(), //사용자 추가필드5 (선택)
    });
}
</script>

<form name="payform">
    <input type="text" name="ORDERNO" id="ORDERNO" placeholder="주문번호" value="">
    <input type="text" name="PRODUCTNAME" id="PRODUCTNAME" placeholder="상품명" value="">
    <input type="text" name="AMOUNT" id="AMOUNT" placeholder="금액" value="">
    <input type="text" name="BUYERNAME" id="BUYERNAME" placeholder="고객명" value="">
    <input type="text" name="BUYEREMAIL" id="BUYEREMAIL" placeholder="고객 e-mail" value="">
    <input type="text" name="PAYMETHOD" id="PAYMETHOD" placeholder="결제수단" value="CARD">
    <input type="text" name="PRODUCTCODE" id="PRODUCTCODE" placeholder="상품 코드" value="">
    <input type="text" name="BUYERID" id="BUYERID" placeholder="고객 ID" value="">
    <input type="text" name="BUYERADDRESS" id="BUYERADDRESS" placeholder="고객 주소" value="">
    <input type="text" name="BUYERPHONE" id="BUYERPHONE" placeholder="고객 휴대폰번호" value="">
    <input type="text" name="RETURNURL" id="RETURNURL" placeholder="결제 완료 후 리다이렉트 url" value="">
    <input type="text" name="ETC1" id="ETC1" placeholder="사용자 추가필드 1" value="">
    <input type="text" name="ETC2" id="ETC2" placeholder="사용자 추가필드 2" value="">
    <input type="text" name="ETC3" id="ETC3" placeholder="사용자 추가필드 3" value="">
    <input type="text" name="ETC4" id="ETC4" placeholder="사용자 추가필드 4" value="">
    <input type="text" name="ETC5" id="ETC5" placeholder="사용자 추가필드 5" value="">
</form>

<button type="button" onclick="pay();">결제하기</button>

</body>
</html>
CURL

샘플 예제

curl -H "Content-Type: application/json" \
     -H "ApiKey": "{쿠키페이 결제 연동 key}" \
     -d '{ "API_ID": "{쿠키페이 결제 연동 id}",
           "ORDERNO": "{주문번호}",
           "PRODUCTNAME": "{상품명}",
           "AMOUNT": "{결제금액}",
           "BUYERNAME": "{고객명}",
           "BUYEREMAIL":"{고객 e-mail}",
           "BUYERPHONE":"{고객 휴대폰번호}",
           "RETURNURL": "{결제 완료 후 리다이렉트 url}",
           "ETC1": "{사용자 추가필드 1}",
           "ETC2": "{사용자 추가필드 2}",
           "ETC3": "{사용자 추가필드 3}",
           "ETC4": "{사용자 추가필드 4}",
           "ETC5": "{사용자 추가필드 5}"
        }' \
    -X POST "https://www.cookiepayments.com/pay/ready"
PHP

샘플 예제

$headers = array(); 

array_push($headers, "Content-Type: application/json; charset=utf-8");
array_push($headers, "ApiKey: {쿠키페이 결제 연동 key}");

$cookiepayments_url = "https://www.cookiepayments.com/pay/ready";

$request_data_array = array(
    'API_ID' => '{쿠키페이 결제 연동 id}',
    'ORDERNO' => '{주문번호}',
    'PRODUCTNAME' => '{상품명}',
    'AMOUNT' => '{결제 금액}',
    'BUYERNAME' => '{고객명}',
    'BUYEREMAIL' => '{고객 e-mail}',
    'RETURNURL' => '{결제 완료 후 리다이렉트 url}',
    'PRODUCTCODE' => '{상품 코드}',
    'PAYMETHOD' => '{결제 수단}',
    'BUYERID' => '{고객 ID}',
    'BUYERADDRESS' => '{고객 주소}',
    'BUYERPHONE' => '{고객 휴대폰번호}',
    'ETC1' => '{사용자 추가필드 1}',
    'ETC2' => '{사용자 추가필드 2}',
    'ETC3' => '{사용자 추가필드 3}',
    'ETC4' => '{사용자 추가필드 4}',
    'ETC5' => '{사용자 추가필드 5}',
);

$cookiepayments_json = json_encode($request_data_array, JSON_UNESCAPED_UNICODE);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $cookiepayments_url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, $cookiepayments_json);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 10);
curl_setopt($ch, CURLOPT_TIMEOUT, 20);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);
curl_close($ch);

var_dump($response);
요청 전문 파라미터

요청 시 주의사항 (필독)

요청 시 ORDERNO(주문번호)는 유니크 한 값이어야 합니다. 결제 시 마다 새로 생성된 값을 넘겨주셔야 합니다. 중복 된 주문번호일 경우 결제 실패가 일어나거나 결제 데이터가 부정확할 수 있습니다.

항목명 길이 내용 구분 비고
ApiKey 제한없음 쿠키페이 결제 연동 key 필수
(헤더)
쿠키페이에서 발급받은 결제 연동 key
API_ID 20 쿠키페이 결제 연동 id 필수 쿠키페이에서 발급받은 결제 연동 id
ORDERNO 50 주문번호 필수 각 주문마다 유니크해야 합니다
PRODUCTNAME 40 상품명 필수 & 문자 포함시 오류 발생
AMOUNT 10 결제 금액 필수 숫자만 사용합니다
BUYERNAME 20 고객명 필수 결제자 이름
BUYEREMAIL 50 고객 e-mail 필수
RETURNURL 100 결제 결과 값 받는 주소 필수 결제 완료 후 리다이렉트 할 URL(새창)
HOMEURL 100 결제 결과 값 받는 주소 필수 결제 완료 후 리다이렉트 할 URL(결제창에서 이동)
(웹뷰 방식의 화면활성화시 HOMEURL을 사용하시기 바랍니다)
페이조아 PG만 사용
DIRECTRESULTFLAG 1 크로스도메인 이슈 선택 페이조아 PG만 사용
파이어폭스 사용시 DIRECTRESULTFLAG: Y 사용하고,
리턴값은 RETURNURL를 사용하지 마시고,
HOMEURL 사용하십시요.(필수)

파이어폭스는 IE와 크롬과 달리 호출창, 팝업창 간에
크로스도메인 이슈 문제 해결을 위한 것입니다.
MTYPE 1 웹뷰 사용시 선택 페이조아 PG만 사용( M : 앱뷰 활성화 )
CANCELURL 100 결제 중지 시 취소 주소 선택 웰컴페이 PG만 사용
PRODUCTCODE 10 상품 코드 선택
PAYMETHOD 20 결제수단 선택 CARD(카드), KAKAOPAY(카카오페이), BANK(계좌이체)
VACCT(가상계좌), MOBILE(휴대폰)
(default: CARD) 결제는 PG사 등록 시 사용신청을 하셔야합니다.
BUYERID 20 고객 ID 선택
BUYERADDRESS 100 고객 주소 선택
BUYERPHONE 20 고객 휴대폰번호 선택 웰컴페이 PG는 필수값
TAXYN 1 과세/비과세 선택 페이조아 PG만 사용(Y:과세, N:비과세) - default : 과세
CANCELULR 100 취소 시 리턴 URL 선택 웰컴페이 PG만 사용
CLOSEURL 100 취소 후 이동할 URL 선택 카카오페이 결제만 사용
FAILURL 100 실패 후 이동할 URL 선택 카카오페이 결제만 사용
ETC1 100 사용자 추가 필드1 선택 입력시 응답파라미터에 값을 전달합니다
ETC2 100 사용자 추가 필드2 선택 입력시 응답파라미터에 값을 전달합니다
ETC3 100 사용자 추가 필드3 선택 입력시 응답파라미터에 값을 전달합니다
ETC4 100 사용자 추가 필드4 선택 입력시 응답파라미터에 값을 전달합니다
ETC5 100 사용자 추가 필드5 선택 입력시 응답파라미터에 값을 전달합니다

인증결제 응답전문

응답 전문 파라미터

결과값은 Form Data로 전송됩니다.

항목명 길이 내용 구분 비고
RESULTCODE 4 결과 코드 필수 PG사 응답 코드 (성공시 "0000", 그외 에러)
RESULTMSG 100 결과 메세지 필수 PG사 응답 메시지 ("성공" 또는 오류 메세지)
ORDERNO 50 주문번호 필수 주문번호
AMOUNT 10 결제 된 금액 필수
TID 20 PG 거래 고유번호 필수 PG사 결제 거래고유번호 (전표출력 및 결제취소에 사용됩니다)
ACCEPTDATE 20 승인일시 필수 PG사 결제 승인일시
ACCEPTNO 10 승인번호 필수 PG사 결제 승인번호
CASH_BILL_NO 10 현금영수증일련번호 필수 가상계좌 및 계좌이체 시 현금영수증 일련번호
CARDNAME 10 입금할 은행명 필수 가상계좌 및 계좌이체 시 입금할 은행명
ACCOUNTNO 10 입금할 계좌번호 필수 가상계좌 시 입금할 계좌번호
RECEIVERNAME 10 입금할 예금주 필수 가상계좌 시 입금할 예금주
DEPOSITENDDATE 10 입금마감일 필수 가상계좌 시 입금마감일
CARDCODE 10 입금할 은행코드 필수 가상계좌 시 입금할 은행코드
ETC1 100 사용자 추가 필드1 선택 결제 요청시 입력한 값
ETC2 100 사용자 추가 필드2 선택 결제 요청시 입력한 값
ETC3 100 사용자 추가 필드3 선택 결제 요청시 입력한 값
ETC4 100 사용자 추가 필드4 선택 결제 요청시 입력한 값
ETC5 100 사용자 추가 필드5 선택 결제 요청시 입력한 값

결제 완료 통지 전문

통지 전문 파라미터

통지 전문은 JSON POST 형식으로 전송됩니다.

통지 전문은 쿠키페이먼트에서 고객사로 전송됩니다.
결제 완료 통지 사용가능 PG사 : 페이조아
결제방식 : 신용카드(인증), 계좌이체, 가상계좌

항목명 길이 내용 구분 비고
API_ID 20 쿠키페이 결제 연동 id 필수(json) 쿠키페이에서 발급받은 결제 연동 id
ORDERNO 50 주문번호 필수(json) 주문번호
AMOUNT 10 결제 된 금액 필수(json)
TID 20 PG 거래 고유번호 필수(json) PG사 결제 거래고유번호 (전표출력 및 결제취소에 사용됩니다)
BUYEREMAIL 50 구매자 이메일 필수(json)
BUYERNAME 20 구매자 이름 필수(json)
PRODUCTCODE 10 상품 코드 필수(json)
PRODUCTNAME 40 상품명 필수(json)
ACCEPT_DATE 10 승인일시 필수(json) PG사 결제 승인일시
ACCEPT_NO 10 승인번호 필수(json) PG사 결제 승인번호
CARDCODE 10 카드 코드 필수(json) 사용 카드 카드번호/가상계좌 시 입금할 은행코드
CARDNAME 10 카드사명 필수(json) 사용 카드사명/가상계좌시 입금할 은행명
CARDNO 20 카드번호 필수(json) 예) **000111
RECEIVERNAME 10 입금할 예금주 필수(json) 가상계좌 시 입금할 예금주
DEPOSITENDDATE 10 입금마감일 필수(json) 가상계좌 시 입금마감일
ETC1 100 사용자 추가 필드1 선택 결제 요청시 입력한 값
ETC2 100 사용자 추가 필드2 선택 결제 요청시 입력한 값
ETC3 100 사용자 추가 필드3 선택 결제 요청시 입력한 값
ETC4 100 사용자 추가 필드4 선택 결제 요청시 입력한 값
ETC5 100 사용자 추가 필드5 선택 결제 요청시 입력한 값

결제정보 검증

결제정보 검증

최종 결제 요청이 브라우저에서 이루어지는 경우 결제 금액을 위변조하여 결제요청을 할 수 있습니다. 이 경우 결제 완료 후 처음 요청했던 금액과 실제로 결제된 금액이 일치하는지 확인하는 과정이 필요합니다.

TOKEN 발행 URL
https://www.cookiepayments.com/payAuth/token [POST]
TOKEN 요청 전문 파라미터
항목명 길이 내용 구문 비고
pay2_id 30 cookiepayments에서 발급받은 ID 필수 cookiepayments사에서 부여
pay2_key 50 cookiepayments에서 발급받은 연동키 필수 cookiepayments사에서 부여
결제 검증 URL
https://www.cookiepayments.com/api/paycert [POST]
결제검증 요청 전문 파라미터
항목명 길이 내용 구문 비고
tid 50 PG사 거래 고유번호 필수 PG사에서 부여
CURL
/* 토큰 발급 API */
curl -H "Content-Type: application/json" \
     -d '{
         "pay2_id": "{쿠키페이 결제 연동 id}",
         "pay2_key": "{쿠키페이 결제 연동 key}"
         }' \
     -X POST "https://www.cookiepayments.com/payAuth/token"

/* 발급 받은 TOKEN으로 결제 취소 API 통신 */
curl -H "Content-Type: application/json" \
     -H "TOKEN: {TOKEN API통해 발행된 TOKEN 값}" \
     -d '{"tid": "{결제 후 응답받은 PG 거래 고유번호}"}' \
     -X POST "https://www.cookiepayments.com/api/paycert"
PHP
/* 토큰 발행 API */
$headers = array(
    'Content-Type: application/json; charset=utf-8',
);

$token_url = "https://www.cookiepayments.com/payAuth/token";

$request_data = array(
    'pay2_id' => '{쿠키페이 결제 연동 id}',
    'pay2_key'=> '{쿠키페이 결제 연동 key}',
);

$request_data = json_encode($request_data, JSON_UNESCAPED_UNICODE);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $token_url);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, $request_data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 10);
curl_setopt($ch, CURLOPT_TIMEOUT, 20);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$result = curl_exec($ch);
curl_close($ch);
$result = json_decode($result, true);

if($result['RTN_CD'] == '0000') {

    $paycert_url = "https://www.cookiepayments.com/api/paycert";

    $headers = array(
        'content-type: application/json; charset=utf-8',
        'TOKEN: ' . $result['TOKEN'],
    );

    $request_data = array(
        'tid' => '{결제 후 응답받은 PG사 거래 고유번호}',
    );

    $request_data = json_encode($request_data, JSON_UNESCAPED_UNICODE);

    $ch = curl_init();

    curl_setopt($ch, CURLOPT_URL, $paycert_url);
    curl_setopt($ch, CURLOPT_POST, false);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $request_data);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 10);
    curl_setopt($ch, CURLOPT_TIMEOUT, 20);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    $response = curl_exec($ch);
    curl_close($ch);

    // 결과 처리
    var_dump($response);
}
결제검증 응답 전문 파라미터
항목명 길이 내용 구분 비고
RESULTCODE 4 PG 사 응답코드 필수(json) 응답 코드 (성공시 "0000", 그외 에러)
RESULTMSG 100 PG 사 응답메시지 필수(json) 응답 메시지 ("성공" 또는 오류 메세지)
ORDERNO 50 주문번호 필수(json) 결제한 주문번호
AMOUNT 10 결제 된 금액 필수(json) 문자 및 특수문자 허용 불가
BUYERNAME 20 고객명 필수(json)
BUYEREMAIL 50 고객 e-mail 필수(json)
PRODUCTNAME 40 상품명 필수(json) '&' 문자 포함시 오류 발생
PRODUCTCODE 10 상품코드 필수(json)
PAYMETHOD 20 결제수단 필수(json) CARD(카드), KAKAOPAY(카카오페이), BANK(계좌이체)
VACCT(가상계좌), MOBILE(휴대폰)
BUYERID 20 고객 ID 필수(json)
TID 50 PG 거래 고유번호 필수(json) PG사 결제 거래고유번호 (전표출력 및 결제취소에 사용됩니다)
ACCEPTNO 10 승인번호 필수(json) PG사 결제 승인번호
ACCEPTDATE 20 승인일시 필수(json) PG사 결제 승인일시
CANCELDATE 20 취소날짜 필수(json) 결제 취소한 경우 취소일시
CANCELMSG 50 취소메시지 필수(json) 결제 취소한 경우 취소메세지
ACCOUNTNO 50 가상계좌번호 (json) 가상계좌 이용 시 리턴 값
RECEIVERNAME 50 예금주성명 (json) 가상계좌 이용 시 리턴 값
DEPOSITENDDATE 50 계좌사용만료일 (json) 가상계좌 이용 시 리턴 값
CARDNAME 50 은행명 (json) 가상계좌 이용 시 리턴 값
CARDCODE 50 은행코드 (json) 가상계좌 이용 시 리턴 값