NAV Navbar

페이레터 해외결제 소개

서비스 안내

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

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

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

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

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) 카드번호 입력

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 가맹점이 전송하는 임의의 값
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

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 기타 에러 코드

결제 취소

요청

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 (전자지갑)