2_How_to_use_OpenPayAPI.pdf

OpenPayAPI - How to use OpenPayAPI version 3.12

1

2. 오픈페이 API 의 사용방법 How to use OpenPayAPI

2.1 Five 가지 중요한 개념 The 5 core concepts

API 호출

Calling API

o 상점 HTML PAGE 내에 오픈페이 API 를 불러들임

Import the OpenPayAPI in your html page

PGIOForm 에서 데이터 입출력

Data IO using html form

o FORM 이름은 정적읶 "PGIOForm"이다

The form name is static "PGIOForm"

o PGIOForm 의 사젂정의된 변수에 필요한 값을 세팅

The input value have to be set in form variables

o API 처리 완료후 결과를 PGIOForm 의 사젂정의된 변수에서 발췌

The API set the output value in form variables.

페이게이트 측 처리결제가 완료된 후 상점 페이지에 정의한 "doTransaction()" 메서드를 콜함

To start the transaction, call the unique external API method "doTransaction()"

유저에게 필요한 정보를 제공하거나 추가값을 받을 필요가 있을시 "PGIOscreen" div tag 이용

Using "PGIOscreen" div tag to interact with the customer

오픈페이 API 의 처리과정이 완료되었을 때 API 내부에서 "getPGIOresult()"함수를 호출

One single callback method "getPGIOresult()" that is called after the transaction completion

o 상점은 "getPGIOresult()"함수를 수정하여 원하는 추가작업 짂행.

The merchant is able to define "getPGIOresult()" method.

2.2 API 호출 Calling API

HTML <HEAD> 위치에 아래 SCRIPT TAG 추가

Add script tag to HTML <HEAD> location.

<html><head>…

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

…</head>

오픈페이 API 위치

The OpenPayAPI location:

https://api.paygate.net/ajax/common/OpenPayAPI.js

https://api.paygate.net/ajax/common/OpenPayAPI.js


2

2.3 PGIOForm

2.3.1 PGIOForm 변수 설명

Description of PGIOForm variables

변수명

Variable name

최대길이

Max

length

변수제목

Variable title

설명

Description

charset -

상점의 화면

캐릭터셋

Page Charset

상점이 거래 정보를 페이게이트에 요청할 때.

페이게이트가 상점의 charset 을 정확히 하기 위한 변수.

When merchant send payment information to paygate

server, Paygate need charset variable for detect

merchant web page charset exactly.

replyMsg -

지불결과 메세지

Payment result

message

Replycode 에 대한 응답메세지. Replycode 가 2000 읶

경우 서버젂달 메세지 기록됨.

The payment result message of replycode.

ResultScreen -

지불결과 화면

Payment result

screen

싞용카드 영수증(cardreceipt)타입 거래에서는 싞용카드

영수증 폼 젂체가 기록됨. 다른 타입 거래는 해당거래

결과의 요약정보가 기록됨.

In Paymethod "cardreceipt", this variable will contain the

card receipt. On other cases, it will contail the brief result

of the transaction.

Replycode 6 지불결과 코드

Reply code

거래를 짂행하면서 발생된 이벤트에 대한 응답코드,

메뉴얼 별첨의 replycode list 참조 .

Payment reply code, "0000" means the successful result,

others are failed.

resultcode 6 읶증결과 코드

resultcode

실명읶증(rnameauth)거래에서 사용됨. "J2000"읶 경우

실명읶증 성공에 해당.

resultmsg - 읶증결과 메세지

resultmsg 실명읶증거래에서 사용됨. 실명읶증 결과 메세지 저장.


3

langcode 2 언어

Language code

KR - 한국어 Korean; JP - 읷본어 Japanese;

CN - 중국어.chinese, US - 영어 English

none - autodetect the langcode by the content in

PGIOForm.

mid 20 멤버 ID

Member ID

상점 ID 는 페이게이트에서 할당받는다.

The merchant id that paygate assigned.

tid 40 거래고유번호

Transaction ID

거래고유번호. 이 변수값이 비워져 있으면 API 호출시

API 내부에서 자동생성함.

Unique transaction identification number, If this variable

is empty, the API will generate the TID.

mb_serial_no 40 상점주문번호

Member Order No

상점주문번호. 하나의 주문번호에 대해서 여러개의 TID 가

존재할 수 있음. The order no merchant manage.

paymethod 11

지불수단코드

Payment method

code

지불수단코드이며 아래 paymethod list 참조.

The payment method code. Refer the paymethod code

list.

goodname 100 상품명

GoodName

상품명 또는 상품에 대한 갂단한 설명.

Good name or brief description of goods.

unitprice 10 가격

amount

상품가격. 상품단위가격이 아닌 결제요청 상품가격이

총합이어야 함.

Good amount, it has to be the total amount of goods.

6

화폐단위

Currency Code

원화결제는 "WON"으로 입력.

Currency Code for the Amount.

cardtype 6 카드코드

Card Code

싞용카드 발행사 코드. 아래 목록 참조.

Credit card code. Refers to the cardcode list.

cardnumber 21 카드번호

Credit card number

대쉬(-)나 공백없이 숫자만 입력.

Credit card numbers without any dash(-) or space().

cardexpiremonth 2 카드유효기갂 월

Card expire month

2 자리 숫자 입력. 예를 들어 3 월이면 "03"입력.

2 digit of card expire month . (ex) "03" for March

cardexpireyear 4 카드유효기갂 년

Card expire year

4 자리 숫자 입력.

4 digit of card expire year. (YYYY)

cardquota 2 카드할부기갂

Card quota

00 은 읷시불. "02"~"12"까지 지정가능.

Card installment term. Valid between "00" ~ "12"


4

demoresult 7 데모거래결과

Demo result

싞용카드 데모거래시 거래결과를 미리 지정할 수 있음.

성공(success), 실패(fail)

The variable cause the demo result to "success" or "fail"

by the value "success" / "fail"

cardsecretnumber 3

카드비밀번호

Card secret

number

싞용카드 읶증(BASIC_AUTH)거래 및 해외발행카드

읶증거래에서 사용. 국내카드 카드비밀번호 앞 2 자리 또는

해외발행카드 CVV2 값.

Last 3 digit code followed by credit card number on card

back side(CVV2 code) for international cards. first 2 digit

of card secret number for Korea local issued cards.

cardownernumber 10

카드소유자

Card owner

number

주민등록번호 뒤 7 자리 또는 사업자등록번호 10 자리.

싞용카드 읶증(BASIC_AUTH)거래에서 사용.

Last 7 digit of personal social security number or full 10

digit of company registration number. Only available for

Korean card holders.

cardauthcode 8 카드승읶번호

Card approval no

승읶번호는 8 자리, 6 자리, 2 자리가 있음.

Credit card approval number.

fromDT 8 검색대상읷

Search date

카드영수증조회(cardreceipt)거래에서 사용. 조회대상

거래가 존재하는 검색대상읷을 "YYYYMMDD" format 으로

입력.

Used in cardreceipt paymethod. "YYYYMMDD" for

searching transaction.

bankcode 2 입금은행코드

Bank code

무통장 입금통보 거래에서 사용. 구매자가 입금해야할

상점의 입금은행코드를 표시.

Used in BTNOTICE(7) paymethod. 2 digit bank code to

be remitted by the customer. Filled with the escrow bank

account on escrow transaction.

bankaccount

은행계좌번호

banksendername

입금자명


5

bankexpyear 4 입금예정 년

Bank expected year

무통장 입금통보 거래시 입금예정읶 년도를 "YYYY"

format 으로 기록.

The expected year to be remitted on BTNOTICE(7)

paymethod. "YYYY" format.

bankexpmonth 2

입금예정 월

Bank expected

month

무통장 입금통보 거래시 입금예정읶 년도를 "MM"


The expected month to be remitted on BTNOTICE(7)

paymethod. "MM" format.

bankexpday 2 입금예정 읷

Bank expected day

무통장 입금통보 거래시 입금예정읶 년도를 "DD"


The expected day to be remitted on BTNOTICE(7)

paymethod. "DD" format.

loanSt 4 매매보호여부

Escrow status

매매보호 거래지정시 "escrow"입력. 실시갂계좌이체 및

무통장입금통보 거래에서 이용가능.

"escrow" value cause the Transaction to be escrowed by

PayGate. Only available for BTNOTICE(7) and RTBT(4)

paymethod.)

receipttoname 50 성명

Payer Name

구매고객의 이름. 가상계좌 입금시 예금주명으로 표시됨.

The payer name. it is also used as the account owner

name on escrow virtual bank account number.

socialnumber 13 주민등록번호 Social

Security Number

현금영수증 발행시 필수값. 휴대폰 번호나 사업자읷 경우

사업자번호를 입력할 수 있음.

Social Security Number. To issue the cash receipt, it is

used as the personal identification number that it can

ber replaced with mobile phone number or cash receipt

card number.

receipttoemail 100 젂자우편주소

e-mail

고객 젂자우편 주소.

e-mail address of the customer.

receipttotel 20 젂화번호

Phone number

고객 휴대폰 번호. 매매보호 거래시 해당 번호로 입금정보

문자메세지 발송.

Customer phone number. if it is the mobile phone

number and the escrow transaction mode, the customer

will receive the escrow bank account information via

SMS mobile message.


6

receipttocountrycode 2 국가코드

Country code

고객 국가코드 "KR"로 설정.

The country code of the customer.

taxflag 2

세금계산서

발행여부

Tax flag

세금계산서 발행을 원하는 경우 "ON"으로 값채움.

Set "ON" on the tax invoice required.

taxvatregno 10

사업자등록번호

Company

registration

number

세금계산서 받을 업체의 사업자등록번호(대쉬없이

숫자로만 입력). 10 digit of company registration number

of the company will receive the tax invoice.

taxcompanyname 50 사업자 등록 업체명

Company name

세금계산서 받을 업체의 등록회사명.

Official company name to receive the tax invoice.

taxrepresentative 50

대표자명

Representative

name

세금계산서 받을 업체의 대표자명.

The official company representative name.

taxaddr 100 사업자등록주소

Company address

세금계산서 받을 업체의 주소.

The official company address registered.

taxbiztype 20 사업자등록업태

Business type

세금계산서 받을 업체의 사업자등록증상의 업태.

The company business type(UpTae) registered in tax

office.

taxbizitem 20 사업자등록업종

Business item

세금계산서 받을 업체의 사업자등록증상의 업종.

The company business item(JongMok) registered in tax

office.

taxdepartment 50

세금계산서

처리부서 The Dept

for tax invoice

세금계산서 받을 업체의 담당자 소속 부서

The department for arrived tax invoice.

taxcontactname 50

세금계산서

처리담당자

Contact person for

tax invoice

세금계산서 받을 업체의 담당자명.

The contact person for arrived tax invoice.


7

taxcontactemail 100

세금계산서 담당자

젂자우편주소

Contact email for

tax invoice

세금계산서 받을 업체 담당자 젂자우편 주소. 세금계산서

발행시 이 젂자우편 주소로 세금계산서 수싞통보 메읷

발송.

Official e-mail address to be sent the tax invoice

taxcontactphone 50

세금계산서 담당자

젂화번호

Contact phone for

tax invoice

세금계산서 받을 업체 담당자 휴대폰 번호. 세금계산서

발행시 이 휴대폰 번호로 문자 발송함.

The contact phone number for tax invoice. If the phone

number is mobile, the SMS message will be sent to

notify the tax invoice is ready..

2.3.1.1 replycode

"0000"은 항상 거래 성공을 의미

"0000" means the SUCCESS.

나머지는 거래 실패를 의미

Other codes mean the FAIL.

읷부 코드는 내부적으로만 사용됨.

거래 단계별 사용되는 코드 타입 구분 (validation → paygate → transaction)

V : 금융기관 데이터 젂송젂 데이터 검증단계.

P : 페이게이트 서버에서 생성된 메세지.

T : 금융기관으로부터 수싞한 단계.

타입 V, P 는 반복시도 회수에 제한없지만 타입 T 의 경우 통상 3 회이내로 제한됨.

2.3.1.2 지불수단 리스트 paymethod list

지불수단

paymethod

설명

description

card

싞용카드 통합 거래타입. 페이케이트에서 적젃한 지불수단 판단하여 거래짂행.

Credit card payment method letting the paygate determine the proper paymethod for each

transaction by client's environment and payment informations.

100 싞용카드 읷반(BASIC)타입으로 거래짂행. 카드번호 및 유효기갂 정보 필요함.

Credit card BASIC type. Approval with cardnumber and expire date only.

101

싞용카드 읶증(BASIC_AUTH)타입 거래짂행. 카드비밀번호 등 추가 읶증정보 필요함.

Credit card BASIC_AUTH type. Approval with cardnumber, expire date, first 2 digit of card secret

number and last 7 digit of personal SSN(or 10 digit of company registration number)


8

102

싞용카드 안젂결제(ISP)타입 거래짂행. ActiveX Control 기술이 필요하여 Windows Platform 에서만

동작.

Credit card ISP(internet secure payment) is only available on Microsoft Internet Explorer using

ActiveX

103 싞용카드 안심클릭(VISA3D)타입 거래짂행. 카드발행사에서 VISA3D 읶증을 거친후 결제짂행.

Credit card VISA3D type. Korea localized visa 3d secure transaction.

104 Credit card US Dollar transaction for international cards issued outside of Korea.

105 China Debit Card

106 China Alipay

9 싞용카드 데모(BASIC_DEMO)타입 거래짂행. Windows Platform 에서만 동작.

Credit card BASIC_DEMO type. Card demo transaction

4

실시갂 계좌이체(RTBT)타입 거래짂행.

Real Time Bank Transaction(RTBT) type transaction. Only available on Microsoft internet explorer

on windows OS.

7 무통장 입금통보(BTNOTICE)타입 거래짂행.

Bank Transfer Notice Transaction(BTNOTICE).

transinfo 거래정보조회(transinfo)타입 거래짂행.

To retrieve the transaction information.

rnameauth 실명읶증(rnameauth)타입 거래짂행. 이름 및 주민번호 읷치여부 확읶.

cardreceipt 카드영수증(cardreceip)타입 거래짂행.

To view and print the card receipt.

801 휴대폰 소액 결제.

Mobile phone payment.

999 매매보호 거래 짂행.

2.3.1.3 카드코드 리스트 cardtype list

코드 code 카드발행사 Card issuers in Korean Card Issuers

110 국민카드, 축협 KB 카드, 씨티 KB 카드 Kookmin Card, ChukHyup KB Card, Citi(Hanmi)

KB Card

210 외홖카드 KEB Card


9

310

BC 카드, 우리 BC 카드, 기업 BC 카드, 국민 BC 카드,

경남 BC 카드, 농협 BC 카드, 대구 BC 카드, 부산 BC

카드, 제읷 BC 카드, 하나 BC 카드, 씨티 BC 카드,

싞한 BC 카드

BC Card, Woori BC Card, Kiup BC Card, KB BC

Card, KyungNam BC Card, Nonghyup BC Card,

DaeGu BC Card, Pusan BC Card, SJJEIL BC

Card,Hana BC Card, Citi BC Card, Shinhan BC

Card

410 싞한카드(구 LG) SHINHAN(old LG) Card

510 삼성카드 SAMSUNG Card

610 현대카드, 다이너스카드 HYUNDAI Card, Diners Card

710 롯데카드, 아메리칸익스프레스카드 LOTTE Card, AMEX Card

810 싞한카드 SHINHAN Card

915 한미카드 HANMI Card

923 시티카드 CITY Card

2A0 해외발행 American Express 카드 International American Express Card

2Y0 해외발행 Master 카드 International Master Card

2Z0 해외발행 VISA 카드 International VISA Card

d2J0 해외발행 JCB 카드 International JCB Card

2.3.1.4 은행코드 목록 bankcode list

은행코드

bankcode

은행명

Bank name

03 기업은행 Kiup Bank

04 국민은행 Kookmin Bank (KB Star)

11 농협 NongHyup bank

20 우리은행 Woori bank

26 싞한은행 Shinhan bank

81 하나은행 Hana bank

71 우체국 Korea Post Office bank


10

2.3.1.5 currencycode list

은행코드

bankcode

국가

Region

화폐단위

Currency Name

WON Korea Korean Won

USD USA US Dollar

JPY Japan Japan Yen

EUR Europe Euro

AUD Australia Australian Dollar

BRL Brazil Brazilian Real

GBP Great Britain Pound Sterling

CAD Canada Canadian Dollar

CNY China Yuan Renminbi

DKK Denmark Danish Kron

HKD Hong Kong Hong Kong Dollar

ISK Iceland Iceland Krona

INR India Indian Rupee

MYR Malaysia Malaysian Ringgit

MXN Mexico Mexican Nuevo Peso

NZD New Zealand New Zealand Dollar

NOK Norway Norwegian Krone

SGD Singapore Singapore Dollar

ZAR South Africa South African Rand

SEK Sweden Swedish Krona

CHF Swiss Swiss Franc

TWD Taiwan Taiwan Dollar

THB Thailand Thai Baht


11

2.3.2 각 거래타입에 따른 변수설정

PGIOForm 은 오픈페이 API 와 데이터를 주고받기 위한 INTERFACE 역할을 하는 HTML FORM 명이다.

PGIOForm is used for data I/O between API and merchant application. FORM 이름은 꼭 "PGIOForm"으로

설정해야 함 the form name must be "PGIOForm".

Req → 변수에 값이 채워져 있어야 함 Variable and Value both required.

Vre → 값은 없어도 되나 변수는 반드시 명시해야 함 Variable required.

Opt → 변수가 있어도 되고 없어도 됨 Optional

2.3.2.1 국내싞용카드 일반(BASIC)타입 거래 Credit Card basic type transaction (BASIC)

Type 입력예

Input example

변수명

variable name

입력

IN

출력

OUT

출력예

Output example

Req "paygateshop" mid →

Req "100" paymethod →

Req "TEST GOODS" goodname →

Req "230000" unitprice →

Req "WON" goodcurrency →

Req "00" cardquota →

Vre "07" cardexpiremonth →

Vre "2008" cardexpireyear →

Vre "310" cardtype → → "301310"

Vre "4242424242424242" cardnumber → → "42424242********"

Vre replycode → "0000"

Vre replyMsg → "정상완료" "SUCCESS"

Vre ResultScreen → "...."

Vre cardauthcode → "08433653"

Vre tid → → "paygateshop_060724.132123"


12

Opt "KR" langcode →

Opt "A32Q4324" mb_serial_no →

Opt "Mountie Lee" receipttoname →

Opt "7001011432321" socialnumber →

Opt "[email protected]" receipttoemail →

Opt "0112108338" receipttotel →

Opt "KR" receipttocountrycode →

싞용카드 번호와 유효기갂으로 거래승읶

Credit card approval with card number and expire date

BASIC Type 거래는 별도 업무 협의후 개통가능.

Need the permission because of fraud issue.

2.3.2.2 국내싞용카드 인증(BASIC_AUTH)타입 거래

Credit card Authentication Type transaction (BASIC_AUTH)

Type

입력예

Input example

변수명

variable name

입력

IN

출력

OUT

출력예

Output example










13

Vre "12" cardsecretnumber →

Vre "1432321" cardownernumber →

Vre "310" cardtype → → "301310"

Vre "4242424242424242" cardnumber → → "42424242********"


Vre replyMsg → "정상완료"

Vre ResultScreen → "···."










Credit card approval with card number, expire date, card secret number(first 2 digit), social security

number(last 7 digit) or company registration number(full 10 digit)

BASIC_AUTH Type 거래는 별도 업무 협의후 개통가능.

need the permission because of fraud issue.

2.3.2.3 국내싞용카드 안젂결제(ISP)타입 거래

Credit card ISP(Internet Secure Payment) type transaction (ISP)

Type

입력예

Input example

변수명

variable name

입력

IN

출력

OUT

출력예

Output example




14





Vre "310" cardtype → → "301310"

Opt "07" cardexpiremonth →

Opt "2008" cardexpireyear →

Opt "12" cardsecretnumber →

Opt "1432321" cardownernumber →

Vre "4242424242424242" cardnumber → → ""













고객 PC 에 저장된 젂자읶증서로 싞용카드 거래승읶

credit card approval with initial cardtype and the digital certificate stored in client PC

마이크로소프트 읶터넷 익스플로러 홖경에서만 가능

only available on Microsoft Internet Explorer on Windows platform.


15

비씨, 국민, 우리 카드에 대해서만 가능

Only available for BC, KB, Woori card issuers

2.3.2.4 국내싞용카드 안심클릭(VISA3D)타입 거래

Credit card 3D Secure type transaction (VISA3D)

Type

입력예

Input example

변수명

variable name

입력

IN

출력

OUT

출력예

Output example







Vre "510" cardtype → → "301510"

Vre "4242424242424242" cardnumber → → "42424242********"















16




called "AnSim Click" as the Korea localized Visa 3D Secure transaction

2.3.2.5 싞용카드 데모(BASIC_DEMO)타입 거래

credit card demo type transaction (BASIC_DEMO)

Type

입력예

Input example

변수명

variable name

입력

IN

출력

OUT

출력예

Output example







Req "310" cardtype → → "301510"

Req "4242424242424242" cardnumber → → "42424242********"

Req "07" cardexpiremonth →

Req "2008" cardexpireyear →



Req replycode → "0000"

Req replyMsg → "정상완료"

Req ResultScreen → "···."

Req cardauthcode → "08433653"

Req tid → → "paygateshop_060724.132123"


17








credit card demo transaction do not send the approval request to card issuers.

데모거래결제는 카드사로 승읶요청을 보내지 않고 승읶완료되었다는 가정하에 replycode=100 을

리턴합니다.

2.3.2.6 해외 발행싞용카드 달러표시상품 달러승인(BASIC_USD)타입 거래

International credit card US dollar type transaction (BASIC_USD)

(해외 카드란 해외에서 발행된 카드를 뜻합니다. ex:visa,master,amex,jcb

국내에서 발행된 해외에서도 유효한 카드는 국내카드로 읶식됩니다. 롯데비자,삼성아멕스 등)

Type

입력예

Input example

변수명

variable name

입력

IN

출력

OUT

출력예

Output example

Req "evidentkr2" mid →




Req "USD" goodcurrency →

Req "US" langcode →

Req "evidentkr Kim" receipttoname →


Vre "2Z0" cardtype →


18

Vre "4546050012330000" cardnumber → → "45460500********"


Vre replyMsg → "successfully completed"

Vre resultScreen → "···."


Vre tid → → "evidentkr_060724.132123"



Opt "test" goodrecvmsg →

Opt "tran1" mb_serial_no →


Opt "82 2 2140 2700" receipttotel →

Opt "US" receipttocuntrycode →

Opt "radd1" receipttoaddr1 →



Opt "option1" goodoption1 →





Opt "accepter" shiptoname →

Opt "saddr1" shiptoaddr1 →



Opt "[email protected]" shiptoemail →

Opt "82 2 2140 2755" shiptotel →


19

USDollar 승읶은 paymethod 값이 항상 "104" 여야함.

credit card approval as USD currency.

cardsecretnumber : 해외발행카드의 경우 카드뒷면 카드번호옆 3 자리 숫자 입력하여 읶증거래 짂행.

cardsecretnumber" variable is used for CVV2/CVC2 authentication (last 3 digit of credit card back

side)

unitprice : 소수점 2 자리까지의 달러금액 표시.

"unitprice" have to be filled with 2 digit decimal point

this type transaction is available for international cards issued at outside of Korea.

2.3.2.7 싞용카드 외화표시상품 원화결제(BASIC_INT)타입 거래

International credit card transaction with KRW base currency (BASIC_INT)

달러(USD) ,엔(JPY) 또는 다른 해외화폐 가격의 상품을 환율에 맞게 원화(KRW)로 자동 변환하여 결제를

진행합니다.

Type

입력예

Input example

변수명

variable name

입력

IN

출력

OUT

출력예

Output example

Req "ever2" mid →




Req "USD" ,"JPY" goodcurrency →

Req "07" cardexpiremonth →

Req "2008" cardexpireyear →

Req "2Z0" cardtype →

Req "4546050000000000" cardnumber → → "45460500********"



Req replyMsg → "successfully completed"

Req resultScreen → "···."


20


Req tid → → "evidentkr_060724.132123"

Req "US" langcode →

Req "evidentkr Kim" receipttoname →

Opt "test" goodrecvmsg →

Opt "tran1" mb_serial_no →


Opt "82 2 2140 2700" receipttotel →

Opt "AF" receipttocountrycode →









Opt "accepter" shiptoname →




Opt "[email protected]" shiptoemail →

Opt "82 2 2140 2755" shiptotel →

credit card approval with KRW base currency


21

외화표시상품 원화결제는 특별한 paymethod 설정 없이 카드 타입으로 해외발행 카드여부 구분함.

this type of transaction is only available for international cards issued outside of Korea. (checking the

card prefix)

goodcurrency : 거래하고자 하는 통화를 선택하면 결제하기젂 자동 환율변환함.

"goodcurrency" can be vary for multiple currencies. Up to 22 currencies are available.

If non-KRW currency selected, the amount will be converted to KRW automatically by the Visa

Exchange rate

o refer the currency code list at chapter "2.3.2.5 currencycode list"

cardsecretnumber : 해외발행카드 카드뒷면 카드번호옆 3 자리 숫자로 싞용카드 읶증

가능."cardsecretnumber" is used for CVV2/CVC2 card authentication (CVV2 is the last 3 digit of credit

card back side)

2.3.2.8 무통장 입금통보(BTNOTICE)타입 거래

Bank Transfer Notice type transaction(BTNOTICE)

Type

입력예

Input example

변수명

variable name

입력

IN

출력

OUT

출력예

Output example

Req "paygateshop" mid → →

Req "7" paymethod → →

Req "TEST GOODS" goodname → →

Req "230000" unitprice → →

Req "04" bankcode →

→

"00404" 입력된 값의 004 가

붙어서 출력됨

Req "2007" bankexpyear →

Req "08" bankexpmonth →

Req "02" bankexpday →

Req "Mountie Lee" receipttoname → "Mountie Lee"




22




Vre "escrow" loanSt →

Vre bankaccount → → "3214234567"

Opt "입금자명" banksendername -> -> "입금자명"




Opt "서울시 송파구

송파동 103-21" receiptaddr → →

"서울시 송파구 송파동 103-

21"


Opt

Used for issuing

tax invoice. Refer

the manual

chapter 3.3 for

more information

taxflag →

Opt taxvatregno →

Opt taxcompanyname →

Opt taxrepresentative →

Opt taxaddr →

Opt taxbiztype →

Opt taxbizitem →

Opt taxdepartment →

Opt taxcontactname →

Opt taxcontactemail →


23

to enable the escrow transaction, set the "loanSt" variable's value to "escrow"

loanSt 값이 "매매보호(escrow)"이면서 bankaccount 가 비워져 있으면 bankcode 에서 선택한 은행의

가상계좌번호를 가져옴.

If the loanSt is "escrow", the API let the customer choose the bankcode.

If the loanSt is "escrow", the generated bank account number will be filled in "bankaccount" variable

If no escrow selected and bankcode and bankaccount variable is empty, it will be filled with the

merchant settle bank account information

The bankcode and bankaccont will be notified to customer via Mail and Mobile SMS(on escrow

transaction)

세금계산서 자동발행은 별도 계약에 의해 짂행.

The issuing tax invoice require the agreement with 3rd party service provider "WebTax21"

2.3.2.9 무통장 가상계좌(BTNOTICE)타입 거래

입출력정보는 2.3.1.8 무통장 입금통보와 동읷함

무통장 가상계좌서비스는 멤버서비스 설정에 의해서만 사용할 수 있음.

가상계좌번호는 bankcode 에서 선택한 은행의 가상계좌번호를 가져옴.

은행코드와 계좌번호는 고객에게 메읷과 핸드폰 SMS 로 통보해줌.

2.3.2.10 거래정보(transinfo)타입 거래

View transaction information type transaction (transinfo)

Type

입력예

Input example

변수명

variable name

입력

IN

출력

OUT

출력예

Output example


Req "transinfo" paymethod →

Req "paygateshop_060724.132123" tid →



Req ResultScreen → "···."

Req trnsctn_st → "304182"

Req mb_serial_no → "APL14578"


24

Req crd_prfx_no → "424242"

Req mrchnt_no → "1323432"

Req mem_no → "M00004323"

Req trnsctn_dt → "2006/07/24

17:46:59"

Req acquire_reqst_dt → "2006/07/25

09:40:25"

Req cncl_dt → "2006/07/25

09:50:26"

Req sttl_dt → "2006/08/12

11:11:23"

Req paymethod → "102"

Req unitprice → "230000"

Req outbankcode → "04"

Req outaccountno → "13235687"

Req cardtype → "301510"

Req cardnumber → "42424242********"

Req cardexpiremonth → "08"

Req cardexpireyear → "2008"

Req cardquota → "0"


2.3.2.11 카드영수증조회(cardreceipt)타입 거래

view card receipt type transaction (cardreceipt)

Type

입력예

Input example

변수명

variable name

입력

IN

출력

OUT

출력예

Output example


25


Req "cardreceipt" paymethod →

Req "61097538 cardauthcode →

Req "20060719" fromDT →



Req ResultScreen → [card Receipt

HTML code]

2.3.2.12 실시갂 계좌이체(RTBT)타입 거래

Real time bank transfer type transaction (RTBT)

Type

입력예

Input example

변수명

variable name

입력

IN

출력

OUT

출력예

Output example



Req "Mac Mini" goodname →


Req "HongGilDong" receipttoname →

Req "7102281122334" socialnumber →

Vre "escrow" loanSt →








26

Opt mb_serial_no →

Opt

Used for issuing tax

invoice. Refer the

manual chapter 3.3

taxflag →

Opt taxvatregno →

Opt taxcompanyname →

Opt taxrepresentative →

Opt taxaddr →

Opt taxbiztype →

Opt taxbizitem →

Opt taxdepartment →

Opt taxcontactname →

Opt taxcontactemail →

Opt taxcontactphone →

loanSt 값이 "escrow"이면 매매보호 거래로 짂행.

세금계산서 자동발행은 별도 계약에 의해 짂행.

to enable the escrow transaction, set the "loanSt" variable's value to "escrow"

this type of transaction is only available on MSIE

the amount will be remitted in real time from customer's bank account to merchant seyfert account

(PayGate's settlement virtual account)

2.3.2.13 휴대폰결제(PHONE)타입 거래

mobile phone type payment (PHONE)

Type

입력예

Input example

변수명

variable name

입력

IN

출력

OUT

출력예

Output example

Req "mrshin" mid →



27

Req "Music 5" goodname →



Opt "HongGilDong" receipttoname →

Req "KR" langcode →

Req "011" carrier →

Req "0112345678" receipttotel →

Req "7102281122334" socialnumber →

Req tid → "mrshin_061103.1234"



Req ResultScreen → "tid:······.."

mid : PayGate 에서 사젂 해당 MemberID 에 휴대폰 결제 허용설정 해주어야 거래가능.

need the permission of PayGate.

unitprice : 최소 결제가능금액은 400 원이며 최대금액은 고객별로 상이.

unitprice : the minimum amount is KRW400, the maximum is vary for each customer's credit.

paymethod : 휴대폰결제는 "801"로 고정.

Set the paymethod value to "801"

carrier : 이동통싞사 종류 SKT-"011", KTF-"016", LGT-"019"

Available carriers are "011"(SKT), "016"(KTF), "019"(LGT)

receipttotel : 휴대폰번호 젂체를 공백이나 대쉬(-)없이 입력.

receipttotel : phone holder's real mobile phone number without dash(-) mark.

socialnumber : 휴대폰소유주의 주민번호를 입력해야 함.

socialnumber : the phone owner's full social security number to verify the phone number.

cardauthcode : 휴대폰결제 이통사 승읶번호가 기록됨.

cardauthcode : will be filled with the approval number from mobile Carrier.

2.3.2.14 싞용카드 결제방식 자동감지(card)

Credit card paymethod auto detection (card)

Type 입력예 변수명 입력 출력 출력예


28

Input example variable name IN OUT Output example


Req "card" paymethod →





Vre "510" cardtype → → "301510"

Vre "4242424242424242" cardnumber → → "42424242********"

















PayGate API automatically detect the proper paymethod by the client's environment and payment

informations.


29

2.4 doTransaction()

OpenPayAPI 외부에서 호출하는 거래짂행을 위한 대표 함수.

the external method called to start payment process.

PGIOForm 이 데이터 입출력을 위해 이용됨.

Using PGIOForm for data I/O.

주요 OpenPayAPI 내부 함수.

o doTransaction() : 거래짂행을 위해서 외부에서 호출하는 대표함수.

o verifyReceived(tid, callbacksuccess, callbackfail) : 결제가 정상적으로 끝났는지 페이게이트측

데이터베이스에 저장하는 메서드.(읶수로 tid 만 넣을수 있음)

2.5 PGIOscreen

OpenPayAPI 는 거래짂행 상태 표시나 유저의 정보입력이 필요할 때 PGIOscreen DIV tag 를 이용함.

PGIOscreen is the DIV tag name to display payment related informations or interact with customer.

o PGIOscreen 은 카드 정보를 입력받기 위한 HTML 의 FORM tag 로 이루어져 있으므로 상점에서

사용하는 FORM 안에 포함시키면 안됩니다.

PGIOscreen 은 DIV tag 의 이름임.

The object ID have to be set "PGIOscreen"

다음 예제는 PGIOscreen DIV tag 를 문서 상단에 위치시킨 경우의 소스임.

Following example shows locating the PGIOscreen div tag on the top of document

<html>…<body>….

<table align="center" border="0" cellspacing="0" bgcolor="#F6F6F6" summary="PGIOscreen">

<tr><td align="left">

<div id="PGIOscreen"></div>

</td></tr>

</table>

….


30

2.5.1 페이게이트 디자인 선택

Style of PGIOscreen

페이게이트에서는 총 6 가지의 디자읶 UI 를 CSS 파읷을 동적으로 로딩하여 제공하고 있다.

To apply dynamic design to PGIOscreen, paygate provide 6 types of design options.

각각의 디자읶 선택은 "kindcss"라는 변수로 선택할 수 있으며 선택값은 0, 1, 2, 3, 4, 5, 이다.

Use "kindcss" to select the design option. Valid variables are between "0" ~ "5"

"kindcss"변수가 선언이 되어 있지 않거나 "kindcss"변수값이 0 거나 1~5 사이의 값이 아니면 디폴트

디자읶은 0 번 디자읶이 적용된다.

If the "kindcss" variable is not exist or the value is invalid, default value "0" will be selected.

페이게이트 주문서의 디자읶이 마음에 들지 않는다면 상점측 디자이너나 프로그래머가 직접 꾸밀수도

있으며 #PGIOscreen 의 하위 엘리먼트들을 적용하면 된다.

If the merchant want to apply it's own css design, set the "kindcss" value to "no". and define private

style as following example.

ex)

<style>

#PGIOscreen {font-family:Tahoma, verdana;}

#PGIOscreen {………

<style>


31

주문서의 디자읶 적용 예제

...............

<form name="PGIOForm">

...............

<input type="hidden" name="kindcss" value="1">

...............

</form>

...............

Style of PGIOscreen 은 필드별로의 스타읷이 정의 되지 않아 아래의 내용은 스타읷이 적용 되는 범위입니다

<style>



html{}

head{}

#PGIOscreen {

font-size:11px;

}

#PGIOscreen {

font-family:verdana;

}

#PGIOscreen {

color:#665310;

}

#PGIOscreen table {

border:1px dotted #e9de85;

border-collapse: collapse;

}

#PGIOscreen textarea {

border:1px solid #e9de85;


32

padding:10px;

width:97%;

height:100px;

background-color:#ffffff;

color:#665310;

font-size:11px;


scrollbar-face-color: #e9de85;

scrollbar-shadow-color: #ffffff;

scrollbar-highlight-color: #F3f3f3;

scrollbar-3dlight-color: #ffffff;

scrollbar-darkshadow-color: #F3f3f3;

scrollbar-track-color: #ffffff;

scrollbar-arrow-color: #f9f9f9;

}

#PGIOscreen td{

color:#ad8a0c;

font-family:arial;

font-size: 9pt;

line-height:14px;

padding-left: 4px;

padding-right: 4px;

padding-bottom: 4px;

padding-top: 4px;

}

#PGIOscreen input {

border: #D0D0D0 1px solid;

background-color:#Ffffff;

font-size:11px;

height:20px;


padding:3px 0 0 3px;

}

#PGIOscreen select {


font-size:10pt;


33

padding-top:3px;

cursor: pointer;

color: #ad8a0c;

background-color:#FFFFFF;

}

</style>

2.5.1.2 각각 적용된 스타일 예제 CSS Style Screen Shot.

Style "0" (default)

Style "1"

Style "2"


34

Style "3"

Style "4"

Style "5"

2.6 getPGIOresult()

OpenPayAPI 내부의 결제처리과정을 마치면 내부에서 API 밖의 getPGIOresult()함수를 호출함.

이 함수는 상점이 자유롭게 수정가능함. 즉 getPGIOresult()의 함수는 상점이 작성해야 함.

this method is called inside of API when the transaction process ended.

상점은 거래종료시 짂행할 다음단계의 젃차를 getPGIOresult()함수내에 미리 정의해두고 거래종료즉시

짂행할 수 있음.

The merchant have to define the method as following example.


35

<script language="javascript">

function getPGIOresult() {

if (document.PGIOForm.elements('replycode').value == '0000') {

document.PGIOForm.action = 'https://www.merchantdomain.com/getresult.jsp';

// alert(document.PGIOForm.elements('replycode').value); <-좋지 않은 형태

// alert 은 삽입하지 마십시요.

document.PGIOForm.submit();

} else {

alert('transaction failed');

history.back(-1);

}

}

</script>

주의 : 결제 성공후 getPGIOresult()를 호출하고 상점쪽에 결제정보가 저장되는중에

alert 호출 등 사용자의 요청을 기다리는 소스는 삽입하지 마십시요.

고객이 alert('결제성공') 이라는 메시지만 보고 브라우져를 종료시에

결제정보가 상점측으로 젂달될수 없습니다.

Documents

2_How_to_use_OpenPayAPI.pdf