Payletter 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. 260 partners in 25 countries
2. Stable payment environment with 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. Exceptional response service compared to other payment services. (98.7% successful with response)

Payment Method and Additional Service

Finance	Simple Payment	Telecom	Voucher	Prepaid Card	Additional Service
Credit card Internet Banking Virtual account	TOSS kakaopay PAYCO SSGPAY Bank Account L.pay Naver Pay SamsungPay Chai SmilePay	Mobile Phone Phone Bill(KT)	Culture Voucher Smart Culture Voucher Book Culture Voucher Happymoney Voucher	Mobile POP Teen Cash CVS Cash Eggmoney Transportation Card (T-money, Cashbee)	Authentication

How to Apply to

Partnership Inquiry : globalpg@payletter.com
1. Apply for Payletter Service in Online (Sign up)
2. Service Review View Unavailable Service
3. Guarantee Insurance - Inquiry: Seoul Guarantee Insurance Seocho Office [Guaranteeinsur Corp / +82-2-3486-0021 or +82-2-3487-0035]
4. Submit a Contract and required document View a contract
5. Review for Each Payment Method - Credit Card/Simple Payment/Mobile: 2 Weeks in general - Internet Banking: 1~2 Days in general - Voucher/Prepaid Card: 3~5 Days in general
6. Make a Payment for Registration Fee and Finish an application

Required Document

Division	Corporate Business	Individual Business
Contract Document	1. 2 Copies of PayoneQ Service Agreement 2. 1 Copy of personal information Agreement
Required Document	1. 1 Copy of Certificate of Business 2. 1 Original copy of Certificate of Corporate Seal Impression (Issued within 3 months) 3. 1 Copy of Bankbook in name of Corporate 4. 1 Copy of Usesignet Seal (In case of being stamped with usesignet in Contract.) 5. 1 Original Copy of Guarantee Insurance	1. 1 Copy of Certificate of Business 2. 1 Copy of Certificate of Seal Impression in Name of Representative (Issued within 3 months) 3. 1 Copy of Bankbook in name of Representative or Corporate 4. 1 Original Copy of Guarantee Insurance

Integration preparation

API HTTPS Protocol

Supportive HTTPS Protocol

Payletter API HTTPS supports TLS 1.2 or higher.

Firewall

Please add inbound IP in order to receive a callback 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. Guide for Contract

Please find out API Key in admin page for merchant.

Each API Key for Payment and Search will be separately issued.

Please send API Key for HttpRequestHeader authorization as follows.

Authorization: PLKEY {APIKey of Client}

API Endpoint URL

Environment	Address
TEST	https://testpgapi.payletter.com/
LIVE	https://pgapi.payletter.com/

It is available to reach the callback_url through only 80,443 port on test environment. So it is require to firewall registration, if you want to use other port.

Please let us know the your IP and port through the technical service team email (poqdev@payletter.com).

Client Information for Test Environment

Integration test in test environment is available through API Key before registering.

Parameter	Value
Client ID	pay_test
API Key (PAYMENT)	MTFBNTAzNTEwNDAxQUIyMjlCQzgwNTg1MkU4MkZENDA=
API Key (SEARCH)	MUI3MjM0RUExQTgyRDA1ODZGRDUyOEM4OTY2QTVCN0Y=

Information by Payment Method

Payment Method	Recurring Payment	Cancellation	Partial Cancellation	Cancellation Period	Minimum Approval Amount (KRW)
Credit Card	O	O	O	D+180	100
Bank Transfer	X	O	O	the day of transaction	1000
Virtual Account	X	X	X	Non-available	500
TOSS	X	O	O	D+180	1
kakaopay	X	O	O	D+180	100
PAYCO	O	O	O	D+180	100
SSGPAY	X	O	O	D+180	100
L.pay	X	O	O	D+180	100
Naver Pay	X	O	O	D+180	100
SamsungPay	X	O	O	D+180	100
Chai	O	O	O	Following to client policy	100
CHECKPAY	O	O	X	D+30	1000
Mobile Phone	O	O	O	Within the month of transaction	10
Phone Bill	X	O	X	Within the month of transaction	10
Culture Voucher	X	O	O	D+24	1
Smart Culture Voucher	X	O	X	D+24	1
Book Voucher	X	O	O	D+24	1
Happymoney Voucher	X	O	O	D+24	1
Mobile POP Card	X	O	O	D+24	10
Teencash	X	O	X	D+24	10
Convenience Cash	X	O	X	D+24	10
Eggmoney	X	O	X	D+24	10
Transportation Card(T-money, Cashbee)	X	O	O	D+24	10
Transportation Card(Cashbee)	X	O	X	D+24	10
SmilePay	X	O	O	Credit Card : D+180 Cash : D+365	100

Notice

Payment Method

1. For TOSS test, browsers above TLS 1.1 is supported.
2. In case of Naver Pay and Smile Pay, according to the selected payment option by the end-user the value of PG Code is set differently in the request of Callback URL.    (Naver Pay : navercard or naverpoint)    (SmilePay : smilecard or smilecash)
3. Need to Tmoney APP (Tmonet Charging Payment Module) on the google paly store when Mobile Tmoney payment.
4. In case of SSGPAY, shoud be member’s mobile number of SSGPAY.
5. SSGPAY and SamsungPay, service_name is must value.
6. Automatic payment of Chai, only support mobile enviroment

Payment Testing

1. For creditcard test, VAN(Creditcard) communication is not supported.
2. For kakaopay, mobile payment and SSGPAY test, the actual payments occurs in the test environment.    (Those payments are cancelled automatically at the same day of the payments.)
3. For virtual account test, the step of “acquiring virtual account number” is the limit.    Cancellation is not available if you make payment to the virtual account.    (If you need to test the step of actual payment, please contact us.)
4. For Phone Bill test, there is no actual phone call in the test environment.
5. For Internet banking, vouchers, pre-paid card tests, please contact us.
6. Credit card payment test in test environment, mobile authentication number is not available. (Possible to put any number for testing)
7. For Chai test, please use test application and test bank account.    More details of this, please refer to the url as below    (https://appdistribution.firebase.google.com/pub/i/7cbb497fd568d25e)

Process of InApp payment

       InApp payment, need to add Schema Refer to App-Schema sample source

1. Android
Need some cording for calling up computer virus vaccine during the payment process. It is for App Card, ISP etc Please take one of the following two measures as a must, in case of developing and updating of package of Android 11 (API30) 1) Deifne a package name on <queries>    - Modify file of AndroidManifest.xml    - Define package on <queries> of Manifast file    - Please refer to Attached file for package name of card and vaccine 2) Add exception logic as WebViewClient shouldOverrideUrlLoading()    - Modify of shouldOverrideUrlLoading() method logic which is re-deined.    - In case of verify whether an app is installed, search the package information     before the startActivity() call.    - If ActivityNotFoundException(Message : No Activity found to handle Intent) error occured when call the startActivity(),process should be     go to the market for app installation.
2. iOS
Get payment URL through the REST API and then open through the WEBVIEW method Faced App-Schema issue, to show how to slove that 1) Add Array Schema chart "LSApplicationQueriesSchemes" on info.plist 2) Add payment methods in Xcode >LSApplicationWueriesSchemes >item

Technical Support

poqdev@payletter.com

For a quicker response, please provide detailed information such as integration environment, client ID, invoice number, time of transaction, token and related others. It would be useful for support.

API Information

List of API

URL	METHOD	KEY TYPE	FEATURES
v1.0/payments/request	POST	PAYMENT	PAYMENT REQUEST
v1.0/payments/request	POST	PAYMENT	AUTOMATIC PAYMENT
v1.0/payments/autopay	POST	PAYMENT	AUTOMATIC PAYMENT (Re-payment request)
v1.0/payments/request	POST	PAYMENT	AUTOMATIC PAYMENT (Verification Only)
v1.0/payments/cancel	POST	PAYMENT	PAYMENT CANCELLATION
v1.0/payments/cancel/partial	POST	PAYMENT	PARTIAL CANCELLATION
v1.0/cashreceipt/issue/{tid}	POST	PAYMENT	ISSUE CASH RECEIPT (E-INVOICE)
v1.0/payments/transaction/list	GET	SEARCH	SEARCH PAYMENT HISTORY
v1.0/receipt/info/{tid}	GET	SEARCH	TRANSACTION HISTORY CONFIRMATION

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 /v1.0/payments/request HTTP/1.1
Host: testpgapi.payletter.com
Authorization: PLKEY MTFBNTAzNTEwNDAxQUIyMjlCQzgwNTg1MkU4MkZENDA=
Content-Type: application/json

{
    "pgcode" : "mobile",
    "user_id":"test_user_id",
    "user_name":"tester",    
    "service_name":"payletter",    
    "client_id":"pay_test",
    "order_no":"1234567890",
    "amount":1000,
    "product_name":"test product",    
    "email_flag":"Y",
    "email_addr":"payletter@payletter.com",
    "autopay_flag":"N",    
    "receipt_flag":"Y",
    "custom_parameter":"this is custom parameter",    
    "return_url":"https://testpg.payletter.com/result",
    "callback_url":"https://testpg.payletter.com/callback",
    "cancel_url":"https://testpg.payletter.com/cancel"
}

Key Type

PAYMENT

HTTP Request

POST v1.0/payments/request

Request Parameters

Parameter	Default	Type	Size	Description
pgcode	Necessary	string	20	Payment method Code Refer to Appendix
client_id	Necessary	string	10	Client ID
service_name		string	20	Name of Service (Mandatory - SSGPAY, SamsungPay)
user_id	Necessary	string	50	Paid User(Member) ID (e-mail, English and number are available)
user_name		string	20	Name of User
order_no		string	40	Order Number
amount	Necessary	number		Payment Amount
taxfree_amount		number		tax-free should be same as amount compound tax
tax_amount		number		VAT (if it is null, (amount-tax-free)/11 : Automatically calculated the result rounded up to after the decimal point )
product_name	Necessary	string	100	Name of Product (Not allowed to use control character such as <, > , carriage return (\n))
email_flag		string	1	Receive e-mail for payment details or not (Y/N)
email_addr		string	100	Receiving e-mail address for payment details.
autopay_flag		string	1	Automatic payment or not
receipt_flag		string	1	Show a page for inputting invoice or not (Y/N) (*Only available in case of contract for e-invoice)
keyin_flag		string	1	Credit Card Payment by hand (*Separate Contracts is necessary)
custom_parameter		string	1024	Random value transmitted by client ex) Return to payment result in case user Information, Order Information and any other details are set up
return_url	Necessary	string	256	Linked webpage URL after completing payment
callback_url	Necessary	string	256	Callback URL to receive payment success results (Process payment in success)
cancel_url		string	256	Linked webpage URL after clicking a cancellation button Naver Pay,SamsungPay,L.Pay - It's not redirect to cancel_url.
inapp_flag		string	1	In-app or not (Y/N)
app_return_url		string	256	Linked webpage URL in case of payment with ISP/KFTF (Account Transfer) from In-app (Ex:IOS - App Address://, Android - App Address://ISPSuccess)
app_cancel_url		string	256	Linked webpage URL after payment cancellation with ISP/KFTF (Account Transfer) from In-app (Ex:IOS - App Address://, Android - App Address:ISPCancel)
expire_date		string	8	Set expiry date for virtual account (YYYYMMDD)
expire_time		string	4	Set expiry time for virtual account (HHMM)
disposable_cup_deposit		number		Disposable cup deposit (* Allowe to part of payments, Not allowe to partial cancellation) * Allowe to part of payments : Credit Card , Naver Pay, Kakaopay, Toss, SSGPay, Transportation Card, Mobile

Response Parameters

Response (success)

HTTP 1.1 200 OK
{
    "token" : 153438847514600001,
    "online_url": "https://testpg.payletter.com/pgsvc/hub.asp?location=online&token=153438847514601",
    "mobile_url": "https://testpg.payletter.com/pgsvc/hub.asp?location=mobile&token=153438847514601" 
}

Response (failure)

HTTP 1.1 401 Unauthorized
{
    "code": 998,
    "message": "Authentication token is missing or incorrect"
}

In case of success

Parameter	Type	Description
token	number	Payment Authentication Token
online_url	string	Payment Page Call URL in PC
mobile_url	string	Payment Page Call URL in Mobile

In case of failure

Parameter	Type	Description
code	number	Error Code
message	string	Error Message

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 return_url transmitted by payment request.

We recommend to process payment completion (business logic of client) in callback_url.

Please refer to following instruction on process of return_url and callback_url.

* callback_url integration is essential for the payment methods as TOSS, Checkpay, Virtual account.

Return URL

Payment result is transmitted to POST parameter in Request.

In case of success

Parameter	Type	Description
code	string	Result
message	string	Message
user_id	string	Paid User(Member) ID (e-mail, English and number are available)
user_name	string	Name of User
order_no	string	Order Number
service_name	string	Name of Service
product_name	string	Name of Product
custom_parameter	string	Transmitted value from Client
tid	string	Unique Payment Number
cid	string	Approval Number
amount	number	Requested Payment Amount
taxfree_amount	number	tax-free should be same as amount compound tax
tax_amount	number	VAT (if it is null, (amount-tax-free)/11 : Automatically calculated the result rounded up to after the decimal point)
pay_info	string	Additional Information for Payment
pgcode	string	Name of payment gateway
billkey	string	Automatic Payment Billkey for re-payment
domestic_flag	string	Domestic/Overseas Credit Card (Y: Overseas, N: Domestic)
transaction_date	string	Transaction Date (YYYY-MM-DD HH:MM:SS)
install_month	number	Month of Installment
card_info	string	Card Number (Middle of 6 digit under masking) general payment (creditcard, payco) and automatic payment (creditcard, payco) only
payhash	string	sha256 hash value to verify parameter sha256(user_id +amount + tid +API Key for payment) * Part of payment methods are not received. (For example, virtual count)
disposable_cup_deposit	number	Requested disposable cup deposit
Virtual account
account_no	string	Number of Virtual Account
account_name	string	Depositor Name
account_holder	string	Account Name
bank_code	string	Bank Code
bank_name	string	Name of Bank
issue_tid	string	Created Approval Number
expire_date	string	Expiry Date (ex: 20210808)
expire_time	string	Expiry Time (ex: 1130)
Cash Receipt
cash_receipt_code	string	Fail Result of Receipt
cash_receipt_message	string	Fail Message
cash_receipt_type	string	Use for(01:Tax Deduction, 02:Proof of expense)
cash_receipt_issue_type	string	Issuing Cash Receipt (1:By Buyer, 2:By oneself)
cash_receipt_cid	string	Approval Number of Receipt
cash_receipt_payer_sid	string	Identification Number(Cellphone Number, Business License)
cash_receipt_deal_no	string	Transferred order number with issued cash receipt

In case of failure

Parameter	Type	Description
code	string	Result
message	string	Message
user_id	string	Paid User(Member) ID (e-mail, English and number are available)
order_no	string	Order Number
service_name	string	Name of Service
product_name	string	Name of Product
custom_parameter	string	Transmitted value from Client

Callback URL

{ 
    "user_id":"test_user_id", 
    "user_name":"tester", 
    "amount":1000, 
    "tid":"tpay_test-201808162396515", 
    "cid":"20180816150336996237", 
    "order_no":"1234567890", 
    "service_name":"payletter", 
    "product_name":"testproduct", 
    "custom_parameter":"this is custom parameter", 
    "transaction_date":"2018-08-16 15:03:52", 
    "pay_info":"0101234567", 
    "pgcode":"mobile", 
    "domestic_flag":"", 
    "billkey":"",
    "card_info" : "457973******1234",
    "payhash" : "9E078A29E6435959A07ED2E8415789234D18250434BAF2C185C2EF3012C77E92",
    "disposable_cup_deposit" : 0,

    "cash_receipt":
    {
        "code":"0",
        "message":"message",
        "cid":"xE7555915",
        "deal_no":"1234567890",
        "issue_type":"1",
        "payer_sid":"01027160590",
        "type":"01"
    }
}

Only in the case of successful payments will be offered the result of payment as a format of json.

*Data of cash receipt from Callback URL will be provided as same below.

Parameter	Type	Description
cash_receipt	object
└ code	string	Result
└ message	string	Message
└ cid	string	Approval Number of Receipt
└ deal_no	string	Order number with issued cash receipt
└ issue_type	string	Issuing Cash Receipt (1:By Buyer, 2:By oneself)
└ payer_sid	string	Identification Number(Cellphone Number, Business License)
└ type	string	Usage (06:No need to issue, 01:Tax Deduction, 02:Proof of expense)

It is preceded with logic such as charging, purchase and etc through transmitted Callback URL and needed to output following json string in case of success.

{"code":0, "message":"Failure reason in case of failure"}

In case of success, please transmit 0. On the contrary, please transmit other value except for 0.

If code is non-zero, the notification is considered it as failure and is retransmitted up to 20 times every 5 minutes.

The result can be found out in field of search failed notification history in client admin page (https://manager.payletter.com)

To protect parameter transmitted to Return Url / CallBack Url against forgery and falsification, please match with payhash after creating sha256 hash value.

Automatic Payment

At first, it should be started Payment Request (v1.0/payments/request). If success, can got a billkey from the Payletter.

Generally, first Automatic Payment consist of Verification + Payment

More details, please refer to Payment Request

Automatic payment (Re-payment request)

Means that customer requests automatic payment with a Billkey which before got.

[Mobile Phone Re-payment]

Mobile automatic re-payment can do after 30 day which got billkey.

If the amount is different or the automatic payment period is different, payment will not be possible with the same billkey and automatic payment will fail.

In other words, if there is no payment history in the previous month, you cannot apply for automatic payment.

Request

POST /v1.0/payments/autopay HTTP/1.1
Host: testpgapi.payletter.com
Authorization: PLKEY MTFBNTAzNTEwNDAxQUIyMjlCQzgwNTg1MkU4MkZENDA=
Content-Type: application/json

{
    "pgcode" : "mobile",
    "client_id":"pay_test",
    "service_name":"payletter",    
    "user_id":"test_user_id",
    "user_name":"tester",    
    "order_no":"1234567890",
    "amount":1000,
    "product_name":"testproduct",    
    "billkey":"tbpay_test201801012359590002",
    "ip_addr":"127.0.0.1"
}

Key Type

PAYMENT

HTTP Request

POST v1.0/payments/autopay

Request Parameters

Parameter	Default	Type	Size	Description
pgcode	Necessary	string	20	Payment method CodeRefer to Appendix
client_id	Necessary	string	10	Client ID
service_name		string	20	Name of Service
user_id	Necessary	string	50	Paid User(Member) ID (e-mail, English and number are available)
user_name		string	20	Name of User
order_no		string	50	Order Number
amount	Necessary	number		Payment Amount
taxfree_amount		number		tax-free should be same as amount compound tax
tax_amount		number		VAT (if it is null, (amount-tax-free)/11 : Automatically calculated the result rounded up to after the decimal point)
product_name	Necessary	string	100	Name of Product (Not allowed to use control character such as <, > , carriage return (\n))
billkey	Necessary	string	40	Automatic Payment Billkey for re-payment (First time response parameter for automatic payment)
ip_addr	Necessary	string	30	Requested IP
disposable_cup_deposit		number		Disposable cup deposit (* Allowe to part of payments, Not allowe to partial cancellation) * Allowe to part of payments : Credit Card, Kakaopay

Response Parameters

Response (success)

HTTP 1.1 200 OK
{
    "tid" :"tpay_test201801012359590003",
    "cid":"123456",
    "amount":1000,
    "billkey":"tbpay_test201801012359590002",
    "transaction_date":"2018-01-01 23:59:59"
}

Response (failure)

HTTP 1.1 401 Unauthorized
{
    "code": 998,
    "message": "Authentication token is missing or incorrect"
}

In case of success

Parameter	Type	Description
tid	string	Unique Payment Number
cid	string	Approval Number
amount	number	Payment Amount
billkey	string	Automatic Payment Billkey for re-payment
transaction_date	string	Date of Transaction (yyyy-MM-dd hh:mm:ss)

In case of failure

Parameter	Type	Description
code	number	Error code
message	string	Error Message

Automatic payment (Verification only)

At first, customer get billkey without any payment. After then, can request automatic payment through the billkey at any time.

For this function use, please contact us.

[Process]

1. Call the "Request API" , after than it will be returned certification URL.(It will be set same as user enviroment PC or Mobile automatically)

2. Call the "Request API" and finish the Verification. (Please refer to Search Payment History about return parameters).

3. When customer need payment, call the "Automatic payment API" with billkey which was returned.

4. In case of Verification only, does not delivered callback_url.

Request

POST /v1.0/payments/request HTTP/1.1
Host: testpgapi.payletter.com
Authorization: PLKEY MTFBNTAzNTEwNDAxQUIyMjlCQzgwNTg1MkU4MkZENDA=
Content-Type: application/json

{
    "pgcode" : "creditcard",
    "user_id":"test_user_id",
    "user_name":"Tester",    
    "service_name":"payletter",    
    "client_id":"pay_test",
    "order_no":"1234567890",
    "amount":0,
    "product_name":"Test Product"",    
    "email_flag":"N",
    "autopay_flag":"Y",     
    "custom_parameter":"this is custom parameter",    
    "return_url":"https://testpg.payletter.com/result",
    "callback_url":"https://testpg.payletter.com/callback",
    "cancel_url":"https://testpg.payletter.com/cancel"
}

Key Type

PAYMENT

HTTP Request

POST v1.0/payments/request

Request Parameters

Parameter	Default	Type	Size	Description
pgcode	Necessary	string	20	Payment method Code (Code : creditcard)
client_id	Necessary	string	10	Client ID
service_name		string	20	Name of Service
user_id	Necessary	string	50	Paid User(Member) ID (email, English and number are available)
user_name		string	20	Name of User
order_no		string	50	Order Number
amount	Necessary	number		Payment Amount
product_name	Necessary	string	100	Name of product (Not allowed to use control character such as <, > , carriage return (\n))
email_flag		string	1	Get payment information email (Y:Use, N:Not Use)
email_addr		string	100	email address
autopay_flag		string	1	Use automatic Payment function(Y: Use)
custom_parameter		string	1024	Random value transmitted by client ex) Return to payment result in case user Information, Order Information and any other details are set up
return_url	Necessary	string	256	Linked webpage URL after completing payment
callback_url	Necessary	string	256	Callback URL to receive payment success results (Process payment in success)
cancel_url		string	256	Linked webpage URL after clicking a cancellation button
inapp_flag		string	1	In-app or not (Y/N)

Response Parameters

Response (success)

HTTP 1.1 200 OK
{
    "token" :153438847514600001,
    "online_url":"https://testpg.payletter.com/pgsvc/hub.asp?location=online&token=153438847514601",
    "mobile_url":"https://testpg.payletter.com/pgsvc/hub.asp?location=mobile&token=153438847514601",
}

Response (failure)

HTTP 1.1 401 Unauthorized
{
    "code": 998,
    "message": "Authentication token is missing or incorrect"
}

In case of success

Parameter	Type	Description
token	number	Payment Authentication Token
online_url	string	Payment Page Call URL in PC
mobile_url	string	Payment Page Call URL in Mobile

In case of failure

Parameter	Type	Description
code	number	Error Code
message	string	Error Message

Automatic Payment (Verification only) Result

Return URL

Payment result is transmitted to POST parameter in Request.

In case of success

Parameter	Type	Description
code	string	Result
message	string	Message
user_id	string	Paid User(Member) ID (e-mail, English and number are available)
user_name	string	Name of User
order_no	string	Order Number
service_name	string	Name of Service
product_name	string	Name of Product
custom_parameter	string	Transmitted value from Client
pay_info	string	Card infomation
pgcode	string	Payment method Code (creditcard, mobile)
billkey	string	Automatic Payment Billkey for re-payment
card_info	string	Card Number (Middle of 6 digit under masking) Only when requesting automatic payment
payhash	string	sha256 hash value to verify parameter Sha256(user_id + billkey + API Key for payment)

In case of failure

Parameter	Type	Description
code	string	Result
message	string	Message
user_id	string	Paid User(Member) ID (e-mail, English and number are available)
order_no	string	Order Number
service_name	string	Name of Service
product_name	string	Name of Product
custom_parameter	string	Transmitted value from Client

Payment Cancellation

Request

POST /v1.0/payments/cancel HTTP/1.1
Host: testpgapi.payletter.com
Authorization: PLKEY MTFBNTAzNTEwNDAxQUIyMjlCQzgwNTg1MkU4MkZENDA=
Content-Type: application/json

{
    "pgcode" : "mobile",
    "client_id":"pay_test",
    "user_id":"test_user_id",
    "tid":"tpay_test2018010123595900001",   
    "amount" : 1000,
    "ip_addr":"127.0.0.1"
}

Key Type

PAYMENT

HTTP Request

POST v1.0/payments/cancel

Request Parameters

Parameter	Default	Type	Size	Description
pgcode		string	20	Payment method Code Refer to Appendix
client_id	Necessary	string	10	Client ID
user_id	Necessary	string	50	Paid User(Member) ID (e-mail, English and number are available)
tid	Necessary	string	40	Unique Payment Number
amount	Necessary	number		Cancelled Amount
ip_addr	Necessary	string	30	Request IP

Response Parameters

Response (success)

HTTP 1.1 200 OK
{
    "tid" :"tpay_test201801012359590003",
    "cid":"123456",
    "amount":1000,
    "cancel_date":"2018-01-01 23:59:59"
}

Response (failure)

HTTP 1.1 401 Unauthorized
{
    "code": 998,
    "message": "Authentication token is missing or incorrect"
}

In case of success

Parameter	Type	Description
tid	string	Unique Payment Number
cid	string	Approval Number
amount	number	Cancelled Amount
cancel_date	string	Date of Cancellation(YYYY-MM-DD HH:MM:SS)

In case of failure

Parameter	Type	Description
code	number	Error code
message	string	Error Message

Partial Cancellation

Parts of payment methods are only available.

Please contact person in charge in advance.

Request

POST /v1.0/payments/cancel/partial HTTP/1.1
Host: testpgapi.payletter.com
Authorization: PLKEY MTFBNTAzNTEwNDAxQUIyMjlCQzgwNTg1MkU4MkZENDA=
Content-Type: application/json

{
    "pgcode" : "mobile",
    "client_id":"pay_test",
    "user_id":"test_user_id",
    "tid":"tpay_test2018010123595900001",   
    "amount" : 1000,
    "taxfree_amount" : 100,
    "tax_amount" : 20,
    "ip_addr":"127.0.0.1"
}

Key Type

PAYMENT

HTTP Request

POST v1.0/payments/cancel/partial

Request Parameters

Parameter	Default	Type	Size	Description
pgcode	Necessary	string	20	Payment method Code Refer to Appendix
client_id	Necessary	string	10	Client ID
user_id	Necessary	string	50	Paid User(Member) ID (e-mail, English and number are available)
tid	Necessary	string	40	Unique Payment Number
amount	Necessary	number		Cancelled Amount
taxfree_amount		number		tax-free should be same as amount compound tax
tax_amount		number		VAT (if it is null, (amount-tax-free)/11 : Automatically calculated the result rounded up to after the decimal point)
ip_addr	Necessary	string	30	Request IP

Response Parameters

Response (success)

HTTP 1.1 200 OK
{
    "tid" :"tpay_test201801012359590003",
    "cid":"123456",
    "amount":1000,
    "cancel_date":"2018-01-01 23:59:59"
}

Response (failure)

HTTP 1.1 401 Unauthorized
{
    "code": 998,
    "message": "Authentication token is missing or incorrect"
}

In case of success

Parameter	Type	Description
tid	string	Unique Payment Number
cid	string	Approval Number
amount	number	Cancelled Amount
cancel_date	string	Date of Cancellation(YYYY-MM-DD HH:MM:SS)

In case of failure

Parameter	Type	Description
code	number	Error Code
message	string	Error Message

Search Payment History

Request

    GET /v1.0/payments/transaction/list?client_id=pay_test&date=20180918&date_type=transaction HTTP/1.1
Host: testpgapi.payletter.com
Authorization: PLKEY MUI3MjM0RUExQTgyRDA1ODZGRDUyOEM4OTY2QTVCN0Y=

Key Type

SEARCH

HTTP Request

GET v1.0/payments/transaction/list

Request Parameters

Parameter	Default	Type	Size	Description
client_id	Necessary	string	10	Client ID
date	Necessary	string	8	Searching Date
date_type	Necessary	string	20	transaction: Transaction Date, settle : Payment/Cancellation Date
pgcode		string	20	Payment Method Code

date_type : Standard with Searching Transaction Status

transaction : Transaction Date

Extract payment status (success or cancellation) through transaction searched by standard of payment date (For example, cancelled payment will be extracted as 1 Cancelled Payment)

settle : Payment/Cancellation Date

Extract approval status in standard of payment date and cancellation in standard of Cancellation date (For example, cancelled payment will be extracted as 1 approval transaction in payment date and 1 cancelled payment in cancellation date)

Response Parameters

Response (success)

HTTP 1.1 200 OK
{
    "total_count": 2,
    "list": [
        {
            "pgcode": "oncash",
            "user_id": "test_user_id",
            "user_name": "tester",
            "tid": "tpay_test-201809142506687",
            "cid": "2506686",
            "amount": 1000,
            "order_no": "1234567890",
            "product_name": "testproduct",
            "status_code": 1,
            "transaction_date": "2018-09-14 17:25:36",
            "cancel_date": "2018-09-18 09:52:29"
        },
        {
            "pgcode": "mobile",
            "user_id": "test_user_id",
            "user_name": "tester",
            "tid": "tpay_test-201809182509659",
            "cid": "20180918095312998861",
            "amount": 100,
            "order_no": "1234567890",
            "product_name": "testproduct",
            "status_code": 2,
            "transaction_date": "2018-09-18 09:53:25",
            "cancel_date": "2018-09-18 09:54:01"
        }
    ]
}

Response (failure)

HTTP 1.1 401 Unauthorized
{
    "code": 998,
    "message": "Authentication token is missing or incorrect"
}

In case of success

Parameter	Type	Description
total_count	number	Total number of searching
list	JSON Array
pgcode	string	Payment Method Code
user_id	string	User ID
user_name	string	Name of User
tid	string	Unique Payment Number
cid	string	Approval Number
amount	number	Payment amount(For cancellation status, cancelled amount)
order_no	string	Order Number
product_name	string	Name of Product
status_code	number	Status(0:Approval, 1:Cancellation, 2:Partial Cancellation)
transaction_date	string	Date of Payment
cancel_date	string	Date of Cancellation

In case of failure

Parameter	Type	Description
code	number	Error code
message	string	Error Message

Issue Cash Receipt (e-Invoice)

Request

POST /v1.0/cashreceipt/issue/tpay_test-201904097449610 HTTP/1.1
Host: testpgapi.payletter.com
Authorization: PLKEY MTFBNTAzNTEwNDAxQUIyMjlCQzgwNTg1MkU4MkZENDA=
Content-Type: application/json

{
    "client_id":"pay_test",
    "type":"0",    
    "tax_flag":"N",    
    "return_url":"https://testpg.payletter.com/result"
}

Key Type

PAYMENT

HTTP Request

POST v1.0/cashreceipt/issue/{tid}

Request Parameters

Parameter	Default	Type	Size	Description
client_id	Necessary	string	10	Store ID
type		string	1	Use for (0:Select by user, 1:Tax Deduction, 2:Proof of expense)
tax_flag		string	1	VAT (N:Include, Y:Not Include)
return_url	Necessary	string	256	Page URL to be connected upon issuing cash receipt

Response Parameters

Response (success)

HTTP 1.1 200 OK
{
    "receipt_url" :"https://testpg.payletter.com/PGSVC/Receipt/ReceiptForm.asp?id=tpay_test-201904097449610&type=1&taxflag=N&returnurl=https://testpg.payletter.com/result&token=155494822989700006"
}

Response (failure)

HTTP 1.1 401 Unauthorized
{
    "code": 998,
    "message": "Authentication token is missing or incorrect"
}

In case of success

Parameter	Type	Description
receipt_url	string	Page URL for issuing cash receipt

In case of failure

Parameter	Type	Description
code	number	Error Code
message	string	Error Message

Transaction History Confirmation

Request

GET /v1.0/receipt/info/tsktest1-202201039368273/?client_id=sktest1&amount=50001&transaction_date=20220103 HTTP/1.1
Host: testpgapi.payletter.com
Authorization: PLKEY NDhBNDJGNUY0QzI5RjY5NjAwMDdDREI0Q0Q4RDVGOTY==

Key Type

SEARCH

HTTP Request

GET v1.0/receipt/info/{tid}

Request Parameters

Parameter	Default	Type	Size	Description
client_id	Necessary	string	10	Store ID
amount	Necessary	number		Payment Amount
transaction_date	Necessary	string	8	Transaction Date(YYYYMMDD)

Response Parameters

Response (Success)

HTTP 1.1 200 OK
{
    "receipt_url" :"https://testpg.payletter.com/PGSVC/AllTheGate/Receipt_All.asp?id=72720c6d230e662b|001|4|3230323230313230313435393434343037383664613733393939b3a96f05b2f37aea1b64c823d9cc57767510d8e0e351a4c1635cefc354af7e2a0418a9ffce0c8ecac4b7c28ceefb3a905d82ee1dcab6b3d4bc18393cb5547ba9eec2b92fe4"
}

Response (failure)

HTTP 1.1 401 Unauthorized
{
    "code": 998,
    "message": "Authentication token is missing or incorrect"
}

In case of success

Parameter	Type	Description
receipt_url	string	Transaction History Confirmation URL

In case of failure

Parameter	Type	Description
code	number	Error Code
message	string	Error Message

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
401	998	Authentication token is missing or incorrect.	Authentication Error
403	993	Yon do not have authorization.	Authentication Error
405	995	Not authorized method.	Method error such as POST / GET and etc
406	2000 ~ 5000	Various error message	Error occurred in business logic processing
500	999	Internal server error	System Error

Appendix

Table of PGCode

PGCode	Note
creditcard	Credit Card
banktransfer	Internet Banking (Korea Financial Telecommunications & Clearings Institute)
virtualaccount	Virtual Account
mobile	Mobile Payment
book	Book Voucher
culture	Culture Voucher
smartculture	Smart Culture Voucher
happymoney	Happymoney Voucher
mobilepop	Mobile POP
teencash	Teen Cash
tmoney	Transportation Card
cvs	CVS Cash
eggmoney	Eggmoney
oncash	Oncash
phonebill	Phonebill
cashbee	Cashbee
kakaopay	Kakaopay
payco	Payco
checkpay	Checkpay
toss	Toss
ssgpay	SSGPAY
lpay	L.Pay
naverpay	Naver Pay
samsungpay	SamsungPay
chai	Chai
smilepay	SmilePay

App-Schema sample source

OS	Sample Source
Android	Download
iOS	Download