개요
이 장에서는 LINE Pay의 기능에 대해 설명한다.
LINE Pay 개요
본 문서는 LINE Pay와 연동하려는 offline 가맹점의 개발자를 위한 문서이다
- 그림 1 LINE Pay Overview
연동환경
이 장에서는 LINE Pay와 연동하기 전에 요구되는 사항과 준비사항에 대해 설명한다.
시스템 요구사항
LINE Pay의 API 연동은 LINE Pay와 가맹점 server간 통신을 기본으로 한다. 따라서 가맹점은 별도의 Payment Server를 구성하여 연동하여야 한다.
Pay Tech 기술 연동 지원 연락처
연동 중 문의 사항이 있거나 내부 오류가 발생한 경우 연락 가능한 각 국가 별 기술 지원 연락처는 아래와 같다.
| 명칭 | 연락처 | 적용국가 |
|---|---|---|
| LINE Pay Japan | dl_tech_support_jp@linecorp.com | 일본 |
| LINE Pay Thailand | dl_tech_support_th@linecorp.com | 태국 |
| LINE Pay Taiwan | dl_tech_support_tw@linecorp.com | 대만 |
| LINE Pay Global | dl_tech_support_global@linecorp.com | 그 외 나머지 국가 |
연동 전 준비사항
LINE Pay Payment API 연동하기 전에 가맹점은 가맹점 등록 및 연동에 필요한 키 정보를 확인해야 한다.
가맹점 등록
LINE Pay와 결제 연동을 위해서는 가맹점 등록이 꼭 이뤄져야 한다.
가맹점 등록 가이드는 가맹점 센터에서 다운받아 등록 절차를 확인한다.
(위치 : https://pay.line.me/developers/documentation/download/tech?locale=ko_KR – LINE Pay 가맹점 등록 가이드)
연동을 위한 준비
- 가맹점 Payment Server의 white list 등록
a. LINE Pay에서는 가맹점 Payment Server의 IP를 등록하여, 가맹점 별로 고유하게 부여된 channel id에서 접근 가능한 서버를 제한한다.
b. IP 등록은 “가맹점 센터(https://pay.line.me)에 로그인- 결제연동관리 – 결제서버 IP 관리”에서 할 수 있다. - channel id와 channel secret 확인
a. API 연동에 있어 필수 정보로 “가맹점 센터(https://pay.line.me)에 로그인 – 결제연동관리 – 연동키관리” 에서, 확인할 수 있다.
b. 해당 정보는 가맹점에게 고유하게 부여된 정보이므로, 외부에 노출되지 않도록 유의해야 한다. - 결제 연동 가능 통화 확인
a. LINE Pay 가맹점은 API 연동시, 하나의 통화를 사용할 수 있으며 지원 가능한 통화는 아래와 같다. “가맹점 센터(https://pay.line.me)에 로그인 – 기본정보 관리 – 가맹점정보”에서 확인할 수 있다.
- JPY
- USD
- THB
- TWD
연동 흐름
Payment Sequence diagram
결제를 만드는 과정을 설명한다.
대상 API
- Payment API(sequence diagram - 4번)
그림 2 Payment Sequence diagram
Payment Sequence diagram 설명
- LINE Pay 회원은 가맹점 단말기에게 MyCode(Barcode/QR Code)를 보여준다.
- 가맹점 단말기는 MyCode(Barcode/QR Code)를 읽는다.
- 가맹점 단말기는 가맹점 Payment Server로 결제 요청을 한다.
- 가맹점 Payment Server는 Payment API를 호출한다.
- API 응답 정보를 확인하여, 결제 완료 여부를 확인한다.
- 가맹점 Payment Server는 결제 결과를 가맹점 단말기에게 응답한다.
- LINE Pay 서버는 결제 결과(성공/실패)를 Push 또는 LINE Pay Official Account Message로 LINE Pay회원에게 알린다.
After Payment Sequence
결제를 만드는 과정 이후 API는 모두 API 한 번의 호출로 처리된다.
대상 API
- VOID
- REFUND
- CAPTURE
- Authorization/Payment Details
API Specifications (Payment)
이 장에서는 LINE Pay 이용자로부터 “oneTImeKey”(LINE Pay main menu상에 “MyCode” 메뉴)를 읽어 결제를 완료까지 사용되는 API들에 대해 설명한다
- Payment
- Payment Status Check
Payment
LINE Pay app 에서 제공하는 MyCode를 가맹점 device가 읽어, 결제를 처리하는 API이다.
Specification
표 1 Payment API Endpoint
| 항목 | 설명 |
|---|---|
| Endpoint URL | Sandbox : https://sandbox-api-pay.line.me/v2/payments/oneTimeKeys/pay Product : https://api-pay.line.me/v2/payments/oneTimeKeys/pay |
| Method | POST |
| Request Header | Required - Content-Type: application/json; charset=UTF-8 - X-LINE-ChannelId: {연동 정보 - channelId} - X-LINE-ChannelSecret: {연동 정보 - channelSecretKey} 가맹점 설정 정보에서 필수 여부 설정 - X-LINE-MerchantDeviceType : device type - X-LINE-MerchantDeviceProfileId : device’s serial no |
| Timeout | Read : 40초 |
표 2 Payment API Request Body
| Name | Type | Mandatory | description |
|---|---|---|---|
| productName | string(4000) | Y | product name |
| amount | number(38) | Y | amount to payment |
| currency | string(3) | Y | currency to payment |
| orderId | string(100) | Y | OrderId given by merchant device. (unique on merchant-side) |
| oneTimeKey | string(12) | Y | Result of scanning and reading QR/Bar code information given by LINE Pay App. oneTimeKey의 유효시간은 5분으로, LINE Pay 회원이 mycode 화면에 접근하여 QR/Bar code를 확인한 시점부터 5분간 유효하다. |
| capture | boolean | N | Whether to capture or not. A boolean value (true or false) default is true. true(default) : payment authorization and captrue are handled at once false : payment is completed only after it is authorized then separately capture by calling "Capture API" |
| Extra fields | |||
| extras.addFriends | object[] | N | 친구 추가 목록
"addFriends" : [{ |
| extras.branchName | string(200) | N | 결제를 요청하는 지점 (100자 넘어서면 100자만 표현됨) |
| extras.promotionRestriction | object | N | 프로모션 제한 정보
"useLimit": 100, "rewardLimit": 100 } |
표 3 Payment API Response Body
| Name | Type | Mandatory | description |
|---|---|---|---|
| returnCode | string(4) | Y | Result code generated by LINE Pay - 0000 : API 요청 성공 - 그 외의 응답 코드는 본 문서의 “부록- API별 응답코드”를 확인한다. |
| returnMessage | string(100) | Y | Result messages or reason for failure |
| info.transactionId | number(19) | Y | LINE Pay's transaction id |
| info.orderId | string(100) | Y | OrderId given by merchant device. (unique on merchant-side) |
| info.transactionDate | string(20) | Y | Transaction Date(ISO8601 UTC). - Time Format : yyyy-MM-dd'T'HH:mm:ss'Z' * reference : https://en.wikipedia.org/wiki/ISO_8601 |
| info.payInfo[].method | string(20) | Y | Payment method used - CREDIT_CARD - BALANCE - DISCOUNT |
| info.payInfo[].amount | number(38) | Y | payment amount |
| info.balance | number(38) | N | remained balance after payment. |
| info.authorizationExpireDate | string(20) | N | Authorization Expire Date(ISO8601 UTC). - Time Format : yyyy-MM-dd'T'HH:mm:ss'Z' when the payment status is "AUTHORIZATION"(capture=false). * reference : https://en.wikipedia.org/wiki/ISO_8601 |
Request
POST https://sandbox-api-pay.line.me/v2/payments/oneTimeKeys/pay HTTP/1.1
Host: sandbox-api-pay.line.me
Content-Type: application/json
X-LINE-ChannelId: {channel id}
X-LINE-ChannelSecret: {channel secret}
X-LINE-MerchantDeviceProfileId: {DEVICE_PROFILE_ID}
{
"productName": "test product",
"amount": 100,
"currency": "THB",
"orderId": "merchant_test_order_1",
"oneTimeKey": "123456789012",
"extras" : {
"addFriends" : [
{
"type" : "LINE_AT",
"idList" : ["@aaa"]
}
],
"branchName" : "test_branch_1",
"branchId" : "branch1"
}
}
Response Body - 결제 완료
{
"returnCode": "0000",
"returnMessage": "success",
"info": {
"transactionId": "2019010112345678910",
"orderId": "test_order_#1",
"transactionDate": "2019-01-01T01:01:00Z",
"payInfo": [{
"method": "BALANCE",
"amount": 10
}, {
"method": "DISCOUNT",
"amount": 5
}],
"balance": 9900,
}
}
Payment Status Check
read timeout이 발생하여 결제의 최종 상태를 알 수 없는 경우 사용하는 API이다.
- 결제의 유효시간은 최대 20분으로, Payment API 응답 시부터 유효시간이 계산된다. 따라서, 가맹점은 최대 20분까지 결제 상태 확인해야 한다. 20분이 초과되었다면, 해당 거래는 유효시간이 초과한 결제로 최종적으로 완료되지 않은 결제 건이 된다.
- 해당 API는 7일 이내에 발생한 결제에 대해서 최종 상태를 체크할 수 있다.
Specification
표 4 Payment Status Check API Endpoint
| 항목 | 설명 |
|---|---|
| Endpoint URL | Sandbox : https://sandbox-api-pay.line.me/v2/payments/orders/{orderId}/check Product : https://api-pay.line.me/v2/payments/orders/{orderId}/check |
| Method | GET |
| Request Header | Required - Content-Type: application/json; charset=UTF-8 - X-LINE-ChannelId: {연동 정보 - channelId} - X-LINE-ChannelSecret: {연동 정보 - channelSecretKey} 가맹점 설정 정보에서 필수 여부 설정 - X-LINE-MerchantDeviceType : device type - X-LINE-MerchantDeviceProfileId : device’s serial no |
| Timeout | Read : 20초 |
표 5 Payment Status Check API URI Parameters
| Name | Type | Mandatory | description |
|---|---|---|---|
| orderId | string(100) | Y | - 가맹점이 결제 요청시 전달한 주문번호 - URI Path 상에 존재하는 파라미터로 꼭 인코딩해서 전달해야 한다 * reference : https://en.wikipedia.org/wiki/Percent-encoding |
표 6 Payment Status Check API Response Body
| Name | Type | Mandatory | description |
|---|---|---|---|
| returnCode | string(4) | Y | result code - 0000 : API 요청 성공 - 그 외의 응답 코드는 본 문서의 “부록- API별 응답코드”를 확인한다. |
| returnMessage | string(100) | Y | result messages |
| info.status | string(20) | Y | payment status - COMPLETE : payment completed. - terminated status - FAIL : payment failed. - terminated status - AUTH_READY: Wait for user confirmation - CANCEL : payment canceled by user * 참고 : “COMPLETE” 또는 “FAIL” 인 경우, 추가로 응답되는 정보가 존재한다. * CANCEL의 경우 ReturnCode는 1165이다. |
| case "info.status" : "COMPLETE" | |||
| info.orderId | string(100) | Y | OrderId given by merchant device. (unique on merchant-side) |
| info.transactionDate | string(20) | Y | Transaction Date(ISO8601 UTC). - Time Format : yyyy-MM-dd'T'HH:mm:ss'Z' * reference : https://en.wikipedia.org/wiki/ISO_8601 |
| info.payInfo[].method | string(20) | Y | Payment method used - CREDIT_CARD - BALANCE - DISCOUNT |
| info.payInfo[].amount | number(38) | Y | payment amount |
| info.balance | number(38) | N | remained balance after payment. |
| info.authorizationExpireDate | string(20) | N | Authorization Expire Date(ISO8601 UTC). - Time Format : yyyy-MM-dd'T'HH:mm:ss'Z' when the payment status is "AUTHORIZATION"(capture=false). * reference : https://en.wikipedia.org/wiki/ISO_8601 |
| case "info.status" : "FAIL" | |||
| info.failReturnCode | string(4) | Y | Fail result code - 응답 코드는 본 문서의 “부록- API별 응답코드”를 확인한다. - Payment API의 응답코드와 동일한 응답코드이다. |
| info.failReturnMessage | string(100) | Y | Fail result messages |
| case "info.status" : "AUTH_READY" | |||
| info.orderId | string(100) | Y | OrderId given by merchant device. (unique on merchant-side) |
| info.transactionId | number(19) | Y | LINE Pay's transaction id |
Example
Request
- “orderId” 가 “test_order_#1” 라면,
GET https://sandbox-api-pay.line.me/v2/payments/orders/test_order_#1/check HTTP/1.1
Host: sandbox-api-pay.line.me
Content-Type: application/json
X-LINE-ChannelId: {channel id}
X-LINE-ChannelSecret: {channel secret}
X-LINE-MerchantDeviceProfileId: {DEVICE_PROFILE_ID}
Response Body - Status가 “COMPLETE”인 경우
{
"returnCode": "0000",
"returnMessage": "success",
"info": {
"status": "COMPLETE",
"transactionId": "2019010112345678910",
"orderId": "test_order_#1",
"transactionDate": "2019-01-01T01:01:00Z",
"payInfo": [{
"method": "BALANCE",
"amount": 10
}, {
"method": "DISCOUNT",
"amount": 5
}],
"balance": 9900
}
}
Response Body - Status가 “FAIL”인 경우
{
"returnCode": "0000",
"returnMessage": "success",
"info": {
"status": "FAIL",
"failReturnCode": "1142",
"failReturnMessage" : "Insufficient balance remains."
}
}
API Specifications (After Payment)
이 장에서는 결제가 완료된 이후, 가맹점 주문 상황에 따라 결제를 환불하거나 내역을 조회하는 API들에 대해 설명한다.
- Void
- Capture
- Refund
- Authorization Details
- Payment Details
Void
인증 거래를 무효 처리하는 API 이다.
Specification
표 7 Void API Endpoint
| 항목 | 설명 |
|---|---|
| Endpoint URL | Sandbox : https://sandbox-api-pay.line.me/v2/payments/orders/{orderId}/void Product : https://api-pay.line.me/v2/payments/orders/{orderId}/void |
| Method | POST |
| Request Header | Required - Content-Type: application/json; charset=UTF-8 - X-LINE-ChannelId: {연동 정보 - channelId} - X-LINE-ChannelSecret: {연동 정보 - channelSecretKey} 가맹점 설정 정보에서 필수 여부 설정 - X-LINE-MerchantDeviceType : device type - X-LINE-MerchantDeviceProfileId : device’s serial no |
| Timeout | Read : 20초 |
표 8 Void API URI Parameters
| Name | Type | Mandatory | description |
|---|---|---|---|
| orderId | string(100) | Y | - 가맹점이 결제 요청시 전달한 주문번호 - URI Path 상에 존재하는 파라미터로 꼭 인코딩해서 전달해야 한다 * reference : https://en.wikipedia.org/wiki/Percent-encoding |
표 9 Void API Response Body
| Name | Type | Mandatory | description |
|---|---|---|---|
| returnCode | string(4) | Y | Result code generated by LINE Pay - 0000 : API 요청 성공 - 그 외의 응답 코드는 본 문서의 “부록- API별 응답코드”를 확인한다. |
| returnMessage | string(100) | Y | Result messages or reason for failure |
Example
Request
- “orderId” 가 “test_order_#1” 라면,
POST https://sandbox-api-pay.line.me/v2/payments/orders/test_order_#1/void HTTP/1.1
Host: sandbox-api-pay.line.me
Content-Type: application/json
X-LINE-ChannelId: {channel id}
X-LINE-ChannelSecret: {channel secret}
X-LINE-MerchantDeviceProfileId: {DEVICE_PROFILE_ID}
Response - 결제완료
{
"returnCode": "0000",
"returnMessage": "success"
}
Capture
인증 거래를 매입 처리하는 API 이다.
Specification
표 10 Capture API Endpoint
| 항목 | 설명 |
|---|---|
| Endpoint URL | Sandbox : https://sandbox-api-pay.line.me/v2/payments/orders/{orderId}/capture Product : https://api-pay.line.me/v2/payments/orders/{orderId}/capture |
| Method | POST |
| Request Header | Required - Content-Type: application/json; charset=UTF-8 - X-LINE-ChannelId: {연동 정보 - channelId} - X-LINE-ChannelSecret: {연동 정보 - channelSecretKey} 가맹점 설정 정보에서 필수 여부 설정 - X-LINE-MerchantDeviceType : device type - X-LINE-MerchantDeviceProfileId : device’s serial no |
| Timeout | Read : 20초 |
표 11 Capture API URI Parameters
| Name | Type | Mandatory | description |
|---|---|---|---|
| orderId | string(100) | Y | - 가맹점이 결제 요청시 전달한 주문번호 - URI Path 상에 존재하는 파라미터로 꼭 인코딩해서 전달해야 한다 * reference : https://en.wikipedia.org/wiki/Percent-encoding |
표 12 Capture API Request Body
| Name | Type | Mandatory | description |
|---|---|---|---|
| amount | number(38) | Y | amount to capture |
| currency | string(3) | Y | currency to capture |
| Extra fields | |||
| extras.promotionRestriction | object | N | 프로모션 제한 정보
"promotionRestriction" : { |
표 13 Capture API Response Body
| Name | Type | Mandatory | description |
|---|---|---|---|
| returnCode | string(4) | Y | Result code generated by LINE Pay - 0000 : API 요청 성공 - 그 외의 응답 코드는 본 문서의 “부록- API별 응답코드”를 확인한다. |
| returnMessage | string(100) | Y | Result messages or reason for failure |
| info.transactionId | number(19) | Y | LINE Pay's transaction id |
| info.orderId | string(100) | Y | OrderId given by merchant device. (unique on merchant-side) |
| info.payInfo[].method | string(20) | Y | Payment method used - CREDIT_CARD - BALANCE - DISCOUNT - POINT |
| info.payInfo[].amount | number(38) | Y | payment amount |
Example
Request
- “orderId” 가 “test_order_#1” 라면,
POST https://sandbox-api-pay.line.me/v2/payments/orders/test_order_#1/capture HTTP/1.1
Host: sandbox-api-pay.line.me
Content-Type: application/json
X-LINE-ChannelId: {channel id}
X-LINE-ChannelSecret: {channel secret}
X-LINE-MerchantDeviceProfileId: {DEVICE_PROFILE_ID}
{
"amount": "100"
"currency": "THB",
"extras" : {
"promotionRestriction": {
"useLimit": 20,
"rewardLimit": 20
}
}
}
Response
{
"returnCode": "0000",
"returnMessage": "success",
"info": {
"transactionId": "2019010112345678910",
"orderId": "test_order_#1",
"transactionDate": "2019-01-01T01:01:00Z",
"payInfo": [{
"method": "BALANCE",
"amount": 95
}, {
"method": "DISCOUNT",
"amount": 5
}]
}
}
Refund
결제완료(매입된 데이터) 이후 환불을 처리하는 API이다.
Specification
표 14 Refund API Endpoint
| 항목 | 설명 |
|---|---|
| Endpoint URL | Sandbox : https://sandbox-api-pay.line.me/v2/payments/orders/{orderId}/refund Product : https://api-pay.line.me/v2/payments/orders/{orderId}/refund |
| Method | POST |
| Request Header | Required - Content-Type: application/json; charset=UTF-8 - X-LINE-ChannelId: {연동 정보 - channelId} - X-LINE-ChannelSecret: {연동 정보 - channelSecretKey} 가맹점 설정 정보에서 필수 여부 설정 - X-LINE-MerchantDeviceType : device type - X-LINE-MerchantDeviceProfileId : device’s serial no |
| Timeout | Read : 20초 |
표 15 Refund API URI Parameters
| Name | Type | Mandatory | description |
|---|---|---|---|
| orderId | string(100) | Y | - 가맹점이 결제 요청시 전달한 주문번호 - URI Path 상에 존재하는 파라미터로 꼭 인코딩해서 전달해야 한다 * reference : https://en.wikipedia.org/wiki/Percent-encoding |
표 16 Refund API Request Body
| Name | Type | Mandatory | description |
|---|---|---|---|
| refundAmount | number(38) | N | amount to refund. - Full refund if this parameter is not passed |
| Extra fields | |||
| extras.promotionRestriction | object | N | 프로모션 제한 정보
"useLimit": 100, "rewardLimit": 100 } |
표 17 Refund API Response Body
| Name | Type | Mandatory | description |
|---|---|---|---|
| returnCode | string(4) | Y | Result code generated by LINE Pay - 0000 : API 요청 성공 - 그 외의 응답 코드는 본 문서의 “부록- API별 응답코드”를 확인한다. |
| returnMessage | string(100) | Y | Result messages or reason for failure |
| info.refundTransactionId | number(19) | Y | LINE Pay's refund transaction id |
| info.refundTransactionDate | string(20) | Y | Refunded Transaction Date(ISO8601 UTC). - Time Format : yyyy-MM-dd'T'HH:mm:ss'Z' * reference : https://en.wikipedia.org/wiki/ISO_8601 |
- 부분 환불 시 1115 error 응답이 오는 경우
- 쿠폰을 사용한 거래거나, 사용자 수수료가 존재하는 등 특별한 경우에 부분 환불 시 1115 오류가 발생하는 경우가 있음.
- 이럴 때는 전액 활불을 통해서 환불을 처리해야 하며, 불가능하거나 추가 문의가 필요한 경우 기술 연동 지원 연락처쪽으로 문의 필요
Request
- “orderId” 가 “test_order_#1” 라면,
POST https://sandbox-api-pay.line.me/v2/payments/orders/test_order_%231/refund HTTP/1.1
Host: sandbox-api-pay.line.me
Content-Type: application/json
X-LINE-ChannelId: {channel id}
X-LINE-ChannelSecret: {channel secret}
X-LINE-MerchantDeviceProfileId: {DEVICE_PROFILE_ID}
{
"refundAmount": "100"
}
Response
{
"returnCode": "0000",
"returnMessage": "success",
"info": {
"refundTransactionId": "2019010112345678910",
"refundTransactionDate": "2019-01-01T01:01:00Z"
}
}
Authorization Details
인증 거래 내역을 조회하는 API 이다. 인증되었거나 인증 취소(void or expire) 처리된 데이터만 조회할 수 있으며, 매입 이후의 데이터는 Payment Details API 에서 조회할 수 있다.
Specification
표 18 Authorizaiton Details API Endpoint
| 항목 | 설명 |
|---|---|
| Endpoint URL | Sandbox : https://sandbox-api-pay.line.me/v2/payments/authorizations Product : https://api-pay.line.me/v2/payments/authorizations |
| Method | GET |
| Request Header | Required - Content-Type: application/json; charset=UTF-8 - X-LINE-ChannelId: {연동 정보 - channelId} - X-LINE-ChannelSecret: {연동 정보 - channelSecretKey} 가맹점 설정 정보에서 필수 여부 설정 - X-LINE-MerchantDeviceType : device type - X-LINE-MerchantDeviceProfileId : device’s serial no |
| Timeout | Read : 20초 |
표 19 Authorization Details API Query Parameters
| Name | Type | Mandatory | description |
|---|---|---|---|
| orderId | string(100) | N | 가맹점이 결제 요청시 전달한 주문번호 |
| transactionId | number(19) | N | LINE Pay’s transaction id |
표 20 Authorization Details API Response Body
| Name | Type | Mandatory | description |
|---|---|---|---|
| returnCode | string(4) | Y | Result code generated by LINE Pay - 0000 : API 요청 성공 - 그 외의 응답 코드는 본 문서의 “부록- API별 응답코드”를 확인한다. |
| returnMessage | string(100) | Y | Result messages or reason for failure |
| info.transactionId | number(19) | Y | LINE Pay's transaction id |
| info.orderId | string(100) | Y | OrderId given by merchant device. (unique on merchant-side) |
| info.transactionDate | string(20) | Y | Transaction Date(ISO8601 UTC). - Time Format : yyyy-MM-dd'T'HH:mm:ss'Z' * reference : https://en.wikipedia.org/wiki/ISO_8601 |
| info.transactionType | String(20) | Y | Transaction Type - PAYMENT : payment - PAYMENT_REFUND : refund - PARTIAL_REFUND : partial refund |
| info.payInfo[].method | string(20) | Y | Payment method used - CREDIT_CARD - BALANCE - DISCOUNT - POINT |
| info.payInfo[].amount | number(38) | Y | Payment amount |
| info.currency | string(3) | Y | Payment currency * reference : https://en.wikipedia.org/wiki/ISO_4217 |
| info.productName | string(4000) | Y | Product name |
| info.payStatus | string(30) | Y | Payment status - AUTHORIZATION : 인증 - VOIDED_AUTHORIZATION : 인증 무효(“void api”를 호출하여 완료된 상태) - EXPIRED_AUTHORIZATION : 인증 만료(LINE Pay에서 가맹점에게 허용한 인증 기한이 지난 상태) |
| info.authorizationExpireDate | string(20) | N | Authorization Expire Date(ISO8601 UTC). - Time Format : yyyy-MM-dd'T'HH:mm:ss'Z' * reference : https://en.wikipedia.org/wiki/ISO_8601 |
Example
Request
GET https://sandbox-api-pay.line.me/v2/payments/authorizations?orderId=20190408003 HTTP/1.1
Host: sandbox-api-pay.line.me
Content-Type: application/json
X-LINE-ChannelId: {channel id}
X-LINE-ChannelSecret: {channel secret}
X-LINE-MerchantDeviceProfileId: {DEVICE_PROFILE_ID}
Response
{
"returnCode": "0000",
"returnMessage": "success",
"info": [
{
"transactionId": 2019049910005498410,
"transactionDate": "2019-04-08T07:02:38Z",
"transactionType": "PAYMENT",
"productName": "test product",
"currency": "THB",
"authorizationExpireDate": "2019-04-13T07:02:38Z",
"payInfo": [
{
"method": "BALANCE",
"amount": 100
}
],
"orderId": "20190408003",
"payStatus": "VOIDED_AUTHORIZATION"
}
]
}
Payment Details
매입 이후의 거래 데이터를 조회하는 API이다.
Specification
표 21 Payment Details API Endpoint
| 항목 | 설명 |
|---|---|
| Endpoint URL | Sandbox : https://sandbox-api-pay.line.me/v2/payments Product : https://api-pay.line.me/v2/payments |
| Method | GET |
| Request Header | Required - Content-Type: application/json; charset=UTF-8 - X-LINE-ChannelId: {연동 정보 - channelId} - X-LINE-ChannelSecret: {연동 정보 - channelSecretKey} 가맹점 설정 정보에서 필수 여부 설정 - X-LINE-MerchantDeviceType : device type - X-LINE-MerchantDeviceProfileId : device’s serial no |
| Timeout | Read : 20초 |
표 22 Payment Details API Query Parameters
| Name | Type | Mandatory | description |
|---|---|---|---|
| orderId | string(100) | N | 가맹점이 결제 요청시 전달한 주문번호 |
| transactionId | number(19) | N | LINE Pay에서 발급한 결제 또는 환불 거래번호 |
표 23 Payment Details API Response Body
| Name | Type | Mandatory | description |
|---|---|---|---|
| returnCode | string(4) | Y | LINE Pay에 의해 생성된 결과 코드 - 0000 : API 요청 성공 - 그 외의 응답 코드는 본 문서의 “부록- API별 응답코드”를 확인한다. |
| returnMessage | string(100) | Y | 결과 메시지 또는 실패 사유 |
| info.transactionId | number(19) | Y | 거래 번호 |
| info.orderId | string(100) | Y | 가맹점 주문 번호 - 가맹점에서 관리되는 유일한 번호 |
| info.transactionDate | string(20) | Y | 거래 일시 (ISO8601 UTC). - Time Format : yyyy-MM-dd'T'HH:mm:ss'Z' * reference : https://en.wikipedia.org/wiki/ISO_8601 |
| info.transactionType | String(20) | Y | 거래 구분 - PAYMENT : payment - PAYMENT_REFUND : refund - PARTIAL_REFUND : partial refund |
| info.payInfo[].method | string(20) | Y | 결제 시 사용된 결제 수단 - CREDIT_CARD - BALANCE - DISCOUNT - POINT |
| info.payInfo[].amount | number(38) | Y | 거래 금액 |
| info.currency | string(3) | Y | 통화 * reference : https://en.wikipedia.org/wiki/ISO_4217 |
| info.productName | string(4000) | Y | 상품명 |
| 원결제 거래 조회 및 환불 거래가 있는 경우 | |||
| info.refundList[].refundTransactionId | number(19) | Y | 환불 거래 번호 |
| info.refundList[].transactionType | string(20) | Y | 거래 구분 - PAYMENT_REFUND : 환불 - PARTIAL_REFUND : 부분 환불 |
| info.refundList[].refundAmount | number(38) | Y | 환불 금액 |
| info.refundList[].refundTransactionDate | String(20) | Y | 환불 거래 일시 (ISO8601 UTC). - Time Format : yyyy-MM-dd'T'HH:mm:ss'Z' * reference : https://en.wikipedia.org/wiki/ISO_8601 |
| When retrieving a refund | |||
| info.originalTransactionId | number(19) | Y | 원결제 거래 번호 |
Request
GET https://sandbox-api-pay.line.me/v2/payments/?orderId=20190408001 HTTP/1.1
Host: sandbox-api-pay.line.me
Content-Type: application/json
X-LINE-ChannelId: {channel id}
X-LINE-ChannelSecret: {channel secret}
X-LINE-MerchantDeviceProfileId: {DEVICE_PROFILE_ID}
Response
{
"returnCode": "0000",
"returnMessage": "success",
"info": [
{
"transactionId": 2019049910005496810,
"transactionDate": "2019-04-08T06:31:19Z",
"transactionType": "PAYMENT",
"productName": "test product",
"currency": "THB",
"payInfo": [
{
"method": "BALANCE",
"amount": 100
}
],
"refundList": [
{
"refundTransactionId": 2019049910005497012,
"transactionType": "PARTIAL_REFUND",
"refundAmount": -1,
"refundTransactionDate": "2019-04-08T06:33:17Z"
}
],
"orderId": "20190408001"
}
]
}
Appendix
Response Codes
LINE Pay에서 발생하는 오류 코드에 대해 정의한다. 오류 코드에 대한 “returnMessage”는 영어로 제공되며, 별도 메시지가 없는 경우에는 하이픈(-) 이 전달된다.
표 24 LINE Pay 응답코드
| 코드(returnCode) | 설명(300byte) |
|---|---|
| 0000 | 성공 |
| 1101 | LINE Pay 회원이 아닙니다. |
| 1102 | 구매 회원이 거래 불가 상태입니다. |
| 1104 | 가맹점이 존재하지 않습니다. |
| 1105 | 현 가맹점은 LINE Pay를 이용할 수 없는 상태입니다. |
| 1106 | 헤더 정보 오류 |
| 1110 | 사용할 수 없는 신용카드입니다. |
| 1124 | 금액 정보 오류입니다(scale). |
| 1133 | 유효하지 않은 oneTimeKey 입니다. |
| 1141 | 결제 계좌 상태 오류 |
| 1142 | 잔액 부족 |
| 1145 | 결제 진행 중 입니다. |
| 1150 | 거래 내역이 존재하지 않습니다. |
| 1152 | 이미 거래가 존재합니다. |
| 1153 | 결제 reserve시 금액과 요청한 금액이 다릅니다. |
| 1155 | 환불할 수 없는 거래 유형의 거래 번호입니다. |
| 1159 | 결제 요청정보가 없습니다. |
| 1163 | 환불 가능일이 지나 환불이 불가능합니다. |
| 1164 | 환불 가능 금액을 초과하였습니다. |
| 1165 | 이미 환불된 거래입니다. |
| 1169 | 결제 confirm을 위한 정보 오류 (LINE Pay에서 결제 수단 선택과 암호 인증을 해야 합니다.) |
| 1170 | 회원 계좌의 잔액이 변동되었습니다. |
| 1172 | 이미 동일 주문번호로 거래된 내역이 존재합니다. |
| 1177 | 최대 조회 가능한 거래 수 초과(100개) |
| 1178 | 가맹점이 지원하지 않는 통화입니다. |
| 1179 | 처리할 수 없는 상태입니다. |
| 1183 | 결제금액이 0보다 커야 합니다. |
| 1184 | 결제금액이 요청시 금액을 초과합니다. |
| 1198 | 요청 처리 중입니다. |
| 1199 | 내부 요청 오류 |
| 1280 | 신용카드 결제 중 일시적 오류 |
| 1281 | 신용카드 결제 오류 |
| 1282 | 신용카드 승인 오류 |
| 1283 | 부정 사용이 의심되어 결제가 거절되었습니다. |
| 1284 | 신용카드 결제가 일시적으로 중단 되었습니다. |
| 1285 | 신용카드 결제 정보 누락 |
| 1286 | 잘못된 신용카드 결제 정보 |
| 1287 | 신용카드 유효기간이 초과되었습니다. |
| 1288 | 신용카드 결제 은행 잔고가 부족합니다 |
| 1289 | 신용카드 한도 초과 |
| 1290 | 신용카드 건당 결제 한도 초과 |
| 1291 | 도난 신고된 카드입니다. |
| 1292 | 사용이 정지된 카드입니다. |
| 1293 | CVN 입력 오류 |
| 1294 | 블랙리스트에 등록된 카드입니다. |
| 1295 | 신용카드 번호가 잘못되었습니다. |
| 1296 | 처리할 수 없는 금액입니다. |
| 1298 | 카드 사용이 거절되었습니다. |
| 1900 | 일시적 오류입니다. 잠시 후 다시 시도하세요. |
| 1901 | 일시적 오류입니다. 잠시 후 다시 시도하세요. |
| 1902 | 일시적 오류입니다. 잠시 후 다시 시도하세요. |
| 1903 | 일시적 오류입니다. 잠시 후 다시 시도하세요. |
| 1999 | 이전 요청 정보와 다릅니다.(요청 재시도시) |
| 2101 | 파라미터 오류 |
| 2102 | JSON 데이터 포맷 오류 |
| 2103 | 잘못된 요청입니다. returnMessage를 확인해주세요. |
| 2104 | 잘못된 요청입니다. returnMessage를 확인해주세요. |
| 9000 | 내부 오류 |
Response Code by API
표 25 API 별 응답코드
| 오류코드 | Payment | Payment status check | 매입 | 인증무효 | 환불 | 인증내역 | 결제내역 |
|---|---|---|---|---|---|---|---|
| 1101 | v | v | v | ||||
| 1102 | v | v | v | ||||
| 1104 | v | v | v | v | v | v | v |
| 1105 | v | v | v | v | v | v | v |
| 1106 | v | v | v | v | v | v | v |
| 1110 | v | ||||||
| 1124 | v | v | |||||
| 1133 | v | ||||||
| 1141 | v | ||||||
| 1142 | v | ||||||
| 1145 | v | ||||||
| 1150 | v | v | v | v | v | v | |
| 1152 | v | ||||||
| 1153 | v | ||||||
| 1154 | |||||||
| 1155 | v | v | v | ||||
| 1159 | v | ||||||
| 1163 | v | ||||||
| 1164 | v | ||||||
| 1165 | v | ||||||
| 1170 | v | v | v | ||||
| 1172 | v | v | |||||
| 1177 | v | v | |||||
| 1178 | v | ||||||
| 1179 | v | v | v | ||||
| 1183 | v | v | |||||
| 1184 | v | v | |||||
| 1194 | v | ||||||
| 1198 | v | v | v | v | |||
| 1199 | v | v | v | v | |||
| 1900 | v | v | v | ||||
| 1901 | v | ||||||
| 1902 | v | ||||||
| 1903 | v | ||||||
| 1999 | v | v | v | ||||
| 2101 | v | v | v | v | v | v | v |
| 2102 | v | v | v | v | v | v | v |
| 2103 | v | v | v | v | v | v | v |
| 2104 | v | v | v | v | v | v | v |
| 9000 | v | v | v | v | v | v | v |
Sandbox OneTimeKey 결제
사용자가 LINE Pay app의 "My Code"에서 보여주는 QR/Bar Code를 가맹점이 읽어 결제를 진행할 수 있다.
Sandbox에서도 "My Code"를 web page로 제공하며, 결제 테스트를 할 수 있다. Sandbox 환경에서 가맹점은 My Code를 읽어, Payment API를 호출하면 My Code 웹 페이지는 결제 simulation 페이지로 이동한다.
Sandbox OneTimeKey URL 명세
표 23 Sandbox OneTimeKey URl Endpoint 명세
| 항목 | 설명 |
|---|---|
| countryCode | 국가 코드. 아래와 같은 국가를 지원하며, 통화는 각 국가의 통화로 설정된다.
|
| paymentMethod | 결제 수단
|
Sandbox OneTimeKey URL Example
- https://sandbox-web-pay.line.me/web/sandbox/payment/oneTimeKey?countryCode=JP&paymentMethod=card
- https://sandbox-web-pay.line.me/web/sandbox/payment/oneTimeKey
포인트 분리 응답
결제 완료/인증 등의 API 응답에서 포인트 결제를 응답으로 구분해서 받고 싶은 경우, 가맹점 마이 페이지(https://pay.line.me) > 기본 정보 관리 > 기타 정보에서 "API의 결제 결과에 유저의 POINT 이용 정보 제공" 항목을 "사용함"으로 설정하면 결제 매입/완료 API에 유저의 POINT 정보가 제공이 된다. 이 정보를 사용하는 경우 info.payInfo[]의 "method"에 "POINT"라는 항목으로 포인트 결제 금액이 추가되어 응답이 전달된다.
위와 같은 경우 만약 POINT 전액 결제를 할 경우, 기존에는 사용자의 주 결제 수단에 포함되어 데이터가 전달되었지만, 위 설정을 "사용함"으로 설정할 경우, POINT 항목만 payInfo에 전달된다.
결제 확정 API 응답 예제 (포인트 전액 결제 - 포인트 이용 정보 제공을 사용하지 않을 경우)
{
"returnCode": "0000",
"returnMessage": "OK",
"info": {
"orderId": "order_210124213",
"transactionId": 20140101123123123,
"payInfo": [{
"method": "BALANCE",
"amount": 15
}]
}
}
결제 확정 API 응답 예제 (포인트 전액 결제 - 포인트 이용 정보 제공을 사용할 경우)
{
"returnCode": "0000",
"returnMessage": "OK",
"info": {
"orderId": "order_210124213",
"transactionId": 20140101123123123,
"payInfo": [{
"method": "POINT",
"amount": 15
}]
}
}