OpenPayAPI Manual Version 3.12

페이게이트 오픈페이API  메뉴얼

PayGate OpenPayAPI Manual 

3. 거래 The Transaction

3.1 신용카드 거래

Credit Card Transactions.

3.1.1 카드타입별 지불수단표

Paymethod map by card types

지불수단

paymethod

국민

KB

외환

KEB

비씨

BC

엘지

Old LG

삼성

SamSung

현대

Hyundai

 롯데

Lotte

신한

Shinhan

신용카드 안심클릭VISA3D

-

OK

-

OK

OK

OK

OK

OK

신용카드 안심클릭 30만원초과 거래

 VISA3D

-

OK

-

OK

-

OK

OK

OK

신용카드 안전결제ISP

OK

-

OK

-

-

-

-

-

신용카드 일반(인증)BASIC(_AUTH)

OK

-

OK

-

-

OK

-

OK

 

지불수단

paymethod

VISA

MASTER

JCB

AMEX

신용카드 달러승인 달러결제BASIC_USD

OK

OK

OK

-

3.1.2 플랫폼별 지불수단

Paymethod map by platforms

지불수단

Paymethod

MSIE_WIN

FIREFOX_WIN

SAFARI_MAC

FIREFOX_LINUX

OTHERS

신용카드일반

BASIC(_AUTH)

O

O

O

O

O

신용카드 안심클릭

Visa3D

 O 

  △ 

 △ 

 △ 

 △ 

신용카드 안심클릭 30만원초과 거래

Visa3D

 O 

 △ 

 △ 

 △ 

 △ 

신용카드 안전결제

ISP

O

신용카드 달러결제BASIC_USD

O

O

O

O

3.1.3 신용카드 일반(인증)

Credit card BASIC(_AUTH)

 

3.1.4 신용카드 안전결제(ISP)타입 거래

Credit card ISP type transaction

3.1.5 신용카드 안심클릭(VISA3D)타입 거래

Credit card VISA3D type transaction

3.1.6 거래상태 및 코드

Transaction Status and code

3.1.6.1 신용카드 거래 흐름도the credit card transaction processed as following flows.  

  3.1.6.2 거래상태에 대한 설명Description for transaction status.

 

3.2 현금영수증

Cash Receipt

3.3 전자세금계산서

Tax Invoice.

3.3.1 세금계산서를 발행하기 위해서는 아래 정보가 필요함.

Following informations are required to issue tax invoice.

Type

입력예

Input example

 변수명

Variable name

설명

Description

Req

"ON"

taxflag

세금계산서 발행요청시 "ON"

Set "ON" to request tax invoice

Req

"2128143426"

taxvatregno

사업자등록번호

Company registration number

Req

"paygateshop Inc"

taxcompanyname

회사명

Official company name

Req

"Hong GilDong"

taxrepresentative

대표자명

Official representative name

Req

"SongpaDong 31"

taxaddr

주소

Official company address

Req

"서비스"

taxbiztype

업태

Company business type

Req

"전자상거래"

taxbizitem

업종

Company business item

Req

"MacBook Pro"

goodname

품명

Good name

Opt

"Service Dept"

taxdepartment

담당부서

The department to handle tax invoice

Opt

"Mountie Lee"

taxcontactname

담당자

Contact person to receive tax invoice

Opt

"mountie@who.net"

taxcontactemail

담당자 전자우편

e-mail to be sent tax invoice

Opt

"0112108396"

taxcontactphone

담당자 휴대폰번호

Contact mobile phone number

 

 

 

3.4 무통장 입금통보

Bank Transfer Notice

3.4.1 무통장 입금 통보

  • 은행코드
  • 은행명
  • 금융기관공동코드
  • 54
  • HSBC
  • 054
  • 04
  • 국민
  • 004
  • 88
  • 신한
  • 088
  • 20
  • 우리
  • 020
  • 11
  • 농협(중앙)
  • 011
  • 12
  • 지역농협
  • 012
  • 23
  • SC제일
  • 023
  • 05
  • 외환
  • 005
  • 81
  • 하나
  • 081
  • 27
  • 씨티
  • 027
  • 03
  • 기업
  • 003
  • 07
  • 수협
  • 007
  • 71
  • 우체국
  • 071
  • 02
  • 산업
  • 002
  • 32
  • 부산
  • 032
  • 37
  • 전북
  • 037
  • 39
  • 경남
  • 039
  • 34
  • 광주
  • 034
  • 31
  • 대구
  • 031
  • 35
  • 제주
  • 035
  • 45
  • 새마을금고
  • 045
  • 48
  • 신용협동조합
  • 048
  • 50
  • 상호저축은행
  • 050
  • 55
  • 도이치
  • 055

3.4.2 가상계좌 무통장 입금 통보

        상점측으로 이를 자동 통보한다.

3.5 실시간 계좌이체

Real time Bank Transfer

 

3.6 매매보호

ESCROW

3.6.1 매매보호 기본

Escrow Basic

3.6.1.1 법적 요구사항The legal requirement

3.6.1.2 매매보호 기본 개념Escrow basic mechanism

 

3.6.2 매매보호 거래 활성화 방법

How to enable escrow transaction

3.6.2.1 유저의 선택에 의해서 매매보호 활성화Enabling by customer’s choice

3.6.2.2 "loanSt"변수값을 "escrow"로 설정하여 활성화Set "escrow" value to "loanSt" variable 

3.6.3 매매보호 가상계좌 번호

Escrow account

3.6.3.1 매매보호 가상계좌번호 할당Assigning the escrow bank account

 3.6.3.2 매매보호 가상계좌번호 정보 공지Notifying the escrow account information

 

3.6.3.3 매매보호 가상계좌 LifeCyclethe escrow account lifecycle

3.6.5 배송정보 제공

Informing the delivery information

3.6.5.2 페이게이트 서버로 SFTP방식으로 일괄 전송Sftp the batch data to paygate server

  • DL    W53212345    W53212345    DHL    7853Q2WZ
  • DL    W53213796    W53213796    FEDEX    9612893
  • MANUAL
  • manual delivery, the tracking no have to be set the personal mobile no.
  • DHL
  • DHL, www.dhl.co.kr
  • FEDEX
  • Fedex, www.fedex.com
  • DAEHAN
  • Korex, www.doortodoor.co.kr
  • LOGEN
  • Logen, www.ilogen.com
  • SAMSUNG
  • Samsung HTH, www.samsunghth.com
  • EPOST
  • ePost, www.epost.go.kr
  • TRANET
  • Tranet, tranet2.logisworld.com
  • HANJIN
  • Hanjin, www.hanjin.co.kr
  • HYUNDAI
  • Hyundai express, www.hyundaiexpress.com
  • FAMILY
  • Family, www.e-family.co.kr
  • CJ
  • CJGLS, www.cjgls.co.kr
  • KGB
  • KGB logistics, www.kgbls.co.k
  • UPS
  • UPS logistics, www.ups.com

 

3.7 거래확인

Transaction verification

3.7.1 서버간 거래확인 방식

Server-to-Server transaction verification 

  1. 고객이 은행에 입금 한다. (페이게이트에서 개설한 업체의 가상계좌)
  2. 은행은 입금결과를 Paygate 측에 통보한다
  3. Paygate측의 PGTL 서버가 업체에서 미리 설정한 URL에 입금 완료 통보 한다. (PGIOForm의 변수명을 그대로 POST하며 bankcode bankaccount payresultcode 을 활용하십시오)
  4. 업체는 입금 완료 통보에 대해 기록하고 포멧에 맞게 String을 작성하여 Return 한다.
  5. 이 응답내용을 PGTL 서버가 Parsing 하여 입근 완료 처리 한다.
  • <PGTL><VERIFYRECEIVED>RCVD</VERIFYRECEIVED><TID>[tid]</TID></PGTL>
    ex) <PGTL><VERIFYRECEIVED>RCVD</VERIFYRECEIVED><TID>paygateshop_071119.123234</TID></PGTL>
  • <html><head>
    <title>Transaction Successfully Completed</title>
    <script language="javascript" src="https://api.paygate.net/ajax/common/OpenPayAPI.js"></script>
    <script language="javascript">
    function businessverify() {
    var tid = document.form1.elements[‘tid’].value;
    verifyReceived(tid);
    }
    </script>
    </head>
    <body onLoad="javascript:business_verify();">
    Thank you for your order
    </body></html>

  *확장형 (기존 verifyNum에 +100을 더함: 상점쪽 db에 인서트되었음을 명시적으로 알림) 

  • <% 상점 데이터베이스에 결과를 기록하는 상점측 로직이 선행되어야 합니다.
    %>
    <html>
    <head>
    <title>Transaction Successfully Completed</title>

    <script language="javascript"  src="https://api.paygate.net/ajax/common/OpenPayAPI.js"></script>

    <script language="javascript">
    function businessverify() {
      setPGIOElement('apilog','100');
      setPGIOElement('tid','해당트랜잭션 아이디');
      verifyReceived();  [or verifyReceived('','업데이트후 호출할 스크립트함수명','실패했을때 호출할
                                                        함수명');
    }
    </script>

    </head>
    <body onLoad="javascript:business_verify();">
    <form name='PGIOForm'></form>    <--반드시 있어야 하며 appendChild로
                                                        스크립트로 구현시 소스의 길이가 상당히 길어지며
                                                            일부 브라우져에서 동작되지 않을수 있습니다.
    거래 주셔서 감사합니다.
    구매하신 물품 정보.
    </body></html>
  • verifyReceived 값 증가를 위해 Apache HttpComponets(http://hc.apache.org/) 의 HttpClient를 사용하여 구현됨.
     
    StringBuilder urlSb = new StringBuilder();
    urlSb.append("https://service.paygate.net/admin/settle/verifyReceived.jsp?tid=");
    urlSb.append(tid);
    urlSb.append("&verifyNum=100");

    try {
        HttpClient client = new HttpClient();
        GetMethod method = new GetMethod(urlSb.toString());
        int statusCode = client.executeMethod(method);
        if(200 == statusCode) {
            if( log.isInfoEnabled() ) {
                log.error("PayGate verifyReceived Call - OK!!");
                }

        } else {
            if( log.isInfoEnabled() ) {
                log.error("PayGate verifyReceived Call - FAIL!!");
                log.error("PayGate verifyReceived Call QueryString - "
                            + method.getQueryString());
                log.error("PayGate verifyReceived Call statusCode - " + statusCode);
            }
        }
     
    } catch (Exception e) {
        if( log.isErrorEnabled() ) {
            log.error("PayGate verifyReceived Call Error!! ", e);
        }
    }



-고객이 결제 진행시 결제가 승인된후 상점쪽으로 전송완료 전이나 상점쪽 페이지  호출전에 브라우저의 종료등의 원인으로 pg에는 결제승인 기록이 있으나 상점쪽에는 결제정보가 없는  현상이 보고됨.
-주의:결제 승인을 한 후에 상점db에 저장하기전 페이지내에 alert()은 하지 말아야함
(결제흐름이 결제 승인 결과를 화면에 보여준후에 상점에 저장하는 흐름도라면고객이 alert('결제완료')되었다는 메시지를 확인후 더이상의 행동(alert창 닫기)을 안한다면 위와 같은현상을 유발함.)

 

    

3.7.3 미확인 거래에 대한 처리

Processing for unverified transactions.

        - data insert 로 구현되어 있을경우 사용자의 정상적인 완료와 미확인 거래 처리 재전송으로 인하여

          중복 입력될 우려가 있습니다.

 

            

                                                      [사진 3-7-1]

 

 

 

3.8 취소 처리 및 취소 방법

 

거래상태 분류에 따른 취소처리

-a.결제 승인 상태 ("거래승인완료","매입요청")

-b.결제 승인후 카드사 매입이 진행되거나 완료된 상태 ("매입중","매입완료","정산완료")

a의 상태일때 취소 요청 접수 => 즉시 승인 취소 및 한도 복구

 

b의 상태일때 취소 요청 접수 => 오전 카드사 송신 => 취소 진행

(통상적으로 1-3일 소요되며 해외 카드 경우 더 지연될수 있습니다.)

 

 

취소 방법

 

1.상점 관리자 영역에서 취소

관리자가 상점 관리자 페이지에 로그인하여 거래 리스트에서 취소 버튼을 눌러 취소함

 

2.페이게이트 관리자 영역에서 취소

페이게이트 직원이 거래를 취소하는것을 말하며 특별한 경우 이외에는 상점의 결제를 취소할수 없습니다.

(결제연동을 위한 테스트 결제 취소, 페이게이트 내 결제 취소, 상점 관리자와 충분한 소통이 있었던 거래취소)

 

3.sftp 를 이용한 취소

취소 데이터들을 취합(상점)

=> 페이게이트 sftp에 upload (상점)

=> 매일 오전 data를 download (페이게이트) => 취소 진행 (페이게이트)

-사전작업 : sftp 통신을 하기 위한 개인키 , 공개키 생성(상점)

            생성된 공개키 페이게이트로 전달.

     upload가능하게 파일서버 셋팅 (페이게이트)

 

4.pgtl 을 이용한 취소

pgtl(java daemon:페이게이트 제공) 상점 구동 => 취소 요청 => 소켓통신 => 취소 진행

-사전작업 : pgtl 구동(java 데몬)

 

5. 취소 jsp 호출

취소 발생시 페이게이트 jsp 를 호출하여 해당 거래를 취소하는 방법입니다.

(상점에서는 php,jsp,asp 등을 이용하여 구현할수 있습니다.)

-사전작업 : 상점서버는 요청 데이터를 aes256 암호화 하여야 합니다.

           aes256암복호화시에 사용되는 key가 등록되어야 합니다.

 

 

3.9 중국 데빗카드 거래

China Debit Card Transaction

3.9.1 중국데빗카드 개요

China Debit Card BASIC

중국 데빗카드는 중국내 은행에서 발행한 Debit카드를 이용한 결제방식이다.

중국 전역의 은행에서 발행한 카드 대부분을 포함하여 약 98%이상의 Debit Card를 포함한다.

은행발급 카드는 신용카드를 포함하여 약 11억장 이상이 발행되어 있으며 그중 데빗카드는 약 10억 5천만장 이상 된다.

일종의 계좌이체 방식으로 결제가 진행되어 일체의 사기거래가 없음을 보장할 수 있다.

구체적인 결제과정은 아래 링크의 예를 참조하십시오.

http://docs.google.com/a/paygate.net/Doc?id=dhm28v4q_1384g766gtc7

3.9.2 China Debit Card 주요 입력변수

Type

입력예제

Input example

변수명

Variable name

입력

In

출력

Out

 출력예

Output example

Req

"paygateshop"

mid

 

 

Req

"105"

paymethod

 

 

Req

"testgood"

goodname

 

 

Req

"1.23"

unitprice

 

 

Req

"CNY"

goodcurrency

 

 

Req

"CN"

langcode

 

 

Vre

"http://1.2.3.4/get.jsp

MemberRedirectURL

 

 

Vre

 

tid

 

"paygateshop_123.123"

Vre

 

replycode

 

"0000"

Vre

 

replyMsg

 

"OK: 12345"

Vre

 

Ipaddress

 

111.222.121.212

Vre

 

ResultScreen

 

"Success"

 

<FORM NAME='PGIOForm' ACTION='https://service.paygate.net/payment/CN/payProcessCN.jsp' METHOD='POST'>

    <INPUT TYPE='HIDDEN' NAME='mid' VALUE='상점아이디'>

    <INPUT TYPE='HIDDEN' NAME='paymethod' VALUE='105'>

    <INPUT TYPE="HIDDEN' NAME='langcode' VALUE='CN'>

    <INPUT TYPE='HIDDEN' NAME='goodcurrency' VALUE='CNY'>

    .........필요소스 추가..........

    상품명 : <INPUT TYPE='TEXT' NAME='goodname'>

    상품가격(CNY) : <INPUT TYPE='TEXT' NAME='unitprice'>

    ........필요소스 추가...........

</FORM>

 

3.9.3 Merchant Charset에 따른 Form Action URL

GB2312인 경우 : https://service.paygate.net/payment/CN/payProcessCN.jsp

UTF-8인 경우 : https://service.paygate.net/INTL/NewPayProcessS.jsp

3.10 중국 알리페이 거래

China Alipay Transaction

 

구체적인 결제과정은 아래 링크의 예를 참조하십시오.

 

http://docs.google.com/Doc?id=dcx54hs6_15spms9dm

3.10.1 China Alipay 주요 입력변수 

Type

입력예제

Input example

변수명

variable name

입력

In

출력

Out

출력예

output example

Req

"paygateshop"

mid

 

 

Req

"106"

paymethod

 

 

Req

"testgood"

goodname

 

"testgood"  

Req

"0.01"

unitprice

 

"2.12"  

Req

"USD"

goodcurrency

 

 

Req

"US"

langcode

 

 

 

<FORM NAME='PGIOForm' ACTION='https://service.paygate.net/payment/CN/payProcessCN.jsp' METHOD='POST'>

    <INPUT TYPE='HIDDEN' NAME='mid' VALUE='상점아이디'>

    <INPUT TYPE='HIDDEN' NAME='paymethod' VALUE='106'>

    <INPUT TYPE="HIDDEN' NAME='langcode' VALUE='CN'>

    <INPUT TYPE='HIDDEN' NAME='goodcurrency' VALUE='USD'>

    <INPUT TYPE='HIDDEN' NAME='langcode' VALUE='US'>

    .........필요소스 추가..........

    상품명 : <INPUT TYPE='TEXT' NAME='goodname'>

    상품가격(USD) : <INPUT TYPE='TEXT' NAME='unitprice'>

    ........필요소스 추가...........

</FORM>

 

3.10.2 Merchant Charset에 따른 Form Action URL

GB2312인 경우 : https://service.paygate.net/payment/CN/payProcessCN.jsp

UTF-8인 경우 : https://service.paygate.net/INTL/NewPayProcessS.jsp

 

3.11 일본 계좌이체

Japan Bank Transfer

일본 계좌 이체는 OpenPayAPI 또는 HTTPS POST 방식으로 Paygate 측에 입금 예정 정보를 전송하는 시스템이며,

이 시스템을 통하여 해당 상점은 입금 완료 결과 자동 확인 및 정산 서비스를 받을 수 있습니다.

 

<form name="PGIOForm" action="https://service.paygate.net/payment/JP/payProcessJP.jsp" method="POST"> 

    <!-- fixed value -->

    <input type="hidden" name="mid" value="paygateshop"> 

    <input type="hidden" name="paymethod" value="7"> 

    <input type="hidden" name="langcode" value="JP">

    <input type="hidden" name="goodcurrency" value="JPY">

    <input type="hidden" name="bankcode" value="PG"> 

 

    <!-- user input value, not visible, posted from previous page OR inserted by script -->

    <input type="hidden" name="unitprice" value="1000">

    <input type="hidden" name="goodname" value="test good">

 

    <!-- input value -->

    <select name="bankaccount">

        <option value="JPPOST861">japan post bank</option>

        <option value="UFJ096">ufj 6796096</option>

        ...

        </select>

    sender name : <input name="receipttoname" value="superman">

    send date : <input name="bankexpyear">/<input name="bankexpmonth">/<input name="bankexpday">

</form>

 

 

Type

입력예제

Input example

변수명

variable name

출력예

output example

Req

"paygateshop"

mid

"paygateshop"

Req

"7"

paymethod

 "300701"

Req

"testgood"

goodname

"testgood"

Req

"1000"

unitprice

"1000"

Req

"JPY"

goodcurrency

 "005JPY"

Req

"JP"

langcode

 "006JP"

Req

"PG"

bankcode

"004PG"

Req

"UFJ096"

bankaccount

"Bank of Tokyo-Mitsubishi UFJ ... 6796096"

 

 

3.12 무통장 가상계좌 입금

Bank Virtual Account  Transfer

3.12.1 가상계좌 설정 방법

3.12.2 가상계좌 입금 완료 알림 서비스

 

3.13 상품별 과세/비과세 구분

 

 

paygate@paygate.net