NAV Navbar
한국어 ENGLISH

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
Naver Pay
SamsungPay
applepay		 Mobile Phone
Phone Bill(KT)		 Voucher
Culture Voucher
Smart Culture Voucher
Book Culture Voucher
Happymoney Voucher 		Mobile POP
Teen Cash
CVS Cash
Eggmoney
Transportation Card (T-money, Cashbee)
Transportation Card (EZL) 		Authentication

How to Apply to

Partnership Inquiry : globalpg@payletter.com
1. Apply for Payletter Service in Online
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 : 211.115.120.167

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 O O O D+180 100
PAYCO O O O D+180 100
SSGPAY X O O D+180 100
Naver Pay X O O D+180 100
SamsungPay X O O D+180 100
applepay X O X D+180 1
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
Voucher X O X D+24 1
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(EZL) X O X D+24 10

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)
3. Need to Tmoney APP (Tmonet Charging Payment Module) on the google paly store when Mobile Tmoney payment.
4. Need to EZL APP (EZL Charging Payment Module) on the google paly store when Mobile EZL payment.
5. In case of SSGPAY, shoud be member’s mobile number of SSGPAY.
6. SSGPAY, SamsungPay and Toss, service_name is must value.
7. Allowed to use : Hyundai Card
   ○ Usable to above iOS 11.3, MacOS 10.12.6, Safari 11.1 on MacOS.
   ○ iPhone, iPad : Recommend to use Safari browser.(Support all browser)
   ○ MacBock : Support to Safari browser only.
   ○ It can be registered a Hyundai Card to digital wallet by contacting the Hyundai Card customer service if user have a WiFi-only iPad.

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. No actual payment are made through test payments with Applypay.
5. For Phone Bill test, there is no actual phone call in the test environment.
6. For Internet banking, vouchers, pre-paid card tests, please contact us.
7. Credit card payment test in test environment, mobile authentication number is not available. (Possible to put any number for testing)

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 Recurring Payment
v1.0/payments/autopay POST PAYMENT Recurring Payment Approval
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
Node.js 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 20 Client ID
service_name string 20 Name of Service (Mandatory - SSGPAY, SamsungPay, Toss)
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 (Only alphanumeric characters are allowed)
amount Necessary number Payment Amount
Exception) In case pgcode is voucher, it's only allowed to set 5000/10000/50000 as a value.
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 Recurring Payment or not
receipt_flag string 1 Show a page for inputting cash receipt or not (Y/N)
(* Only available in case of contract for cash receipt. Not applicable to foreign corporations.)
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 - 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/KFTC (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/KFTC (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 (Tmoney/Cashbee), Mobile
company_name_flag string 1 Display of merchant name within the card payment authentication window (Y: Display merchant name, N: Display Payletter, Applied Credit Card only)

[Process of InApp payment]

General Details

When integrating in-app payments, Payletter’s payment page should be implemented as mobile WebView and
should be able to call external app for the payments of card companies and each institutions.

An app scheme should be added to call external apps. Please find the attached file for the
app scheme values based on the mobile OS.

Android

Using the shouldOverrideUrlLoading() function of WebViewClient when moving to external apps

1) If @Override is not added to the redefined shouldOverrideUrlLoading() function,
net::ERR_UNKNOWN_URL_SCHEME error may occur.

2) In case of verify whether an app is installed, search the package information before
the call startActivity(). In case of checking package information before calling startActivity()
to confirm if the app is installed Remove the installation check logic and immediately call startActivity().

3) When calling startActivity, if an ActivityNotFoundException(Message : No Activity found to
handle Intent) is thrown, the app is assumed to be uninstalled and the user is directed to
the market to install the app.


Notes for developing on Android 11 (API 30)

According to Google's security policy, if you set your app's targetSdkVersion to 30 or higher,
you must take the following actions.

1) Set the usesCleartextTraffic property to true in the AndroidManifest.xml file to avoid the net:
ERR_CLEARTEXT_NOT_PERMITTED error.

2) To check the status of other packages within the app, define the package in the "queries"
element of the AndroidManifest.xml for visibility.

3) Please see the attachments for the package names of the card companies and vaccines.

ios

After getting the URL of the payment page through the REST API, you can use the WEBVIEW method to open the checkout page.

Register the necessary App Scheme in info.plist for calling external apps from the webview.

If you list the App Scheme in info.plist, a window asking to run an external app
will pop up and it will be automatically processed.


1) In iOS 9.0 or higher, LSApplicationQueriesSchemes is added as a security policy enhancement.
When opening external apps using URL schemes, this is to increase security by allowing
only schemes registered in the whitelist to be opened. To open a card company/institution app,
you need to add a whitelist (allowlist, info.plist).

2) In iOS 6.0 or higher, Safari's cookie preferences have been changed to allow sessions to be
maintained only when always set, which may cause a session expiration error.
Please set cookies to always allow.

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.

When a user proceeds with a payment, the payment result is returned to the return_url and callback_url (only in case of successful payment) that you provided in the payment request.

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
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 Recurring 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 Recurring Payment (creditcard, payco) only
payhash string sha256 hash value to verify parameter
Sha256(user_id +amount + tid +API Key for payment)
(Recurring payment) When it is requested without a payment amount
, Sha256 will be 'user_id + billkey + 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 for Virtual Accont
account_holder string Account Name
bank_code string Bank Code
bank_name string Name of Bank
issue_tid string Virtual Account Issuance 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 Cash 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
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,
    "method_info" : "",
    "coupon_amount" : 0,
    "receipt_possible_amount" : 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.

The CallbackUrl content, which is provided additionally along with the ReturnUrl data, is in the following format:

Parameter Type Description
method_info string Combined payment (ex: Creditcard + (rechargeable) Point)
(Applied Payment Method: Naver Pay, kakaopay, SSGPAY, PAYCO, TOSS)
ex) navercard : card
    navermoney : money
    kakaocard : card
    kakaomoney : money
    ssgpaycms : cms
    ssgpaycard : card
    ssgpaymoney : money
    tosscard : card
    tosspoint : money
    payco : The method used for payment
coupon_amount number Amount of coupon (Applied PAYCO only)
receipt_possible_amount number The amount eligible for cash receipt for rechargeable point of SSGPAY, Naver Pay
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.

[Guidance on Processing return_url and callback_url]

[return_url]

The return_url operates through a page redirection method, which can be affected by the payer's device environment or network conditions.

Therefore, the following situations may occur:

  - The payer may close the payment window or refresh the page before receiving the return_url

  - The return_url transmission may not be smooth depending on the network environment

Consequently, it is recommended that the merchant's delivery of goods and key business logic after payment completion be processed through the callback_url.

[callback_url]

The payment result is transmitted only when the payment is successful.

This minimizes the possibility of transaction discrepancies between the merchant and Payletter.

As it operates through server-to-server communication, it allows for more stable data reception without being affected by network issues or device environments.

[Recommended Processing Guidelines

It is more stable to process the callback_url and return_url with independent logic.

While the callback_url is typically processed first, the order of reception may vary depending on network conditions. Therefore, it is recommended to handle these two URLs separately.

Recurring Payment

Recurring Payment is to request and process transactions at a time desired by the merchant after the first transaction.

1.Request of recurring payment

Request recurring payment through the Payment Request API(v1.0/payments/request) and set
whether to request recurring payment with autopay_flag parameter.

2.Issue a billkey of recurring payment

A billkey for recurring payment will be issued.

3.Request approval for recurring payment

A merchant can request approval with billkey through recurring payment API(v1.0/payments/autopay)
at the time the merchant needs the recurring payment.


Client Information for Test Environment

The recurring payment can be tested with the merchant ID and API Key below.

Parameter Value
ClientID auto_test
API Key (PAYMENT) NDBBREM2RjhEMENBQ0ZGODZDNkEyNEQxQUIxRTY5QUE=
API Key (SEARCH) QjBCMjZBNUNBMEMzRDVDNzY2NkQ2OTU3QzFEQkM2QkY=

[Payment Request without a payment amount]

If you would like to register the recurring payment without payment, request payment with the amount of ‘0’.

Only the billkey will be issued and you can request recurring payment approval with the billkey.

As actual payment was not occurred, the payment data will not be sent to callback_url.

The value of payhash is Sha256(user_id+billkey+API Key for PAYMENT).

setting is needed. Please contact to sales person who is in charge of.


Client Information for Test Environment

The recurring payment can be tested with the merchant ID and API Key below.

Parameter Value
ClientID auto_test1
API Key (PAYMENT) NUMzRDJFQzVERkRBNTQzQjY1MkUzMTQ3NThFREU2Mzg=
API Key (SEARCH) QUI4MUEyOEYxQTZFMTAxQjE4NjY3M0I5MjBDMzk1OEM=

Recurring Payment Approval

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

[Mobile recurring payment approval policy]

1. The payment should be requested as same amount and date.

2. The recurring payment approval request is available after 1month (about 30days) from the first payment.

3. The recurring payment approval is not available if there is no history of payment in last month.

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 20 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 (Only alphanumeric characters are allowed)
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 Recurring Payment Billkey for re-payment (First time response parameter for Recurring 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 Recurring 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

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",   
    "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 20 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
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 20 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 20 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
order_no string 50 Order number (To be used only when viewing the details of a specific payment transaction.)

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

Payment Status Check

Request

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

{
    "client_id":"pay_test",
    "order_no":"pay_test2023118164578"
}

Key Type

PAYMENT

HTTP Request

POST v1.0/payments/status

Request Parameters

Parameter Default Type Size Description
client_id Necessary string 20 Client ID
order_no Necessary string 50 Order Number

Response Parameters

Response (success)

HTTP 1.1 200 OK
{
    "code" :0,
    "message":"ok",
    "client_id":"pay_test",
    "order_no":"pay_test2023118164578",
    "token":"170202154314200189",   
    "tid":"tpay_test-202312082315563",
    "status_code":5
}

Response (failure)

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

In case of success

Parameter Type Description
code string Result
message string Message
client_id string Client ID
order_no string Order Number
token string Payment Token
tid string Unique Payment Number
status_code number Payment status code
( 1.Create payment, 2.Entering payment (Open the payletter payment process page), 3.Payment progress , 4.Payment failure , 5.Payment success)

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 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 20 Store ID

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
400 997 Various error message. Invalid request (request parameter verification required)
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
voucher 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 EZL
kakaopay Kakaopay
payco Payco
checkpay Checkpay
toss Toss
ssgpay SSGPAY
naverpay Naver Pay
samsungpay SamsungPay
applepay applepay

Table of CardCode

Card Code Namd of Cardcompany
P001 비씨(페이북) (BC Paybook)
P002 KB Pay(국민) (Kookmin)
P003 하나 (Hana)
P004 삼성 (Samsung)
P005 신한 (Shinhan)
P006 현대 (Hyundai)
P007 롯데 (Lotte)
P008 NH (Nonghyup)
P009 씨티(구.한미) (City)
P011 우리 (Woori)
P012 신협 (ShinHyup)
P013 광주 (Kwangju)
P014 전북 (JeonBuk)
P015 제주 (Jeju)
P016 우체국 (Post)
P017 MG 새마을금고 (MG Community Credit Cooperatives)
P018 저축은행 (Saving Bank)
P019 카카오뱅크 (Kakao Bank)

App-Schema sample source

OS Sample Source
Android Download
iOS Download