본문 바로가기
개발가이드진위 확인결제카드 판독(OCR)

결제카드 판독(OCR) API

명세 내보내기
OpenAPI 3.0.3Postman 컬렉션Markdown

신용·체크카드 사진에서 카드번호·유효기간·소유자명을 읽어 돌려줍니다. 카드번호는 첫 6자리와 끝 4자리만 보여 주고 가운데는 *로 가립니다. 결제수단 등록 화면에서 카드 정보를 손으로 옮겨 적는 일을 줄이는 데 맞춰 만들었습니다.

POSThttps://apick.app/rest/payment_card_ocr
인증
Bearer 키
요청 형식
form-data
응답
JSON
경로
1개

왜 결제카드 판독(OCR)인가

카드 사진 한 장이면 결제수단 등록 입력이 끝납니다

결제수단 등록 화면에서 카드번호 열여섯 자리를 직접 입력하게 하면 오타·이탈이 늘고, 받은 번호를 그대로 쌓아 두면 보관 부담이 생깁니다. 사진에서 번호를 읽되 가운데는 가리고 원문은 남기지 않아 입력은 짧게, 보관 위험은 낮춥니다.

도입 효과

  • 카드번호 직접 입력 단계를 줄여 등록 이탈 감소
  • 번호 원문을 남기지 않아 보관 위험을 낮춤
  • 유효기간·소유자명까지 한 번에 채움

이런 곳에서 많이 씁니다

  • 구독 서비스 결제수단 등록
  • 마이페이지 카드 정보 갱신
  • 오프라인 매장 키오스크 카드 등록
가입하고 API 키 받기API 키 하나로 바로 호출 · 실패한 요청은 과금되지 않습니다

알아둘 점

업로드 용량 제한: 50MB
첨부 이미지 합계는 최대 50MB입니다. 서버가 판독 가능한 크기로 최적화하며, 지나치게 큰 해상도는 정확도를 높이지 않고 처리시간만 늘릴 수 있습니다.
제한을 초과하면 HTTP 413과 REQUEST_TOO_LARGE 오류가 반환되며 과금되지 않습니다.

한눈에 보는 흐름

  1. 고객 앱이 카드 앞면 사진을 image로 보냅니다.
  2. 카드 글자를 읽어 카드번호 후보를 찾고, 카드번호 검증 숫자(Luhn)를 통과한 번호만 받습니다.
  3. 가린 카드번호(data.card_number)와 유효기간·소유자명을 돌려줍니다. 카드번호 원문은 응답에 담지 않습니다.
  4. 고객 서비스는 결제수단 입력칸의 앞·뒤 자리와 유효기간을 채우고, 사용자가 가운데 자리를 직접 확인·입력하게 합니다.

이용 전 확인

PNG·JPEG 이미지를 받습니다. 카드 앞면 전체가 화면에 들어오고 숫자가 선명하게 나온 사진이 가장 정확합니다. 빛 반사가 숫자를 가리면 카드번호를 찾지 못할 수 있습니다.

카드번호는 첫 6자리와 끝 4자리만 돌려주며, 원문은 응답하지도 저장하지도 않습니다. 보낸 사진은 판독이 끝나면 바로 지웁니다.

읽지 못한 값을 추측으로 채우지 않습니다. 유효기간을 읽지 못하면 expiry는 빈 문자열, expiry_month·expiry_year는 0입니다. 소유자명이 없는 카드는 cardholder가 빈 문자열입니다.

요금은 15P입니다. 글자를 읽지 못했거나 카드번호를 찾지 못하면 과금되지 않습니다.

결과를 이렇게 쓰세요

확인할 값
상태
권장 처리
data.checks.카드번호_Luhn
true
번호를 바르게 읽었습니다. 앞·뒤 자리를 입력칸에 채웁니다.
data.expiry
빈 문자열
유효기간만 사용자에게 직접 입력받습니다.
data.error
문구 있음
카드 앞면이 선명하게 나오도록 다시 찍게 합니다.

판독 결과는 입력을 돕는 자료입니다. 결제 승인 전에 사용자가 카드 정보를 확인하는 단계를 두세요.

요청과 응답

API 요청
POST/rest/payment_card_ocr
  • Bearer 인증
  • multipart/form-data
  • JSON 응답
요청 파라미터 1개 · 필수 1
파라미터
설명
imagefile필수
분석할 이미지 파일입니다. JPG·PNG·WEBP를 지원하며, 파일 크기·해상도 제한은 요청 표를 확인하세요.
응답 필드 17개
응답 필드
설명
dataobject
요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.
data.card_numberstring
가운데를 *로 가린 카드번호입니다(예: 123456******7890).
data.card_number_last4string
카드번호 끝 4자리입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.card_number_first6string
카드번호 첫 6자리입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.expirystring
유효기간 MM/YY입니다. 읽지 못하면 빈 문자열입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.expiry_monthinteger
유효기간 월입니다. 읽지 못하면 0입니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.
data.expiry_yearinteger
유효기간 연도(4자리)입니다. 읽지 못하면 0입니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.
data.cardholderstring
카드에 영문으로 적힌 소유자명입니다. 없으면 빈 문자열입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.checksobject
자동 확인 결과입니다. 하위 필드에 코드·이름·상태 같은 세부 값이 들어 있으며, 자료가 없으면 빈 객체이거나 생략됩니다.
data.successinteger
업무 처리 결과 코드입니다. 1은 정상 결과, 0은 실패 또는 무료 응답입니다. 서비스에 따라 2·3처럼 추가 코드를 쓰므로 같은 응답의 status·msg·error 필드도 함께 확인하세요.
apiobject
API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.
api.successboolean
API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.
api.costinteger
이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.
api.msinteger
서버가 요청을 받아 응답 본문을 만들기까지 걸린 처리 시간(밀리초)입니다. 네트워크 왕복 시간과 클라이언트 대기 시간은 포함되지 않습니다.
api.pl_idinteger
포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다.
하위 필드 2개 더 보기
응답 필드
설명
data.checks.카드번호_형식boolean
카드번호가 13~19자리인지 여부입니다. true/false로 오며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 이 필드가 나타내는 조건이 성립한 경우, false = 성립하지 않은 경우입니다. 두 값 모두 정상 응답에 올 수 있으며, 값이 없으면 필드가 생략되거나 null일 수 있습니다.
data.checks.카드번호_Luhnboolean
카드번호 검증 숫자가 맞는지 여부입니다. true/false로 오며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 이 필드가 나타내는 조건이 성립한 경우, false = 성립하지 않은 경우입니다. 두 값 모두 정상 응답에 올 수 있으며, 값이 없으면 필드가 생략되거나 null일 수 있습니다.
입력 조건·전송 규칙
항목
설정
메서드·주소
POST https://apick.app/rest/payment_card_ocr
인증 헤더
Authorization: Bearer 내 계정의 API 인증키
본문 형식
multipart/form-data
요청 예시

응답 처리

HTTP 성공과 업무 결과를 구분하세요. 경로별 응답 필드와 예시는 위 요청과 응답에 함께 있습니다.

응답 예시
{
    "data": {
        "card_number": "123456******7890",
        "card_number_last4": "7890",
        "card_number_first6": "123456",
        "expiry": "08/29",
        "expiry_month": 8,
        "expiry_year": 2029,
        "cardholder": "HONG GILDONG",
        "checks": {
            "카드번호_형식": true,
            "카드번호_Luhn": true
        },
        "success": 1
    },
    "api": {
        "success": true,
        "cost": 15,
        "ms": 1820,
        "pl_id": 108611
    }
}
원문 응답 필드 표 보기
필드
타입
설명
data
object
판독 결과
card_number
string
가운데를 *로 가린 카드번호입니다(예: 123456******7890).
card_number_first6
string
카드번호 첫 6자리입니다.
card_number_last4
string
카드번호 끝 4자리입니다.
expiry
string
유효기간 MM/YY입니다. 읽지 못하면 빈 문자열입니다.
expiry_month
integer
유효기간 월입니다. 읽지 못하면 0입니다.
expiry_year
integer
유효기간 연도(4자리)입니다. 읽지 못하면 0입니다.
cardholder
string
카드에 영문으로 적힌 소유자명입니다. 없으면 빈 문자열입니다.
checks
object
자동 확인 결과입니다.
카드번호_형식
boolean
카드번호가 13~19자리인지 여부입니다.
카드번호_Luhn
boolean
카드번호 검증 숫자가 맞는지 여부입니다.
success
integer
처리 결과입니다. 1: 성공(과금), 0: 실패, 3: 시간 초과(과금 없음).
api
object
호출 공통 정보
success
boolean
요청을 정상 처리했는지 여부입니다.
cost
integer
이번 요청에서 차감된 포인트입니다.
ms
integer
처리 시간(밀리초)입니다.
pl_id
integer
결제 기록 번호입니다. 문의할 때 함께 알려 주세요.

오류 코드

응답을 아래 순서로 확인하세요. 결과 유무와 과금 여부는 서로 다릅니다.

  1. HTTP 상태전송·인증·입력 오류
  2. api.successAPI 처리 여부
  3. data · result업무 결과와 오류 문구
  4. api.cost이번 요청의 과금
업무 실패 응답 data.error
  • 입력값이 맞지 않거나 대상 자료가 없거나 일시적으로 처리하지 못하면 data.error(사유 문구)와 data.success=0을 돌려줍니다. HTTP 상태는 사유에 따라 400·404·408·424 중 하나입니다.
  • 이때 api.cost는 0이며 과금되지 않습니다. data.error 문구를 그대로 기록하고 사용자에게 보여 주세요.
  • 입력 오류(400)는 값을 고친 뒤 다시 요청하세요. 408·424는 잠시 후 한 번 다시 시도하고, 같은 입력으로 짧은 간격의 자동 반복은 하지 마세요.
{
  "data": {
    "error": "입력값을 확인해 주세요.",
    "success": 0
  },
  "api": {
    "success": true,
    "cost": 0,
    "ms": 5
  }
}
서비스 코드·조건

오류와 대처

실패하면 data.error에 문구가 담기고 api.cost는 0입니다.

HTTP
data.error
대처
400
판독할 이미지(image)가 없습니다.
카드 사진을 image 필드로 보내세요.
400
이미지 형식의 파일만 보낼 수 있습니다.
PNG·JPEG 이미지인지 확인하세요.
422
이미지에서 글자를 읽지 못했습니다. …
카드 전체가 밝고 반듯하게 나오도록 다시 찍게 하세요.
422
카드번호를 찾지 못했습니다. …
카드 앞면 번호가 선명하게 나오도록 다시 찍게 하세요.
424
카드를 판독하지 못했습니다. 잠시 후 다시 시도해 주세요.
잠시 뒤 한 번 더 요청하세요.
인증·포인트 오류 result.error 문구
코드
HTTP
의미·조치
유효하지 않은 API키 입니다.
401
Authorization: Bearer 헤더의 인증키를 확인하세요.
허용되지 않은 IP주소 입니다.
401
마이페이지의 허용 IP 설정과 요청 서버 IP를 확인하세요.
비활성화된 계정입니다.
401
계정 이용 상태를 고객지원으로 문의하세요.
사용 가능한 포인트이 부족합니다.
200
HTTP 200이어도 result.error가 있으면 실패입니다. 포인트를 충전한 뒤 다시 요청하세요. 이 응답은 과금되지 않습니다.
무료 포인트로 사용할 수 없는 서비스입니다.
200
최소 1회 결제 후 이용할 수 있습니다. result.error 전체 문구를 그대로 표시하세요.
인증 정보를 확인할 수 없습니다.
424
일시적인 확인 실패입니다. 잠시 후 다시 시도하세요.
폼 입력 오류 error.code
코드
HTTP
의미·조치
FORM_DATA_INVALID
400
필드 이름·값의 타입·배열 인덱스를 확인하세요. 인덱스는 0부터 연속으로 사용합니다.
FORM_DATA_FIELD_CONFLICT
400
같은 값과 중첩 경로를 동시에 지정하지 마세요.
MULTIPART_LIMIT_OR_PARSE_ERROR
400·413
boundary·파일 크기·필드 개수를 확인하세요. 서비스별 제한이 우선 적용됩니다.

요금·이용 조건

기본 요금기본 단가 15P · 건당무료 포인트로는 이용할 수 없으며 최소 1회 결제 후 이용할 수 있습니다.

실제 차감 금액은 응답의 api.cost로 확인하세요. 상세 요금은 요금정책에서 볼 수 있습니다.

연동 팁

  • 요청 예제의 오류 처리 포함 모드는 시간 제한과 업무 실패 판정을 함께 보여줍니다.
  • 인증키는 서버 환경변수에 두고 브라우저·앱에 넣지 마세요.
  • HTTP 성공과 업무 결과를 구분하고, 실패 응답의 오류 문구를 그대로 기록하세요.

개발가이드 검색

API 이름·경로·파라미터·오류 코드로 찾을 수 있습니다.

표시 가격은 기본 단가입니다. 상세 과금 조건은 각 가이드에서 확인하세요.