NAV Navbar

페이레터 결제 소개

서비스 안내

몇 번을 고민해도, 당신의 파트너는 페이레터입니다!

페이레터는 온라인 상점의 재화/서비스 판매를 위한 전자결제 대행 서비스를 제공합니다.

국내외 보안인증 획득을 통한 안전성 검증, 다양한 결제수단,

안정적인 거래 처리 능력을 바탕으로 편리한 결제 서비스를 제공하기 위해 노력하고 있습니다.

1. 전세계 25개국, 260개 가맹점에서 페이레터 서비스 이용 중
2. 글로벌 신용카드 데이터 보안 인증 PCI-DSS, 국내 정보 보안표준 ISMS 인증 획득으로 안전한 결제 환경 제공
3. 국내 1위 E-Commerce, 음원 서비스, VOD 서비스 등의 거래를 통해 검증된 거래 처리 능력
4. 튼튼한 재무 구조로 안정적 서비스 제공 및 대금 정산 가능
5. 경쟁사 대비 월등한 콜센터 고객 응대율(98.7%)

결제수단 및 부가서비스

금융 간편결제 통신 상품권 선불카드 부가서비스
신용카드
인터넷뱅킹
가상계좌
토스(TOSS)
카카오페이
페이코
SSG페이
계좌 간편결제(체크페이)
네이버페이
삼성페이
스마일페이
애플페이
휴대폰 결제
KT 집전화 결제
문화상품권
컬쳐랜드상품권
스마트문상
도서문화상품권
해피머니상품권
모바일팝
틴캐시
편의점캐시
에그머니
교통카드(티머니, 캐시비)
교통카드(이즐)
본인확인

가입절차

신규 가입문의 : 영업팀 장민수 (02-6191-3744 / msjang@payletter.com)
1. 온라인 가입 가입하기
2. 가입심사 진행 이용불가업종 보기
3. 보증보험 가입
- 문의 : 서울보증보험 서초지점 [(주)개런티인슈] / 02-3486-0021, 02-3487-0035
4. 계약서 및 구비서류 제출 계약서 보기
5. 결제수단별 심사 진행
- 신용카드/간편결제/휴대폰 : 약 2주 소요
- 인터넷뱅킹 : 약 1~2일 소요
- 상품권/선불카드 : 약 3~5일 소요
6. 등록비 납부 및 가입 완료

구비서류

구분 법인사업자 개인사업자
계약서류 1. 페이레터 통합결제서비스 이용계약서 2부
2. 개인정보 수집 이용 및 활용 동의서 1부
구비서류 1. 사업자등록증 사본 1부
2. 법인 인감증명서 원본 1부(3개월 이내 발급분)
3. 입금계좌 사본 1부(법인명의)
4. 사용인감계 1부(계약서에 사용인감 날인 시)
5. 지급이행 보증보험증권 원본 1부
1. 사업자등록증 사본 1부
2. 대표자 인감증명서 원본 1부(3개월 이내 발급분)
3. 입금계좌 사본 1부(대표자 또는 사업자명의)
4. 지급이행 보증보험증권 원본 1부

연동 전 확인사항

API HTTPS 프로토콜

지원하는 HTTPS 프로토콜

페이레터 API HTTPS는 TLS 1.2 이상 지원합니다.

방화벽

결제완료 Callback 을 수신하기 위하여 inbound IP를 추가해 주시기 바랍니다.

테스트 : 121.254.205.166

라이브 : 211.115.72.37, 211.115.72.38, 211.115.117.11(예비)

API Authorization

가맹점 계약이 완료되면 API Key가 발급됩니다. 가맹점 계약 안내

API Key는 가맹점 관리자 페이지 에서 확인하실 수 있습니다.

API Key는 결제(PAYMENT) / 조회(SEARCH) 용 두 가지 Key가 발급됩니다.

HttpRequestHeader Authorization 항목에 다음과 같이 API Key를 보내 주시기 바랍니다.

Authorization: PLKEY {가맹점_apikey}

API Endpoint URL

환경 주소
테스트 https://testpgapi.payletter.com/
라이브 https://pgapi.payletter.com/

테스트 환경에서는 callback_url 호출 시 80, 443만 허용하고 있어 이 외 포트 이용 시 방화벽 등록이 필요합니다.

등록 가능한 공용 IP 및 Port 정보를 기술지원 메일(poqdev@payletter.com)로 등록 요청하시길 바랍니다.

테스트 환경 가맹점 정보

가입 전에 테스트 환경에서 미리 구성된 API Key로 연동 테스트가 가능합니다.

Parameter Value
가맹점 아이디 pay_test
API Key (PAYMENT) MTFBNTAzNTEwNDAxQUIyMjlCQzgwNTg1MkU4MkZENDA=
API Key (SEARCH) MUI3MjM0RUExQTgyRDA1ODZGRDUyOEM4OTY2QTVCN0Y=

결제수단별 옵션

결제수단 자동결제 결제취소 부분 취소 취소가능기간 최소 승인가능금액
신용카드  O O O D+180 100원
인터넷뱅킹  X O O 결제 당일 1000원
가상계좌 X X X 취소불가 500원
토스(TOSS)  X O O D+180 1원
카카오페이  X O O D+180 100원
페이코  O O O D+180 100원
SSG페이 X O O D+180 100원
네이버페이 X O O D+180 100원
삼성페이 X O O D+180 100원
애플페이 X O X D+180 1원
계좌 간편결제(체크페이) O O X D+30 1000원
휴대폰  O O O 결제 당월 10원
KT 집전화 결제 X O X 결제 당월 10원
문화상품권  X O X D+24 1원
컬쳐랜드상품권  X O O D+24 1원
스마트문상  X O X D+24 1원
도서문화상품권  X O O D+24 1원
해피머니상품권  X O O D+24 1원
모바일팝  X O O D+24 10원
틴캐시  X O X D+24 10원
편의점캐시  X O X D+24 10원
에그머니  X O X D+24 10원
교통카드결제(티머니/캐시비) X O X D+24 10원
교통카드결제(이즐) X O O D+24 10원
스마일페이 X O O 신용카드 : D+180
캐시 : D+365
100원

결제수단별 참고사항

결제수단

1. 토스(TOSS)의 경우 TLS 1.1 이상 브라우저만 지원합니다.
2. 네이버페이, 스마일페이의 경우 Callback URL로 결제 결과 전달 시
   사용자가 선택한 결제수단에 따라 pgcode가 다르게 전달됩니다.
   (네이버페이 : navercard or naverpoint)
   (스마일페이 : smilecard or smilecash)
3. 모바일 티머니 결제 시 티머니 모듈이 필요합니다.
   (구글 플레이스토어에서 (주)티모넷의 충전결제모듈, 모바일티머니 어플 다운로드 후 결제 가능)
4. 모바일 이즐 결제 시 이즐 모듈이 필요합니다.
   (구글 플레이스토어에서 주식회사 이동의즐거움의 모바일이즐 어플 다운로드 후 결제 가능)
5. SSG페이 회원으로 등록되지 않은 휴대폰번호의 경우 결제 페이지에서 호출 시 오류가 발생합니다.
6. SSG페이,삼성페이 결제 요청 시 파라메터 중 "service_name"이 필수값입니다.
7. 애플페이 사용 가능 카드 : 현대카드
   ○ iOS 11.3이상, MacOS 10.12.6이상, Safari 11.1이상에서 사용 가능
   ○ iPhone, iPad : Safari이외의 브라우저도 사용은 가능하나 Safari 브라우저 사용 권장
   ○ MacBock : Safari 브라우저에서만 사용 가능
   ○ wifi만 사용 가능한 iPad는 전자지갑에 현대카드 등록시 현대카드 고객센터에 연락하여 등록 가능.(유저문의시 안내)

테스트 결제

1. 신용카드 테스트의 경우 밴(신용카드)사 통신은 하지 않습니다.
2. 카카오페이, 휴대폰결제, SSG페이의 경우 테스트 환경에서 실제로 결제가 발생합니다.
   (결제 당일 밤에 자동으로 결제 취소되오니 참고하시기 바랍니다.)
3. 가상계좌 테스트는 채번단계까지만 가능합니다. 실제 입금 시, 취소가 불가한 점 참고하시기 바랍니다.
   (실제 입금테스트가 필요하신 경우 별도 문의하시기 바랍니다.)
4. 애플페이 테스트의 경우 밴(신용카드)사 통신은 하지 않습니다.(실결제 되지 않음)
5. KT 집전화 결제의 경우, 테스트 환경에서는 전화가 오지 않습니다.
6. 인터넷뱅킹/상품권/선불카드의 테스트가 필요하신 경우 별도 문의하시기 바랍니다.
7. 테스트 환경의 경우 신용카드 자동결제 휴대폰 인증 시 인증번호가 문자로 발송되지 않습니다.
   (임의의 번호 입력 후 진행 가능)

기술지원

poqdev@payletter.com

결제 관련 문의 시에는 연동 환경, 가맹점 아이디, 주문번호, 거래시간, token 등

상세 정보를 보내주시면 보다 빠른 응대가 가능합니다.

결제 API

API 목록

URL METHOD KEY TYPE 기능
v1.0/payments/request POST PAYMENT 결제 요청
v1.0/payments/request POST PAYMENT 자동결제
v1.0/payments/autopay POST PAYMENT 자동결제 승인
v1.0/payments/cancel POST PAYMENT 결제 취소
v1.0/payments/cancel/partial POST PAYMENT 부분 취소
v1.0/cashreceipt/issue/{tid} POST PAYMENT 현금영수증발급
v1.0/payments/transaction/list GET SEARCH 결제 내역 조회
v1.0/payments/status POST PAYMENT 거래 상태 조회
v1.0/receipt/info/{tid} GET SEARCH 거래 내역 확인서

결제 프로세스

API 샘플소스

페이레터 API 샘플 소스는 ASP, ASP.NET, JSP, PHP 언어를 제공하고 있습니다.

언어 샘플소스
ASP 다운로드

ASP.NET 다운로드

JSP 다운로드

PHP 다운로드

Node.js 다운로드

결제 요청

요청

POST /v1.0/payments/request HTTP/1.1
Host: testpgapi.payletter.com
Authorization: PLKEY MTFBNTAzNTEwNDAxQUIyMjlCQzgwNTg1MkU4MkZENDA=
Content-Type: application/json

{
    "pgcode" : "mobile",
    "user_id":"test_user_id",
    "user_name":"테스터",    
    "service_name":"페이레터",    
    "client_id":"pay_test",
    "order_no":"1234567890",
    "amount":1000,
    "taxfree_amount": 100,
    "tax_amount": 20,
    "product_name":"테스트상품",    
    "email_flag":"Y",
    "email_addr":"payletter@payletter.com",
    "autopay_flag":"N",    
    "receipt_flag":"Y",
    "custom_parameter":"this is custom parameter",    
    "return_url":"https://testpg.payletter.com/result",
    "callback_url":"https://testpg.payletter.com/callback",
    "cancel_url":"https://testpg.payletter.com/cancel"
}

Key Type

PAYMENT

HTTP Request

POST v1.0/payments/request

Request Parameters

Parameter Default Type Size Description
pgcode 필수 string 20 결제수단 코드 첨부 참조
client_id 필수 string 20 가맹점 아이디
service_name string 20 결제 서비스명
(삼성페이, SSG페이는 필수)
user_id 필수 string 50 가맹점 결제자(회원) 아이디(email, 영문 및 숫자 가능)
user_name string 20 가맹점 결제자(회원) 이름
order_no string 40 가맹점 주문번호
amount 필수 number 결제금액
예외) 문화상품권 (pgcode : voucher) 인 경우, 5000/10000/50000 외의 값 입력불가
taxfree_amount number 비과세 금액 적용은 amount값과 동일값으로 처리
복합 과세 금액 적용은 amount(전체 금액), taxfree_amount(비과세 금액)으로 처리
tax_amount number 부가세 금액(세팅하지 않는 경우 (결제금액 - 비과세 금액)/11 : 소수점이하 반올림으로 자동 계산)
product_name 필수 string 100 결제 상품(컨텐츠)명
(<, > ,캐리지 리턴(\n) 등의 제어문자 사용불가)
email_flag string 1 결제내역 메일 수신 여부 (Y:사용, N:미사용)
email_addr string 100 결제내역 메일 수신 주소
(*email_flag를 "Y"로 세팅한 경우에만 사용)
autopay_flag string 1 자동결제 여부 (Y:사용, N:미사용)
receipt_flag string 1 현금영수증 입력 창 노출 여부 (Y:사용, N:미사용)
(*현금영수증 계약이 되어 있는 경우에만 사용 가능)
keyin_flag string 1 신용카드 수기결제 여부
(*별도 계약이 되어 있는 경우에만 사용 가능)
custom_parameter string 1024 가맹점이 전송하는 임의의 값
ex) 고객정보, 주문정보, 기타 필요한 정보를 세팅하면 결제 결과로 다시 리턴
return_url 필수 string 256 결제 완료 후 연결할 웹 페이지 URL
callback_url 필수 string 256 결제 성공 결과를 수신할 callback URL
(가맹점 결제 성공 처리)
cancel_url string 256 취소 버튼 클릭시 연결할 웹 페이지 URL
일부 결제 수단은 cancel_url로 이동하지 않음 (네이버페이, 삼성페이 등)
inapp_flag string 1 In-app 사용 여부 (Y:사용, N:미사용)
app_return_url string 256 In-app 에서 ISP / KFTC(계좌이체)결제시 연결할 앱 스키마
(예:IOS - 앱 Address://, 안드로이드 - 앱 Address://ISPSuccess)
app_cancel_url string 256 In-app 에서 ISP / KFTC(계좌이체)결제 취소(중단)시 연결할 앱 스키마
(예:IOS - 앱 Address://, 안드로이드 - 앱 Address://ISPCancel)
expire_date string 8 가상계좌 채번시 만료일 설정(YYYYMMDD)
expire_time string 4 가상계좌 채번시 만료시각 설정(HHMM)
disposable_cup_deposit number 일회용 컵 보증금(*특정 결제 수단 사용 가능, 부분 취소 불가)
*특정 결제 수단 : 신용카드, 네이버페이, 카카오페이, 토스(TOSS), SSG페이, 교통카드결제 (티머니/캐시비), 휴대폰
company_name_flag string 1 카드사 인증창 내 가맹점명 노출 여부 (Y:노출, N: Payletter 노출, 신용카드만 사용가능)

[인앱 결제 연동]

공통사항

인앱 결제 연동 시 모바일 웹뷰(WebView)로 당사 결제창을 구현하고 카드사 및 기관별 결제를 위해

외부 앱을 호출할 수 있도록 처리하여야 문제없이 결제가 진행됩니다. 외부 앱 호출을 위해

앱 스킴이 추가되어야 하니 첨부 파일에서 모바일 OS에 따른 앱 스킴 값을 확인하시기 바랍니다.

●Android

외부 앱 이동 시 WebViewClient의 shouldOverrideUrlLoading() 함수 사용

1) 재정의한 shouldOverrideUrlLoading() 함수 내 @Override을 추가하지 않으면 net::ERR_UNKNOWN_URL_SCHEME

오류가 발생할 수 있음

2) 앱 설치여부 확인을 위해 startActivity() 호출 전에 패키지 정보를 조회하는 경우 설치 여부 확인 로직을

제거하고 바로 startActivity()을 호출

3) startActivity() 호출 시 ActivityNotFoundException(Message : No Activity found to handle Intent)이

발생한 경우 앱이 설치되지 않은 것으로 간주하고 앱 설치를 위해 마켓으로 이동하도록 처리


Android 11 (API 30) 에서 개발 시 유의사항

구글 보안정책에 따라서 앱의 targetSdkVersion을 30 이상으로 설정하게 되면 아래 사항을 필수로 조치해야 합니다.

1) AndroidManifest.xml 파일에 usesCleartextTraffic 속성을 true로 설정하여 net::ERR_CLEARTEXT_NOT_PERMITTED 오류 방지

2) 앱 내에서 다른 패키지 상태 확인을 위해 AndroidManifest.xml 의 queries 요소에 패키지 정의하여 가시성 확보

3) 카드사 및 백신의 패키지명은 첨부 파일을 참고하시길 바랍니다.

●ios

REST API를 통해 결제 페이지의 URL을 받으신 후 결제창을 WEBVIEW 방식을 통해 여는 방법을 사용하시면 됩니다.

웹뷰에서의 외부 앱 호출을 위해 info.plist 에 필요한 앱 스킴(App Scheme)을 등록해야 합니다.

info.plist에 앱 스킴(App Scheme)을 나열해두면 외부 앱 실행을 묻는 창이 뜨면서 자동으로 처리됩니다.


1) ios 9.0 버전 이상에서는 보안정책 강화로 LSApplicationQueriesSchemes 항목을 추가했습니다.

URL scheme을 사용해서 외부 앱을 열 경우, 화이트리스트에 등록된 scheme만 열 수 있게 하여

보안을 강화하기 위함입니다. 카드사/기관 앱을 열려면 화이트리스트 (허용 목록, info.plist)를 추가

해야 합니다.

2) ios 6.0 버전 이상에서 사파리(Safari)의 쿠키 기본설정이 항상 설정시에만 세션 유지가 가능하게 바뀌어

세션 만료 오류가 발생할 수 있습니다. 쿠키를 항상 허용으로 설정해주세요.

Response Parameters

성공시

HTTP 1.1 200 OK
{
    "token" : 153438847514600001,
    "online_url": "https://testpg.payletter.com/pgsvc/hub.asp?location=online&token=153438847514601",
    "mobile_url": "https://testpg.payletter.com/pgsvc/hub.asp?location=mobile&token=153438847514601" 
}

실패시

HTTP 1.1 401 Unauthorized
{
    "code": 998,
    "message": "Authentication token is missing or incorrect"
}

성공시

Parameter Type Description
token number 결제 인증 토큰
online_url string PC 환경 결제 창 호출 URL
mobile_url string Mobile 환경 결제 창 호출 URL

실패시

Parameter Type Description
code number 에러 코드
message string 에러 메시지

결제 연동

결제요청 API Response로 리턴된 URL을 사용하여 결제창을 호출합니다.

사용자가 결제를 진행하면 결제요청에서 전달하신 return_url로 결제 결과가 반환됩니다.

결제완료 처리(재화 지급 등 가맹점의 business logic)은 callback_url에서 수행하는 것을 권장합니다.

return_url 과 callback_url에서의 프로세스는 아래 설명을 참고하시기 바랍니다.

* 토스, 체크페이, 가상계좌는 반드시 callback_url을 연동하셔야 합니다.

Return URL

결제 결과는 Request의 POST 파라메터로 전송됩니다.

성공시

Parameter Type 설명
code string 결과
message string 메시지
user_id string 가맹점 결제자(회원) 아이디(email, 영문 및 숫자 가능)
user_name string 가맹점 결제자(회원) 이름
order_no string 가맹점 주문번호
service_name string 결제 서비스명
product_name string 결제 상품(컨텐츠)명
custom_parameter string 결제요청시 가맹점에서 전송한 값
tid string 결제고유번호
cid string 승인번호
amount number 결제요청 금액
taxfree_amount number 비과세 금액
tax_amount number 부가세 금액(세팅하지 않는 경우 (결제금액 - 비과세 금액)/11 : 소수점이하 반올림으로 자동 계산)
pay_info string 결제 부가정보
pgcode string 결제요청한 pg명
billkey string 자동결제 재결제용 키
domestic_flag string 국내 / 해외 신용카드 구분 (Y : 해외, N : 국내)
transaction_date string 거래일시(YYYY-MM-DD HH:MM:SS)
install_month number 할부개월수
card_info string 마스킹(중간6자리) 카드번호
(일반결제(신용카드, 페이코) / 자동결제(신용카드, 페이코) 에만 전달)
payhash string 파라메터 검증을 위한 sha256 hash 값
Sha256(user_id +amount + tid +결제용 API Key)
* 일부 결제 수단은 전달되지 않습니다.(가상계좌 등)
disposable_cup_deposit number 결제요청한 일회용 컵 보증금
가상계좌
account_no string 가상계좌 번호
account_name string 가상계좌 입금자명
account_holder string 가상계좌 예금주명
bank_code string 가상계좌 은행 코드
bank_name string 가상계좌 은행명
issue_tid string 가상계좌 채번 승인번호
expire_date string 가상계좌 입금만료일 (ex: 20210808)
expire_time string 가상계좌 만료시각 (ex: 1130)
현금영수증
cash_receipt_code string 실패 코드
cash_receipt_message string 실패 메시지
cash_receipt_type string 거래자구분(01:소득공제용, 02:사업자지출증빙용)
cash_receipt_issue_type string 현금영수증 발행 구분(1:구매자발급, 2:자체발급)
cash_receipt_cid string 현금영수증 승인번호
cash_receipt_payer_sid string 신분확인 번호(휴대폰번호, 사업자번호)
cash_receipt_deal_no string 현금영수증 발급시 전달받은 주문번호

실패시

Parameter Type 설명
code string 결과
message string 메시지
user_id string 가맹점 결제자(회원) 아이디(email, 영문 및 숫자 가능)
order_no string 가맹점 주문번호
service_name string 결제 서비스명
product_name string 결제 상품(컨텐츠)명
custom_parameter string 결제요청시 가맹점에서 전송한 값

Callback URL

{
    "user_id":"test_user_id", 
    "user_name":"테스트", 
    "amount":1000,
    "tax_amount":20,
    "taxfree_amount":100,
    "tid":"tpay_test-201808162396515", 
    "cid":"20180816150336996237", 
    "order_no":"1234567890", 
    "service_name":"페이레터", 
    "product_name":"테스트상품", 
    "custom_parameter":"this is custom parameter", 
    "transaction_date":"2018-08-16 15:03:52", 
    "pay_info":"0101234567", 
    "pgcode":"mobile", 
    "domestic_flag":"", 
    "billkey":"",
    "card_info" : "457973******1234",
    "payhash" : "9E078A29E6435959A07ED2E8415789234D18250434BAF2C185C2EF3012C77E92",
    "disposable_cup_deposit" : 0,
    "method_info" : "",
    "coupon_amount" : 0,
    "receipt_possible_amount" : 0,

    "cash_receipt":
    {
        "code":"결과",
        "message":"메시지",
        "cid":"현금영수증 승인번호",
        "deal_no":"현금영수증 발급시 주문번호",
        "issue_type":"현금영수증 발행 구분",
        "payer_sid":"신분확인 번호",
        "type":"거래자구분"
    }
}

결제가 성공한 경우에만 결제 결과가 json형태로 제공되며,

Return Url의 데이터와 함께 추가로 전달 되는 Callback Url의 내용은 아래와 같은 형태로 제공됩니다.

Parameter Type 설명
method_info string 복합결제 (예: 신용카드+(충전)포인트) 시 메인 결제 수단
(적용결제 수단: 네이버페이, 카카오페이, SSG페이, 스마일페이, 페이코, 토스(예정))
예) navercard : card
    navermoney : money
    kakaocard : card
    kakaomoney : money
    ssgpaycms : cms
    ssgpaycard : card
    ssgpaymoney : money
    smilecard : card
    smilecash : money
    payco : 결제 후 타입에 따라 지정
coupon_amount number 쿠폰 금액 (페이코만 적용)
receipt_possible_amount number SSG페이, 네이버페이에서 충전형 포인트에 대한 현금영수증 발급가능 금액
cash_receipt object
 └ code string 결과
 └ message string 메시지
 └ cid string 현금영수증 승인번호
 └ deal_no string 현금영수증 발급시 주문번호
 └ issue_type string 현금영수증 발행 구분
 └ payer_sid string 신분확인 번호
 └ type string 거래자구분

전달받은 Callback URL 을 통해서 결과값을 받아서 가맹점에 맞는 충전, 구매 등의 로직을 수행하도록 합니다.

Callback URL에서 처리 완료 후 성공시 아래 json 문자 열을 출력해 주시기 바랍니다.

{"code":0, "message":"실패시 실패 사유"}

code 는 성공시 0, 실패시 0이 아닌 다른 값을 전달해 주시면 됩니다.

code 가 0이 아닌 경우에는 통보가 실패한 것으로 간주되어 5분마다 최대 20번까지 재 전송됩니다.

발송 내역은 가맹점 관리자 사이트(https://manager.payletter.com)에 로그인 후

조회/취소->노티실패내역조회 메뉴에서 확인이 가능합니다.

Return Url / CallBack Url로 전달된 파라메터는 위/변조 방지를 위하여

sha256 hash 값을 생성한 후 전달된 payhash 와 비교 검증을 수행하시기 바랍니다.

자동결제

자동결제는 1회 결제 이후 가맹점에서 원하는 시점에 결제 요청 및 처리 되는 방식입니다.


1.자동결제 등록 요청

자동결제는 결제요청 API (v1.0/payments/request)로 요청할 수 있고 autopay_flag 파라메터로
자동결제 요청 여부를 설정합니다.

2.자동결제 빌키(billkey) 발급

자동결제 승인 용도의 빌키(billkey)가 발급됩니다.

3.자동결제 승인 요청

가맹점에서 자동결제 승인이 필요한 시점에 빌키(billkey)로 자동결제 API (v1.0/payments/autopay)를
통해 승인 요청을 할 수 있습니다.


테스트 가맹점 정보

자동결제 테스트는 아래의 가맹점 아이디 및 API Key로 테스트 가능합니다

Parameter Value
가맹점 아이디 auto_test
API Key (PAYMENT) NDBBREM2RjhEMENBQ0ZGODZDNkEyNEQxQUIxRTY5QUE=
API Key (SEARCH) QjBCMjZBNUNBMEMzRDVDNzY2NkQ2OTU3QzFEQkM2QkY=


[결제 금액 없이 요청]

결제 없이 자동결제 등록을 원할 경우 amount에 ‘0원’으로 결제 요청을 할 수 있습니다.

자동결제 빌키까지만 발급되고, 빌키를 이용해 자동결제 승인 요청을 할 수 있습니다.

실결제가 발생하지 않아 callback_url로 결제 데이터를 전송하지 않습니다.

당사의 내부 설정 후 연동 가능하므로 영업 담당자와 별도의 상의가 필요합니다


테스트 가맹점 정보

결제 금액 없이 요청 테스트는 아래의 가맹점 아이디 및 API Key로 테스트 가능합니다.

Parameter Value
가맹점 아이디 auto_test1
API Key (PAYMENT) NUMzRDJFQzVERkRBNTQzQjY1MkUzMTQ3NThFREU2Mzg=
API Key (SEARCH) QUI4MUEyOEYxQTZFMTAxQjE4NjY3M0I5MjBDMzk1OEM=

자동결제 승인

자동결제 요청 시 전달받은 빌키(billkey)를 설정하여 2회차 이후 부터 승인 요청을 할 수 있습니다.

[휴대폰 자동결제 승인 정책]

1.매월 동일한 금액 및 일자에 결제 요청이 발생해야 정상적으로 결제가 처리됩니다.

2.첫 결제 후 1개월(약 30일) 이후에 재결제 요청이 가능합니다.

3.전월에 결제 내역이 없다면 자동결제를 신청 할 수 없습니다.

요청

POST /v1.0/payments/autopay HTTP/1.1
Host: testpgapi.payletter.com
Authorization: PLKEY MTFBNTAzNTEwNDAxQUIyMjlCQzgwNTg1MkU4MkZENDA=
Content-Type: application/json

{
    "pgcode" : "mobile",
    "client_id":"pay_test",
    "service_name":"페이레터",    
    "user_id":"test_user_id",
    "user_name":"테스터",    
    "order_no":"1234567890",
    "amount":1000,
    "taxfree_amount": 100,
    "tax_amount": 20,
    "product_name":"테스트상품",    
    "billkey":"tbpay_test201801012359590002",
    "ip_addr":"127.0.0.1"
}

Key Type

PAYMENT

HTTP Request

POST v1.0/payments/autopay

Request Parameters

Parameter Default Type Size Description
pgcode 필수 string 20 결제수단 코드(첨부7.1)
client_id 필수 string 20 가맹점 아이디
service_name string 20 결제 서비스명
user_id 필수 string 50 가맹점 결제자(회원) 아이디(email, 영문 및 숫자 가능)
user_name string 20 가맹점 결제자(회원) 이름
order_no string 50 가맹점 주문번호
amount 필수 number 결제 금액
taxfree_amount number 비과세 금액
tax_amount number 부가세 금액(세팅하지 않는 경우 (결제금액 - 비과세 금액)/11 : 소수점 이하 반올림으로 자동 계산)
product_name 필수 string 100 결제 상품(컨텐츠)명
(<, > ,캐리지 리턴(\n) 등의 제어문자 사용불가)
billkey 필수 string 40 자동결제 재결제용 키(자동결제 첫 회차 응답 파라메터)
ip_addr 필수 string 30 요청 아이피
disposable_cup_deposit number 일회용 컵 보증금(*특정 결제 수단 사용 가능, 부분 취소 불가)
*특정 결제 수단 : 신용카드, 카카오페이

Response Parameters

성공시

HTTP 1.1 200 OK
{
    "tid" :"tpay_test201801012359590003",
    "cid":"123456",
    "amount":1000,
    "billkey":"tbpay_test201801012359590002",
    "transaction_date":"2018-01-01 23:59:59"
}

실패시

HTTP 1.1 401 Unauthorized
{
    "code": 998,
    "message": "Authentication token is missing or incorrect"
}

성공시

Parameter Type Description
tid string 결제 고유 번호
cid string 승인번호
amount number 결제 금액
billkey string 자동결제 재결제용 키
transaction_date string 거래 일시(yyyy-MM-dd hh:mm:ss)

실패시

Parameter Type Description
code number 에러 코드
message string 에러 메시지

결제 취소

요청

POST /v1.0/payments/cancel HTTP/1.1
Host: testpgapi.payletter.com
Authorization: PLKEY MTFBNTAzNTEwNDAxQUIyMjlCQzgwNTg1MkU4MkZENDA=
Content-Type: application/json

{
    "pgcode" : "mobile",
    "client_id":"pay_test",
    "user_id":"test_user_id",
    "tid":"tpay_test2018010123595900001",   
    "ip_addr":"127.0.0.1"
}

Key Type

PAYMENT

HTTP Request

POST v1.0/payments/cancel

Request Parameters

Parameter Default Type Size Description
pgcode string 20 결제수단 코드 첨부 참조
client_id 필수 string 20 가맹점 아이디
user_id 필수 string 50 가맹점 결제자(회원) 아이디(email, 영문 및 숫자 가능)
tid 필수 string 40 결제 고유 번호
ip_addr 필수 string 30 요청 아이피

Response Parameters

성공시

HTTP 1.1 200 OK
{
    "tid" :"tpay_test201801012359590003",
    "cid":"123456",
    "amount":1000,
    "cancel_date":"2018-01-01 23:59:59"
}


실패시

HTTP 1.1 401 Unauthorized
{
    "code": 998,
    "message": "Authentication token is missing or incorrect"
}

성공시

Parameter Type Description
tid string 결제 고유 번호
cid string 승인번호
amount number 취소 금액
cancel_date string 취소일시(YYYY-MM-DD HH:MM:SS)

실패시

Parameter Type Description
code number 에러 코드
message string 에러 메시지

부분 취소

일부 결제수단만 부분 취소가 가능합니다.

부분 취소가 가능한 결제수단 및 기능 사용 관련 문의는 영업 담당자에게 연락해 주십시오.

요청

POST /v1.0/payments/cancel/partial HTTP/1.1
Host: testpgapi.payletter.com
Authorization: PLKEY MTFBNTAzNTEwNDAxQUIyMjlCQzgwNTg1MkU4MkZENDA=
Content-Type: application/json

{
    "pgcode" : "mobile",
    "client_id":"pay_test",
    "user_id":"test_user_id",
    "tid":"tpay_test2018010123595900001",   
    "amount" : 1000,
    "taxfree_amount": 100,
    "tax_amount": 20,
    "ip_addr":"127.0.0.1"
}

Key Type

PAYMENT

HTTP Request

POST v1.0/payments/cancel/partial

Request Parameters

Parameter Default Type Size Description
pgcode 필수 string 20 결제수단 코드 첨부 참조
client_id 필수 string 20 가맹점 아이디
user_id 필수 string 50 가맹점 결제자(회원) 아이디(email, 영문 및 숫자 가능)
tid 필수 string 40 결제 고유 번호
amount 필수 number 부분 취소 금액
taxfree_amount number 비과세 금액
tax_amount number 부가세 금액(세팅하지 않는 경우 (결제금액 - 비과세 금액)/11 : 소수점이하 반올림으로 자동 계산)
ip_addr 필수 string 30 요청 아이피

Response Parameters

성공시

HTTP 1.1 200 OK
{
    "tid" :"tpay_test201801012359590003",
    "cid":"123456",
    "amount":1000,
    "cancel_date":"2018-01-01 23:59:59"
}


실패시

HTTP 1.1 401 Unauthorized
{
    "code": 998,
    "message": "Authentication token is missing or incorrect"
}

성공시

Parameter Type Description
tid string 결제 고유 번호
cid string 승인번호
amount number 취소 금액
cancel_date string 취소 일시(yyyy-MM-dd hh:mm:ss)

실패시

Parameter Type Description
code number 에러 코드
message string 에러 메시지

결제 내역 조회

요청

GET /v1.0/payments/transaction/list?client_id=pay_test&date=20180918&date_type=transaction HTTP/1.1 
Host: testpgapi.payletter.com 
Authorization: PLKEY MUI3MjM0RUExQTgyRDA1ODZGRDUyOEM4OTY2QTVCN0Y=
            
		

Key Type

SEARCH

HTTP Request

GET v1.0/payments/transaction/list

Request Parameters

Parameter Default Type Size Description
client_id 필수 string 20 가맹점 아이디
date 필수 string 8 조회 일자
date_type 필수 string 20 transaction : 결제일 기준, settle : 결제/취소일 기준
pgcode string 20 사용 결제 수단 코드

date_type : 거래상태 조회 기준

transaction : 결제일 기준

결제일 기준으로 검색된 거래 건으로 현재기준 정상 또는 취소 내역 추출 (예: 취소된 건은 취소건 1건으로 추출됨)

settle : 결제/취소일 기준

결제일 기준의 승인내역과, 취소일 기준의 취소 내역 추출 (예: 취소된 건은 결제일의 승인건 1건, 취소일의 취소건 1건으로 추출됨)

Response Parameters

성공시

HTTP 1.1 200 OK
{
    "total_count": 2,
    "list": [
        {
            "pgcode": "oncash",
            "user_id": "test_user_id",
            "user_name": "테스터",
            "tid": "tpay_test-201809142506687",
            "cid": "2506686",
            "amount": 1000,
            "taxfree_amount": 100,
            "tax_amount": 20,
            "order_no": "1234567890",
            "product_name": "테스트상품",
            "status_code": 1,
            "transaction_date": "2018-09-14 17:25:36",
            "cancel_date": "2018-09-18 09:52:29"
        },
        {
            "pgcode": "mobile",
            "user_id": "test_user_id",
            "user_name": "테스터",
            "tid": "tpay_test-201809182509659",
            "cid": "20180918095312998861",
            "amount": 100,
            "taxfree_amount": 100,
            "tax_amount": 20,
            "order_no": "1234567890",
            "product_name": "테스트상품",
            "status_code": 2,
            "transaction_date": "2018-09-18 09:53:25",
            "cancel_date": "2018-09-18 09:54:01"
        }
    ]
}

실패시

HTTP 1.1 401 Unauthorized
{
    "code": 998,
    "message": "Authentication token is missing or incorrect"
}

성공시

Parameter Type Description
total_count number 전체 조회건수
list JSON Array
pgcode string 사용 결제 수단 코드
user_id string 가맹점의 결제자 아이디
user_name string 가맹점의 결제자 명
tid string 결제고유번호
cid string 승인 번호
amount number 결제금액 (취소 상태인 경우 취소 금액)
taxfree_amount number 비과세 금액
tax_amount number 부가세 금액(세팅하지 않는 경우 (결제금액 - 비과세 금액)/11 : 소수점이하 반올림으로 자동 계산)
order_no string 가맹점 주문번호
product_name string 상품(컨텐츠)명
status_code number 상태(0:승인, 1:전체취소, 2:부분 취소)
transaction_date string 결제 일시
cancel_date string 취소 일시

실패시

Parameter Type Description
code number 에러 코드
message string 에러 메시지

현금영수증 발급

요청

POST /v1.0/cashreceipt/issue/tpay_test-201904097449610 HTTP/1.1
Host: testpgapi.payletter.com
Authorization: PLKEY MTFBNTAzNTEwNDAxQUIyMjlCQzgwNTg1MkU4MkZENDA=
Content-Type: application/json

{
    "client_id":"pay_test",
    "type":"0",    
    "tax_flag":"N",    
    "return_url":"https://testpg.payletter.com/result"
}

Key Type

PAYMENT

HTTP Request

POST v1.0/cashreceipt/issue/{tid}

Request Parameters

Parameter Default Type Size Description
client_id 필수 string 20 가맹점 아이디
type string 1 용도 (0:사용자가 선택, 1:소득공제용, 2:지출증빙용)
tax_flag string 1 부가세 포함 여부 (N:포함, Y:미포함)
return_url 필수 string 256 발급 완료 후 연결할 웹 페이지 URL

Response Parameters

성공시

HTTP 1.1 200 OK
{
    "receipt_url" :"https://testpg.payletter.com/PGSVC/Receipt/ReceiptForm.asp?id=tpay_test-201904097449610&type=1&taxflag=N&returnurl=https://testpg.payletter.com/result&token=155494822989700006"
}

실패시

HTTP 1.1 401 Unauthorized
{
    "code": 998,
    "message": "Authentication token is missing or incorrect"
}

성공시

Parameter Type Description
receipt_url string 현금영수증 발급 페이지 URL

실패시

Parameter Type Description
code number 에러 코드
message string 에러 메시지

거래 상태 조회

요청

POST /v1.0/payments/status HTTP/1.1
Host: testpgapi.payletter.com
Authorization: PLKEY MTFBNTAzNTEwNDAxQUIyMjlCQzgwNTg1MkU4MkZENDA=
Content-Type: application/json

{
    "client_id":"pay_test",
    "order_no":"pay_test2023118164578"
}

Key Type

PAYMENT

HTTP Request

POST v1.0/payments/status

Request Parameters

Parameter Default Type Size Description
client_id 필수 string 20 가맹점 아이디
order_no 필수 string 40 가맹점 주문번호

Response Parameters

성공시

HTTP 1.1 200 OK
{
    "code" :0,
    "message":"ok",
    "client_id":"pay_test",
    "order_no":"pay_test2023118164578",
    "token":"170202154314200189",   
    "tid":"tpay_test-202312082315563",
    "status_code":5
}


실패시

HTTP 1.1 401 Unauthorized
{
    "code": 998,
    "message": "Authentication token is missing or incorrect"
}

성공시

Parameter Type Description
code string 결과
message string 메시지
client_id string 가맹점 아이디
order_no string 가맹점 주문번호
token string 결제 토큰
tid string 결제고유번호
status_code number 상태 코드 (1:생성, 2:진입, 3:인증, 4:실패, 5:완료)

실패시

Parameter Type Description
code number 에러 코드
message string 에러 메시지

거래 내역 확인서

요청

GET /v1.0/receipt/info/tsktest1-202201039368273/?client_id=sktest1 HTTP/1.1
Host: testpgapi.payletter.com
Authorization: PLKEY NDhBNDJGNUY0QzI5RjY5NjAwMDdDREI0Q0Q4RDVGOTY=

Key Type

SEARCH

HTTP Request

GET v1.0/receipt/info/{tid}

Request Parameters

Parameter Default Type Size Description
client_id 필수 string 20 가맹점 아이디

Response Parameters

성공시

HTTP 1.1 200 OK
{
    "receipt_url" :"https://testpg.payletter.com/PGSVC/AllTheGate/Receipt_All.asp?id=72720c6d230e662b|001|4|3230323230313230313435393434343037383664613733393939b3a96f05b2f37aea1b64c823d9cc57767510d8e0e351a4c1635cefc354af7e2a0418a9ffce0c8ecac4b7c28ceefb3a905d82ee1dcab6b3d4bc18393cb5547ba9eec2b92fe4"
}

실패시

HTTP 1.1 401 Unauthorized
{
    "code": 998,
    "message": "Authentication token is missing or incorrect"
}

성공시

Parameter Type Description
receipt_url string 거래 내역 확인서 URL

실패시

Parameter Type Description
code number 에러 코드
message string 에러 메시지

오류코드

API 요청에 대한 성공/실패 여부는 HTTP StatusCode로 확인합니다.

StatusCode 200 OK 인 경우에만 요청 처리 성공이며, 성공이 아닌 경우에는 아래 StatusCode를 참고하시기 바랍니다.

오류코드 표

HTTP 응답 오류코드 오류메시지 설명
400 997 오류 상세 메세지 유효하지 않은 요청(요청 파라미터 확인 필요)
401 998 Authentication token is missing or incorrect. 인증 오류
403 993 Yon do not have authorization. 인증 오류
405 995 요청된 메소드는 권한이 없습니다. POST / GET 등 메소드 오류
406 2000 ~ 5000 오류 상세 메시지 비즈니스 로직 처리중 오류
500 999 Internal server error System 오류

첨부

PGCode 표

PGCode 비고
creditcard 신용카드
banktransfer 인터넷뱅킹(금융결제원)
virtualaccount 가상계좌
mobile 휴대폰
voucher 문화상품권
book 도서문화상품권
culture 컬쳐랜드상품권
smartculture 스마트문상
happymoney 해피머니상품권
mobilepop 모바일팝
teencash 틴캐시
tmoney 교통카드결제
cvs 편의점캐시
eggmoney 에그머니
oncash 온캐시
phonebill 폰빌
cashbee 이즐
kakaopay 카카오페이
payco 페이코
checkpay 체크페이
toss 토스
ssgpay SSG페이
naverpay 네이버페이
samsungpay 삼성페이
smilepay 스마일페이
applepay 애플페이

앱 스키마 목록

언어 샘플소스
안드로이드 다운로드
iOS 다운로드