페이레터 결제 소개
서비스 안내
몇 번을 고민해도, 당신의 파트너는 페이레터입니다!
페이레터는 온라인 상점의 재화/서비스 판매를 위한 전자결제 대행 서비스를 제공합니다.
국내외 보안인증 획득을 통한 안전성 검증, 다양한 결제수단,
안정적인 거래 처리 능력을 바탕으로 편리한 결제 서비스를 제공하기 위해 노력하고 있습니다.
1. 전세계 25개국, 260개 가맹점에서 페이레터 서비스 이용 중 |
2. 글로벌 신용카드 데이터 보안 인증 PCI-DSS, 국내 정보 보안표준 ISMS 인증 획득으로 안전한 결제 환경 제공 |
3. 국내 1위 E-Commerce, 음원 서비스, VOD 서비스 등의 거래를 통해 검증된 거래 처리 능력 |
4. 튼튼한 재무 구조로 안정적 서비스 제공 및 대금 정산 가능 |
5. 경쟁사 대비 월등한 콜센터 고객 응대율(98.7%) |
결제수단 및 부가서비스
금융 | 간편결제 | 통신 | 상품권 | 선불카드 | 부가서비스 |
---|---|---|---|---|---|
신용카드 인터넷뱅킹 가상계좌 |
토스(TOSS) 카카오페이 페이코 SSG페이 계좌 간편결제(체크페이) L.pay 네이버페이 삼성페이 차이 스마일페이 |
휴대폰 결제 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원 |
L.pay | X | O | O | D+180 | 100원 |
네이버페이 | X | O | O | D+180 | 100원 |
삼성페이 | X | O | O | D+180 | 100원 |
차이 | O | O | O | 가맹점 정책에 따름 | 100원 |
계좌 간편결제(체크페이) | O | O | X | D+30 | 1000원 |
휴대폰 | O | O | O | 결제 당월 | 10원 |
KT 집전화 결제 | X | O | X | 결제 당월 | 10원 |
문화상품권 | 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 | O | D+24 | 10원 |
교통카드결제(캐시비) | X | O | X | 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. SSG페이 회원으로 등록되지 않은 휴대폰번호의 경우 결제 페이지에서 호출 시 오류가 발생합니다. |
5. SSG페이,삼성페이 결제 요청 시 파라메터 중 "service_name"이 필수값입니다. |
6. 차이는 PC에서의 자동결제는 지원하지 않아 모바일 환경에서만 자동결제가 가능합니다. |
테스트 결제
1. 신용카드 테스트의 경우 밴(신용카드)사 통신은 하지 않습니다. |
2. 카카오페이, 휴대폰결제, SSG페이의 경우 테스트 환경에서 실제로 결제가 발생합니다. (결제 당일 밤에 자동으로 결제 취소되오니 참고하시기 바랍니다.) |
3. 가상계좌 테스트는 채번단계까지만 가능합니다. 실제 입금 시, 취소가 불가한 점 참고하시기 바랍니다. (실제 입금테스트가 필요하신 경우 별도 문의하시기 바랍니다.) |
4. KT 집전화 결제의 경우, 테스트 환경에서는 전화가 오지 않습니다. |
5. 인터넷뱅킹/상품권/선불카드의 테스트가 필요하신 경우 별도 문의하시기 바랍니다. |
6. 테스트 환경의 경우 신용카드 자동결제 휴대폰 인증 시 인증번호가 문자로 발송되지 않습니다. (임의의 번호 입력 후 진행 가능) |
7. 차이 테스트 결제는 테스트 어플과 계좌를 이용해야 하며 상세 정보는 아래 URL에서 참고하시기 바랍니다. (https://appdistribution.firebase.google.com/pub/i/7cbb497fd568d25e) |
인앱 결제 연동
인앱 결제 연동 시 스키마 추가가 필요합니다. 첨부 참조
1. 안드로이드 |
안드로이드 결제 시 안심클릭, 앱카드, ISP를 통한 결제 중 백신, 앱가드 앱 등을 안드로이드 11(API 30) 패키지로 개발 및 업데이트 하는 경우 아래 두가지 방안 중 |
1) <queries> 요소에 패키지 정의 - AndroidManifest.xml 파일 수정 - 매니페스트 파일의 <queries> 요소에 패키지를 정의하면 패키지의 가시성이 확보됩니다. - 카드사 및 백신의 패키지명은 첨부 파일을 참고하시길 바랍니다. 2) WebViewClient shouldOverrideUrlLoading() 예외처리 로직 추가 - 재정의한 shouldOverrideUrlLoading() 메소드 로직 수정 필요 - 앱 설치여부 확인을 위해 startActivity() 호출 전에 패키지 정보를 조회하는 경우, - startActivity() 호출 시 ActivityNotFoundException(Message : No Activity found to |
2. iOS |
REST API를 통해 결제 페이지의 URL을 받으신 후 결제창을 WEBVIEW 방식을 통해 여는 방법을 사용하시면 됩니다. App-Schema 이슈발생 시 적용 할 수 있는 방법은 아래 두 가지 중 한가지로 적용하실 수 있습니다. 1)info.plist 파일에 "LSApplicationQueriesSchemes" 배열내 스키마 목록 추가 2)Xcode 에서 LSApplicationWueriesSchemes >item 항목에 결제 수단을 추가 |
기술지원
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/request | 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/receipt/info/{tid} | GET | SEARCH | 거래내역확인서 |
결제 프로세스
API 샘플소스
페이레터 API 샘플 소스는 ASP, ASP.NET, JSP, PHP 언어를 제공하고 있습니다.
언어 | 샘플소스 |
---|---|
ASP | 다운로드 |
ASP.NET | 다운로드 |
JSP | 다운로드 |
PHP | 다운로드 |
결제 요청
요청
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 | 10 | 가맹점 아이디 |
service_name | string | 20 | 결제 서비스명 (삼성페이, SSG페이는 필수) |
|
user_id | 필수 | string | 50 | 가맹점 결제자(회원) 아이디(email, 영문 및 숫자 가능) |
user_name | string | 20 | 가맹점 결제자(회원) 이름 | |
order_no | string | 40 | 가맹점 주문번호 | |
amount | 필수 | number | 결제금액 | |
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로 이동하지 않음 (네이버페이, 삼성페이, L.Pay 등) |
|
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페이, 교통카드결제 (티머니/캐시비), 휴대폰 |
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,
"cash_receipt":
{
"code":"결과",
"message":"메시지",
"cid":"현금영수증 승인번호",
"deal_no":"현금영수증 발급시 주문번호",
"issue_type":"현금영수증 발행 구분",
"payer_sid":"신분확인 번호",
"type":"거래자구분"
}
}
결제가 성공한 경우에만 결제 결과가 json형태로 제공됩니다.
*Callback URL로 전달되는 현금영수증 데이터의 경우 하기와 같은 형태로 제공 됩니다.
Parameter | Type | 설명 |
---|---|---|
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 와 비교 검증을 수행하시기 바랍니다.
최초 자동결제 요청
자동결제를 위한 첫 결제 API는 결제요청(v1.0/payments/request)로 처리하셔야 하며 결제 성공 시 billkey 값이 리턴됩니다.
결제요청(v1.0/payments/request)에서 autopay_flag 파라메터로 자동 결제 여부를 설정하실 수 있습니다.
자동결제는 인증+결제로 1회차 결제가 바로 처리되는 방식입니다.
상세한 결제요청 API 는 상단의 결제요청(v1.0/payments/request)을 참고 바랍니다.
자동결제 재결제 요청
재결제 요청은 2회차 이후 결제부터 해당됩니다.
최초 자동결제 요청 시 리턴받은 billkey를 세팅하여 재결제 요청 처리를 하실 수 있습니다.
*휴대폰 재결제 유의사항
매월 동일한 금액으로 동일한 날짜에 결제가 이뤄지는 것이 원칙이며, 금액이 상이하거나 자동 결제 기간이 달라질 경우 동일한 billkey 로는 결제가 불가하여 자동 결제가 실패하게 됩니다.
또한, 통신사 정책상 첫 결제 후 1개월(약 30일) 이후에 재결제 요청이 가능합니다.
즉, 전월에 결제 내역이 없다면 자동결제를 신청 할 수 없습니다.
요청
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 | 10 | 가맹점 아이디 |
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 | 에러 메시지 |
자동결제 인증만 요청
자동결제 인증만 요청 방식은 사용자의 카드정보 인증을 통해 자동결제 billkey만 생성하는 방식입니다.
이후, 자동결제가 필요한 시점에 billkey로 재결제를 처리하는 방식으로 진행할 수 있습니다.
인증만 방식은 당사의 내부 세팅을 통해 연동 가능하므로 영업 담당자와 별도의 상의가 필요합니다.
[프로세스 진행 순서]
1."결제 요청 API"를 호출하여 인증 페이지 URL을 리턴 받은 후 PC/Mobile 환경에 따른 URL을 호출합니다.
2."결제 요청 API"의 URL을 호출하여 인증처리를 완료합니다.(완료 후 리턴되는 파라메터에 대한 정의는 "인증 결과" 참고)
3. 결제가 필요한 시점에 "결제 요청 API" Response로 리턴된 billkey를 사용하여 "자동 결제 API"를 호출합니다.
4. 인증만 방식은 실결제가 발생하지 않아 callback_url로 결제 데이터를 전송하지 않습니다.
요청
POST /v1.0/payments/request HTTP/1.1
Host: testpgapi.payletter.com
Authorization: PLKEY MTFBNTAzNTEwNDAxQUIyMjlCQzgwNTg1MkU4MkZENDA=
Content-Type: application/json
{
"pgcode" : "creditcard",
"user_id":"test_user_id",
"user_name":"테스터",
"service_name":"페이레터",
"client_id":"pay_test",
"order_no":"1234567890",
"amount":0,
"product_name":"테스트상품",
"email_flag":"N",
"autopay_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 | 결제수단 코드 (신용카드:creditcard) |
client_id | 필수 | string | 10 | 가맹점 아이디 |
service_name | string | 20 | 결제 서비스명 | |
user_id | 필수 | string | 50 | 가맹점 결제자(회원) 아이디(email, 영문 및 숫자 가능) |
user_name | string | 20 | 가맹점 결제자(회원) 이름 | |
order_no | string | 40 | 가맹점 주문번호 | |
amount | 필수 | number | 결제금액 | |
product_name | 필수 | string | 100 | 결제 상품(컨텐츠)명 (<, > ,캐리지 리턴(\n) 등의 제어문자 사용불가) |
email_flag | string | 1 | 결제내역 메일 수신 여부 (Y:사용, N:미사용) | |
email_addr | string | 100 | 결제내역 메일 수신 주소 | |
autopay_flag | string | 1 | 자동 결제 여부 *자동결제 인증만 방식 사용 시 (Y:사용)으로 적용 필수 |
|
custom_parameter | string | 1024 | 가맹점이 전송하는 임의의 값 ex) 고객정보, 주문정보, 기타 필요한 정보를 세팅하면 결제 결과로 다시 리턴 |
|
return_url | 필수 | string | 256 | 결제 완료 후 연결할 웹 페이지 URL |
callback_url | 필수 | string | 256 | 결제 성공 결과를 수신할 callback URL (인증만 방식에서 사용되는 파라메터는 아니오나, 결제요청 API 필수파라메터로 임의의 데이터 셋팅 부탁 드립니다.) |
cancel_url | string | 256 | 취소 버튼 클릭시 연결할 웹 페이지 URL | |
inapp_flag | string | 1 | In-app 사용 여부 (Y:사용, N:미사용) |
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 | 에러 메시지 |
인증요청 결과
Return URL
결제 결과는 Request의 POST 파라메터로 전송됩니다.
성공시
Parameter | Type | Description |
---|---|---|
code | string | 결과 |
message | string | 메시지 |
user_id | string | 가맹점 결제자(회원) 아이디(email, 영문 및 숫자 가능) |
user_name | string | 가맹점 결제자(회원) 이름 |
order_no | string | 가맹점의 주문 번호 |
service_name | string | 결제 서비스명 |
product_name | string | 결제 상품(컨텐츠)명 |
custom_parameter | string | 주문요청시 가맹점이 전송한 값 |
pay_info | string | 카드명 |
pgcode | string | 결제수단 코드 (신용카드:creditcard) |
billkey | string | 자동결제 재결제용 키 |
card_info | string | 카드 번호 (중간 4자리 masking 처리 ) |
payhash | string | 파라메터 검증을 위한 sha256 hash 값 sha256(userid+billkey+API 결제용 키) |
실패시
Parameter | Type | Description |
---|---|---|
code | number | 에러 코드 |
message | string | 에러 메시지 |
user_id | string | 가맹점 결제자(회원) 아이디(email, 영문 및 숫자 가능) |
order_no | string | 가맹점의 주문 번호 |
service_name | string | 결제 서비스명 |
product_name | string | 결제 상품(컨텐츠)명 |
custom_parameter | 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",
"amount" : 1000,
"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 | 10 | 가맹점 아이디 |
user_id | 필수 | string | 50 | 가맹점 결제자(회원) 아이디(email, 영문 및 숫자 가능) |
tid | 필수 | string | 40 | 결제 고유 번호 |
amount | 필수 | number | 취소 금액 | |
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 | 10 | 가맹점 아이디 |
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 | 10 | 가맹점 아이디 |
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 | 10 | 가맹점 아이디 |
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 | 에러 메시지 |
거래내역확인서
요청
GET /v1.0/receipt/info/tsktest1-202201039368273/?client_id=sktest1&amount=50001&transaction_date=20220103 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 | 10 | 가맹점 아이디 |
amount | 필수 | number | 결제금액 | |
transaction_date | 필수 | string | 8 | 거래일자(YYYYMMDD) |
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 응답 | 오류코드 | 오류메시지 | 설명 |
---|---|---|---|
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 | 휴대폰 |
book | 도서문화상품권 |
culture | 문화상품권 |
smartculture | 스마트문상 |
happymoney | 해피머니상품권 |
mobilepop | 모바일팝 |
teencash | 틴캐시 |
tmoney | 교통카드결제 |
cvs | 편의점캐시 |
eggmoney | 에그머니 |
oncash | 온캐시 |
phonebill | 폰빌 |
cashbee | 캐시비 |
kakaopay | 카카오페이 |
payco | 페이코 |
checkpay | 체크페이 |
toss | 토스 |
ssgpay | SSG페이 |
lpay | L.Pay |
naverpay | 네이버페이 |
samsungpay | 삼성페이 |
chai | 차이 |
smilepay | 스마일페이 |
앱 스키마 목록
언어 | 샘플소스 |
---|---|
안드로이드 | 다운로드 |
iOS | 다운로드 |