API 연동

크레디탑은 언제나 여러분과 함께 합니다.

API 연동

수기/온라인

크레디탑 API연동 안내입니다.

API 구성방법

(1) 연동방법

  • 웹사이트의 REST API URL 페이지를 호출해서 응답 값을 받아 연동합니다.
  • REST API URL 페이지 호출은 서버에서 실행이 되어야 합니다. (Server Side 호출)

(2) 요청/응답처리

① http
protocols HTTPs (TLS v1.0~1.2), 128bit 이상의 Cipher Suite 사용
method GET, POST, PUT
data Format JSON
character set UTF-8
authorization 온라인 결제 KEY(Pay Key) 사용
contents types application/json
② 응답 http 코드
200 요청이 성공적으로 처리된 경우
400 Content-type이 application/json이 아닌 경우
401 유효하지 않은 Key 사용
③ Response JSON (Result Object)
resultCd 정의된 응답코드
“0000” : 정상 , “9999” : CREDITOP 실패 메세지
그외에는 매입사 응답 코드 및 메시지
resultMsg 대분류 실패 사유
advanceMsg 포맷에러, 승인실패, 한도부족 등에 대한 상세 메시지
create 응답 시간 ( YYYYMMDDHHMMSS )

echo

(1) 인증 및 망테스트

  • 망테스트 또는 인증테스트를 위하여 사용
  • 초기 연동 시 echo를 통하여 정상적으로 망에 연동되는지 여부 확인 필요(Authorizaion의 PayKey가 유효한 Key인지 여부 확인)
  • 결제 시 항상 체크해야 하는 부분은 아니며, 망 테스트 전용으로 사용 권장

(2) api url / 호출 및 응답 파라메터

api url /api/echo
호출 파라메터 없음
응답 파라메터 Result Object

get

(1) 결재결과재조회

  • 승인 결과에 대한 조회 가능
  • 승인 취소에 대한 결과 조회는 지원하지 않음

(2) API URL / 호출 파라메터

api url /api/get/{TRACK_ID}{TRX_ID}
호출 파라메터
  • 가맹점 주문번호(trackId) 또는 부국위너스 거래번호로 요청 가능
  • URL 뒤에 /api/get/거래번호, 주문번호

(3)응답파라메터

① Result Object
② Pay Object
trxId 거래번호 string Y
trxType “ONTR” 수기(기본) / "3DTR" 온라인 / "WHTR" Allat무선 string Y
tmnId 터미널 아이디 string Y
trackId 가맹점 주문번호 string Y
amount 매입 금액 long Y
udf1 가맹점 정의 필드 1: 응답 시 회신 됩니다 string O
udf2 가맹점 정의 필드 2: 응답 시 회신 됩니다 string O
card 결제 시 사용된 카드 정보 card Y
products 주문 시 상품 정보 products Y
③ Card Object
cardId 카드아이디 string Y
installment 할부기간 2자리 숫자로 (00). integer O
last4 카드 마지막 4자리 string Y
bin bin string Y
issuer 발급사 string Y
cardType 카드 유형 string Y
acquirer 매입사 string Y
issuerCode 발급사 코드 string Y
acquirerCode 매입사 코드 string Y

pay

(1) 인증 및 자동매입

  • 카드 승인 시 사용하는 Function 으로 요청 시 Pay는 기본 필수 값 및 Card, Products Array 로 구성됩니다.

(2) API URL

api url /api/pay

(3) 호출 파라메터

① Pay Object
trxType “ONTR” 수기(기본) / "3DTR" 온라인 / "WHTR" Allat무선 string Y
trackId 가맹점 주문번호 string Y
amount 결제 금액 long Y
payerName 구매자 성명 string Y
payerEmail 구매자 이메일 string Y
payerTel 구매자 전화번호 string Y
udf1 가맹점 정의 필드 1: 응답 시 회신 됩니다. string O
udf2 가맹점 정의 필드 2: 응답 시 회신 됩니다. string O
card 결제 시 사용된 카드 정보 card Y
products 온라인 주문 시 상품 정보 Array 로 구성됨 products Y
② Card Object
number 20 자리 미만의 카드 번호 string Y
expiry 카드 유효기간 YYMM string Y
cvv 카드 뒷면에 표기된 3~4자리 숫자 string O
installment 할부기간 2자리 숫자로 (00). integer O
③ Product Object
prodId
name 상품명 string Y
qty 구매 수량 integer O
price 객 단가 integer O
desc 상세설명 string O

(4) 응답 파라메터

  • Result Object
  • Pay Object

refund

(1) 승인취소/매입취소

  • rootTrxId로 취소 시 rootTrackId, rootTrxDay 정보 필요 없음
  • rootTrackId로 취소 시 rootTrxDay 정보 필수

(2) API URL

api url /api/refund

(3) 호출 파라메터

① Refund Object
trxType “ONTR” 수기(기본) / "3DTR" 온라인 / "WHTR" Allat무선 string Y
trackId 취소 시의 가맹점 주문번호 string Y
Amount 취소 금액 long Y
udf1 가맹점 정의 필드 1: 응답 시 회신 됩니다. string O
udf2 가맹점 정의 필드 2: 응답 시 회신 됩니다. string O
rootTrxId 원거래에 대한 부국위너스 거래번호 string O
rootTrackId 원거래에 대한 가맹점 주문번호 string Y
rootTrxDay 원거래의 거래 기준일 ( YYYYMMDD ) string Y

(4) 응답 파라메터

  • Result Object
  • Pay Object

가상계좌

echo

(1) 인증 및 망테스트

  • 망테스트 또는 인증테스트를 위하여 사용
  • 초기 연동 시 echo를 통하여 정상적으로 망에 연동되는지 여부 확인 필요(Authorizaion의 PayKey가 유효한 Key인지 여부 확인)
  • 결제 시 항상 체크해야 하는 부분은 아니며, 망 테스트 전용으로 사용 권장

(2) API URL

api url /api/echo

(3) 호출 파라메터

  • 없음

(4) 응답 파라메터

  • Result Object

open

(1) 발급

  • 실명인증, 1원인증, ARS인증을 거친 후 발급 됨

(2) API URL

api url /api/vact/authopen

(3) 호출 파라메터

① Object
publicKey 결제키 (pk_로 시작하는 가맹점 public Key) string Y
trackId 가맹점 주문번호 (가맹점의 유니크한 주문번호) string Y
Identity 통합인증용 고객 실명번호, 생년월일 6자리(YYMMDD) string Y
holderName 통합인증용 고객 이름 (계좌인증시 필요) string Y
phoneNo 통합인증용 고객 전화번호 (계좌인증시 필요) string Y
backCd 가상계좌 은행코드 string Y
responseFunction 가상계좌 발급결과를 javascript funtion으로 리턴 Function O
redirectUrl 가상계좌 발급완료 후 이동되는 페이지
* 발급결과를 전달		 string O
account 가상계좌 번호 (‘-‘ 하이픈 미포함)
* 영구계좌시 필수		 string O
amount 가상계좌에 입금할 금액
* 임시계좌시 필수		 string O
oper 가상계좌에 입금할 금액 수식
* 임시계좌시 필수 (임시계좌는eq만 사용가능)
“eq” : 요청한 금액과 동일할 경우만 입금 처리
“ge” : 요청한 금액보다 작거나 같은 경우만 입금 처리
“gt” : 아래 요청한 금액보다 작은 경우만 입금 처리
“le” : 아래 요청한 금액보다 크거나 같은 경우만 입금 처리
“lt” : 아래 요청한 금액보다 큰 경우만 입금 처리		 string O

(4) 응답 파라메터

① Result Object
② Auth Object
totalAuthId 통합인증 ID string Y
trackId 가맹점 주문번호 회신 string Y
③ Vact Object
trackId 가맹점 주문번호 회신 string Y
bankCd 은행코드 string Y
account 가상계좌번호 string Y
accountPretty 가상계좌번호 (pretty) string Y
holderName 고객명 string Y
amount 입금할 금액 string Y
oper 입금할 금액 수식 string Y
companyName 가상계좌 예금주명 string Y
issueId 가상계좌 발행번호 string Y
expireAt 가상계좌 만료시간(YYYYMMDDHH)
영구계좌 : 1년, 임시계좌 : 3일		 string Y
status 가상계좌 상태 “발행” string Y
udf1 가맹점 설정 필드1 string N
udf2 가맹점 설정 필드2 string N

close

(1) 사용자 만료

  • 발행된 계좌에 대한 만료 처리 요청

(2) API URL

api url /api/vact/close/{ISSUE_ID} or {TRACK_ID}

(3) 응답 파라메터

① Result Object
② Vact Object
bankCd 은행코드 string Y
account 가상계좌번호 (‘-‘ 하이픈미포함) string Y
trackId 가맹점 주문번호 회신 string Y
holderName 가상계좌 수취조회시 응답될 가맹점 명 string Y
oper 가상계좌 수취조회 사용 시 요청 수식 string Y
amount 금액 string Y
udf1 가맹점 설정 필드1 string O
udf2 가맹점 설정 필드2 string O
issueId 가상계좌 발행 번호 string Y
expireAt 가상계좌 만료 시간 ( YYYYMMDDHH )
서비스 신청 시 신청된 만료시간 영구 : 1년, 임시 : 3일		 string Y
status 가상계좌 상태 “사용자만료” string Y

patch

(1) 정보 변경

  • 발행된 계좌에 대한 정보 변경 , 아래 필드 중 값을 보낸 필드에 대해서만 변경 됨

(2) API URL

api url /api/vact/patch/{ISSUE_ID} or {TRACK_ID}

(3) 호출 파라메터

① Vact Object
trackId 가맹점 주문번호 회신 string O
holderName 가상계좌 수취조회시 응답될 가맹점 명 string O
oper 가상계좌 수취조회 사용 시 요청 수식 string O
account 금액 string O
udf1 가맹점 설정 필드 1 string O
udf2 가맹점 설정 필드 2 string O

(4) 응답 파라메터

① Result Object
② Vact Object
trackId 가맹점 주문번호 회신 string O
holderName 가상계좌 수취조회시 응답될 가맹점 명 string O
oper 가상계좌 수취조회 사용 시 요청 수식 string O
account 금액 string O
udf1 가맹점 설정 필드 1 string O
udf2 가맹점 설정 필드 2 string O

status

(1) 입금내역 확인

  • 가상계좌에 대한 발급 상태를 조회하며 거래가 있을 경우 해당 거래내역 리스트를 제공

(2) API URL

api url /api/vact/status/{ISSUE_ID} or {TRACK_ID}

(3) 응답 파라메터

① Result Object
② Vact Object
bankCd 은행코드 string Y
account 가상계좌번호 string Y
trackId 가맹점 주문번호 회신 string Y
holderName 가상계좌 수취조회시 응답될 가맹점 명 string Y
oper 가상계좌 수취조회 사용 시 요청 수식 string Y
amount 금액 string Y
udf1 가맹점 설정 필드1 string O
udf2 가맹점 설정 필드2 string O
issueId 가상계좌 발행 번호 string Y
expireAt 가상계좌 만료 예정 시간 ( YYYYMMDDHH ) string Y
status 가상계좌 상태 “예비” , “발급”, “사용만료”, “기한만료”,”사용자만료” string Y
datas 가상계좌 거래정보 Array 가상계좌 통지 정보

error

(1) 오류내역 확인

  • 가상계좌 입금시 오류가 발생한 계좌를 조회

(2) API URL

api url /api/vact/search/error/{ISSUE_ID}

(3) 응답 파라메터

① Result Object
② VactStatus Object
account 가상계좌번호 string Y
status 가상계좌상태 (예비/대기/발행/만료/사용자만료/기한만료) string Y
withDrawBankCd 출금계좌은행 string Y
withDrawBankAccount 출금계좌번호 (뒤 8자리까지 표시) string Y
reception 수취조회 내역 (에러값만 표시) string Y
③ Reception Object
recvDay 응답일시 string Y
recvTime 응답시간 string Y
amount 입금금액 string Y
resultCd 수취조회 결과코드 string Y
resultMsg 수취조회 결과메세지 string Y
udf2 가맹점 설정 필드 2 string Y

trx

(1) 출금내역 확인

  • 출금 거래번호로 해당 출금정보 리턴

(2) API URL

api url /api/vact/search/trx/{TRX_ID}

(3) 응답 파라메터

① Result Object
② vactPayOut Object
trxId 출금거래번호 string Y
mchtId 가맹점 아이디 string Y
status 출금상태(대기/전송/완료) string Y
retry 출금시도횟수 int Y
trxDay 거래일자 string Y
trxTime 거래시간 string Y
amount 출금원금 long Y
fee 수수료 long Y
feeVat 수수료 부과세 long Y
netAmount 실출금액 long Y
balance 거래후잔액 long Y
trackId 주문번호 string Y
bankCd 출금은행 string Y
account 출금계좌 (뒤 8자리만 표시) string Y
resultCd 출금결과코드 string Y
resultMsg 출금결과메세지 string Y

간편결제

pay

(1) 승인

  • 카드 승인 시 사용하는 Function 으로 요청 시 Pay는 기본 필수 값 및 Card, Products Array 로 구성
  • 결제페이지를 호출할 페이지에서 clientsideV2.js 를 import 하고 MARU.pay() 함수를 사용하여 결제창을 호출

(2) 호출 파라메터

① Pay Object
amount 결제금액 입력 number Y
publicKey 결제키 (pk_로 시작하는 가맹점 Public Key) string Y
payRoute 결제 유형 (간편결제는 ‘simple’로 고정) string Y
trxType 간편결제 유형(KAKAO, NAVER, PAYCO, SSG, LPAY) 대문자로 작성 string Y
products 구매 상품정보 Object Array Array Y
redirectURL 결제완료후 이동할 페이지(모바일결제시 필수) string O
responseFunction 결제결과를javascript function으로 리턴 function N
webhookUrl 결제결과를 webhook URL로 리턴 string N
udf1 사용자 임의 데이터 string N
udf2 사용자 임의 데이터 string N
payerName 구매자 성명 string Y
payerTel 구매자 연락처 string Y
payerEmail 구매자 이메일 string N
② Products Object
name 상품명 string Y
holderName 가상계좌 수취조회시 응답될 가맹점 명 string O
qty 구매 수량 integer O
price 객 단가 integer O
desc 상세설명 string O

(3) 응답 파라메터

① Result Object
② Pay Object

refund

(1) 승인/매입 취소

  • 익일정산: 당일 취소만 가능
  • 그 외(D+3, D+5 등): 정산예정일 전일까지 취소 가능
  • 단, 승인 취소의 경우 원 거래 금액과 동일해야 하며. 매입 취소는 원 거래금액 이하여야 합니다.

(2) API URL

api url /api/refund

(3) 호출 파라메터

① Refund Object
trxType “ONTR” 기본 string Y
trackId 취소 시의 가맹점 주문번호 string Y
Amount 취소 금액 long Y
udf1 가맹점 정의 필드 1: 응답 시 회신 됩니다. string O
udf2 가맹점 정의 필드 2: 응답 시 회신 됩니다. string O
rootTrxId 원거래에 대한 CREDITOP 거래번호 string O
rootTrackId 원거래에 대한 가맹점 주문번호 string Y
rootTrxDay 원거래의 거래 기준일 ( YYYYMMDD ) string Y
Metadata 현재 사용하지 않음 metadata N
trxId [응답 시 회신] CREDITOP 취소 거래 번호 string N
authCd [응답 시 회신] 취소 승인번호 string N
Settle [응답 시 회신] 취소에 대한 정산 예정일 및 정산 정보 settle N

(4) 응답 파라메터

① Result Object
② Pay Object

영수증 조회

receipt

(1) 영수증 조회

  • 거래번호의 값이 주어진 경우, 그 외의 값들은 무시하고 거래번호의 값으로만 영수증 조회가 가능합니다.
  • 거래번호의 값이 주어지지 않았을 때, 가맹점 아이디 또는 터미널 아이디의 값이 주어진 경우, 주문번호, 승인번호, 금액, 거래일자의 값을 모두 포함하여 영수증 조회가 가능합니다.

(2) API URL

api url /receipt

(3) 호출 파라메터

① parameter
trxId 거래번호 string Y
mchtId 가맹점 아이디 string Y
tmnId 터미널 아이디 string Y
trackId 주문번호 string Y
authCd 승인번호 string Y
amount 금액 number Y
regDay 거래일자(YYYYMMDD) string Y