오프라인 API

LINE Pay 오프라인 API는 가맹점의 단말기를 이용해 처리되는 오프라인 결제를 위한 web API이며 HTTPS로 통신합니다.

오프라인 API를 호출할 때 자격 증명 정보(credentials)가 필요합니다. 가맹점 가입 후 가맹점 센터 My Page 메뉴에서 채널 ID와 채널 비밀키를 얻을 수 있는데, 이를 각각 X-LINE-ChannelId, X-LINE-ChannelSecret 헤더에 입력하면 됩니다. 가맹점 센터는 테스트 환경(Sandbox)과 실제 서비스용(Production) 채널 정보를 제공합니다.

엔드포인트

API의 엔드포인트 형식은 다음과 같습니다.

https://{host}/{apiPath}?{queryString}

• host는 API 서버의 호스트입니다.
  • 샌드박스 서버(테스트용): sandbox-api-pay.line.me
  • 프로덕션 서버(실서비스용): api-pay.line.me
• apiPath는 호출할 API의 경로입니다. 각 엔드포인트 상세 설명에서 확인할 수 있습니다. API 버전도 apiPath 안에 포함됩니다.
• queryString은 쿼리 파라미터의 집합입니다. 각 파라미터는 key=value 쌍이며 각각 &로 구분합니다.

다음과 같은 엔드포인트가 있습니다.

• 결제 요청

  POST /v2/payments/oneTimeKeys/pay

• 결제 상태 조회

  GET /v2/payments/orders/{orderId}/check

• 승인 정보 조회

  GET /v2/payments/authorizations

• 매입

  POST /v2/payments/orders/{orderId}/capture

• 승인 취소

  POST /v2/payments/orders/{orderId}/void

• 결제 내역 조회

  GET /v2/payments

• 환불

  POST /v2/payments/orders/{orderId}/refund

요청

API 요청은 아래와 같은 규약을 따릅니다.

• 모든 API 요청은 HTTPS로 전송합니다.
• 파라미터는 패스(path), 쿼리(query) 혹은 JSON 형식의 요청을 본문으로 전달할 수 있습니다.

요청 헤더

API 요청은 다음과 같은 헤더를 공통으로 요구합니다.

헤더 이름(key)	자료형	설명	필수 여부
Content-Type	String	application/json을 설정합니다.	필수
X-LINE-ChannelId	String	채널 ID	필수
X-LINE-ChannelSecret	String	채널 비밀키	필수
X-LINE-MerchantDeviceProfileId	String	기기 프로파일 ID. 추후, LINE Pay가 제공하는 보고서에서 기기별 통계를 확인할 수 있습니다. 주로 가맹점 단말기의 시리얼 번호를 입력하며 필요 시 사용합니다. X-LINE-MerchantDeviceType 헤더와 함께 입력하세요.	선택
X-LINE-MerchantDeviceType	String	기기 타입. 가맹점에서 구분 용도로 정의한 기기 유형을 입력하세요. X-LINE-MerchantDeviceProfileId 헤더와 함께 입력하세요.	선택

아래는 요청 HTTP 헤더의 예시입니다.

Host: sandbox-api-pay.line.me
Content-Type: application/json
X-LINE-ChannelId: YOUR_CHANNEL_ID
X-LINE-ChannelSecret: YOUR_CHANNEL_SECRET
X-LINE-MerchantDeviceProfileId: YOUR_DEVICE_PROFILE_ID
X-LINE-MerchantDeviceType: YOUR_DEVICE_TYPE

요청 본문

특정 엔드포인트는 요청 본문으로 파라미터를 전달할 수 있습니다. 요청 본문은 JSON 객체 형태입니다.

아래는 요청 본문의 예입니다.

{
  "productName": "Brown pen",
  "amount": 1000,
  "currency": "TWD",
  "orderId": "Ord2018123100000001"
}

응답

API 응답은 항상 HTTP 상태 코드 200 OK가 전달되며, 응답 헤더, 응답 본문으로 구성된 요청 결과를 전달합니다.

응답 헤더

API 응답은 다음과 같은 헤더를 공통으로 포함합니다.

헤더 이름(key)	자료형	설명	포함 여부
Content-Type	String	application/json	항상

응답 본문

응답 본문은 상세한 요청 결과를 담은 JSON 객체로, 다음과 같은 필드를 포함합니다.

필드 이름	자료형	설명	포함 여부
info	Object	API 요청 결과 데이터. API 호출이 성공했을 때만 응답에 포함됩니다.	조건부
returnCode	String	결과 코드	항상
returnMessage	String	returnCode에 상응하는 메시지	항상

성공 응답

API 요청이 문제 없이 처리되면, 응답 본문은 returnCode를 0000로 설정하며, 결과 데이터가 있으면 info 필드에 넣어 전달합니다.

아래는 성공한 API 요청의 응답 본문 예입니다.

{
  "returnCode": "0000",
  "returnMessage": "OK",
  "info": {
    "orderId": "MKSI_M_20180904_1000001",
    "transactionId": 2018082512345678910,
    "payInfo": [
      {
        "method": "BALANCE",
        "amount": 1000
      }
    ]
  }
}

오류 응답

API 요청에 오류가 있으면, 서버는 이를 실패로 간주하고 오류 원인에 상응하는 결과 코드를 반환합니다. 실패한 API 요청의 응답 본문은 오류 정보를 전달하며, 이때 info 필드는 반환되지 않습니다.

아래는 실패한 API 요청의 응답 본문 예입니다.

{
  "resultCode": 1104,
  "statusMessage": "Merchant not found."
}

트랜잭션 ID

트랜잭션은 LINE Pay 서버가 결제 과정에서 처리하는 작업을 구분한 개념으로 결제 요청, 결제 승인, 매입, 환불과 같은 작업은 모두 트랜잭션입니다. 트랜잭션 ID는 19 자리의 정수 값으로 이런 작업을 식별하는데 사용합니다. LINE Pay 서버는 어떤 작업이 처리됐을 때 트랜잭션 ID를 반환하며, 이를 이용해 해당 트랜잭션 정보를 조회하거나 해당 트랜잭션에 관한 작업을 요청할 수 있습니다.

트랜잭션 ID는 64 bit 정수 유형(long integer)으로 처리돼야 합니다. 만약, 64 bit 정수 유형으로 처리하는 것에 문제가 있다면 문자열(string)로 변환해서 처리하세요. 예를 들면, LINE Pay 서버에서 2023010112345678910라는 값을 보내더라도 64 bit 정수 값을 처리하지 못하는 다른 시스템에서 이를 정수 자료형으로 취급한다면 2023010112345678800으로 인식될 수 있습니다.

다음은 위의 문제를 피하기 위한 JavaScript 코드 예제입니다. LINE Pay API 응답을 일반 텍스트로 처리한 후 JSON 객체로 파싱(parse)하기 전에 JavaScript에서 사용할 수 있는 안전한 정수값(2^53 - 1) 범위 밖의 값을 문자열로 처리하는 예입니다. 아래 코드는 응답 값 중에 16자리 이상 숫자가 연속으로 등장하면 문자열로 변경합니다.

function handleBigInteger(text) {
  const largeNumberRegex = /:\s*(\d{16,})\b/g;
  const processedText = text.replace(largeNumberRegex, ': "$1"');

  const data = JSON.parse(processedText);

  return data;
}

async function requestLINEPayAPI({
  method = "GET",
  baseUrl = "https://sandbox-api-pay.line.me",
  apiPath,
  queryString = "",
  data = {},
}) {
  // ...

  const response = await fetch(
    `${baseUrl}${apiPath}${queryString !== "" ? "&" + queryString : ""}`,
    {
      // ...
    }
  );

  const processedResponse = handleBigInteger(await response.text());

  return processedResponse;
}

결과 코드

API 호출 결과는 아래와 같이 결과 코드(returnCode)와 결과 메시지(returnMessage)로 제공됩니다. 아래 표를 참고하세요.

별도의 메시지가 제공되지 않는 결과 코드는 하이픈 기호(-)가 메시지로 전달됩니다.

결과 코드	Description
0000	요청이 성공했습니다.
1101	고객은 LINE Pay 사용자가 아닙니다.
1102	고객은 현재 LINE Pay로 거래할 수 없는 상태입니다.
1104	가맹점 센터에 등록되지 않은 가맹점입니다. 올바른 자격 증명 정보를 입력했는지 확인하세요.
1105	해당 가맹점은 현재 LINE Pay를 이용할 수 없는 상태입니다.
1106	요청 헤더 정보에 오류가 있습니다.
1110	사용할 수 없는 신용 카드입니다
1124	금액 정보에 오류가 있습니다.
1133	유효하지 않은 My Code(oneTimeKey)입니다.
1141	계좌 상태에 문제가 있습니다.
1142	잔액이 부족합니다.
1145	결제 진행 중입니다.
1150	거래 내역이 없습니다.
1152	동일한 거래 내역이 있습니다.
1153	결제 요청 금액과 매입 금액이 다릅니다.
1155	잘못된 트랜잭션 ID입니다.
1159	결제 요청 정보가 없습니다.
1163	환불이 불가능합니다.(환불 가능 기간 초과)
1164	환불 가능 금액을 초과했습니다.
1165	이미 환불된 거래입니다.
1169	LINE Pay에서 결제 수단 선택과 암호 인증을 해야 합니다.
1170	회원 계좌의 잔액이 변동됐습니다.
1172	이미 동일한 주문번호로 거래한 내역이 있습니다.
1177	조회할 수 있는 최대 거래 수를 초과했습니다.(100개)
1178	가맹점이 지원하지 않는 통화입니다.
1179	처리할 수 없는 상태입니다.
1183	결제 금액이 설정한 최소 금액보다 커야 합니다.
1184	결제 금액이 설정한 최대 금액보다 작아야 합니다.
1198	API 호출이 중복 요청됐습니다.
1199	내부 요청에서 오류가 발생했습니다.
1280	신용 카드 결제 중 일시적 오류가 발생했습니다.
1281	신용 카드 결제 중 오류가 발생했습니다.
1282	신용 카드 승인 중 오류가 발생했습니다.
1283	부정 사용이 의심돼 결제가 거절됐습니다.
1284	신용 카드 결제가 일시적으로 중단됐습니다.
1285	신용 카드 결제 정보가 누락됐습니다.
1286	신용 카드 결제 정보에 틀린 정보가 있습니다.
1287	신용 카드 유효 기간이 초과됐습니다.
1288	신용 카드 결제 계좌의 잔액이 부족합니다.
1289	신용 카드 한도를 초과했습니다.
1290	신용 카드 건당 결제 한도를 초과했습니다.
1291	도난 신고된 카드입니다.
1292	사용이 정지된 카드입니다.
1293	CVN 입력 오류입니다.
1294	블랙리스트에 등록된 카드입니다.
1295	신용 카드 번호가 잘못됐습니다.
1296	처리할 수 없는 금액입니다.
1298	카드 사용이 거절됐습니다.
190X	일시적 오류입니다. 잠시 후 다시 시도해주세요.
1999	(요청 재시도 시) 이전 요청 정보와 다릅니다.
2101	파라미터 오류입니다.
2102	JSON 데이터의 포맷 오류입니다.
2103	허용되지 않은 파라미터를 입력했습니다.
2104	잘못된 요청입니다. 결과 메시지를 확인해주세요.
9000	내부 오류가 발생했습니다.