Payletter Overseas Payment Service

Introduction

No matter how many times you think, Payletter is your partner at all times!

Payletter provides an electronic payment service for sales of product at online store.

We are trying our best to provide the most convenient payment service with our capability in stable transaction

processing, various kinds of payment method and security certification.

1. Possession of multiple payment methods that can cover the entire global market, including Southeast Asia, the Americas, and Europe
2. Stable payment environment based on PCI-DSS(Global Credit Card data security standard, ISMS (Data security standard certificated in local organization)
3. Proven capability in transaction processing from experience in working with local No.1 e-commerce, music streaming and VOD service
4. Stable service and settlement in basis of solid financial structure
5. Prompt response for merchants and customers’ inquirires

Payment Method and Additional Service

Credit/Debit Cards	E-wallets	Prepaid cards	Convenience store payment	Mobile Payment
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

*For additional inquiries about payment methods, please contact us separately.

How to Apply

Partnership Inquiry : globalpg@payletter.com
1. Apply for Payletter Service Online
2. Service Review
3. Submission of contract and required documents
4. Screening of each payment methods - Credit card: It takes about 2 weeks - Other payment methods: It takes about 1 month
5. Sign up completed

Required Document

Division	Corporate Business	Individual Business
Contract Document	1. Copies of Global PayoneQ Service Agreement
Required Documents	1. 1 Copy of Certificate of Business 2. 1 Original Certificate of Seal Impression (Corporate) 3. 1 Copy of Certificate of Usesignet (If you stamped the usesignet) 4. 1 Original Certified Copy of the Registry 5. 1 Copy of Bankbook (Under the corporate name) 6. The document that you checked in [Appendix 5] of Agreement	1. 1 Copy of Certificate of Business 2. 1 Original Certificate of Seal Impression (Individual) 3. 1 Copy of Representative ID 4. 1 Copy of Bankbook (Under the representative name)

Integration preparation

Information to be provided by Store	Description
Notification URL	Notification URL for payment to be received as backend It is available to reach the Notification URL through only 80,443 port on test environment So it is required to register firewall if you want to use other ports. Please send us your IP and Port to the following email. gpoqdev@payletter.com
IP	Store’s Request IP when you integrate an private access API

Information to be provided by the Payletter	Description
StoreID	StoreID provided after contract with Payletter
API Key	API Key provided after contract with Payletter

API HTTPS Protocol

Payletter API HTTPS supports TLS 1.2 or higher.

Firewall

Please add inbound IP in order to receive a notification for payment completion.

Test : 121.254.205.166

Live : 211.115.72.37, 211.115.72.38, 211.115.117.11(Reserve)

API Authorization

API Key will be issued once contract is completed.

Please send API Key for HttpRequestHeader authorization as follows.

Authorization: GPLKEY {store_apikey}

API Endpoint URL

Environment	URL
Test	https://dev-api.payletter.com
Live	https://api.payletter.com

Store Information for Test Environment

Integration test is available with registered StoreID and API Key in test environment.

Test payment is only available with PLCreditcard(non-certified) and PayPalExpressCheckout.

StoreID	PL_Merchant
API KEY	PL_Merchant

[Payment Test]

Test payment can be made in our test environment. Please refer to following information for your test.

1. Credit card payment is only available with a card issued overseas basically. We do not provide test cards.

2. If you need a test for credit card(PLCreditcardMpi) or UnionPay, please contact us separately.

3. A test for credit card(PLCreditcard) is available with random numbers. Please refer to following steps.

1) Please enter credit card number like below.

• Visa: Random number starting with 4
• Master: Random number starting with 51
• JCB: Random number starting with 35
• Amex: Random number starting with 34

2) Please enter Expiry date and CVV number randomly.

4. PayPal test is available with your PayPal account in sandbox server.

Options by payment method

Payment Method	Recurring Payment	Cancellation	Partial Cancellation	Cancellation Period
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	cannot be canceled
FPX	X	X	X	cannot be canceled
Maybank2U	X	X	X	cannot be canceled
AIS 12 Call	X	X	X	cannot be canceled
True Money	X	X	X	cannot be canceled
Razer Gold PIN	X	X	X	cannot be canceled
Razer Gold Wallet	X	X	X	cannot be canceled
Gcash	X	X	X	cannot be canceled
7eleven	X	X	X	cannot be canceled
Alfamart	X	X	X	cannot be canceled
Indomaret	X	X	X	cannot be canceled
Bank transfer (Indonesia)	X	X	X	cannot be canceled
Doku wallet	X	X	X	cannot be canceled
Maxis	X	X	X	cannot be canceled
Fawry	X	X	X	cannot be canceled
Etisalat	X	X	X	cannot be canceled
Zain	X	X	X	cannot be canceled
Ooredoo	X	X	X	cannot be canceled
Bank Transfer (Vietnam)	X	O	X	D+150
VTCPay	X	O	X	D+180
Cherry Credits	X	X	X	cannot be canceled

Technical Support

gpoqdev@payletter.com

For quick response, please provide detailed information such as integration environment, Store ID, invoice number,

time of transaction, token and related others. It would be useful for support.

Overseas Payment API

List of API

As allowed IPs are available to access for Private API,

please send your request IP to the person in charge of contract.

URL	METHOD	ACCESS	DESCRIPTION
api/payment/request	POST	Public	Payment Request
payment/recurring	POST	Private	Payment request after the first recurring payment
payment/refund	POST	Public	Payment Cancellation/Partial Cancellation
payment/cpdaesalist	POST	Private	Payment Details Inquire
settlement/detailslist	POST	Private	Settlement Details Inquire
paypal/subscription/cancel	POST	Public	PayPal Recurring Payment(Subscription) Cancellation
receipt/info/{paytoken}	GET	Public	Transaction history confirmation
payment/transaction/list	POST	Private	Daily Payment Details Inquiry

Payment Process

API Sample Source

The available programming languages for API sample sources of PAYLETTER are ASP, ASP.NET, JSP, PHP.

Programming Language	Sample Source
ASP	Download
ASP.NET	Download
JSP	Download
PHP	Download

Payment Request

Request

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"
}

Access Authority

Public

HTTP Request

POST api/payment/request

Request json data

Division	Parameter	Type	Size	M/O	Description
Common	storeid	string	20	M	Store ID
	currency	string	3	M	Currency code (ISO 4217) Ex) USD, JPY (Not required if pinflag = Y)
	storeorderno	string	128	M	Store Order Number
	amount	number		M	Payment amount (remove thousands sign) *All the currencies may include up to the second decimal place, except KRW, JPY, VND. *KRW, JPY, VND should not include any decimal place. (Not required if pinflag = Y)
	payerid	string	50	M	Store payer (member) ID (E-mail, English and numeric characters are available)
	payeremail	string	50	M	Store payer (member) email
	returnurl	string	256	M	Web page URL to connect after completing the payment
	notiurl	string	256	O	Notification URL to receive successful payment result
	servicename	string	100	O	Store service name (Required if WechatPay, AlipayPlus, PayPalExpressCheckout & recurringtype=Y)
	pginfo	string	40	O	Payment request PG information (PG Code Table) (Required for Directpay type)
	payinfo	string	200	O	Additional payment information
	pinflag	string	1	O	For zGold-MOLPoints Direct Top Up, set to Y
	recurringtype	string	1	O	Whether to use recurring payment or not (Y: use, N: not use)
	custom	string	2000	O	Random value sent by store After setting customer information, order information, and other necessary information return to the payment result ( This value cannot contain any of the following characters: | ' )
Creditcard Authentication	billaddrcity	string	64	O	the card billing address city
	billaddrcountry	string	3	O	card billing address country (ISO 3166-1 numeric three-digit country code) Ex) 410 (Korea), 840 (USA)
	billaddrline1	string	50	O	the card billing address
	billaddrpostcode	string	16	O	card billing address zip code
PayPal Common	paypalisppflag	string	1	O	Set to ”Y” when using PayPal ISPP (If paypalisppflag=Y, payerfirstname, payerlastname, payerphone, payercountrycode, payercreatedate required data)
	payerfirstname	string	50	O	payer first name
	payerlastname	string	50	O	payer last name
	payerphone	string	20	O	Payer phone number (national notation) Ex) (042) 1123 4567)
	payercreatedate	string	30	O	Payer join day (ISO 8601 date format) Ex) 2023-04-09T19:14:55.277-0:00
	payercountrycode	string	2	O	Ipayer country code (ISO Alpha-2 Country Code) Ex) AU, KR
	paypalcnlurlflag	string	1	O	Whether to use returnurl in PayPal payment cancellation page ( Y : use, N : not use ) (If opened as a popup, it will close) (If the page is a type of moving, it will connect to returnurl)
PayPal Recurring Payment(Subscription)	intervaltype	string	1	O	PayPal subscription billing cycle (1: DAY, 2: WEEK, 3: MONTH, 4: YEAR) (Required if PayPalExpressCheckout & recurringtype=Y)
	intervalcnt	string	3	O	PayPal subscription billing interval (DAY: 1~365, WEEK: 1~52, MONTH: 1~12, YEAR: 1) (Required if PayPalExpressCheckout & recurringtype=Y)
	totalcycles	string	3	O	Number of PayPal subscription charges (2-999, Unlimited: 0) (Required if PayPalExpressCheckout & recurringtype=Y)
PayPal Recurring Payment(Billing)	paypalrecurrflag	string	1	O	Whether to use paypal recurring payment(billing) or not (Y: use, N: not use) (if paypalrecurrflag= "Y", recurringtype = "Y" need)

[PayPal Recurring Payment]

Division	Description	Required Parameter	Note
Common	Request payment with recurringtype = "Y" to use PayPal Recurring Payment	recurringtype = "Y"
PayPal Recurring Payment (Subscription)	1. Request recurring payment (subscription) with PayPal billing information 2. Forward notifytype = 5 (PayPal recurring payment (subscription) creation complete) when PayPal recurring payment (subscription) creation is completed 3. Forward PayPal transactions with notifytype = 1 (payment completed) 4. afterward, PayPal will automatically create transactions based on your billing information and forward them to you with notifytype = 1 (payment completed)	recurringtype = "Y" intervaltype intervalcnt totalcycles
PayPal Recurring Payment (Billing)	1. Request recurring payment (Billing) 2. the user agrees to the recurring payment on PayPal page 3. forward notifytype = 1 (payment completed) with POQToken (recurring payment token) after the user's agree process is completed 4. Use POQ token (recurring payment token) to make recurring payment	recurringtype = "Y" paypalrecurrflag = "Y"
PayPal Recurring Payment (Billing) with no amount	1. Request recurring payment (Billing) (do not forward the amount and currency values) 2. the user agrees to the recurring payment on PayPal page 3. forward notifytype = 7 (recurring payment token) with POQToken after the user's agree process is completed (no payment will be made) 4. Use POQ token (recurring payment token) to make recurring payment	recurringtype = "Y" paypalrecurrflag = "Y"	Supports DirectPay only

Response json Data

In case of success

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" 
}
        

In case of failure

HTTP 1.1 400 BadRequest
{
    "error": {
        "code": 997,
        "message": "The request is invalid.",
        "detail": "[2102]Not exist PG contract information",
        "plcode": 997
    }
}

In case of success

Parameter	Type	Description
token	number	Payment Authentication Token
online_url	string	Payment Page Call URL in PC For payment methods that only support the mobile environment, pass an empty value (WechatpayH5Payment)
mobile_url	string	Payment Page Call URL in Mobile For payment methods that only support the pc environment, pass an empty value (WechatpayQRCodePayment)

In case of failure

Parameter	Type	Description
error	object
└ code	number	Error Code
└ message	string	Error Message
└ detail	string	Error Detail Message
└ plcode	number	Other error codes

Payment Integration

Please call payment page using URL returned to payment request API Response.

Once user proceeds with payment, payment result will be returned to returnurl transmitted by payment request.

We recommend to process payment completion (store's business logic, such as payment of goods) in notiurl.

or notification URL of the store registered in advance.

Please refer to following instruction on process of returnurl and notiurl.

Result Processing (returnurl)

Payment result is transmitted to POST parameter in Request.

For payment methods that do not immediately transact, such as bank transfer and cvs

the success or failure of the payment authentication request is returned.

Therefore, you should not process purchases in returnurl.

Parameter	Type	Description
retcode	string	code (0=success 0<>failure)
retmsg	string	message
storeid	string	Store ID
storeorderno	string	Store Order Number
payamt	number	Amount of payment
custom	string	Random value sent by store
pginfo	string	Paid PG information

Payment Processing (Notification URL, notiurl)

The successful payment result is delivered as POST as shown below.

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 unique identification number
notifytype	number	Notification type 1: Successful payment (Processing store purchase) 2: Cancellation (Processing cancellation of purchases from store) 3: Chargeback (Processing cancellation of purchases from store) 4: Partial cancellation (Processing Partial cancellation of purchases from store) 5: PayPal Subscription Create (Processing store PayPal subscription create) 6: PayPal Pending (Processing store PayPal payment pending status) 7: PayPal Recurring Payment(Billing) with no amount (recurring payment token)
storeid	string	Store ID
countrycode	string	Country code
currency	string	Currency code
storeorderno	string	Store Order Number (In case of PayPal subscription transaction, a randomly generated value is transmitted)
paytoken	string	Payletter payment unique number
payamt	number	Amount of payment
pginfo	string	Paid PG information
payerid	string	Store payer (member) ID
payeremail	string	Store payer (member) email
servicename	string	Store service name
custom	string	Random value sent by store
payinfo	string	Additional payment information
timestamp	number	Unix time stamp
hash	string	SHA256 hash value for parameter verification SHA256(storied + currency + storeorderno + payamt + payerid + timestamp +API Key) For the Request PayPal recurring payment (billing) without amount, SHA256(storied + storeorderno + payerid + timestamp +API Key)
trantime	string	Payletter payment time (yyyy-MM-dd HH:mm:ss)
poqtoken	string	Payletter recurring payment token (forward if recurringtype = Y)
cardkind	string	Card name (Transfer in case of PLCreditCard, PLCreditCardMpi, PLCreditCard_CY_)
cardno	string	Card number (only the last 4 digits are transmitted and the rest is masked) (Transfer in case of PLCreditCard, PLCreditCardMpi, PLCreditCard_CY_)
intervaltype	number	PayPal subscription billing cycle (1: DAY, 2: WEEK, 3: MONTH, 4: YEAR) (Forward if notifytype = 5)
intervalcnt	number	PayPal subscription billing interval (DAY: 1~365, WEEK: 1~52, MONTH: 1~12, YEAR: 1) (Forward if notifytype = 5)
totalcycles	number	Number of PayPal subscription charges (2~999, unlimited: 0) (Forward if notifytype = 5)
retcode	number	Result code (0 fixed)
retmsg	string	Result message (fixed empty value)

Receives the result value and executes the business logic of the Store, such as payment of goods suitable for the Store.

After completion of processing in Notification URL, please print the following string if successful.

<RESULT>OK</RESULT>

Otherwise, the notification is considered failed and resent every 5 minutes up to 10 times. (Basic 10 times, adjustable)

On success, ensure that no html and other code other than <RESULT>OK</RESULT> is exposed on the page.

To prevent forgery/falsification of the delivered result value, create a sha256 hash value and then compare and

verify the delivered hash parameter.

In addition to payment success, notification for processing completion such as cancellation/partial cancellation

and chargeback are also sent, so the store's business logic should be executed according to the notifytype parameter.

Notification delivery history can be checked in the Sales Mgmt > Notify List menu on the Store manager site..

Payment request after the first Recurring payment

The first recurring payment is requested by setting the recurringtype parameter of the Payment Request API (api/payment/request) to Y.

When the payment for this request is successful, the recurring payment request is completed. From the second payment request, payment/recurring API can be used.

(In the case of PayPal, from the second payment request, PayPal creates a payment according to the billing conditions,

and if successful, it delivers the result to Payletter, and Payletter sends a payment success notice to the store.)

Request

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"
}

Access Authority

Private

HTTP Request

POST payment/recurring

Request json data

Division	Parameter	Type	Size	M/O	Description
Division	storeid	string	20	M	Store ID
	poqtoken	string	40	M	Payletter Recurring payment token received at the time of the first recurring payment
	storeorderno	string	128	M	Store Order Number
	currency	string	3	M	Currency code (ISO 4217) Ex) USD, JPY
	amount	number		M	Payment amount (remove thousands sign) *All the currencies may include up to the second decimal place, except KRW, JPY, VND. *KRW, JPY, VND should not include any decimal place.
	pginfo	string	40	M	Payment request PG information(PG Code Table)
	payinfo	string	200	O	Additional payment information
	payerid	string	50	O	Store payer (member) ID
	custom	string	2000	O	Random value sent by store
PayPal Recurring Payment (Billing)	paypalisppflag	string	1	O	Set to ”Y” when using PayPal ISPP (If paypalisppflag=Y, payerfirstname, payerlastname, payerphone, payercountrycode, payercreatedate required data)
	payerfirstname	string	50	O	payer first name
	payerlastname	string	50	O	payer last name
	payerphone	string	20	O	Payer phone number (national notation) Ex) (042) 1123 4567)
	payercreatedate	string	30	O	Payer join day (ISO 8601 date format) Ex) 2023-04-09T19:14:55.277-0:00
	payercountrycode	string	2	O	Ipayer country code (ISO Alpha-2 Country Code) Ex) AU, KR

Response json Data

In case of success

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"
    }
}

In case of failure

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
    }
}

In case of success

Parameter	Type	Description
data	object
└ storeid	string	Store ID
└ countrycode	string	Country code
└ storeorderno	string	Store Order Number
└ amount	number	Amount of payment
└ payerid	string	Store payer (member) ID
└ poqtoken	string	Payletter recurring payment token
└ paytoken	string	Payletter payment unique number
└ paydate	string	Payletter payment time (yyyy-MM-dd HH:mm:ss)

In case of failure

Parameter	Type	Description
error	object
└ code	number	Error Code
└ message	string	Error Message
└ detail	string	Error Detail Message
└ plcode	number	Other error codes

Payment Refund

Request

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
}

Access Authority

Public

HTTP Request

POST payment/refund

Request json data

Parameter	Type	Size	M/O	Description
storeid	string	20	M	Store ID
paytoken	string	20	M	Payletter payment unique number of the payment to be canceled
currency	string	3	M	Currency code (ISO 4217) Ex) USD, JPY
amount	number		M	Cancellation amount (thousands sign removed) *All the currencies may include up to the second decimal place, except KRW, JPY, VND. *KRW, JPY, VND should not include any decimal place.
pginfo	string	40	O	PG information of the payment request for cancellation (PG Code Table)

Response json data

In case of success

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"
    }
}
        

In case of failure

HTTP 1.1 400 BadRequest
{
    "error": {
        "code": 997,
        "message": "The request is invalid.",
        "detail": "[2104]The payment transaction does not exist",
        "plcode": 997
    }
}

In case of success

Parameter	Type	Description
data	object
└ storeid	string	Store ID
└ paytoken	string	Payletter payment unique number
└ pginfo	string	PG information
└ storeorderno	string	Store Order Number
└ currency	string	Currency code
└ amount	number	Cancellation amount
└ refunddate	string	Payletter Payment Cancellation Time (yyyy-MM-dd HH:mm:ss) (For VTCDomesticBank and VTCPay, the cancellation request time is delivered, not the payment canceled time, and a cancellation notice (notifytype=2) is delivered when cancellation is completed later)

In case of failure

Parameter	Type	Description
error	object
└ code	number	Error Code
└ message	string	Error Message
└ detail	string	Error Detail Message
└ plcode	number	Other error codes

Payment Details Inquiry

Request

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
}

Access Authority

Private

HTTP Request

POST payment/cpdaesalist

Request json data

Parameter	Type	Size	M/O	Description
storeid	string	20	M	Store ID
pgcode	string	20	O	PG Code (PG Code Table)
pgsubcode	string	20	O	PG Sub Code (PG Code Table)
currency	string	3	O	Currency code (ISO 4217) Ex) USD, JPY
datefrom	string	8	M	Start Date (yyyyMMdd)
dateto	string	8	M	End Date (yyyyMMdd)
searchtype	number		M	Inquiry criteria 0: All 1: Payment (based on payment date) 2: Cancellation (based on cancellation date) 3: Partial cancellation (based on cancellation date)

Response json data

In case of success

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"
        }
    ]
}
}

In case of failure

HTTP 1.1 403 Forbidden
{
    "error": {
        "code": 993,
        "message": "You do not have authorization.",
        "detail": "Not allowed ip address.",
        "plcode": 993
    }
}

In case of success

Parameter	Type	Description
data	object
└ rowcount	object	Number of transactions
└ total	number	Total number of transactions
└ success	number	Number of success Transactions
└ cancel	number	Number of canceled transactions
└ datalist	json array	Transaction data
└ paytoken	string	Payletter payment unique number
└ pginfo	string	PG information
└ storeorderno	string	Store Order Number
└ payerid	string	Store payer (member) ID
└ amount	number	Amount of payment
└ currency	string	Currency code
└ state	number	Payment status code (1: OK, 2: Canceled, 3: Partial Cancellation)
└ ymd	string	Payment date
└ regdate	string	Registration date
└ cnldate	string	Cancellation date
└ pgtoken	string	PG transaction number (Transaction ID for PayPal)

In case of failure

Parameter	Type	Description
error	object
└ code	number	Error Code
└ message	string	Error Message
└ detail	string	Error Detail Message
└ plcode	number	Other error codes

Settlement Details Inquiry

Request

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"
}

Access Authority

Private

HTTP Request

POST settlement/detailslist

Request json data

Parameter	Type	Size	M/O	Description
storeid	string	20	M	Store ID
pgcode	string	20	O	PG Code (PG Code Table)
pgsubcode	string	20	O	PG Sub Code (PG Code Table)
currencytype	number		M	Currency type (1: Payment currency, 2: Settlement currency)
searchtype	number		M	Settlement type (1: by payment method, 2: by details)
settlestate	number		O	Settlement status (fixed value : 0)
settlesymd	string	8	M	Settlement start date (yyyyMMdd)
settleeymd	string	8	M	Settlement end date (yyyyMMdd)

Response json data

In case of success

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"
        }
    ]
}
}

In case of failure

HTTP 1.1 403 Forbidden
{
    "error": {
        "code": 993,
        "message": "You do not have authorization.",
        "detail": "Not allowed ip address.",
        "plcode": 993
    }
}

In case of success

Parameter	Type	Description
data	object
└ datalist	json array	Settlement Data
└ storeid	string	Store ID
└ settleymd	string	Settlement Date
└ pgcode	string	PG Code
└ pgsubcode	string	PG Sub Code
└ currency	string	Currency code
└ settlestate	number	Settlement status (1: Settlement, 2: Settlement scheduled)
└ paycnt	number	Number of payments
└ payamt	number	Amount of payment
└ settleamt	number	Settlement amount
└ totalfee	number	Total fee
└ vat	number	VAT
└ supplyamt	number	supply value
└ storefee	number	Store Fee
└ transactionfee	number	Transaction Fee
└ chargebackfee	number	Chargeback Fee
└ refundfee	number	Refund Fee
└ etcfee	number	other Fees
└ note	string	Remarks (fee rate or reference)
└ notedesc	string	Remark details (fee rate or reference)
└ rollingreserve	string	RollingReserve
└ paytoken	string	Payletter payment unique number

In case of failure

Parameter	Type	Description
error	object
└ code	number	Error Code
└ message	string	Error Message
└ detail	string	Error Detail Message
└ plcode	number	Other error codes

PayPal Recurring Payment(Subscription) Cancel Request

Request

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"
}

Access Authority

Public

HTTP Request

POST paypal/subscription/cancel

Request json data

Parameter	Type	Size	M/O	Description
storeid	string	20	M	Store ID
poqtoken	string	40	M	Payletter recurring payment token

Response json data

In case of success

HTTP 1.1 200 OK
{
    "data" : {
        "code" :0,
        "message":"OK"
    }
}

In case of failure

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
    }
}

In case of success

Parameter	Type	Description
data	object
└ code	number	Response Code
└ message	string	Response Message

In case of failure

Parameter	Type	Description
error	object
└ code	number	Error Code
└ message	string	Error Message
└ detail	string	Error Detail Message
└ plcode	number	Other error codes

Transaction history confirmation

Request

GET receipt/info/2024062771EFO2U4ZCKF?storeid=PL_Merchant HTTP/1.1
Host: dev-api.payletter.com
Authorization: GPLKEY PL_Merchant

Access Authority

Public

HTTP Request

GET receipt/info/{paytoken}

Request json data

Parameter	Type	Size	M/O	Description
storeid	string	20	M	Store ID

Response json data

In case of success

HTTP 1.1 200 OK
{
    "receipt_url" : {
        "https://dev-api.payletter.com/receipt/info/2024062771EFO2U4ZCKF?storeid=PL_Merchant"
}
        

In case of failure

HTTP 1.1 400 BadRequest
{
    "error": {
        "code": 997,
        "message": "The request is invalid.",
        "detail": "The payment does not exist.",
        "plcode": 997
    }
}

In case of success

Parameter	Type	Description
receipt_url	string	Transaction history confirmation URL

In case of failure

Parameter	Type	Description
error	object
└ code	number	Error Code
└ message	string	Error Message
└ detail	string	Error Detail Message
└ plcode	number	Other error codes

Daily Payment Details Inquiry

Request

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
}

Access Authority

Private

HTTP Request

POST payment/transaction/list

Request json data

Parameter	Type	Size	M/O	Description
storeid	string	20	M	Store ID
pgcode	string	20	O	PG Code (PG Code Table)
pgsubcode	string	20	O	PG Sub Code (PG Code Table)
currency	string	3	O	Currency code (ISO 4217) Ex) USD, JPY
date	string	8	M	Search date (yyyyMMdd)
searchtype	number		M	Inquiry criteria 0: All 1: Payment (based on payment date) 2: Cancellation (based on cancellation date) 3: Partial cancellation (based on cancellation date)
paytoken	string	20	O	Payletter payment unique number

Response json data

In case of success

HTTP 1.1 200 OK
{
    "data" : {
        "rowcount": {
            "total": 2,
            "success": 2,
            "cacnel": 0
        },
    "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"
        }
    ]
}
}

In case of failure

HTTP 1.1 403 Forbidden
{
    "error": {
        "code": 993,
        "message": "You do not have authorization.",
        "detail": "Not allowed ip address.",
        "plcode": 993
    }
}

In case of success

Parameter	Type	Description
data	object
└ rowcount	object	Number of transactions
└ total	number	Total number of transactions
└ success	number	Number of success Transactions
└ cancel	number	Number of canceled transactions
└ datalist	json array	Transaction data
└ paytoken	string	Payletter payment unique number
└ pginfo	string	PG information
└ storeorderno	string	Store Order Number
└ payerid	string	Store payer (member) ID
└ amount	number	Amount of payment
└ currency	string	Currency code
└ state	number	Payment status code (1: OK, 2: Canceled, 3: Partial Cancellation)
└ ymd	string	Payment date
└ regdate	string	Registration date
└ cnldate	string	Cancellation date
└ pgtoken	string	PG transaction number (Transaction ID for PayPal)

In case of failure

Parameter	Type	Description
error	object
└ code	number	Error Code
└ message	string	Error Message
└ detail	string	Error Detail Message
└ plcode	number	Other error codes

Error Code

Success or failure for API request can be checked by HTTP StatusCode

In case of StatusCode 200 OK, request is in success, Except for this case, please refer to following StatusCode.

Table of Error code

HTTP Response	Error Code	Error Message	Description
400	997	The request is invalid	request parameter error
401	998	Authentication token is missing or incorrect	authentication error
403	993	You do not have authorization	authentication error
406	990	Detail Error Message	Error processing business logic
500	999	Internal Error	system error

Appendix

PG Code Table

PGInfo	PGCode	PGSubCode	Description
PLCreditCard	PL	CreditCard	Unauthorized credit card payment
PLCreditCard_CY	PL	CreditCard_CY	Cybersource credit card payment
PLCreditCardMpi	PL	CreditCardMpi	Authorized credit card payment
PLUnionPay	PL	UnionPay	UnionPay
PLUnionPay_HC	PL	UnionPay_HC	UnionPay
CCCherryCredits	CC	CherryCredits	CherryCredits (Prepaid card)
CodaPay12Call	CodaPay	12Call	12 Call (Prepaid card)
Codapay7ElevenPH	CodaPay	7ElevenPH	7Eleven (Convenience store payment)
CodaPay7ElevenTHA	CodaPay	7ElevenTHA	7Eleven (Convenience store payment)
CodapayAlfamart	CodaPay	Alfamart	Alfamart (Convenience store payment)
CodapayBankTransfer	CodaPay	BankTransfer	Bank Transfer
CodaPayBankTransferTHA	CodaPay	BankTransferTHA	Bank Transfer
CodaPayCarrierBillingAIS	CodaPay	CarrierBillingAIS	AIS (Mobile payment)
CodaPayCarrierBillingDTAC	CodaPay	CarrierBillingDTAC	DTAC (Mobile payment)
CodapayCarrierBillingMaxis	CodaPay	CarrierBillingMaxis	Maxis (Mobile payment)
CodaPayCarrierBillingTMH	CodaPay	CarrierBillingTMH	TMH (Mobile payment)
CodapayDokuWallet	CodaPay	DokuWallet	Doku Wallet (E-Wallet)
CodaPayDolfin	CodaPay	Dolfin	Dolfin (E-Wallet)
CodaPayEtisalat	CodaPay	Etisalat	Etisalat (Mobile payment)
CodaPayFawry	CodaPay	Fawry	Fawry (E-Wallet)
CodaPayGcash	CodaPay	Gcash	Gcash (E-Wallet)
CodapayIndomaret	Codapay	Indomaret	Indomaret (Convenience store payment)
CodaPayKplus	CodaPay	Kplus	Kplus (Bank Transfer)
CodaPayOoredooKuwait	CodaPay	OoredooKuwait	Ooredoo (Mobile payment)
CodaPayPromptpay	CodaPay	Promptpay	PromptPay (Bank Transfer)
CodaPayRabbitLINEPay	CodaPay	RabbitLINEPay	Rabbit LINE Pay (E-Wallet)
CodaPayShopeePayTH	CodaPay	ShopeePayTH	ShopeePay (E-Wallet)
CodaPayTrueMoneyCashCard	CodaPay	TrueMoneyCashCard	True Money Cash Card (Prepaid card)
CodaPayTrueMoneyWallet	CodaPay	TrueMoneyWallet	True Money Wallet (E-Wallet)
CodaPayZainBahrain	CodaPay	ZainBahrain	Zain (Mobile payment)
CodaPayZainKuwait	CodaPay	ZainKuwait	Zain (Mobile payment)
DegicaBancontact	Degica	Bancontact	Bancontact (E-Wallet)
DegicaBankTransfer	Degica	BankTransfer	BankTransfer
DegicaBitCash	Degica	BitCash	BitCash (Prepaid card)
DegicaCreditCard	Degica	CreditCard	CreditCard
DegicaEPS	Degica	EPS	EPS (Bank Transfer)
DegicaGiroPay	Degica	GiroPay	GiroPay (Bank Transfer)
DegicaIdeal	Degica	Ideal	iDEAL (Bank Transfer)
DegicaJapanMobile	Degica	JapanMobile	JapanMobile (Mobile payment)
DegicaKonbini	Degica	Konbini	Konbini (Convenience store payment)
DegicaLinePay	Degica	LinePay	LINE Pay (E-Wallet)
DegicaMerPay	Degica	MerPay	MerPay (E-Wallet)
DegicaMultibanco	Degica	Multibanco	Multibanco (Bank Transfer)
DegicaMyBank	Degica	MyBank	MyBank (Bank Transfer)
DegicaNetCash	Degica	NetCash	NetCash (Prepaid card)
DegicaPayEasy	Degica	PayEasy	PayEasy (Online Banking)
DegicaPayPay	Degica	PayPay	PayPay (E-Wallet)
DegicaPaysafecard	Degica	Paysafecard	Paysafecard (EPIN)
DegicaPrzelewy24	Degica	Przelewy24	Przelewy24 (Bank Transfer)
DegicaSofortBanking	Degica	SofortBanking	Sofort (Bank Transfer)
DegicaWebMoney	Degica	WebMoney	WebMoney (Prepaid card)
ICBAlipay	ICB	Alipay	Alipay (E-Wallet)
MOLAIS 12 Call Prepaid	MOL	AIS 12 Call Prepaid	AIS 12 Call (Prepaid card)
MOLFPX	MOL	FPX	FPX (Online Banking)
MOLLoadCentral	MOL	LoadCentral	LoadCentral (Prepaid card)
MOLMaybank2U	MOL	Maybank2U	Maybank (Online Banking)
MOLMOLPoint_PP	MOL	MOLPoint_PP	Razer Gold PIN (Prepaid card)
MOLTrueMoney	MOL	True Money	True Money (Prepaid card)
MOLzGold-MOLPoints	MOL	zGold-MOLPoints	Razer Gold Wallet (E-Wallet)
MyCardPPCard	MyCard	PPCard	MyCard (Prepaid card)
PaypalExpressCheckout	Paypal	ExpressCheckout	PayPal (E-Wallet)
VTCDomesticBank	VTC	DomesticBank	Bank Transfer (Bank Transfer)
VTCVTCPay	VTC	VTCPay	VTCPay (E-Wallet)
WeChatPayH5Payment	WeChatPay	H5Payment	WeChatPay (E-Wallet)
WeChatPayQRCodePayment	WeChatPay	QRCodePayment	WeChatPay (E-Wallet)