페이레터 해외결제 소개
서비스 안내
몇 번을 고민해도, 당신의 파트너는 페이레터입니다!
페이레터는 온라인 상점의 재화/서비스 판매를 위한 전자결제 대행 서비스를 제공합니다.
국내외 보안인증 획득을 통한 안전성 검증, 다양한 결제수단,
안정적인 거래 처리 능력을 바탕으로 편리한 결제 서비스를 제공하기 위해 노력하고 있습니다.
1. 동남아, 미주, 유럽 등 글로벌 전반을 커버할 수 있는 다수 결제수단 보유 |
2. 글로벌 신용카드 데이터 보안 인증 PCI-DSS, 국내 정보 보안표준 ISMS 인증 획득으로 안전한 결제 환경 제공 |
3. 국내 1위 E-Commerce, 음원 서비스, VOD 서비스 등의 거래를 통해 검증된 거래 처리 능력 |
4. 튼튼한 재무 구조로 안정적 서비스 제공 및 대금 정산 가능 |
5. 고객 및 가맹점에 대한 신속한 응대 |
결제수단 및 부가서비스
신용/체크카드 | 전자지갑 | 선불카드 | 편의점 결제 | 핸드폰 결제 |
---|---|---|---|---|
Visa Master JCB Amex UnionPay |
PayPal Alipay WechatPay Razer Gold Wallet Line Pay PayPay |
Paysafecard Cherry Credits Webmoney Bitcash Netcash |
7eleven Alfamart Indomaret Konbini |
Maxis Etisalat Zain Ooredoo Carrier Billing for Japan |
*결제수단에 대한 추가 문의 사항은 별도 문의 바랍니다
가입절차
신규 가입문의 : globalpg@payletter.com |
---|
1. 온라인 가입 가입하기 |
2. 서비스 이용 관련 상담 진행 |
3. 계약서 및 구비서류 제출 |
4. 결제수단별 심사 진행 - 신용카드 : 약 2주 소요 - 그 외 결제수단 : 약 1개월 소요 |
5. 가입 완료 |
구비서류
구분 | 법인사업자 | 개인사업자 |
---|---|---|
계약서류 | 1. 페이레터 통합결제서비스 이용계약서 2부 | |
구비서류 | 1. 사업자등록증 사본 1부 2. 법인 인감증명서 원본 1부 (3개월 이내 발급분) 3. 사용인감계 1부(계약서에 사용인감 날인시) 4. 법인 등기부등본 원본 1부 5. 입금계좌 사본 1부(법인명의) 사용인감 날인 시) 6. 계약서 [별첨5] 서류 내 해당 제출 서류 |
1. 사업자등록증 사본 1부 2. 대표자 인감증명서 원본 1부 (3개월 이내 발급분) 3. 대표자 신분증 사본 1부 4. 입금계좌 사본 1부(대표자 또는 사업자명의) |
연동 전 확인사항
가맹점에서 제공 해야 하는 정보 | 비고 |
---|---|
Notification URL | backend로 수신할 결제 관련 통보 URL 테스트 환경에서는 Notification URL 호출 시 80, 443만 허용하고 있어 이 외 포트 이용 시 방화벽 정책 등록이 필요합니다. 등록 가능한 공용 IP 및 Port 정보를 아래 기술지원 메일로 요청하시길 바랍니다. gpoqdev@payletter.com |
IP | 접근 권한이 Private인 API를 연동할 경우, 가맹점의 요청 IP |
페이레터에서 제공 해야 하는 정보 | 비고 |
---|---|
StoreID | 페이레터 계약 시 제공 되는 가맹점 ID |
API Key | 페이레터 계약 시 제공 되는 API Key |
API HTTPS 프로토콜
페이레터 API HTTPS는 TLS 1.2 이상 지원합니다.
방화벽
결제완료 Notification을 수신하기 위하여 inbound IP를 추가해 주시기 바랍니다.
테스트 : 121.254.205.166
라이브 : 211.115.72.37, 211.115.72.38, 211.115.117.11(예비)
API Authorization
가맹점 계약이 완료되면 API Key가 발급됩니다.
HttpRequestHeader Authorization 항목에 다음과 같이 API Key를 보내 주시기 바랍니다.
Authorization: GPLKEY {가맹점_apikey}
API Endpoint URL
환경 | 주소 |
---|---|
테스트 | https://dev-api.payletter.com |
라이브 | https://api.payletter.com |
테스트 환경 가맹점 정보
가입 전에 테스트 환경에서 미리 구성된 StoreID와 API Key를 통해 연동 테스트가 가능합니다.
테스트 결제는 PLCreditcard(비인증), PayPalExpressCheckout만 가능합니다.
StoreID | PL_Merchant |
API KEY | PL_Merchant |
[테스트 결제]
테스트 결제는 당사에서 제공하는 테스트 환경 내에서 진행하실 수 있습니다. 진행 간에 아래 내용 참고 바랍니다.
1. 신용카드 결제는 기본적으로 해외에서 실제 발행된 카드로만 결제가 가능합니다. 당사에서 테스트 카드는 제공하지 않습니다.
2. 신용카드(PLCreditcardMpi), 유니온페이 결제 테스트가 필요할 경우 당사에 별도로 문의 주시기 바랍니다.
3. 신용카드(PLCreditcard)는 예외적으로 임의의 숫자 입력으로 테스트 가능합니다. 아래 방법으로 진행해 주시기 바랍니다.
1) 카드번호 입력
- Visa: 4로 시작하는 임의의 숫자
- Master: 51로 시작하는 임의의 숫자
- JCB: 35로 시작하는 임의의 숫자
- Amex: 34로 시작하는 임의의 숫자
2) 유효기간, CVV 넘버 임의 입력
4. 페이팔은 가맹점에서 직접 샌드박스 서버의 페이팔 계정을 생성하여 테스트가 가능합니다.
결제수단별 옵션
결제수단 | 자동결제 | 결제취소 | 부분취소 | 취소가능기간 |
---|---|---|---|---|
Credit card(VISA, Master, JCB) | O | O | O | D+180 |
Credit card(Amex) | O | O | O | D+180 |
UnionPay | O | O | O | D+730 |
PayPal | O | O | O | D+180 |
WeChatPay (H5/QR) | X | O | O | D+365 |
Alipay | X | O | O | D+365 |
Alipay+ | X | O | O | D+365 |
LoadCentral | X | X | X | 취소불가 |
FPX | X | X | X | 취소불가 |
Maybank2U | X | X | X | 취소불가 |
AIS 12 Call | X | X | X | 취소불가 |
True Money | X | X | X | 취소불가 |
Razer Gold PIN | X | X | X | 취소불가 |
Razer Gold Wallet | X | X | X | 취소불가 |
Gcash | X | X | X | 취소불가 |
7eleven | X | X | X | 취소불가 |
Alfamart | X | X | X | 취소불가 |
Indomaret | X | X | X | 취소불가 |
Bank transfer (Indonesia) | X | X | X | 취소불가 |
Doku wallet | X | X | X | 취소불가 |
Maxis | X | X | X | 취소불가 |
Fawry | X | X | X | 취소불가 |
Etisalat | X | X | X | 취소불가 |
Zain | X | X | X | 취소불가 |
Ooredoo | X | X | X | 취소불가 |
Bank Transfer (Vietnam) | X | O | X | D+150 |
VTCPay | X | O | X | D+180 |
Cherry Credits | X | X | X | 취소불가 |
기술지원
gpoqdev@payletter.com
결제 관련 문의 시에는 연동 환경, 가맹점 아이디, 주문번호, 거래시간, token 등
상세 정보를 보내주시면 보다 빠른 응대가 가능합니다.
해외결제 API
연동 API 목록
접근 권한이 Private인 API는 허용된 IP만 접근 가능하므로 해당 API를 연동할 경우
요청 IP를 가맹점 계약 시 전달해 주시기 바랍니다.
URL | METHOD | ACCESS | DESCRIPTION |
---|---|---|---|
api/payment/request | POST | Public | 결제 요청 |
payment/recurring | POST | Private | 자동 결제 1회차 이후 결제 요청 |
payment/refund | POST | Public | 결제 취소/부분 취소 |
payment/cpdaesalist | POST | Private | 결제 내역 조회 |
settlement/detailslist | POST | Private | 정산 내역 조회 |
paypal/subscription/cancel | POST | Public | PayPal 자동결제(구독형) 해지 |
receipt/info/{paytoken} | GET | Public | 거래 내역 확인서 |
payment/transaction/list | POST | Private | 일별 결제 내역 조회 |
결제 프로세스
API 샘플소스
페이레터 API 샘플 소스는 ASP, ASP.NET, JSP, PHP 언어를 제공하고 있습니다.
언어 | 샘플소스 |
---|---|
ASP | 다운로드 |
ASP.NET | 다운로드 |
JSP | 다운로드 |
PHP | 다운로드 |
결제 요청
요청
POST api/payment/request HTTP/1.1
Host: dev-api.payletter.com
Authorization: GPLKEY PL_Merchant
Content-Type: application/json
{
"storeid" : "PL_Merchant",
"currency" : "USD",
"storeorderno" : "123456789",
"amount":1.00,
"payerid":"tester",
"payeremail":"tester@test.com",
"returnurl":"https://merchant.test.com/Return.aspx",
"notiurl":"https://merchant.test.com/PaymentNoti.aspx",
"pginfo":"PLCreditCard"
}
접근 권한
Public
HTTP Request
POST api/payment/request
Request json data
구분 | Parameter | Type | Size | M/O | Description |
---|---|---|---|---|---|
공통 | storeid | string | 20 | M | 가맹점 아이디 |
currency | string | 3 | M | 통화 코드 (ISO 4217) Ex) USD, JPY (pinflag = Y 인 경우, 필수 아님) |
|
storeorderno | string | 128 | M | 가맹점 주문 번호 | |
amount | number | M | 결제 금액 (천 단위 기호 제거) (KRW, JPY, VND는 정수, 이외 소수점 둘째 자리) (pinflag = Y 인 경우, 필수 아님) |
||
payerid | string | 50 | M | 가맹점 결제자(회원) 아이디 (이메일, 영문 및 숫자 가능) | |
payeremail | string | 50 | M | 가맹점 결제자(회원) 이메일 | |
returnurl | string | 256 | M | 결제 완료 후 연결할 웹 페이지 URL | |
notiurl | string | 256 | O | 결제 성공 결과를 수신할 Notification URL | |
servicename | string | 100 | O | 가맹점 서비스명 (WechatPay, AlipayPlus, PayPalExpressCheckout & recurringtype=Y 인 경우, 필수) |
|
pginfo | string | 40 | O | 결제 요청 PG 정보 (PGCode 표) (Direct Pay 결제 방식 시 필수) |
|
payinfo | string | 200 | O | 추가 결제정보 | |
pinflag | string | 1 | O | zGold-MOLPoints Direct Top Up인 경우, Y로 설정 | |
recurringtype | string | 1 | O | 자동 결제 신청 여부 (Y: 사용, N: 미사용) | |
custom | string | 2000 | O | 가맹점이 전송하는 임의의 값 ex) 고객정보, 주문 정보, 기타 필요한 정보를 세팅하면 결제 결과로 다시 리턴 (이 값에는 | ' 특수문자 사용불가) |
|
해외카드 인증 |
billaddrcity | string | 64 | O | 카드 청구지 주소 도시 |
billaddrcountry | string | 3 | O | 카드 청구지 주소 국가 (ISO 3166-1 numeric three-digit country code) Ex) 410(한국), 840(미국) |
|
billaddrline1 | string | 50 | O | 카드 청구지 주소 | |
billaddrpostcode | string | 16 | O | 카드 청구지 주소 우편 번호 | |
PayPal 공통 |
paypalisppflag | string | 1 | O | PayPal ISPP 사용 여부 (Y: 사용, N: 미사용) (paypalisppflag=Y인 경우, payerfirstname, payerlastname, payerphone, payercountrycode, payercreatedate 필수 데이터) |
payerfirstname | string | 50 | O | 결제자 이름 | |
payerlastname | string | 50 | O | 결제자 성 | |
payerphone | string | 20 | O | national notation Ex) (042) 1123 4567) |
|
payercreatedate | string | 30 | O | 결제자 가입일 (ISO 8601 date format) Ex) 2023-04-09T19:14:55.277-0:00 |
|
payercountrycode | string | 2 | O | 결제자 국가 코드 (ISO Alpha-2 Country Code) Ex) AU, KR |
|
paypalcnlurlflag | string | 1 | O | 결제 취소 페이지 returnurl 사용 여부( Y : 사용, N : 미사용) (팝업창으로 열리는 경우, 팝업창 닫힘) (페이지 이동 방식인 경우, returnurl 이동) |
|
PayPal 자동결제(구독형) |
intervaltype | string | 1 | O | PayPal 자동결제(구독형) 청구 주기 (1: DAY, 2: WEEK, 3: MONTH, 4: YEAR) |
intervalcnt | string | 3 | O | PayPal 자동결제(구독형) 청구 간격 (DAY: 1~365, WEEK: 1~52, MONTH: 1~12, YEAR: 1) |
|
totalcycles | string | 3 | O | PayPal 자동결제(구독형) 청구 횟수 (2~999, 제한 없음: 0) |
|
PayPal 자동결제(청구형) |
paypalrecurrflag | string | 1 | O | PayPal 자동결제(청구형) 결제 사용 여부 (Y: 사용, N: 미사용) (paypalrecurrflag= "Y" 인 경우 recurringtype = "Y" 필수) |
[PayPal 자동결제]
구분 | Description | 필수 파라미터 | 비고 |
---|---|---|---|
공통 | PayPal 자동결제를 사용하기 위해 recurringtype = "Y" 로 결제 요청 | recurringtype = "Y" | |
PayPal 자동결제 (구독형) |
1. PayPal 청구 정보와 함께 자동결제(구독형) 신청 요청 2. PayPal 자동결제(구독형) 생성이 완료 되면 notifytype = 5(PayPal 자동결제(구독형)생성 완료) 전달 3. PayPal 거래 건 notifytype = 1(결제 완료) 전달 4. 이후 PayPal 측에서 청구 정보에 따라 자동으로 거래 건을 생성하여 notifytype = 1(결제 완료) 전달 |
recurringtype = "Y" intervaltype intervalcnt totalcycles |
|
PayPal 자동결제 (청구형) |
1. PayPal 자동결제(청구형) 요청 2. 유저가 PayPal 측에서 자동결제 동의 진행 3. 동의가 완료되면 POQToken(자동결제 토큰)을 포함한 notifytype = 1 (결제 완료) 전달 4. 이후 POQToken(자동결제 토큰) 이용하여 자동결제 진행 |
recurringtype = "Y" paypalrecurrflag = "Y" |
|
PayPal 자동결제 (청구형) 금액 없이 요청 |
1. PayPal 자동결제(청구형) 요청 (amount와 currency 값은 전달 하지 않음) 2. 유저가 PayPal 측에서 자동결제 동의 진행 3. 동의가 완료되면 POQToken(자동결제 토큰)을 포함한 notifytype = 7 (자동결제 토큰) 전달 (결제는 발생하지 않음) 4. 이후 POQToken(자동결제 토큰) 이용하여 자동결제 진행 |
recurringtype = "Y" paypalrecurrflag = "Y" |
DirectPay 방식만 지원 |
Response json Data
성공시
HTTP 1.1 200 OK
{
"token" : 167702306200001,
"online_url": "https://devgpgclient.payletter.com/hub.aspx?location=online&token=167702306200001",
"mobile_url": "https://devgpgclient.payletter.com/hub.aspx?location=mobile&token=167702306200001"
}
실패시
HTTP 1.1 400 BadRequest
{
"error": {
"code": 997,
"message": "The request is invalid.",
"detail": "[2102]Not exist PG contract information",
"plcode": 997
}
}
성공시
Parameter | Type | Description |
---|---|---|
token | number | 결제 인증 토큰 |
online_url | string | PC 환경 결제 창 호출 URL Mobile 환경만 지원하는 결제수단의 경우, 빈 값으로 전달함(WechatpayH5Payment) |
mobile_url | string | Mobile 환경 결제 창 호출 URL PC 환경만 지원하는 결제수단의 경우, 빈 값으로 전달함(WechatpayQRCodePayment) |
실패시
Parameter | Type | Description |
---|---|---|
error | object | |
└ code | number | 에러 코드 |
└ message | string | 에러 메시지 |
└ detail | string | 에러 상세 메시지 |
└ plcode | number | 기타 에러 코드 |
결제 연동
결제요청 API Response로 리턴된 URL을 사용하여 결제창을 호출합니다.
사용자가 결제를 진행하면 결제요청에서 전달하신 return_url로 결제 결과가 반환됩니다.
결제 완료 처리(재화 지급 등 가맹점의 business logic)는 notiurl
또는 사전에 등록된 가맹점의 notification URL 에서 수행하는 것을 권장합니다
returnurl 과 notiurl에서의 프로세스는 아래 설명을 참고하시기 바랍니다
결과 처리 (returnurl)
결제 결과는 Request의 POST 파라메터로 전송됩니다.
bank transfer, cvs 등 즉시 거래가 이루어 지지 않는 결제수단들은 결제 인증 요청에 대한 성공 유무가 리턴 됩니다.
따라서 returnurl에서는 구매 처리를 하면 안됩니다.
Parameter | Type | 설명 |
---|---|---|
retcode | string | 코드 (0=성공 0<>실패) |
retmsg | string | 메시지 |
storeid | string | 가맹점 아이디 |
storeorderno | string | 가맹점 주문 번호 |
payamt | number | 결제 금액 |
custom | string | 가맹점이 전송하는 임의의 값 |
pginfo | string | 결제된 PG 정보 |
결제 처리 (Notification URL, notiurl)
결제 성공 결과가 아래와 같이 POST로 전달됩니다.
storeid=PL_Merchant&countrycode=KOR¤cy=USD&storeorderno=167633275456&payamt=1
&payerid=testid&payeremail=testid@payletter.com&servicename=Payment+GPOQ&custom=testcustom&payinfo=
&pginfo=PLCreditCard×tamp=1676365201&hash=55e1d4db5c7adfc5226b27b8e3bf8e1d76efccab0125ece6c5a7ee42826278d5
¬ifytype=1&paytoken=20230214V5G503IU2OXH&trantime=2023-02-14 09:00:00&retcode=0&retmsg=&poqtoken=&cardkind=testcard
&cardno=************6156¬ifyid=180293
Parameter | Type | Description |
---|---|---|
notifyid | number | Notification 고유 식별번호 |
notifytype | number | Notification 타입 1: 성공(가맹점 구매 처리 진행) 2: 전체 취소(가맹점 구매 취소 처리 진행) 3: Chargeback (가맹점 구매 취소 처리 진행) 4: 부분 취소(Store 구매 부분 취소 처리 진행) 5: PayPal Subscription Create (가맹점 PayPal 정기결제 신청 처리 진행) 6: PayPal Pending (가맹점 PayPal 결제 보류 상태 처리 진행) 7: Paypal 자동결제(청구형) 금액 없이 요청 (자동결제 토큰) |
storeid | string | 가맹점 아이디 |
countrycode | string | 국가 코드 |
currency | string | 통화 코드 |
storeorderno | string | 가맹점 주문 번호 (PayPal subscription 거래 건인 경우 임의로 생성한 값이 전달됨) |
paytoken | string | 페이레터 결제 고유번호 |
payamt | number | 결제 금액 |
pginfo | string | 결제된 PG 정보 |
payerid | string | 가맹점 결제자(회원) 아이디 |
payeremail | string | 가맹점 결제자(회원) 이메일 |
servicename | string | 가맹점 서비스명 |
custom | string | 가맹점이 전송하는 임의의 값 |
payinfo | string | 추가 결제정보 |
timestamp | number | Unix time stamp |
hash | string | Parameter 검증을 위한 SHA256 hash 값 SHA256(storied + currency + storeorderno + payamt + payerid + timestamp +API Key) PayPal 정기결제(청구형) 금액 없이 요청 방식의 경우 SHA256(storied + storeorderno + payerid + timestamp +API Key) |
trantime | string | 페이레터 결제시간 (yyyy-MM-dd HH:mm:ss) |
poqtoken | string | 페이레터 자동결제 토큰 (recurringtype = Y 인 경우 전달) |
cardkind | string | 카드 명 (PLCreditCard, PLCreditCardMpi, PLCreditCard_CY_인 경우 전달) |
cardno | string | 카드번호(끝자리 4자리만 전달하고 나머지는 마스킹 처리) (PLCreditCard, PLCreditCardMpi, PLCreditCard_CY_인 경우 전달) |
intervaltype | number | PayPal 정기결제 청구 주기 (1: DAY, 2: WEEK, 3: MONTH, 4: YEAR) (notifytype = 5 인 경우 전달) |
intervalcnt | number | PayPal 정기결제 청구 간격 (DAY: 1~365, WEEK: 1~52, MONTH: 1~12, YEAR: 1) (notifytype = 5 인 경우 전달) |
totalcycles | number | PayPal 정기결제 청구 횟수 (2~999, 제한 없음: 0) (notifytype = 5 인 경우 전달) |
retcode | number | 결과 코드 (0 고정) |
retmsg | string | 결과 메시지(빈 값 고정) |
결과값을 받아서 가맹점에 맞는 재화 지급 등 가맹점의 비즈니스 로직을 수행하도록 합니다.
Notification URL에서 처리 완료 후 성공 시 아래 문자 열을 출력해 주시기 바랍니다.
<RESULT>OK</RESULT>
이 외의 결과가 나올 경우, 노티가 실패한 것으로 간주되어 5분마다 10회까지 재전송됩니다. (기본10회, 조정 가능)
성공 시 <RESULT>OK</RESULT> 외의 html 및 다른 코드가 해당 페이지에 노출 되지 않도록 합니다.
전달된 결과값은 위/변조 방지를 위하여 sha256 hash 값을 생성한 후 전달된 hash parameter와
비교 검증을 수행하시기 바랍니다.
결제 성공 외의 취소/부분 취소, 차지백 등 처리 완료에 대한 노티도 전송되므로
notifytype parameter에 따라 가맹점의 비즈니스 로직을 수행하도록 합니다.
노티 발송 내역은 가맹점 관리자 사이트에 로그인 후 매출정보 > 노티 발송 내역 메뉴에서 확인이 가능합니다.
자동결제 1회차 이후 결제 요청
자동결제 1회차는 결제 요청 API(api/payment/request)의 recurringtype parameter를 Y로 설정하여 요청합니다.
이 요청의 결제가 성공하면 자동 결제 신청이 완료됩니다. 이 후 2회차 결제 요청부터는 payment/recurring API를 사용합니다
(PayPal의 경우, 2회차부터는 PayPal측에서 청구 조건에 따라 결제를 생성하고 성공하면 페이레터로 결과를 전달해주고
페이레터는 가맹점으로 결제 성공 노티를 전송하기 때문에 가맹점 측에서 요청하지 않습니다.)
요청
POST payment/recurring HTTP/1.1
Host: dev-api.payletter.com
Authorization: GPLKEY PL_Merchant
Content-Type: application/json
{
"storeid" : "PL_Merchant",
"poqtoken":"TPL_Merchant20230509235776",
"storeorderno":"123456789",
"currency":"USD",
"amount":1.00,
"pginfo":"PLCreditCard"
}
접근 권한
Private
HTTP Request
POST payment/recurring
Request json data
구분 | Parameter | Type | Size | M/O | Description |
---|---|---|---|---|---|
공통 | storeid | string | 20 | M | 가맹점 아이디 |
poqtoken | string | 40 | M | 첫 자동결제 시 전달 받은 페이레터 자동결제 토큰 | |
storeorderno | string | 128 | M | 가맹점 주문 번호 | |
currency | string | 3 | M | 통화 코드 (ISO 4217) Ex) USD, JPY | |
amount | number | M | 결제 금액 (천 단위 기호 제거) (KRW, JPY, VND는 정수, 이외 소수점 둘째 자리) |
||
pginfo | string | 40 | M | 결제 요청 PG 정보(PGCode 표) | |
payinfo | string | 200 | O | 추가 결제정보 | |
payerid | string | 50 | O | 가맹점 결제자(회원) 아이디 | |
custom | string | 2000 | O | 가맹점이 전송하는 임의의 값 |
Response json Data
성공시
HTTP 1.1 200 OK
{
"data" : {
"storeid" :"PL_Merchant",
"countrycode":"KOR",
"storeorderno":"123456789",
"amount":1.00,
"payerid":"testid",
"poqtoken":"TPL_Merchant20230509235776",
"paytoken":"20230509XZFMAPBYZTW5",
"paydate":"2023-05-09 09:31:00"
}
}
실패시
HTTP 1.1 400 BadRequest
{
"error": {
"code": 997,
"message": "The request is invalid.",
"detail": "Request failed.Check the customer's payment information again",
"plcode": 997
}
}
성공시
Parameter | Type | Description |
---|---|---|
data | object | |
└ storeid | string | 가맹점 아이디 |
└ countrycode | string | 국가 코드 |
└ storeorderno | string | 가맹점 주문 번호 |
└ amount | number | 결제 금액 |
└ payerid | string | 가맹점 결제자(회원) 아이디 |
└ poqtoken | string | 페이레터 자동결제 토큰 |
└ paytoken | string | 페이레터 결제 고유번호 |
└ paydate | string | 페이레터 결제시간 (yyyy-MM-dd HH:mm:ss) |
실패시
Parameter | Type | Description | |||
---|---|---|---|---|---|
error | object | ||||
└ code | number | 에러 코드 | |||
└ message | string | 에러 메시지 | |||
└ detail | string | 에러 상세 메시지 | |||
└ plcode | number | 기타 에러 코드 | |||
구분 | Parameter | Type | Size | M/O | Description |
공통 | storeid | string | 20 | M | 가맹점 아이디 |
poqtoken | string | 40 | M | 첫 자동결제 시 전달 받은 페이레터 자동결제 토큰 | |
storeorderno | string | 128 | M | 가맹점 주문 번호 | |
currency | string | 3 | M | 통화 코드 (ISO 4217) Ex) USD, JPY | |
amount | number | M | 결제 금액 (천 단위 기호 제거) (KRW, JPY, VND는 정수, 이외 소수점 둘째 자리) |
||
pginfo | string | 40 | M | 결제 요청 PG 정보(PGCode 표) | |
payinfo | string | 200 | O | 추가 결제정보 | |
payerid | string | 50 | O | 가맹점 결제자(회원) 아이디 | |
custom | string | 2000 | O | 가맹점이 전송하는 임의의 값 | |
PayPal 자동결제 (청구형) |
paypalisppflag | string | 1 | O | PayPal ISPP 사용 여부 (Y: 사용, N: 미사용) (paypalisppflag=Y인 경우, payerfirstname, payerlastname, payerphone, payercountrycode, payercreatedate 필수 데이터) |
payerfirstname | string | 50 | O | 결제자 이름 | |
payerlastname | string | 50 | O | 결제자 성 | |
payerphone | string | 20 | O | national notation Ex) (042) 1123 4567) |
|
payercreatedate | string | 30 | O | 결제자 가입일 (ISO 8601 date format) Ex) 2023-04-09T19:14:55.277-0:00 |
|
payercountrycode | string | 2 | O | 결제자 국가 코드 (ISO Alpha-2 Country Code) Ex) AU, KR |
결제 취소
요청
POST payment/refund HTTP/1.1
Host: dev-api.payletter.com
Authorization: GPLKEY PL_Merchant
Content-Type: application/json
{
"storeid" : "PL_Merchant",
"paytoken":"20230214V5G503IU2OXH",
"currency":"USD",
"amount":1.00
}
접근 권한
Public
HTTP Request
POST payment/refund
Request json data
Parameter | Type | Size | M/O | Description |
---|---|---|---|---|
storeid | string | 20 | M | 가맹점 아이디 |
paytoken | string | 20 | M | 취소 할 결제 건의 페이레터 결제 고유 번호 |
currency | string | 3 | M | 통화 코드 (ISO 4217) Ex) USD, JPY |
amount | number | M | 취소 금액 (천 단위 기호 제거) (KRW, JPY, VND는 정수, 이외 소수점 둘째 자리) |
|
pginfo | string | 40 | O | 취소 요청할 결제 건의 PG 정보 (PGCode 표) |
Response json data
성공시
HTTP 1.1 200 OK
{
"data" : {
"storeid" :"PL_Merchant",
"paytoken":"20230509XZFMAPBYZTW5",
"pginfo":"PLCreditCard",
"storeorderno":"123456789",
"currency":"USD",
"amount":1.00,
"refunddate":"2023-05-09 09:32:00"
}
}
실패시
HTTP 1.1 400 BadRequest
{
"error": {
"code": 997,
"message": "The request is invalid.",
"detail": "[2104]The payment transaction does not exist",
"plcode": 997
}
}
성공시
Parameter | Type | Description |
---|---|---|
data | object | |
└ storeid | string | 가맹점 아이디 |
└ paytoken | string | 페이레터 결제 고유 번호 |
└ pginfo | string | PG 정보 |
└ storeorderno | string | 가맹점 주문 번호 |
└ currency | string | 통화 코드 |
└ amount | number | 취소 금액 |
└ refunddate | string | 페이레터 결제 취소 시간 (yyyy-MM-dd HH:mm:ss) (VTCDomesticBank, VTCPay의 경우, 결제 취소된 시간이 아닌 취소 요청 시간이 전달, 추후 취소 완료 시 취소 노티(notifytype=2)가 전달) |
실패시
Parameter | Type | Description |
---|---|---|
error | object | |
└ code | number | 에러 코드 |
└ message | string | 에러 메시지 |
└ detail | string | 에러 상세 메시지 |
└ plcode | number | 기타 에러 코드 |
결제 내역 조회
요청
POST payment/cpdaesalist HTTP/1.1
Host: dev-api.payletter.com
Authorization: GPLKEY PL_Merchant
Content-Type: application/json
{
"storeid" : "PL_Merchant",
"currency":"USD",
"datefrom":"20230510",
"dateto":"20230510",
"searchtype": 0
}
접근 권한
Private
HTTP Request
POST payment/cpdaesalist
Request json data
Parameter | Type | Size | M/O | Description |
---|---|---|---|---|
storeid | string | 20 | M | 가맹점 아이디 |
pgcode | string | 20 | O | PG 코드(PGCode 표) |
pgsubcode | string | 20 | O | PG 서브 코드(PGCode 표) |
currency | string | 3 | O | 통화 코드 (ISO 4217) Ex) USD, JPY |
datefrom | string | 8 | M | 시작일 (yyyyMMdd) |
dateto | string | 8 | M | 종료일 (yyyyMMdd) |
searchtype | number | M | 조회 기준 0: 전체 1: 결제(결제일 기준) 2: 취소(취소일 기준) 3: 부분 취소(취소일 기준) |
Response json data
성공시
HTTP 1.1 200 OK
{
"data" : {
"rowcount": {
"total": 2,
"success": 2,
"cacnel": 0
},
"datalist": [
{
"paytoken": "20230510NAZWKSA17H4W",
"pginfo": "CreditCard",
"storeorderno": "168368243526",
"payerid": "test123",
"amount": 1.00,
"currency": "USD",
"state": 1,
"ymd": "20230510",
"regdate": "2023-05-10 10:34:24.970",
"cnldate": "",
"pgtoken": "0841304"
},
{
"paytoken": "20230101K2ICLQZRWJ8X",
"pginfo": "PaypalExpressCheckout",
"storeorderno": "168368248080",
"payerid": "test567",
"amount": 1.00,
"currency": "USD",
"state": 1,
"ymd": "20230510",
"regdate": "2023-05-10 10:35:25.573",
"cnldate": "",
"pgtoken": "66S82102WA838793D"
}
]
}
}
실패시
HTTP 1.1 403 Forbidden
{
"error": {
"code": 993,
"message": "You do not have authorization.",
"detail": "Not allowed ip address.",
"plcode": 993
}
}
성공시
Parameter | Type | Description |
---|---|---|
data | object | |
└ rowcount | object | 거래 건수 |
└ total | number | 총 거래 건수 |
└ success | number | 정상 거래 건수 |
└ cancel | number | 취소 거래 건수 |
└ datalist | json array | 거래 데이터 |
└ paytoken | string | 페이레터 결제 고유번호 |
└ pginfo | string | PG 정보 |
└ storeorderno | string | 가맹점 주문 번호 |
└ payerid | string | 가맹점 결제자(회원) 아이디 |
└ amount | number | 결제 금액 |
└ currency | string | 통화 코드 |
└ state | number | 결제 상태 코드(1: 정상, 2: 취소, 3: 부분 취소) |
└ ymd | string | 결제 일시 |
└ regdate | string | 등록 일시 |
└ cnldate | string | 취소 일시 |
└ pgtoken | string | PG 거래 번호 (PayPal 의 경우 Transaction ID) |
실패시
Parameter | Type | Description |
---|---|---|
error | object | |
└ code | number | 에러 코드 |
└ message | string | 에러 메시지 |
└ detail | string | 에러 상세 메시지 |
└ plcode | number | 기타 에러 코드 |
정산 내역 조회
요청
POST settlement/detailslist HTTP/1.1
Host: dev-api.payletter.com
Authorization: GPLKEY PL_Merchant
Content-Type: application/json
{
"storeid" : "PL_Merchant",
"currencytype":1,
"searchtype": 1,
"settlestate": 0,
"settlesymd":"20230509",
"settleeymd":"20230510"
}
접근 권한
Private
HTTP Request
POST settlement/detailslist
Request json data
Parameter | Type | Size | M/O | Description |
---|---|---|---|---|
storeid | string | 20 | M | 가맹점 아이디 |
pgcode | string | 20 | O | PG 코드 (PGCode 표) |
pgsubcode | string | 20 | O | PG 서브 코드 (PGCode 표) |
currencytype | number | M | 통화 타입 (1: 결제 통화, 2: 정산 통화) | |
searchtype | number | M | 정산 타입 (1: 결제수단 별, 2: 상세 내역 별) | |
settlestate | number | O | 정산 상태 (고정값 : 0) | |
settlesymd | string | 8 | M | 정산 시작일 (yyyyMMdd) |
settleeymd | string | 8 | M | 정산 종료일 (yyyyMMdd) |
Response json data
성공시
HTTP 1.1 200 OK
{
"data" : {
"datalist": [
{
"storeid": "PL_Merchant",
"settleymd": "20230131",
"pgcode": "PL",
"pgsubcode": "CreditCardMpi",
"currency": "",
"settlestate": 1,
"paycnt": 1,
"payamt": 0,
"settleamt": -414.0,
"totalfee": 0,
"vat": 0,
"supplyamt": 0,
"storefee": 0,
"transactionfee": 0,
"chargebackfee": 0,
"refundfee":0,
"etcfee": 0,
"note": "20230131 testtest",
"notedesc": "",
"rollingreserve": -414.0,
"paytoken": ""
},
{
"storeid": "PL_Merchant",
"settleymd": "20230131",
"pgcode": "PL",
"pgsubcode": "CreditCard",
"currency": "USD",
"settlestate": 1,
"paycnt": 1,
"payamt": 79.99,
"settleamt": 73.94,
"totalfee": 6.05,
"vat": 0.55,
"supplyamt": 5.5,
"storefee": 5.0,
"transactionfee": 0.5,
"chargebackfee": 0,
"refundfee":0,
"etcfee": 0,
"note": "4.00",
"notedesc": "",
"rollingreserve": "",
"paytoken": "20221218TN79J9V1YBSV"
}
]
}
}
실패시
HTTP 1.1 403 Forbidden
{
"error": {
"code": 993,
"message": "You do not have authorization.",
"detail": "Not allowed ip address.",
"plcode": 993
}
}
성공시
Parameter | Type | Description |
---|---|---|
data | object | |
└ datalist | json array | 정산 데이터 |
└ storeid | string | 가맹점 아이디 |
└ settleymd | string | 정산일 |
└ pgcode | string | PG 코드 |
└ pgsubcode | string | PG 서브 코드 |
└ currency | string | 통화 코드 |
└ settlestate | number | 정산 상태(1: 정산, 2: 정산 예정) |
└ paycnt | number | 결제 건수 |
└ payamt | number | 결제 금액 |
└ settleamt | number | 정산 금액 |
└ totalfee | number | 수수료 합계 |
└ vat | number | 부가세 |
└ supplyamt | number | 공급가액 |
└ storefee | number | 가맹점 수수료 |
└ transactionfee | number | 거래 수수료 |
└ chargebackfee | number | 차지백 수수료 |
└ refundfee | number | 취소 수수료 |
└ etcfee | number | 기타 수수료 |
└ note | string | 비고 (수수료율 or 참고사항) |
└ notedesc | string | 비고 상세 (수수료율 or 참고사항) |
└ rollingreserve | string | RollingReserve |
└ paytoken | string | 페이레터 결제 고유번호 |
실패시
Parameter | Type | Description |
---|---|---|
error | object | |
└ code | number | 에러 코드 |
└ message | string | 에러 메시지 |
└ detail | string | 에러 상세 메시지 |
└ plcode | number | 기타 에러 코드 |
PayPal 자동결제(구독형) 해지 요청
요청
POST paypal/subscription/cancel HTTP/1.1
Host: dev-api.payletter.com
Authorization: GPLKEY PL_Merchant
Content-Type: application/json
{
"storeid" : "PL_Merchant",
"poqtoken":"TPL_Merchant20230509235776"
}
접근 권한
Public
HTTP Request
POST paypal/subscription/cancel
Request json data
Parameter | Type | Size | M/O | Description |
---|---|---|---|---|
storeid | string | 20 | M | 가맹점 아이디 |
poqtoken | string | 40 | M | 페이레터 자동결제 토큰 |
Response json data
성공시
HTTP 1.1 200 OK
{
"data" : {
"code" :0,
"message":"OK"
}
}
실패시
HTTP 1.1 400 BadRequest
{
"error": {
"code": 997,
"message": "The request is invalid.",
"detail": "[2235]This PayPal subscription information has already been canceled ",
"plcode": 997
}
}
성공시
Parameter | Type | Description |
---|---|---|
data | object | |
└ code | number | 응답 코드 |
└ message | string | 응답 메시지 |
실패시
Parameter | Type | Description |
---|---|---|
error | object | |
└ code | number | 에러 코드 |
└ message | string | 에러 메시지 |
└ detail | string | 에러 상세 메시지 |
└ plcode | number | 기타 에러 코드 |
거래 내역 확인서
요청
GET receipt/info/2024062771EFO2U4ZCKF?storeid=PL_Merchant HTTP/1.1
Host: dev-api.payletter.com
Authorization: GPLKEY PL_Merchant
접근 권한
Public
HTTP Request
GET receipt/info/{paytoken}
Request json data
Parameter | Type | Size | M/O | Description |
---|---|---|---|---|
storeid | string | 20 | M | 가맹점 아이디 |
Response json data
성공시
HTTP 1.1 200 OK
{
"receipt_url" : {
"https://dev-api.payletter.com/receipt/info/2024062771EFO2U4ZCKF?storeid=PL_Merchant"
}
실패시
HTTP 1.1 400 BadRequest
{
"error": {
"code": 997,
"message": "The request is invalid.",
"detail": "The payment does not exist.",
"plcode": 997
}
}
성공시
Parameter | Type | Description |
---|---|---|
receipt_url | string | 거래 내역 확인서 URL |
실패시
Parameter | Type | Description |
---|---|---|
error | object | |
└ code | number | 에러 코드 |
└ message | string | 에러 메시지 |
└ detail | string | 에러 상세 메시지 |
└ plcode | number | 기타 에러 코드 |
일별 결제 내역 조회
요청
POST payment/transaction/list HTTP/1.1
Host: dev-api.payletter.com
Authorization: GPLKEY PL_Merchant
Content-Type: application/json
{
"storeid" : "PL_Merchant",
"currency":"USD",
"date":"20240821",
"searchtype": 0
}
접근 권한
Private
HTTP Request
POST payment/transaction/list
Request json data
Parameter | Type | Size | M/O | Description |
---|---|---|---|---|
storeid | string | 20 | M | 가맹점 아이디 |
pgcode | string | 20 | O | PG 코드(PGCode 표) |
pgsubcode | string | 20 | O | PG 서브 코드(PGCode 표) |
currency | string | 3 | O | 통화 코드 (ISO 4217) Ex) USD, JPY |
date | string | 8 | M | 조회일 (yyyyMMdd) |
searchtype | number | M | 조회 기준 0: 전체 1: 결제(결제일 기준) 2: 취소(취소일 기준) 3: 부분 취소(취소일 기준) |
|
paytoken | string | 20 | O | 페이레터 결제 고유번호 |
Response json data
성공시
HTTP 1.1 200 OK
{
"data" : {
"rowcount": {
"total": 2,
"success": 1,
"cacnel": 1
},
"datalist": [
{
"paytoken": "20240821HCH95D17M6PT",
"pginfo": "PLCreditCard",
"storeorderno": "bb1bbfdc-871c",
"payerid": "test123",
"amount": 1.00,
"currency": "USD",
"state": 1,
"ymd": "20240821",
"regdate": "2024-08-21 12:13:49",
"cnldate": "",
"pgtoken": "1234567"
},
{
"paytoken": "20240821HCH95D17M6PT",
"pginfo": "PLCreditCard",
"storeorderno": "bb1bbfdc-871c",
"payerid": "test123",
"amount": 1.00,
"currency": "USD",
"state": 2,
"ymd": "20240821",
"regdate": "2024-08-21 12:13:49",
"cnldate": "2024-08-21 13:13:49",
"pgtoken": "1234567"
}
]
}
}
실패시
HTTP 1.1 403 Forbidden
{
"error": {
"code": 993,
"message": "You do not have authorization.",
"detail": "Not allowed ip address.",
"plcode": 993
}
}
성공시
Parameter | Type | Description |
---|---|---|
data | object | |
└ rowcount | object | 거래 건수 |
└ total | number | 총 거래 건수 |
└ success | number | 정상 거래 건수 |
└ cancel | number | 취소 거래 건수 |
└ datalist | json array | 거래 데이터 |
└ paytoken | string | 페이레터 결제 고유번호 |
└ pginfo | string | PG 정보 |
└ storeorderno | string | 가맹점 주문 번호 |
└ payerid | string | 가맹점 결제자(회원) 아이디 |
└ amount | number | 결제 금액 |
└ currency | string | 통화 코드 |
└ state | number | 결제 상태 코드(1: 정상, 2: 취소, 3: 부분 취소) |
└ ymd | string | 결제 일시 |
└ regdate | string | 등록 일시 |
└ cnldate | string | 취소 일시 |
└ pgtoken | string | PG 거래 번호 (PayPal 의 경우 Transaction ID) |
실패시
Parameter | Type | Description |
---|---|---|
error | object | |
└ code | number | 에러 코드 |
└ message | string | 에러 메시지 |
└ detail | string | 에러 상세 메시지 |
└ plcode | number | 기타 에러 코드 |
오류코드
API 요청에 대한 성공/실패 여부는 HTTP StatusCode로 확인합니다.
StatusCode 200 OK 인 경우에만 요청 처리 성공이며, 성공이 아닌 경우에는 아래 StatusCode를 참고하시기 바랍니다.
오류코드 표
HTTP Response | Error Code | Error Message | Description |
---|---|---|---|
400 | 997 | The request is invalid | 요청 parameter 오류 |
401 | 998 | Authentication token is missing or incorrect | 인증 오류 |
403 | 993 | You do not have authorization | 인증 오류 |
406 | 990 | 오류 상세 메시지 | 비즈니스 로직 처리중 오류 |
500 | 999 | Internal Error | 시스템 오류 |
첨부
PGCode 표
PGInfo | PGCode | PGSubCode | 비고 |
---|---|---|---|
PLCreditCard | PL | CreditCard | 해외카드 비인증 |
PLCreditCard_CY | PL | CreditCard_CY | 해외카드 사이버소스 |
PLCreditCardMpi | PL | CreditCardMpi | 해외카드 인증 |
PLUnionPay | PL | UnionPay | 유니온페이 |
PLUnionPay_HC | PL | UnionPay_HC | 유니온페이 |
CCCherryCredits | CC | CherryCredits | CherryCredits (선불카드) |
CodaPay12Call | CodaPay | 12Call | 12 Call (선불카드) |
Codapay7ElevenPH | CodaPay | 7ElevenPH | 7Eleven (편의점 결제) |
CodaPay7ElevenTHA | CodaPay | 7ElevenTHA | 7Eleven (편의점 결제) |
CodapayAlfamart | CodaPay | Alfamart | Alfamart (편의점 결제) |
CodapayBankTransfer | CodaPay | BankTransfer | Bank Transfer (계좌이체) |
CodaPayBankTransferTHA | CodaPay | BankTransferTHA | Bank Transfer (계좌이체) |
CodaPayCarrierBillingAIS | CodaPay | CarrierBillingAIS | AIS (핸드폰 결제) |
CodaPayCarrierBillingDTAC | CodaPay | CarrierBillingDTAC | DTAC (핸드폰 결제) |
CodapayCarrierBillingMaxis | CodaPay | CarrierBillingMaxis | Maxis (핸드폰 결제) |
CodaPayCarrierBillingTMH | CodaPay | CarrierBillingTMH | TMH (핸드폰 결제) |
CodapayDokuWallet | CodaPay | DokuWallet | Doku Wallet (전자지갑) |
CodaPayDolfin | CodaPay | Dolfin | Dolfin (전자지갑) |
CodaPayEtisalat | CodaPay | Etisalat | Etisalat (핸드폰 결제) |
CodaPayFawry | CodaPay | Fawry | Fawry (전자지갑) |
CodaPayGcash | CodaPay | Gcash | Gcash (전자지갑) |
CodapayIndomaret | Codapay | Indomaret | Indomaret (편의점 결제) |
CodaPayKplus | CodaPay | Kplus | Kplus (계좌이체) |
CodaPayOoredooKuwait | CodaPay | OoredooKuwait | Ooredoo (핸드폰 결제) |
CodaPayPromptpay | CodaPay | Promptpay | PromptPay (계좌이체) |
CodaPayRabbitLINEPay | CodaPay | RabbitLINEPay | Rabbit LINE Pay (전자지갑) |
CodaPayShopeePayTH | CodaPay | ShopeePayTH | ShopeePay (전자지갑) |
CodaPayTrueMoneyCashCard | CodaPay | TrueMoneyCashCard | True Money Cash Card (선불카드) |
CodaPayTrueMoneyWallet | CodaPay | TrueMoneyWallet | True Money Wallet (전자지갑) |
CodaPayZainBahrain | CodaPay | ZainBahrain | Zain (핸드폰 결제) |
CodaPayZainKuwait | CodaPay | ZainKuwait | Zain (핸드폰 결제) |
DegicaBancontact | Degica | Bancontact | Bancontact (전자지갑) |
DegicaBankTransfer | Degica | BankTransfer | BankTransfer (계좌이체) |
DegicaBitCash | Degica | BitCash | BitCash (선불카드) |
DegicaCreditCard | Degica | CreditCard | CreditCard (신용카드) |
DegicaEPS | Degica | EPS | EPS (계좌이체) |
DegicaGiroPay | Degica | GiroPay | GiroPay (계좌이체) |
DegicaIdeal | Degica | Ideal | iDEAL (계좌이체) |
DegicaJapanMobile | Degica | JapanMobile | JapanMobile (핸드폰 결제) |
DegicaKonbini | Degica | Konbini | Konbini (편의점 결제) |
DegicaLinePay | Degica | LinePay | LINE Pay (전자지갑) |
DegicaMerPay | Degica | MerPay | MerPay (전자지갑) |
DegicaMultibanco | Degica | Multibanco | Multibanco (계좌이체) |
DegicaMyBank | Degica | MyBank | MyBank (계좌이체) |
DegicaNetCash | Degica | NetCash | NetCash (선불카드) |
DegicaPayEasy | Degica | PayEasy | PayEasy (온라인 뱅킹) |
DegicaPayPay | Degica | PayPay | PayPay (전자지갑) |
DegicaPaysafecard | Degica | Paysafecard | Paysafecard (EPIN) |
DegicaPrzelewy24 | Degica | Przelewy24 | Przelewy24 (계좌이체) |
DegicaSofortBanking | Degica | SofortBanking | Sofort (계좌이체) |
DegicaWebMoney | Degica | WebMoney | WebMoney (선불카드) |
ICBAlipay | ICB | Alipay | Alipay (전자지갑) |
MOLAIS 12 Call Prepaid | MOL | AIS 12 Call Prepaid | AIS 12 Call (선불카드) |
MOLFPX | MOL | FPX | FPX (온라인 뱅킹) |
MOLLoadCentral | MOL | LoadCentral | LoadCentral (선불카드) |
MOLMaybank2U | MOL | Maybank2U | Maybank (온라인 뱅킹) |
MOLMOLPoint_PP | MOL | MOLPoint_PP | Razer Gold PIN (선불카드) |
MOLTrueMoney | MOL | True Money | True Money (선불카드) |
MOLzGold-MOLPoints | MOL | zGold-MOLPoints | Razer Gold Wallet (전자지갑) |
MyCardPPCard | MyCard | PPCard | MyCard (선불카드) |
PaypalExpressCheckout | Paypal | ExpressCheckout | PayPal (전자지갑) |
VTCDomesticBank | VTC | DomesticBank | Bank Transfer (계좌이체) |
VTCVTCPay | VTC | VTCPay | VTCPay (전자지갑) |
WeChatPayH5Payment | WeChatPay | H5Payment | WeChatPay (전자지갑) |
WeChatPayQRCodePayment | WeChatPay | QRCodePayment | WeChatPay (전자지갑) |