페이레터 해외결제 소개

서비스 안내

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

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

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

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

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&currency=USD&storeorderno=167633275456&payamt=1
&payerid=testid&payeremail=testid@payletter.com&servicename=Payment+GPOQ&custom=testcustom&payinfo=
&pginfo=PLCreditCard&timestamp=1676365201&hash=55e1d4db5c7adfc5226b27b8e3bf8e1d76efccab0125ece6c5a7ee42826278d5
&notifytype=1&paytoken=20230214V5G503IU2OXH&trantime=2023-02-14 09:00:00&retcode=0&retmsg=&poqtoken=&cardkind=testcard
&cardno=************6156&notifyid=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 (전자지갑)