3_OpenPayAPI_Transactions.pdf

OpenPayAPI Manual Version 3.12

1

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 -


2

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 X X X X

싞용카드

달러결제 BASIC_USD O O O O O

3.1.3 싞용카드 일반(인증)

Credit card BASIC(_AUTH)

싞용카드 일반(BASIC_AUTH)타입 거래와 싞용카드 외화표시상품 원화결제(BASIC_INT)타입 거래,

싞용카드 달러표시상품 달러결제(BASIC_USD )타입 거래.

the basic type transaction is similar to BASIC_AUTH, BASIC_INT, BASIC_USD that approved

with the credit card number, expire date and some authentication information (if required)

BASIC 거래는 카드번호와 유효기간만으로 거래승인. paymethod 변수값이 100.

BASIC type is approved with credit cardnumber and expire date only with paymethod "100"

싞용카드 인증거래는 카드 비밀번호 앞 2 자리 및 카드소유자 주민번호 뒤 7 자리 숫자가 필요함.

사업자의 경우 주민번호 대싞 사업자번호 10 자리 입력. paymethod 변수값이 101.

BASIC_AUTH type is approved with credit card number, expire date, first 2 digit of card secret


3

number, last 7 digit of personal SSN or full 10 digit of company registration number with

paymethod "101"

달러승인 달러결제 같은 경우는 paymethod 값을 기준으로 구붂된다. paymethod 변수값이

104.

BASIC_USD type is approved with credit card number, expire date and some authentication

code (if required) with paymethod "104"

원화 승인 달러 결제 같은 경우는 paymethod 값을 기준으로 구붂된다. paymethod 변수값이

100. CVV2 넘버는 카드 뒷면에 적힌 일렦번호의 맨 뒤 3 자리를 뜻한다. CVV2 넘버는 변수명

cardsecretnumber 에 기록되어 처리된다. 서비스 옵션에서 '인증거래 미지원 카드 거래차단' 을

통해 CVV2 넘버를 확인할 것인지 확인하지 않을 것인지 선택할 수 있다. CVV2 넘버를

주문서에서 입력하여 짂행할 시에는 중간단계에서 CVV2 입력화면이 나타나지 않고, CVV2

넘버가 없는 주문서에서 싞용카드 인증거래 짂행할 시에는 중간단계에서 CVV2 인증화면이

나타나서 추가로 CVV2 넘버를 입력해야 한다. BASIC_INT type is approved with credit card

number, expire date and some authentication code (if required) for international cards issued

outside of Korea with paymethod code "100"

CVV2/CVC2 code is the last 3 digit number at the backside of credit card.

the value have to be set at "cardsecretnumber" variable.

By the service option setting, it is possible to pass the CVV2 authentication without cvv2

value.

if the cvv2 code is required and the value is not set, the confirmation screen will be shown to

customer as following screen shot:

흐름도

Flow diagram


4

3.1.4 싞용카드 안젂결제(ISP)타입 거래

Credit card ISP type transaction

고객 PC 의 인증서 및 개인키로 싞용카드 정보를 암호화하고 젂자서명함.

the payment order is encrypted and signed with the certificate store at client PC and issued

by card issuer.

인증서 제어를 위해 윈도우저 ActiveX 기술이 사용됨.(윈도우 운영체제에서만 동작함.)

To handle the certificate, the ActiveX technology is used. (ActiveX is only available for

Microsoft Internet Explorer on windows OS)

흐름도

Flow diagram

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

Credit card VISA3D type transaction

모듞 홖경에서 VISA3D 거래가 가능하도록 하기 위하여 VISA3D 결제과정에 약간의 수정이

가해짐.

VISA3D is 3D-Secure compliance authentication method.

VISA 에서 처음 제시한 새로운 온라인 결제수단으로 MasterCard SecureCode, JCB J/Secure 와

상호 호홖이 됨.

Called SecureCode at MasterCard, J/Secure at JCB.

PayGate 는 VISA3D 거래처리를 위한 MPI 서버 운영중.

PayGate is run the internal MPI(Merchant Plug-In) Server.

싞용카드 안심클릭의 흐름도

Flow diagram of OpenPayAPI Visa3D


5

3.

3.1.6 거래상태 및 코드 Transaction Status and code

3.1.6.1 싞용카드 거래 흐름도 The credit card transaction is processed as follows

fl


6

3.1.6.2 거래상태에 대한 설명

Description for transaction status.

304113 거래실패 : 초기 거래시작시 거래실패로 시작함.

failed : the initial transaction status is "failed".

304111 승인요청 : 실제 금융기관에 승인요청 데이터를 젂송하고 결과를 받는과정. 약 1~5 초

정도 승인요청 상태유지.

request to approval : the status is set before the real request data is sent to card issuer. It will

be live for 1~5 seconds on approving time.

304113 승인완료 : 카드사부터 승인번호 획득시 승인완료상태 변경됨. 다음단계(매입요청 또는

승인취소) 까지는 승인완료상태 유지함. 승인완료상태는 카드사별로 조금 차이는 나지만 약

20 일 정도 유지 가능함.

approved : the status is set when the transaction is approved by card issuers. It will be live up

to 20 days until the next steps (acquiring or cancel).

304181 승인취소요청 : 카드사와 데이터 송수싞 기간동안의 약 1~5 초 정도 상태유지.

request to cancel approved : the status is set on data processing time between PayGate and

card issuer. It will be live for 1~5 seconds.

304182 승인취소완료 : 거래승인 취소완료시의 상태.

approval canceled : on the case that the approved transaction is canceled successfully.

304130 매입요청 : 매입대상 거래를 표시(Marking)하는 단계로 실제 데이터를 카드사로는

송싞하기 젂.

request to acquire : to mark the transactions to be acquired. Before to send the real data to

card acquirer.

304131 매입중 : 매입요청 데이터를 카드사로 송싞한 이후. 약 1 일~7 일 정도 소요.

acquiring : after send the acquiring data to card acquirer. It will live up to 7 days until it is

acquired

304132 매입완료 : 카드사부터 매입결과를 받은 이후 세팅. 돈보다 결과데이터가 먼저 들어옴.

acquired : status is set when the result data arrived from card acquirer.

304160 매입후 취소요청 : 매입중이거나 매입완료 거래를 취소하고자 할 때 취소대상 거래에

대한 표시.

request to cancel for acquired trans : mark to cancel for acquiring or acquired transaction.

304161 매입후 취소중 : 매입후 취소데이터를 카드사로 송싞한 상태임. 약 1 일~7 일 정도 소요.

cancelling for acquired trans : status is set after sending real data to card acquirer to cancel

the acquiring or acquired trans. It will live up to 7 days.

304162 매입후 취소완료 : 이미 매입된 거래에 대한 취소가 완료된 상태.

canceled for acquired trans : the status successfully canceled for acquiring or acquired trans.


7

304141 정산중 : 상점 지금 대금 계산하여 입금짂행중. 일체의 상태변경 안됨.

settling : calculating the amount to be settled to merchant.

304142 정산완료 : 상점 세이퍼트 대금으로 정산금을 모두 지급한 이후 상태.

settled : status set after to transfer the settle amount to merchant.

304195 정산후 취소요청 : 정산이 완료된 거래에 대한 취소요청 접수, 이후 PayGate 에서

해당거래 심사후 취소과정 짂행여부 결정함.

request to cancel for settled trans : request to be verified for canceling the settled trans.

304190 정산후 취소확인 : 정산완료된 거래에 대한 취소짂행 결정하여 취소대상 거래로

표시(Mark)함.

verify the cancel request for settled trans : PayGate verify the transaction is available for

canceling in case already settled.

304191 정산후 취소중 : 정산완료된 거래의 취소요청을 카드사로 송싞함. 약 1 일~7 일 소요.

cancelling the settled trans : status is set after send the real data to card acquirer to cancel

settled trans. It will live up to 7 days.

304192 정산후 취소완료 : 정산후 취소완료 상태.

canceled for settled trans : status is set after canceling successfully completed.

3.2 현금영수증

Cash Receipt

현금영수증은 실시간 계좌이체 및 무통장 입금거래에 대해서만 발행.

Cash receipt is only available for cash type transactions like BTNOTICE(7) or RTBT(4).

온라인에서 현금영수증 발행을 위해서는 상점 관리영역 로그인 후 부가서비스의 현금영수증

승인요청 메뉴에서 발행가능.

to issue cash receipt, login to administration area and select "부가서비스 -> 현금영수증

승인요청" menu.


8

이미 발행된 현금영수증은 2 일~3 일후 국세청 사이트에서 발행여부 확인가능.

the issued cash receipt is able to verify on Government tax office

website.(http://www.taxsave.go.kr/)

현금영수증 발행시 주민등록번호 외의 휴대폮 번호로도 영수증 발행이 가능함. (국세청 정책상

온라인을 통한 거래시 현금영수증 발행 요청을 할 때 현금 영수증 카드 번호를 사용 할 수

없습니다.)

the formal required value to issue cash receipt is the social security number. but to protect

the privacy, mobile phone number is also available. (cash receipt card number is not

supported in online payment)

"socialnumber" 라는 변수에 휴대폮 번호나 현금영수증 카드번호를 주민번호 대싞 입력하여

영수증을 발행하게 되며 사업자일 경우 사업자번호를 입력할 수 있음. 세금계산서와 현금영수증

발행요청이

동시에 접수되는 경우 현금영수증보다 세금계산서를 우선하여 처리하고 현금영수증 발행요청은

무시함.

The personal identification number has to be set on "socialnumber".

The tax invoice is unable to co-exist with cash receipt. If the request for tax invoice and cash

receipt arrived at the same time, the cash receipt request will be ignored.

발행된 현금 영수증의 취소는 다음과 같이 현금 영수증을 조회하여 취소 버튺을 누릅니다.

http://www.taxsave.go.kr/


9

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


10

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 "[email protected]" taxcontactemail

담당자 젂자우편

e-mail to be sent tax invoice

Opt "0112108396" taxcontactphone

담당자 휴대폮번호

Contact mobile phone number

싞용카드 거래가 아닐 시 해당 거래정보를 WebTax21 로 젂송하여 세금계산서가 발행될 수

있도록 지원한다. (WebTax21 은 페이게이트와 제휴된 제 3 의 젂자계산서 발행 젂문업체임)

세금계산서 관리 및 추가 정보는 다음 URL 을 참조하십시오. (http://www.webtax21.com/)

Tax Invoice is processed by WebTax21, the 3rd party service provider. (the agreement

required between merchant and webtax21). Refer the www.webtax21.com website.

세금계산서가 발행될 수 있도록 taxflag 가 "ON"이 되도록 한다.

Set "taxflag" value to "ON" to issue tax invoice.

기본제공 정보가 모두 정확한 경우 세금계산서 발행의 젂 과정은 자동처리되며 에러 발행시

별도 지정된 수싞 E-Mail 주소로 세금 계산서 발송실패/반송 경고 메일을 발송하여 관리자가

수동 처리할 수 있도록 정보를 제공한다.

If all required information is correct, the tax invoice will be issued automatically, on the

error case, the alert mail will be sent to continue manual process.

http://www.webtax21.com/


11

싞용카드 거래에 대해서는 세금계산서를 별도 발행하지 않습니다.

Tax invoice is not available for credit card transaction.

흐름도 Flow Diagram

3.4 무통장 입금통보 Bank Transfer Notice

3.4.1 무통장 입금 통보

무통장 입금통보 거래는 단지 지정된 상점 계좌로 해당 대금이 입금예정이라는 정보를 알려주는

역할을 한다.

Bank Transfer Notice is used for notifying intend the transfer amount in future.

무통장 입금통보 거래에서 입금완료된 거래에 대해서는 현금영수증 및 세금계산서 발행을

지원한다.

If the order is verified to be transferred, cash receipt or tax invoice is able to issue.

또한 기 발생된 거래에 대해서 현금영수증 및 세금계산서를 포함한 부붂취소를 지원한다.

거래에 사용되는 은행 코드는 여러 은행에서 사용되는 표준 은행 코드로서 다음과 같다.

은행코드 은행명 금융기관공동코드

54 HSBC 054

04 국민 004

88 싞한 088

20 우리 020

11 농협(중앙) 011

12 지역농협 012

23 SC 제일 023

05 외홖 005

81 하나 081


12

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

60 Bank of America

58 Mizuho 은행

59 Tokyo Mitsubishi 은행

57 UFJ 은행

흐름도

Flow Diagram


13

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

페이게이트가 제공하는 가상계좌로 고객이 결제시에 가상계좌가 채번되어 결제가 짂행되며

무통장 입금 통보와 동일하나 고객이 실제로 ATM 기 등을 이용하여 입금이 완료되면

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

3.5 실시간 계좌이체 Real time Bank Transfer

실시간 계좌이체는 고객의 계좌에서 상점의 세이퍼트 계좌로 실시간 이체가 된다.

real time bank transfer type transaction transfers the order amount from customer bank

account to merchant seyfert account in realtime.

실시간 계좌이체 거래에 대해서는 현금영수증 및 세금계산서 발행을 지원한다.

The tax invoice or cash receive is available for real time bank transfer transaction.

흐름도

Flow Diagram

3.6 매매보호 ESCROW

3.6.1 매매보호 기본 Escrow Basic

3.6.1.1 법적 요구사항

The legal requirement:

매매보호 거래는 10 만원이상의 현금거래(무통장입금, 실시간 계좌이체)에 대해서 소비자가

매매보호 거래짂행 여부를 선택할 수 있도록 해야함.

the merchant have to give a choice to customers when the order amount is over 100000KRW


14

페이게이트는 젂자금융거래법상의 매매보호 사업자임.

by the electronic transaction law, the licensed escrow service provider exist.

매매보호 거래는 이용업체와 페이게이트와의 계약체결을 해야함.

PayGate is the licensed escrow service provider. License No 02-006-00007

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

매매보호 거래발생후 유저가 거래대금을 지불 (가상계좌 입금 또는 실시간 계좌이체

성공)

페이게이트에서 구매자 확인후 배송요청 통보

업체에서는 관리화면의 매매보호 배송관리 메뉴에서 배송요청 거래건 확인 및 배송

배송처리후 배송업체에서 제공하는 운송장 번호를 매매보호 배송관리 화면의 입력란에

기록

페이게이트에서 운송장번호로 배송완료여부 확인 후 정산.

When the transaction completed, the escrow service provider hold the amount until

the delivery completed.

Real time bank transfer paymethod case

When the transaction completed online, paygate send the notice to merchant

with the payment result.

The merchant have to give delivery information to paygate via online admin

area or batch file upload.

After verifying the delivery completion, paygate settle the escrowed amount

to merchant.

Bank transfer notice paymethod case

When the transaction happen, paygate assign the escrow account number for

each transaction.

If the customer remit the amount to escrow account, paygate close the

transaction completed.

Paygate send the transaction result to merchant via online transaction status

list or daily report.

The merchant have to give delivery information to paygate via online admin

area or batch file upload.

After verifying the delivery completion, paygate settle the escrowed amount

to merchant.


15

3.6.2 매매보호 거래 활성화 방법 How to enable escrow transaction

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

서비스 옵션에서 매매보호 이용함으로 설정된 경우 10 만원 이상 현금거래시 유저가 매매보호

거래를 선택할 수 있는 화면이 제시됨.

if the amount is over 100,000KRW, the API will automatically show the guide screen that the

customer select to be escrowed or not.

If the customer choose to continue the transaction escrowed, the transaction is enabled as

the escrow transaction.

paymethod 값을 "999"로 설정하면 매매보호 거래가 가능한 지불수단의 목록이 제시되고 유저가

원하는 지불수단을 선택하여 매매보호 거래로 짂행가능.

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

Set "escrow" value to "loanSt" variable

거래발생시 "loanSt"변수의 값이 "escrow"로 설정하면 해당거래는 금액관계없이 매매보호

거래로 인식.

if the merchant set the "escrow" value to "loanSt" variable, the whole transaction will be

escrowed. ex) <input type=hidden name="loanSt" value="escrow">

\3.6.3 매매보호 가상계좌 번호

3.6.3.1 매매보호 가상계좌번호 할당

Assigning the escrow bank account

paymethod 는 "7" 무통장 입금 선택

loanSt 값은 "escrow"로 설정

bankcode 에는 입금하고자 하는 은행코드 선택

bankaccount 값이 없다면 서버에서 가상계좌번호를 채번하여 유저에게 제시.

if the transaction type is BTNOTICE(7) escrow, the escrow account will be assigned for each

transaction.

The "bankaccount", "bankcode" variables are used for assigning the account number.

Valid "bankcode" are as following

o 04 – 국민은행 KBStar bank

o 11 – 농협 NongHyup

o 26 – 싞한은행 ShinHan bank

o 20 – 우리은행 Woori bank


16

o 71 – 우체국 Korea post bank

o 81 – 하나은행 Hana bank

o 03 – 기업은행 Kiup bank

If the valid bankcode was selected, a new bankaccount number will be assigned and set to

"bankaccount" variable.

Escrow bank account number pool has 200,000 count for each valid bankcode.

For the non-escrowed transaction, the bankcode and bankaccount will be filled with the

merchant settle bank information.

The "receipttoname"’s value is used as the account owner name.

3.6.3.2 매매보호 가상계좌번호 정보 공지

Notifying the escrow account information

Notifying to merchant

the merchant is able to retrieve the escrow account from "bankaccount" variable of PGIOForm

ex)

var bankcode = document.PGIOForm.elements[‘bankcode’].value;

var bankaccount = document.PGIOForm.elements[‘bankaccount’].value;

notifying to customer

if the valid mobile phone number is in "receipttotel" variable, the escrow account

information will be sent via SMS mobile message.

As default, the escrow account information will be sent via e-mail.

3.6.3.3 매매보호 가상계좌 LifeCycle

the escrow account lifecycle

When the escrow account was assigned, it will wait to be remitted up to 3 months.

When the first transfer completed, the account will be closed and the other try will be denied.

If the amount that the customer is trying to remit is different from the original transaction,

the try will be denied.

When the account is filled with the amount customer transferred, the bank will notify to

paygate in realtime. Paygate will update the transaction and hold the amount.

When the account closed, it will be re-used at least 3 months passed.

3.6.5 배송정보 제공

Informing the delivery information


17

When the merchant start to deliver the good to customer, the merchant have to inform it to

paygate to verify and be settled as following ways.

3.6.5.1 상점 관리영역에서 배송정보 입력

Enter the delivery information on merchant admin website.

the merchant is able to enter delivery information on merchant admin website for each transaction.

3.6.5.2 페이게이트 서버로 SFTP 방식으로 일괄 젂송

Sftp the batch data to paygate server

filename naming rule

DLVRYINFO_[mid]_[YYMMDD].txt

ex) DLVRYINFO_paygateshop_071119.tx

file format

[DL](tab)[TID](tab)[ORDER_ID](tab)[DELIVERY METHOD](tab)[TRACKING NO](new line)

ex)

DL W53212345 W53212345 DHL 7853Q2WZ

DL W53213796 W53213796 FEDEX 9612893

SFTP Server

211.53.212.13

login ID : (assigned by paygate)

cut-off time

08:00 AM at every day.

Delivery method list

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


18

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

업체에서 거래결과를 정상수싞하였다는 응답을 주면 최종 거래를 종결하는 메커니즘임

Transaction verification verified that the merchant receive the transaction successfully.

3.7.1 서버간 거래확인 방식

Server-to-Server transaction verification

거래가 완료되면 페이게이트 서버에서 업체의 지정된 URL 로 거래결과를 젂달합니다.

when the transaction was completed, paygate server send the transacton result to pre-

defined URL of merchant.

거래결과 젂달 URL 은 상점 관리영역내의 서비스 옵션메뉴에서 사젂 등록해둘 수 있습니다.

The receiving URL is set at the service option of merchant admin website.

거래결과 젂달 URL 에 PGIOResult 에서 가져올 수 있는 모듞 값을 POST 합니다. 업체의 지정된

URL 의 Application 은 PGIOForm 의 parameter 를 parsing 하며 응답 메세지로 다음의 포멧을

요구합니다.

무통장 입금 확인 거래 과정

고객이 은행에 입금 한다. (페이게이트에서 개설한 업체의 가상계좌)

은행은 입금결과를 Paygate 측에 통보한다

Paygate 측의 PGTL 서버가 업체에서 미리 설정한 URL 에 입금 완료 통보 한다. (PGIOForm 의

변수명을 그대로 POST 하며 bankcode bankaccount payresultcode 을 홗용하십시오)

업체는 입금 완료 통보에 대해 기록하고 포멧에 맞게 String 을 작성하여 Return 한다.

이 응답내용을 PGTL 서버가 Parsing 하여 입근 완료 처리 한다.

거래결과를 수싞한 업체는 아래 포맷의 응답을 주어야합니다.

The merchant have to return as following format.


19

<PGTL><VERIFYRECEIVED>RCVD</VERIFYRECEIVED><TID>[tid]</TID></PGTL>

ex)

<PGTL><VERIFYRECEIVED>RCVD</VERIFYRECEIVED><TID>paygateshop_071119.123234</TID></PGT

L>

서버간의 확인방식은 확인수치 10 이 부여됩니다.

Server-to-Server verification add "10" verify count.

3.7.2 비지니스 처리가 완료된 이후 거래확인

Verification after business process completed.

*일반형 (기존 verifyNum 에 +1 을 더함)

상점은 거래결과를 수싞한 이후 상점의 모듞 비지니스 프로세스가 종결된 이후 응답을

줄 수 있습니다.

The merchant is able to verify after it’s business process completed.

"verifyReceived()"라는 자바스크립트 메소드가 사용됩니다.

The "verifyReceived()" javascript method is prepared to verify the business process

completed successfully.

추가작업 없이 openPayApi 결제방식에서 자동으로 1 번 호출하게 되어 있습니다.

사용예

Usage)

<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>


20

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

상점은 거래결과를 수싞한후에 상점쪽에 결과를 기록한후에 응답을 줄 수 있습니다.

반드시 상점쪽에 결과를 기록한 후에 호출하여야 합니다.

사용예 1.

<% 상점 데이터베이스에 결과를 기록하는 상점측 로직이 선행되어야 합니다.

%>

<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>


21

위와 다르게 스크립트 처리하셨다면 웹표준에 준수하여 작성하시기 바랍니다.

팝업창으로 https://service.paygate.net/verifyReceived.jsp?tid=거래 tid&verifyNum=100 을

호출하는 방식은 안됩니다.(고객께서 팝업창 차단을 사용하고 있다면 문제가 됨)

크로싱 브라우져(ie,모질라,파이어폭스,네스케이프)를 고려하셔서 테스트 해보시기 바랍니다.

사용예 2. (권장)

비지니스 로직에서 다음을 처리합니다.

https://service.paygate.net/verifyReceived.jsp?tid=거래 tid&verifyNum=100 을 호출을 합니다

-java 구현 샘플:

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 - "

https://service.paygate.net/verifyReceived.jsp?tid=%EA%B1%B0%EB%9E%98tid&verifyNum=100

https://service.paygate.net/verifyReceived.jsp?tid=%EA%B1%B0%EB%9E%98tid&verifyNum=100

http://hc.apache.org/

https://service.paygate.net/admin/settle/verifyReceived.jsp?tid


22

+ method.getQueryString());

log.error("PayGate verifyReceived Call statusCode - " + statusCode);

}

}

} catch (Exception e) {

if( log.isErrorEnabled() ) {

log.error("PayGate verifyReceived Call Error!! ", e);

}

}

-다른 얶어 샘플은 차후 추가 예정.

- HttpClient 는 jakarta 의 Commons Codec library 를 필요로 합니다

-고객이 결제 짂행시 결제가 승인된후 상점쪽으로 젂송완료 젂이나 상점쪽 페이지

호출젂에 브라우저의 종료등의 원인으로 pg 에는 결제승인 기록이 있으나 상점쪽에는 결제정보가 없는

현상이 보고됨.

-주의:결제 승인을 한 후에 상점 db 에 저장하기젂 페이지내에 alert()은 하지 말아야함

(결제흐름이 결제 승인 결과를 화면에 보여준후에 상점에 저장하는 흐름도라면

고객이 alert('결제완료')되었다는 메시지를 확인후 더이상의 행동(alert 창 닫기)을 안한다면 위와 같은

현상을 유발함.)

3.7.3 미확인 거래에 대한 처리

Processing for unverified transactions.

거래확인 검증용 서버 배치 프로세서는 매 2-5 붂마다 동작합니다.

the server batch script run at every 5 minutes check the transaction is verified.

검증대상은 거래발생시간 3 시간이젂부터 ~ 5 붂젂까지의 거래들입니다.

다음과 같은 처리를 상점에서 선택 지정하여 행할수 있습니다. 이는 서비스옵션에서 설정되며

미확인 거래가 발생시 자동으로 행하여 짂행됩니다.

1.서비스 사용여부 :

2.확장형 +100 적용여부

11.sms 상점관리자에게 발송 ex:01012345678,010-323-2323

12.sms 구매자에게 발송 (marking 'S')

21.email 상점관리자에게 발송 ex: [email protected]

22.email 구매자에게 발송 (marking 'E')

mailto:[email protected]


23

31.결제승인 취소 (marking 'C')

41. 거래 결과 재젂송 (marking 'R')

ex: http://www.paygate.net/result.jsp

//12,22,31 차후 서비스 예정.

위에 옵션을 체크박스로 다중 선택합니다.

12,21,31 번이 선택되었다면

거래불일치건이 발생시 결제승인을 취소시키고 이를 구매자에게 sms 로 젂송하고

상점관리자에게 이메일로 발송한다 등으로 처리를 미리 셋팅할수 있습니다.

41. 거래 결과 재젂송 (* 거래 결과를 재젂송 받는 페이지에서 처리는 data insert 가 아닌 data

update 를 권장합니다)

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

인하여

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

거래에서 확인하기

하단 [사짂 3-7-1]은 확장형 verifyNum 을 사용하는 업체의 거래목록중 일부입니다.

사짂에서 동그라미 안에 숫자는 해당거래의 verify Number 를 뜻합니다.

이는 상점로그인시에 거래목록 리스트 결과메시지 뒤에 표현됩니다.

-파랑 동그라미 안에 '102' 는 openPayApi 방식이므로 +1 , 상점 db 인서트 +100

verynum 이 처음 null 일때 1 로 처리되므로 1+1+100=102

해당거래가 정상적으로 상점에 기록이 되엇음을 의미합니다..

-빨강 동그라미 안에 숫자 '2' 는 openPayApi 방식이므로 +1 을 하였고 정상적으로 승인이

되었지만 상점측 db 에 기록이 되지 않았음을 의미합니다.

이는 페이게이트 상점 로그인을 하면 있으나 상점이 자체적으로 사용하는 관리자 화면에는

해당 거래가 기록되지 않았을것으로 예상할 수 있습니다.

http://www.paygate.net/result.jsp


24

[사짂 3-7-1]

3.8 취소 처리 및 취소 방법

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

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

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

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

b 의 상태일때 취소 요청 접수 => 오젂 카드사 송싞 => 취소 짂행

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

취소 방법

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

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

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

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

없습니다.

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

거래취소)


25

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

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


26

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"

이 매뉴얼에서 소개하는 내용은 HTTP POST 방식의 결제를 근거로 한다.

결제를 사용하는 브라우져의 캐릭터 셋은 "GB2312"나 "UTF-8"로 되어 있어야 한다.

SAMPLE CODE

<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'>


27

<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

paymethod : 106

Currency : USD

payment type : HTTPS POST

입력 및 출력 변수

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

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 →

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


28

Req "testgood" goodname → → "testgood"

Req "0.01" unitprice → → "2.12"

Req "USD" goodcurrency →

Req "US" langcode →

이 매뉴얼에서 소개하는 내용은 HTTP POST 방식의 결제를 근거로 한다.

Sample Code

<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


29

3.11 일본 계좌이체

Japan Bank Transfer

일본 계좌 이체는 OpenPayAPI 또는 HTTPS POST 방식으로 Paygate 측에 입금 예정 정보를 젂송하는

시스템이며,

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

테스트 방법

https://api.paygate.net/orderforms/order_sjis.html 접속

하단 주요 입력 변수를 참고로 필요한 값을 채워 [OpenPay API] 또는 [OpenPay Post] 버튺을

클릭한다.

필수값

mid : 상점 id

langcode : JP

paymethod : BTNOTICE

currency : Japan Yen

goodname : 상품 이름

bankcode : Paygate Bank

bankaccount : 목록에서 선택

선택값

transfer d-day : 입금 예정 날짜

receipttoname : 입금자 이름

상점 admin 에서 설정된 서비스 옵션중 MemberRedirectURL 을 기록하여 해당 URL 로 post 된

내용을 확인할 수 있습니다. (4.5 장 참고)

연동 방법

테스트 시에 사용된 입력 변수를 사용해 거래 정보를 젂송합니다.

상점의 charset 에 따라 action URL 은 다음과 같이 변경됩니다.

UTF-8 : https://serivce.paygate.net/INTL/NewPayProcessS.jsp

EUC-JP : https://serivce.paygate.net/EUCJP/NewPayProcessS.jsp

Shift_JIS : https://serivce.paygate.net/JP/NewPayProcessS.jsp 또는

https://service.paygate.net/payment/JP/payProcessJP.jsp

Sample Code

(OpenPayAPI 방식일 경우 doTransaction(form); 호출 / HTTP POST 방식일 경우는 해당

action 으로 POST)

https://api.paygate.net/order_sjis.html

https://serivce.paygate.net/INTL/NewPayProcessS.jsp

https://serivce.paygate.net/EUCJP/NewPayProcessS.jsp

https://serivce.paygate.net/JP/NewPayProcessS.jsp



30

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

method="POST">



<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">



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

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



<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"



31

Req "PG" bankcode "004PG"

Req "UFJ096" bankaccount

"Bank of Tokyo-

Mitsubishi UFJ ...

6796096"

paymethod 는 701 을 사용하며 7 은 기존 사용자를 위한 호홖성을 위해서 사용됩니다. 따라서 701 을

사용해 주시기 바랍니다.

charset : UTF-8, Shift-JIS

langcode : US, JP bankaccount

입금은행을 페이게이트 계좌로 지정하는 경우 페이게이트에서 거래내역 확인후 자동입금완료

설정됩니다. 아래는 페이게이트 입금 계좌목록입니다.

If you assign the bankaccount number of PayGate's, PayGate verify the transfer and update the status.

the following is the PayGate bank account list.

JPPOST861 : JAPAN POST BANK ゆうちょ銀行 10220 92618861

UFJ096: Bank of Tokyo-Mitsubishi UFJ 三菱東京 UFJ 銀行橫浜西口支店 6796096

MIZUHO587 : MIZUHO BANK みずほ銀行橫浜驛前支店 2216587

SMBC742 : Sumitomo Mitsui Bank 三井住友銀行橫浜驛前支店 8656742

3.12 무통장 가상계좌 입금 Bank Virtual Account Transfer

3.12.1 가상계좌 설정 방법

무통장 가상계좌 서비스를 이용하기 위해서는 무통장 결제 서비스에서 '가상계좌사용함'으로

설정되어 있어야 한다. (상점에서는 이 서비스를 이용하기 위해 싞청 해야 한다.)

무통장 가상계좌 입금 서비스는 거래발생시 가상 계좌 번호가 채번되어 구매자의 핸드폮과

이메일로 젂송된다. (상점은 고객이 어느 계좌로 입금할지에 대해서는 알 수 없다.)

해당 대금이 계좌로 입금완료시에는 입금완료라는 정보를 알려주고, 상점의 세이퍼트 계좌로

입금된 금액을 자동 이체한다.


32

가상계좌를 사용가능한 은행코드는 다음과 같다.

o 03 - 기업은행 Kiup bank

o 04 - 국민은행 KBStar bank

o 11 - 농협 NongHyup

o 20 - 우리은행 Woori bank

o 26 - 싞한은행 ShinHan bank

o 71 - 우체국 Korea post bank

o 81 - 하나은행 Hana bank

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

구매자가 가상 계좌에 ATM, 인터넷 뱅킹등을 이용하여 송금하면 즉시 그 결과가 상점

관리영역의 거래 내역에 업데이트 됨.

거래 젂송 내역을 수싞한 업체는 반드시 3.7.1 젃에 명시된 거래 결과에 대한 응답을 주어야

합니다.

상점은 입금 예정에서 입금 완료가 된 정보를 상점 자체 DB 에 기록하기 위해서 다음의 방법을

사용할 수 있음.

o 업데이트 받을 URL 을 기록 (회원 정보 수정)

o 해당 URL 로 POST 되는 변수 목록

tid : 원거래에 대한 tid

mb_serial_no : 원거래에 대한 상점 고유 거래 번호

banksendername : 송금을 한 사람의 이름

totalamount : 송금한 금액

replycode : 0000 일 경우 성공적으로 송금이 완료된 것임.

paymethod : 3007, 무통장 입금 거래


33

transactionstatus : 304212, 입금 완료 상태

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

상점 아이디별 과세/비과세를 설정하는 위치는 상점 로그인후 서비스 옵션에서 과세/비과세구붂

옵션에서 요청하시면 됩니다.

하나의 상점아이디에서 과세/비과세 품목이 다 있는 경우에는 일단 서비스 사용 옵션에서

기본적으로

과세로 선택 되어 있습니다.

과세 선택된 상태에서 변수명

<input type='hidden' name='tax_amt' value="''> 입니다.

tax_amt = 실금액 - 부과세금액

결과적으로 tax_amt 에 결제될 금액( unitprice )와 동일하게 해주시면

매출젂표를 출력하실때 부과세에 대한 금액이 출력되지 않습니다.(비과세상품)

그리고 <input type='hidden' name='tax_amt' value="''> 상태나 tax_amt 의 변수가 없으면

기존의 출력하시던 젂표형식으로 보실수 있습니다.

Documents

3_OpenPayAPI_Transactions.pdf