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 SmilePay 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 : 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 |
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 |
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. 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 and SamsungPay, 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 | 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 |
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) | |
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 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 | 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 - 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 |
||
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.
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,
"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, SmilePay, PAYCO, TOSS(Planned)) ex) navercard : card navermoney : money kakaocard : card kakaomoney : money ssgpaycms : cms ssgpaycard : card ssgpaymoney : money smilecard : card smilecash : 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.
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 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.
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",
"sequence_no":1,
"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 | |
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) 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",
"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 |
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 | 40 | 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=
Content-Type: application/json
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 |
smilepay | SmilePay |
applepay | applepay |
App-Schema sample source
OS | Sample Source |
---|---|
Android | Download |
iOS | Download |