정기결제

카드 정기결제 시작하기

카드 자동 결제는 Billing 정기결제로 카유생비(카드번호, 유효기간, 생년월일, 비밀번호)를 보내 빌링키를 취득 한 후, 원하는 결제시점에 API로 빌링키 + 결제금액을 보내 결제하는 방식입니다.
특성상 빌링키 발급받는 과정만 클라이언트 작업이 필요하며 , 해당 빌링키로 결제를 요청, 예약, 취소하는 작업은 서버사이드에서 이루어집니다.

빌링키란?
구독형 정기결제, 종량제 과금결제 등 원하는 시점에 재 결제를 진행할 수 있는 결제용 암호화 키 입니다. 가맹점이 고객의 카드정보를 소유할 수 없기 때문에 카드사로부터 해당 카드에 대응하는 빌링키 발급 받아 저장하고 원하는 시점에 해당 빌링키로 결제를 청구할 수 있습니다.

진행 순서

1. 빌링키 발급 요청합니다.
   
   • 비인증방식 - 개발사의 UI에서 지불수단을 입력받아 PG사에 전달 (클라이언트/서버사이드)
     
2. 빌링키로 결제 요청하기
   
   • 또는 결제를 미리 예약하기
     
   • 예약된 결제 취소하기
     
   • 반복해서 자동결제 하기
     
   • 원하실 경우 빌링키 취소하기
     
3. 빌링키 조회하기
   
   • API를 통한 빌링키의 정보를 확인 할 수 있습니다.
     

빌링키를 발급받는 것이 시작이며, 발급된 빌링키로 결제를 요청하거나, 예약하거나, 결제 반복을 구현할 수 있습니다.

빌링키 발급받기 - 비인증방식

기본도메인(요청도메인)

라이브 : https://www.cookiepayments.com [POST] 
테스트 : https://sandbox.cookiepayments.com [POST] 

TOKEN 발행 URL

{요청도메인}/payAuth/token [POST]

TOKEN 요청 전문 파라미터

샘플예제

CURL

/* 토큰 발급 API */
curl -H "Content-Type: application/json" \
     -d '{
         "pay2_id": "cookiepayments에서 발급받은 ID",
         "pay2_key": "cookiepayments에서 발급받은 연동키"
         }' \
     -X POST "{요청도메인}/payAuth/token"

PHP

/* 토큰 발행 API */
$tokenheaders = array(); 
array_push($tokenheaders, "content-type: application/json; charset=utf-8");

$token_url = "{요청도메인}/payAuth/token";

$token_request_data = array(
    'pay2_id' => 'cookiepayments에서 발급받은 ID',
    'pay2_key'=> 'cookiepayments에서 발급받은 연동키',
);

$req_json = json_encode($token_request_data, TRUE);

$ch = curl_init(); // curl 초기화

curl_setopt($ch,CURLOPT_URL, $token_url);
curl_setopt($ch,CURLOPT_POST, false);
curl_setopt($ch,CURLOPT_POSTFIELDS, $req_json);
curl_setopt($ch,CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch,CURLOPT_CONNECTTIMEOUT ,3);
curl_setopt($ch,CURLOPT_TIMEOUT, 20);
curl_setopt($ch, CURLOPT_HTTPHEADER, $tokenheaders);
$RES_STR = curl_exec($ch);
curl_close($ch);
$RES_STR = json_decode($RES_STR,TRUE);

TOKEN 요청 응답 전문 파라미터

응답데이터 예

{
    "RTN_CD": "0000",
    "RTN_MSG": "성공",
    "TOKEN": "암호화된코드"
}

빌링키 발행 URL

{요청도메인}/Subscribe/billkeygen [POST]

요청 전문 파라미터

샘플예제

CURL

/* 토큰 발급 API */
curl -H "Content-Type: application/json" \
     -d '{
         "pay2_id": "cookiepayments에서 발급받은 ID",
         "pay2_key": "cookiepayments에서 발급받은 연동키"
         }' \
     -X POST "{요청도메인}/payAuth/token"

/* 정기결제 API */
curl -H "Content-Type: application/json" \
     -H "ApiKey: COOKIEPAY에서 발급받은 연동키" \
     -H "TOKEN: TOKEN API통해 발행된 TOKEN 값" \
     -d '{
            "API_ID": "COOKIEPAY에서 발급받은 가맹점연동 ID",
            "ORDERNO": "주문번호",
            "PRODUCTNAME": "상품명",
            "PRODUCTCODE": "상품코드",
            "AMOUNT": "결제금액",
            "CARDNO": "카드번호",
            "EXPIREDT": "카드유효기간 (YYMM)",
            "CARDPWD": "카드비밀번호 앞 2자리",
            "CARDAUTH": "카드소유자 생년월일(YYMMDD)",
            "QUOTA":"할부개월",
            "BUYERNAME": "고객명",
            "BUYERID": "고객 ID",
            "BUYERPHONE":"고객 휴대폰번호",
            "BUYEREMAIL":"고객 E-MAIL",
            "PRODUCTTYPE":"2",
        }' \
     -X POST "{요청도메인}/Subscribe/billkeygen"

PHP

/* 토큰 발행 API */
$tokenheaders = array(); 
array_push($tokenheaders, "content-type: application/json; charset=utf-8");

$token_url = "{요청도메인}/payAuth/token";

$token_request_data = array(
    'pay2_id' => 'cookiepayments에서 발급받은 ID',
    'pay2_key'=> 'cookiepayments에서 발급받은 연동키',
);

$req_json = json_encode($token_request_data, TRUE);

$ch = curl_init(); // curl 초기화

curl_setopt($ch,CURLOPT_URL, $token_url);
curl_setopt($ch,CURLOPT_POST, false);
curl_setopt($ch,CURLOPT_POSTFIELDS, $req_json);
curl_setopt($ch,CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch,CURLOPT_CONNECTTIMEOUT ,3);
curl_setopt($ch,CURLOPT_TIMEOUT, 20);
curl_setopt($ch, CURLOPT_HTTPHEADER, $tokenheaders);
$RES_STR = curl_exec($ch);
curl_close($ch);
$RES_STR = json_decode($RES_STR,TRUE);
/* 여기 까지 */
if($RES_STR['RTN_CD'] == '0000'){

$headers = array(); 
array_push($headers, "content-type: application/json; charset=utf-8");
array_push($headers, "ApiKey: COOKIEPAY에서 발급받은 연동키");
array_push($headers, "TOKEN: TOKEN API통해 발행된 TOKEN 값");

$cookiepayments_url = "{요청도메인}/Subscribe/billkeygen";

$request_data_array = array(
                                'API_ID' => 'COOKIEPAY에서 발급받은 가맹점연동 ID',
                                'ORDERNO' => '주문번호',
                                'PRODUCTNAME' => '상품명',
                                'PRODUCTCODE' => '상품코드',
                                'AMOUNT' => '결제금액',
                                'CARDNO' => '카드번호',
                                'EXPIREDT' => '카드유효기간 (YYMM)',
                                'CARDPWD' => '카드비밀번호 앞 2자리',
                                'CARDAUTH' => '카드소유자 생년월일(YYMMDD)',
                                'QUOTA' => '할부개월',
                                'BUYERNAME' => '고객명',
                                'BUYERID' => '고객 ID',
                                'BUYERPHONE' => '고객 휴대폰번호',
                                'BUYEREMAIL' => '고객 E-MAIL',
                                'PRODUCTTYPE' => '2',
                        );

$cookiepayments_json = json_encode($request_data_array, TRUE);

$ch = curl_init(); // curl 초기화

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 ,3);
curl_setopt($ch,CURLOPT_TIMEOUT, 20);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);
curl_close($ch);

var_dump($response);

응답 전문 파라미터

응답데이터 예

{
  "RESULTCODE": "0000",
  "RESULTMSG": "성공",
  "ENC_DATA": "uCAMEsaW+tdhYKcIvzbezan137Igm4u0dEMawS93EhwaaoLE+lAgiMH07ysmVI/q3Ky7X1LOIZ3WuSsGgGkyvQ=="
}

응답전문 파라미터 > 복호화 응답 파라미터 ( 암호화 전문 복호화하기 참조)

복호화 응답데이터 예

{
  "RESULTCODE": "0000",
  "RESULTMSG": "성공",
  "decryptData": {
      "BILLKEY": "발급된BILLKEY",
      "GENDATE": "20220920135340",
      "ORDERNO": "TEST-ORDER-220920-094625",
      "AMOUNT": "0",
      "TID": "",
      "ACCEPTDATE": "",
      "ACCEPTNO": "",
      "BUYERNAME": "홍길동",
      "BUYERID": "BUYERID",
      "BUYERADDRESS": "BUYERADDRESS",
      "BUYERPHONE": "010-1234-5678",
      "BUYEREMAIL": "ufound@gmail.com"
      "CARDCODE": "CCLG"
  }
}

빌링키 조회하기

TOKEN 발행 URL

{요청도메인}/payAuth/token [POST]

2-2 빌링키 조회 URL

{요청도메인}/Subscribe/billingkeylookup [POST]

요청 전문 파라미터

샘플예제

CURL

/* 토큰 발급 API */
curl -H "Content-Type: application/json" \
     -d '{
         "pay2_id": "cookiepayments에서 발급받은 ID",
         "pay2_key": "cookiepayments에서 발급받은 연동키"
         }' \
     -X POST "{요청도메인}/payAuth/token"

/* 정기결제 API */
curl -H "Content-Type: application/json" \
     -H "ApiKey: COOKIEPAY에서 발급받은 연동키" \
     -H "TOKEN: TOKEN API통해 발행된 TOKEN 값" \
     -d '{
         "API_ID": "COOKIEPAY에서 발급받은 가맹점연동 ID",
         "BILLKEY": "빌링키",
         }' \
     -X POST "{요청도메인}/Subscribe/billingkeylookup"

PHP

/* 토큰 발행 API */
$tokenheaders = array(); 
array_push($tokenheaders, "content-type: application/json; charset=utf-8");

$token_url = "{요청도메인}/payAuth/token";

$token_request_data = array(
    'pay2_id' => 'cookiepayments에서 발급받은 ID',
    'pay2_key'=> 'cookiepayments에서 발급받은 연동키',
);

$req_json = json_encode($token_request_data, TRUE);

$ch = curl_init(); // curl 초기화

curl_setopt($ch,CURLOPT_URL, $token_url);
curl_setopt($ch,CURLOPT_POST, false);
curl_setopt($ch,CURLOPT_POSTFIELDS, $req_json);
curl_setopt($ch,CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch,CURLOPT_CONNECTTIMEOUT ,3);
curl_setopt($ch,CURLOPT_TIMEOUT, 20);
curl_setopt($ch, CURLOPT_HTTPHEADER, $tokenheaders);
$RES_STR = curl_exec($ch);
curl_close($ch);
$RES_STR = json_decode($RES_STR,TRUE);
/* 여기 까지 */
if($RES_STR['RTN_CD'] == '0000'){

$headers = array(); 
array_push($headers, "content-type: application/json; charset=utf-8");
array_push($headers, "ApiKey: COOKIEPAY에서 발급받은 연동키");
array_push($headers, "TOKEN: TOKEN API통해 발행된 TOKEN 값");

$cookiepayments_url = "{요청도메인}/Subscribe/billingkeylookup";

$request_data_array = array(
    'API_ID' => 'COOKIEPAY에서 발급받은 가맹점연동 ID',
    'BILLKEY'=> '빌링키',
);

$cookiepayments_json = json_encode($request_data_array, TRUE);

$ch = curl_init(); // curl 초기화

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 ,3);
curl_setopt($ch,CURLOPT_TIMEOUT, 20);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);
curl_close($ch);

var_dump($response);

응답 전문 파라미터

응답데이터 예

{
  "RESULTCODE": "0000",
  "RESULTMSG": "성공",
  "ENC_DATA": "uCAMEsaW+tdhYKcIvzbezan137Igm4u0dEMawS93EhwaaoLE+lAgiMH07ysmVI/q3Ky7X1LOIZ3WuSsGgGkyvQ=="
}

응답전문 파라미터 > 복호화 응답 파라미터 (암호화 전문 복호화하기 참조)

복호화 응답데이터 예

{
  "RESULTCODE": "0000",
  "RESULTMSG": "성공",
  "decryptData": {
      "BILLKEY": "조회요청한BILLKEY",
      "GENDATE": "20220920135619",
      "ORDERNO": "TEST-ORDER-220920-094625",
      "PRODUCTNAME": "테스트상품100",
      "PRODUCTCODE": "TP-100",
      "AMOUNT": "0",
      "TAXFREECD": "Y",
      "QUOTA": "00",
      "BUYERNAME": "홍길동",
      "BUYERID": "BUYERID",
      "BUYERADDRESS": "BUYERADDRESS",
      "BUYERPHONE": "010-1234-5678",
      "BUYEREMAIL": "ufound@gmail.com",
      "CARDCODE": "",
      "KEY_STATUS": "사용가능"
  }
}

빌링키 발급 취소하기

TOKEN 발행 URL

{요청도메인}/payAuth/token [POST]

3-2 빌링키 취소 URL

{요청도메인}/Subscribe/billingkeycancel [POST]

요청 전문 파라미터

샘플예제

CURL

/* 토큰 발급 API */
curl -H "Content-Type: application/json" \
     -d '{
         "pay2_id": "cookiepayments에서 발급받은 ID",
         "pay2_key": "cookiepayments에서 발급받은 연동키"
         }' \
     -X POST "{요청도메인}/payAuth/token"

/* 정기결제 API */
curl -H "Content-Type: application/json" \
     -H "ApiKey: COOKIEPAY에서 발급받은 연동키" \
     -H "TOKEN: TOKEN API통해 발행된 TOKEN 값" \
     -d '{
         "API_ID": "COOKIEPAY에서 발급받은 가맹점연동 ID",
         "BILLKEY": "빌링키",
         }' \
     -X POST "{요청도메인}/Subscribe/billingkeycancel"

PHP

/* 토큰 발행 API */
$tokenheaders = array(); 
array_push($tokenheaders, "content-type: application/json; charset=utf-8");

$token_url = "{요청도메인}/payAuth/token";

$token_request_data = array(
    'pay2_id' => 'cookiepayments에서 발급받은 ID',
    'pay2_key'=> 'cookiepayments에서 발급받은 연동키',
);

$req_json = json_encode($token_request_data, TRUE);

$ch = curl_init(); // curl 초기화

curl_setopt($ch,CURLOPT_URL, $token_url);
curl_setopt($ch,CURLOPT_POST, false);
curl_setopt($ch,CURLOPT_POSTFIELDS, $req_json);
curl_setopt($ch,CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch,CURLOPT_CONNECTTIMEOUT ,3);
curl_setopt($ch,CURLOPT_TIMEOUT, 20);
curl_setopt($ch, CURLOPT_HTTPHEADER, $tokenheaders);
$RES_STR = curl_exec($ch);
curl_close($ch);
$RES_STR = json_decode($RES_STR,TRUE);
/* 여기 까지 */
if($RES_STR['RTN_CD'] == '0000'){

$headers = array(); 
array_push($headers, "content-type: application/json; charset=utf-8");
array_push($headers, "ApiKey: COOKIEPAY에서 발급받은 연동키");
array_push($headers, "TOKEN: TOKEN API통해 발행된 TOKEN 값");

$cookiepayments_url = "{요청도메인}/Subscribe/billingkeycancel";

$request_data_array = array(
    'API_ID' => 'COOKIEPAY에서 발급받은 가맹점연동 ID',
    'BILLKEY'=> '빌링키',
);

$cookiepayments_json = json_encode($request_data_array, TRUE);

$ch = curl_init(); // curl 초기화

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 ,3);
curl_setopt($ch,CURLOPT_TIMEOUT, 20);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);
curl_close($ch);

var_dump($response);

응답 전문 파라미터

응답데이터 예

{
  "RESULTCODE": "0000",
  "RESULTMSG": "성공",
  "ENC_DATA": "uCAMEsaW+tdhYKcIvzbezan137Igm4u0dEMawS93EhwaaoLE+lAgiMH07ysmVI/q3Ky7X1LOIZ3WuSsGgGkyvQ=="
}

응답전문 파라미터 > 복호화 응답 파라미터 (암호화 전문 복호화하기 참조)

복호화 응답데이터 예

{
  "RESULTCODE": "0000",
  "RESULTMSG": "성공",
  "decryptData":  {
      "BILLKEY": "취소된 BILLKEY",
  }
}

빌링키로 결제 요청하기

기본도메인(요청도메인)

라이브 : https://www.cookiepayments.com [POST] 
테스트 : https://sandbox.cookiepayments.com [POST] 

TOKEN 발행 URL

{요청도메인}/payAuth/token [POST]

빌링키로 결제 요청 URL

{요청도메인}/Subscribe/payments [POST]

요청 전문 파라미터

샘플예제

CURL

/* 토큰 발급 API */
curl -H "Content-Type: application/json" \
     -d '{
         "pay2_id": "cookiepayments에서 발급받은 ID",
         "pay2_key": "cookiepayments에서 발급받은 연동키"
         }' \
     -X POST "{요청도메인}/payAuth/token"

/* 정기결제 API */
curl -H "Content-Type: application/json" \
     -H "ApiKey: COOKIEPAY에서 발급받은 연동키" \
     -H "TOKEN: TOKEN API통해 발행된 TOKEN 값" \
     -d '{
            "API_ID": "COOKIEPAY에서 발급받은 가맹점연동 ID",
            "BILLKEY": "빌링키",
            "ORDERNO": "주문번호",
            "PRODUCTNAME": "상품명",
            "PRODUCTCODE": "상품코드",
            "AMOUNT": "결제금액",
            "TAXFREECD":"과세여부",
            "QUOTA":"할부개월",
            "BUYERID": "고객 ID",
            "BUYERNAME": "고객명",
            "BUYERPHONE":"고객 휴대폰번호",
            "BUYEREMAIL":"고객 E-MAIL",
            "BUYERADDRESS":"고객 주소",
            "PRODUCTTYPE":"2"
        }' \
     -X POST "{요청도메인}/Subscribe/payments"

PHP

/* 토큰 발행 API */
$tokenheaders = array(); 
array_push($tokenheaders, "content-type: application/json; charset=utf-8");

$token_url = "{요청도메인}/payAuth/token";

$token_request_data = array(
    'pay2_id' => 'cookiepayments에서 발급받은 ID',
    'pay2_key'=> 'cookiepayments에서 발급받은 연동키',
);

$req_json = json_encode($token_request_data, TRUE);

$ch = curl_init(); // curl 초기화

curl_setopt($ch,CURLOPT_URL, $token_url);
curl_setopt($ch,CURLOPT_POST, false);
curl_setopt($ch,CURLOPT_POSTFIELDS, $req_json);
curl_setopt($ch,CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch,CURLOPT_CONNECTTIMEOUT ,3);
curl_setopt($ch,CURLOPT_TIMEOUT, 20);
curl_setopt($ch, CURLOPT_HTTPHEADER, $tokenheaders);
$RES_STR = curl_exec($ch);
curl_close($ch);
$RES_STR = json_decode($RES_STR,TRUE);
/* 여기 까지 */
if($RES_STR['RTN_CD'] == '0000'){

$headers = array(); 
array_push($headers, "content-type: application/json; charset=utf-8");
array_push($headers, "ApiKey: COOKIEPAY에서 발급받은 연동키");
array_push($headers, "TOKEN: TOKEN API통해 발행된 TOKEN 값");

$cookiepayments_url = "{요청도메인}/Subscribe/payments";

$request_data_array = array(
                                'API_ID' => 'COOKIEPAY에서 발급받은 가맹점연동 ID',
                                'BILLKEY' => '빌링키',
                                'ORDERNO' => '주문번호',
                                'PRODUCTNAME' => '상품명',
                                'PRODUCTCODE' => '상품코드',
                                'AMOUNT' => '결제금액',
                                'TAXFREECD' => '과세여부',
                                'QUOTA' => '할부개월',
                                'BUYERID' => '고객 ID',
                                'BUYERNAME' => '고객명',
                                'BUYERPHONE' => '고객 휴대폰번호',
                                'BUYEREMAIL' => '고객 E-MAIL',
                                'BUYERADDRESS'=>'고객 주소',
                                'PRODUCTTYPE'=>'2'
                        );

$cookiepayments_json = json_encode($request_data_array, TRUE);

$ch = curl_init(); // curl 초기화

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 ,3);
curl_setopt($ch,CURLOPT_TIMEOUT, 20);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);
curl_close($ch);

var_dump($response);

응답 전문 파라미터

응답데이터 예

{
  "RESULTCODE": "0000",
  "RESULTMSG": "성공",
  "ENC_DATA": "uCAMEsaW+tdhYKcIvzbezan137Igm4u0dEMawS93EhwaaoLE+lAgiMH07ysmVI/q3Ky7X1LOIZ3WuSsGgGkyvQ=="
}

응답전문 파라미터 > 복호화 응답 파라미터 (암호화 전문 복호화하기 참조)

복호화 응답데이터 예

{
    "RESULTCODE": "0000",
    "RESULTMSG": "성공",
    "decryptData": {
        "BILLKEY": "결제요청한BILLKEY",
        "ORDERNO": "TEST-ORDER-220920-094625",
        "AMOUNT": "100",
        "TID": "cEH000000000000000",
        "ACCEPTDATE": "20220528133047",
        "ACCEPTNO": "00000000",
        "BUYERNAME": "홍길동",
        "BUYERID": "guest",
        "BUYERADDRESS": "",
        "BUYERPHONE": "",
        "BUYEREMAIL": ""
    }
}

결제정보 검증

결제정보 검증

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

기본도메인(요청도메인)

라이브 : https://www.cookiepayments.com [POST] 
테스트 : https://sandbox.cookiepayments.com [POST] 

TOKEN 발행 URL

{요청도메인}/payAuth/token [POST]

TOKEN 요청 전문 파라미터

결제 검증 URL

{요청도메인}/api/paycert [POST]

결제검증 요청 전문 파라미터

CURL

/* 토큰 발급 API */
curl -H "Content-Type: application/json" \
     -d '{
         "pay2_id": "{쿠키페이 결제 연동 id}",
         "pay2_key": "{쿠키페이 결제 연동 key}"
         }' \
     -X POST "{요청도메인}/payAuth/token"

/* 발급 받은 TOKEN으로 결제 취소 API 통신 */
curl -H "Content-Type: application/json" \
     -H "TOKEN: {TOKEN API통해 발행된 TOKEN 값}" \
     -d '{"tid": "{결제 후 응답받은 PG 거래 고유번호}"}' \
     -X POST "{요청도메인}/api/paycert"

PHP

/* 토큰 발행 API */
$headers = array(
    'Content-Type: application/json; charset=utf-8',
);

$token_url = "{요청도메인}/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 = "{요청도메인}/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);
}

결제검증 응답 전문 파라미터

결제 예약 시작하기

결제 요청하기는해당 시점(유저 액션 또는 개발사에서 구현한 스케쥴러)에 결제를 요청하는 것이라면,
이와 다르게 미리 결제를 예약하는 방법을 소개하고자 합니다.

결제 예약은 주로 반복결제(subscription)를 구현하고자 하는 개발사에서 많이 이용합니다.
쿠키페이 정책상주기적인 반복결제(periodic)기능은 제공하지 않고 있습니다.
개발사에서 반복결제를 쉽게 구현하는 방법으로는 결제 예약 이후 해당 건 결제 결과 서버 통지시 개발사가 다음 결제를 연계하여 예약건다면, 반복결제가 쉽게 구현 가능합니다.

반복결제를 위한 예약 절차

1) 결제정보 및 예약 실행시간을 포함해 결제 예약 API로 요청합니다.

• 예약이 실패한 경우 오류처리를 진행합니다. 예약이 실패할 수 있는 경우는 다음과 같습니다.
  ① 잘못된 빌링키를 보냈거나 다른 프로젝트의 빌링키로 요청한 경우
  ② 결제 최소금액을 잘못 기입한 경우
  ③ 결제 예약시간이 과거의 시간인 경우
  ④ 빌링키가 만료된 경우 ( 사용 불가 상태인 경우 )
  

2) 예약이 성공적으로 되었다면, RESERVE_ID를 저장합니다. 예약 취소시 반드시 필요한 값 입니다.

3) 쿠키페이 서버에서 예약된 시간(매시 0분, 20분, 40분)에 결제를 실행합니다.

• 결제가 실패한 경우 오류 내용은 서버로 통지됩니다.

4) 쿠키페이 서버에서 결제 성공결과를 서버로 통지합니다.

5) 예약결제 완료 이후 다음 예약결제를 진행하려면 다시 1)번 자동결제 예약 API를 진행합니다.

결제예약 요청하기

기본도메인(요청도메인)

라이브 : https://www.cookiepayments.com [POST] 
테스트 : https://sandbox.cookiepayments.com [POST] 

TOKEN 발행 URL

{요청도메인}/payAuth/token [POST]

5-1-2 결제예약 요청 URL

{요청도메인}/Subscribe/schedule_reserve [POST]

요청 전문 파라미터

샘플예제

CURL

/* 토큰 발급 API */
curl -H "Content-Type: application/json" \
     -d '{
         "pay2_id": "cookiepayments에서 발급받은 ID",
         "pay2_key": "cookiepayments에서 발급받은 연동키"
         }' \
     -X POST "{요청도메인}/payAuth/token"

/* 정기결제 API */
curl -H "Content-Type: application/json" \
     -H "ApiKey: COOKIEPAY에서 발급받은 연동키" \
     -H "TOKEN: TOKEN API통해 발행된 TOKEN 값" \
     -d '{
            "API_ID": "COOKIEPAY에서 발급받은 가맹점연동 ID",
            "BILLKEY": "빌링키",
            "ORDERNO": "주문번호",
            "PRODUCTNAME": "상품명",
            "PRODUCTCODE": "상품코드",
            "AMOUNT": "결제금액",
            "TAXFREECD":"과세여부",
            "QUOTA":"할부개월",
            "SCHEDULE_AT":"결제시간(202201010101)",
            "BUYERNAME": "고객명",
            "PRODUCTTYPE": "2",
            "BUYERID": "고객 ID",
            "BUYERPHONE":"고객 휴대폰번호",
            "BUYEREMAIL":"고객 E-MAIL",
            "BUYERADDRESS":"고객 주소",
            "NOTICE_URL":"진행결과 수신할 통보 URL"
        }' \
     -X POST "{요청도메인}/Subscribe/schedule_reserve"

PHP

/* 토큰 발행 API */
$tokenheaders = array(); 
array_push($tokenheaders, "content-type: application/json; charset=utf-8");

$token_url = "{요청도메인}/payAuth/token";

$token_request_data = array(
    'pay2_id' => 'cookiepayments에서 발급받은 ID',
    'pay2_key'=> 'cookiepayments에서 발급받은 연동키',
);

$req_json = json_encode($token_request_data, TRUE);

$ch = curl_init(); // curl 초기화

curl_setopt($ch,CURLOPT_URL, $token_url);
curl_setopt($ch,CURLOPT_POST, false);
curl_setopt($ch,CURLOPT_POSTFIELDS, $req_json);
curl_setopt($ch,CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch,CURLOPT_CONNECTTIMEOUT ,3);
curl_setopt($ch,CURLOPT_TIMEOUT, 20);
curl_setopt($ch, CURLOPT_HTTPHEADER, $tokenheaders);
$RES_STR = curl_exec($ch);
curl_close($ch);
$RES_STR = json_decode($RES_STR,TRUE);
/* 여기 까지 */
if($RES_STR['RTN_CD'] == '0000'){

$headers = array(); 
array_push($headers, "content-type: application/json; charset=utf-8");
array_push($headers, "ApiKey: COOKIEPAY에서 발급받은 연동키");
array_push($headers, "TOKEN: TOKEN API통해 발행된 TOKEN 값");

$cookiepayments_url = "{요청도메인}/Subscribe/schedule_reserve";

$request_data_array = array(
                                'API_ID' => 'COOKIEPAY에서 발급받은 가맹점연동 ID',
                                'BILLKEY' => '빌링키',
                                'ORDERNO' => '주문번호',
                                'PRODUCTNAME' => '상품명',
                                'PRODUCTCODE' => '상품코드',
                                'AMOUNT' => '결제금액',
                                'TAXFREECD' => '과세여부',
                                'QUOTA' => '할부개월',
                                'SCHEDULE_AT' => '202212310101',
                                'BUYERNAME' => '고객명',
                                'PRODUCTTYPE' => '2',
                                'BUYERID' => '고객 ID',
                                'BUYERPHONE' => '고객 휴대폰번호',
                                'BUYEREMAIL' => '고객 E-MAIL',
                                'BUYERADDRESS'=>'고객 주소',
                                'NOTICE_URL'=>'진행결과 수신할 통보 URL'
                        );

$cookiepayments_json = json_encode($request_data_array, TRUE);

$ch = curl_init(); // curl 초기화

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 ,3);
curl_setopt($ch,CURLOPT_TIMEOUT, 20);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);
curl_close($ch);

var_dump($response);

응답 전문 파라미터

응답데이터 예

{
  "RESULTCODE": "0000",
  "RESULTMSG": "성공",
  "ENC_DATA": "uCAMEsaW+tdhYKcIvzbezan137Igm4u0dEMawS93EhwaaoLE+lAgiMH07ysmVI/q3Ky7X1LOIZ3WuSsGgGkyvQ=="
}

응답전문 파라미터 > 복호화 응답 파라미터 (암호화 전문 복호화하기 참조)

복호화 응답데이터 예

{
    "RESULTCODE": "0000",
    "RESULTMSG": "성공",
    "decryptData": {
      "RESERVE_ID": "9jm1kkbzqjwog8kzg40o1zewv6q1",
      "RESERVE_EXECUTE_AT": "202405060709",
      "NOTICE_URL": "https://www.domain.com/noti_result"
    }
}

통보URL 응답 전문 파라미터

응답데이터 예

{
  "RESULTCODE": "0000",
  "RESULTMSG": "성공",
  "RESERVE_ID": "9jm1ksbzqjwog8kzg40o1xewv6q1",
  "BILLKEY": "celgydqdplt4skc8e9ie",
  "ORDERNO": "TEST-ORDER-220921-1112071",
  "AMOUNT": "100",
  "TID": "cTS22092112400490628",
  "ACCEPTDATE": "20220921124003",
  "ACCEPTNO": "01002110",
  "BUYERNAME": "홍길동",
  "BUYERID": "user_id",
  "BUYERADDRESS": "",
  "BUYERPHONE": "010-1234-5678",
  "BUYEREMAIL": "ufound@gmail.com"
}

결제예약 취소하기

TOKEN 발행 URL

{요청도메인}/payAuth/token [POST]

결제예약 취소 요청 URL

{요청도메인}/Subscribe/schedule_cancel [POST]

요청 전문 파라미터

샘플예제

CURL

/* 토큰 발급 API */
curl -H "Content-Type: application/json" \
     -d '{
         "pay2_id": "cookiepayments에서 발급받은 ID",
         "pay2_key": "cookiepayments에서 발급받은 연동키"
         }' \
     -X POST "{요청도메인}/payAuth/token"

/* 정기결제 API */
curl -H "Content-Type: application/json" \
     -H "ApiKey: COOKIEPAY에서 발급받은 연동키" \
     -H "TOKEN: TOKEN API통해 발행된 TOKEN 값" \
     -d '{
            "API_ID": "COOKIEPAY에서 발급받은 가맹점연동 ID",
            "RESERVE_ID": "예약ID",
        }' \
     -X POST "{요청도메인}/Subscribe/schedule_cancel"

PHP

/* 토큰 발행 API */
$tokenheaders = array(); 
array_push($tokenheaders, "content-type: application/json; charset=utf-8");

$token_url = "{요청도메인}/payAuth/token";

$token_request_data = array(
    'pay2_id' => 'cookiepayments에서 발급받은 ID',
    'pay2_key'=> 'cookiepayments에서 발급받은 연동키',
);

$req_json = json_encode($token_request_data, TRUE);

$ch = curl_init(); // curl 초기화

curl_setopt($ch,CURLOPT_URL, $token_url);
curl_setopt($ch,CURLOPT_POST, false);
curl_setopt($ch,CURLOPT_POSTFIELDS, $req_json);
curl_setopt($ch,CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch,CURLOPT_CONNECTTIMEOUT ,3);
curl_setopt($ch,CURLOPT_TIMEOUT, 20);
curl_setopt($ch, CURLOPT_HTTPHEADER, $tokenheaders);
$RES_STR = curl_exec($ch);
curl_close($ch);
$RES_STR = json_decode($RES_STR,TRUE);
/* 여기 까지 */
if($RES_STR['RTN_CD'] == '0000'){

$headers = array(); 
array_push($headers, "content-type: application/json; charset=utf-8");
array_push($headers, "ApiKey: COOKIEPAY에서 발급받은 연동키");
array_push($headers, "TOKEN: TOKEN API통해 발행된 TOKEN 값");

$cookiepayments_url = "{요청도메인}/Subscribe/schedule_cancel";

$request_data_array = array(
                                'API_ID' => 'COOKIEPAY에서 발급받은 가맹점연동 ID',
                                'RESERVE_ID' => '예약ID',
                        );

$cookiepayments_json = json_encode($request_data_array, TRUE);

$ch = curl_init(); // curl 초기화

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 ,3);
curl_setopt($ch,CURLOPT_TIMEOUT, 20);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);
curl_close($ch);

var_dump($response);

응답 전문 파라미터

응답데이터 예

{
  "RESULTCODE": "0000",
  "RESULTMSG": "성공",
  "ENC_DATA": "uCAMEsaW+tdhYKcIvzbezan137Igm4u0dEMawS93EhwaaoLE+lAgiMH07ysmVI/q3Ky7X1LOIZ3WuSsGgGkyvQ=="
}

응답전문 파라미터 > 복호화 응답 파라미터 (암호화 전문 복호화하기 참조)

복호화 응답데이터 예

{
  "RESULTCODE": "0000",
  "RESULTMSG": "성공",
  "decryptData": {
     "RESERVE_ID": "9jm1ksbcqjxog8kzg4o01xewv5q1"
  }
}

결제예약 목록요청

TOKEN 발행

{요청도메인}/payAuth/token [POST]

결제예약 목록요청 URL

{요청도메인}/Subscribe/schedule_list [POST]

요청 전문 파라미터

샘플예제

CURL

/* 토큰 발급 API */
curl -H "Content-Type: application/json" \
     -d '{
         "pay2_id": "cookiepayments에서 발급받은 ID",
         "pay2_key": "cookiepayments에서 발급받은 연동키"
         }' \
     -X POST "{요청도메인}/payAuth/token"

/* 정기결제 API */
curl -H "Content-Type: application/json" \
     -H "ApiKey: COOKIEPAY에서 발급받은 연동키" \
     -H "TOKEN: TOKEN API통해 발행된 TOKEN 값" \
     -d '{
            "API_ID": "COOKIEPAY에서 발급받은 가맹점연동 ID",
            "RESERVE_ID": "예약ID",
        }' \
     -X POST "{요청도메인}/Subscribe/schedule_list"

PHP

/* 토큰 발행 API */
$tokenheaders = array(); 
array_push($tokenheaders, "content-type: application/json; charset=utf-8");

$token_url = "{요청도메인}/payAuth/token";

$token_request_data = array(
    'pay2_id' => 'cookiepayments에서 발급받은 ID',
    'pay2_key'=> 'cookiepayments에서 발급받은 연동키',
);

$req_json = json_encode($token_request_data, TRUE);

$ch = curl_init(); // curl 초기화

curl_setopt($ch,CURLOPT_URL, $token_url);
curl_setopt($ch,CURLOPT_POST, false);
curl_setopt($ch,CURLOPT_POSTFIELDS, $req_json);
curl_setopt($ch,CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch,CURLOPT_CONNECTTIMEOUT ,3);
curl_setopt($ch,CURLOPT_TIMEOUT, 20);
curl_setopt($ch, CURLOPT_HTTPHEADER, $tokenheaders);
$RES_STR = curl_exec($ch);
curl_close($ch);
$RES_STR = json_decode($RES_STR,TRUE);
/* 여기 까지 */
if($RES_STR['RTN_CD'] == '0000'){

$headers = array(); 
array_push($headers, "content-type: application/json; charset=utf-8");
array_push($headers, "ApiKey: COOKIEPAY에서 발급받은 연동키");
array_push($headers, "TOKEN: TOKEN API통해 발행된 TOKEN 값");

$cookiepayments_url = "{요청도메인}/Subscribe/schedule_list";

$request_data_array = array(
                                'API_ID' => 'COOKIEPAY에서 발급받은 가맹점연동 ID',
                                'STD_DT' => '시작일',
                                'END_DT' => '마감일',
                                'RESERVE_ID' => '예약ID',
                        );

$cookiepayments_json = json_encode($request_data_array, TRUE);

$ch = curl_init(); // curl 초기화

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 ,3);
curl_setopt($ch,CURLOPT_TIMEOUT, 20);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);
curl_close($ch);

var_dump($response);

응답 전문 파라미터

응답데이터 예

{
  "RESULTCODE": "0000",
  "RESULTMSG": "정상",
  "ENC_DATA": "uCAMEsaW+tdhYKcIvzbezan137Igm4u0dEMawS93EhwaaoLE+lAgiMH07ysmVI/q3Ky7X1LOIZ3WuSsGgGkyvQ=="
}

응답전문 파라미터 > 복호화 응답 파라미터 (암호화 전문 복호화하기 참조)

복호화 응답데이터 예

{
  "RESULTCODE": "0000",
  "RESULTMSG": "정상",
  "decryptData": [
    {
      "RESERVE_ID": "9jn1ksbcqjwog8kgg4001xxwv5q1",
      "BILLKEY": "jnjben1txbwo0oko28j1",
      "ORDERNO": "TEST-ORDER-220920-094625",
      "AMOUNT": "100",
      "BUYERNAME": "홍길동",
      "PRODUCTNAME": "테스트상품100",
      "PRODUCTCODE": "TP-100",
      "TAXFREECD": "Y",
      "QUOTA": "00",
      "NOTICE_URL": "https://domain.com/noti",
      "SCHEDULE_AT": "2022-09-21 09:10:00",
      "REGDATE": "2022-09-20 10:59:18",
      "STATUSDATE": "2022-09-20 11:17:53",
      "STATUS": "9"
    },
    {
      "RESERVE_ID": "9jn1ksbcqjwog8kgg4001xxwv5q2",
      "BILLKEY": "sidisf1txbwo0okososlsl",
      "ORDERNO": "TEST-ORDER-220920-094626",
      "AMOUNT": "100",
      "BUYERNAME": "홍길동",
      "PRODUCTNAME": "테스트상품100",
      "PRODUCTCODE": "TP-100",
      "TAXFREECD": "Y",
      "QUOTA": "00",
      "NOTICE_URL": "https://domain.com/noti",
      "SCHEDULE_AT": "2022-09-21 09:10:00",
      "REGDATE": "2022-09-20 10:59:28",
      "STATUSDATE": "2022-09-20 11:17:58",
      "STATUS": "9"
    },
    ......
  ]
}

자동결제 반복하기

쿠피페이에서는cron과 같이 주기적인(periodic) 결제 방식은 지원하고 있지 않습니다. 그래서 자동결제 예약 반복을 하기 위해서는 2가지 방식으로 진행해야합니다.

방법1. 가맹점 서버에서 cron과 같은 주기적인 실행 프로그램으로 반복하기

가맹점 서버 내에서 cron과 같이 주기적인 스케쥴러 프로그램을 통해 결제를 진행해야합니다. 발급받은 빌링키를 데이터베이스에 저장한 후에 스케쥴러에서 빌링키로 결제하기를 통해서 주기적으로 결제할 수 있도록 구현합니다.

방법2. 자동결제 예약 실행 이후 리턴되는 통지URL 처리에서 다음 자동결제 예약을 수행하기

① 결제 이후 통지가 오면 결제완료/결제실패를 분리하여 처리를 진행합니다.
② 결제가 완료가 되었다면, 다음 결제 일자를 정해서 결제 예약 API를 통해 예약을 추가로 진행하면 반복적인 결제를 구현할 수 있습니다.