서비스 소개
본 문서는 위루트파이낸셜에서 제공하는 API에 대하여 기술합니다.
결제통지 API
결제 발생 시, 가맹점 관리자에 등록된 Noti URL (Webhook URL)로 아래 형식의 거래 데이터를 전송합니다.
거래정보를 정상적으로 수신하려면 사이트 관리자에서 결제통지 URL을 반드시 등록해 주세요.
방화벽 설정 안내
보안 설정이 필요한 경우 아래 IP를 허용하세요.
Webhook 서버 IP: 221.168.33.162
결제통지 전송 규격
필수 여부의 X 값들의 value는 빈 값으로 전달됩니다.
| 필드명 | 필드 ID | 필수여부 | 최대길이(byte) | 비고 |
|---|---|---|---|---|
| 가맹점 ID | mid | O | 50 | 결제 MID |
| 단말기 ID | tid | X | 50 | 결제 TID |
| 거래번호 | trx_id | O | 100 | 취소시 사용됩니다. |
| 거래금액 | amount | O | 20 | |
| 주문번호 | ord_num | O | 30 | |
| 승인번호 | appr_num | O | 10 | |
| 상품명 | item_name | X | 100 | 온라인 결제건에 한해 전송됩니다. |
| 구매자명 | buyer_name | X | 100 | 온라인 결제건에 한해 전송됩니다. |
| 구매자번호 | buyer_phone | X | 100 | 온라인 결제건에 한해 전송됩니다. |
| 발급사명 | issuer | O | 20 | |
| 매입사명 | acquirer | O | 20 | |
| 발급사 코드 | issuer_code | O | 3 | 각 코드번호는 금융기관 정의 탭을 참고하세요. |
| 매입사 코드 | acquirer_code | O | 3 | 각 코드번호는 금융기관 정의 탭을 참고하세요. |
| 카드번호 | card_num | O | 20 | |
| 할부기간 | installment | O | 2 | |
| 거래시간 | trx_dttm | O | 20 | |
| 취소시간 | cxl_dttm | X | 20 | |
| 취소여부 | is_cancel | O | 1 | |
| 모듈타입 | module_type | O | 1 | 0=장비, 1=수기, 2=인증, 3=간편, 4=빌링 |
| 타임스탬프 | timestamp | O | 10 | 1722258514 |
| 무결성 보장 값 | signature | O | 64 |
key=value형태로 생성된 데이터를 SHA256으로 단방향 암호화한 값입니다.
sha256("sign_key=value×tamp=value&mid=value") |
| 승인 요청시 입력했던 임시 예약필드 | temp | O | 500 |
결제통지 응답 규격
결제통지를 성공적으로 받았을 시, body에 작성하셔야할 내용입니다.
| 상황별 응답 | http code | body | 비고 |
|---|---|---|---|
| 성공시 응답 | 200 | {} | |
| 실패시 응답 | 200 외 http status code | {"message":"실패한 사유"} | 출력 body 내용은 전산내 결제통지 전송이력에 표시됩니다. (message 파라미터는 필수입니다.) |
거래조회 API
가맹점 주문번호와 취소회차로 거래건을 조회합니다.
타임아웃 발생시 해당 API를 통해 실제 거래가 성공했는지 예외처리 구문을 만들 수 있습니다.
거래조회 전송 규격
URL: https://api.weroutefincorp.com/api/v2/transactions/{ord_num}
예시 요청:
const params = {
'cxl_seq' : cxl_seq,
};
const headers = {
'Accept': 'application/json',
'Content-Type': 'application/json',
'Authorization': `${pay_key}`,
};
const res = $.get('https://api.weroutefincorp.com/api/v2/transactions/{ord_num}', params, headers);
use Illuminate\Support\Facades\Http;
$params = [
'cxl_seq' => cxl_seq,
];
$headers = [
'Accept' => 'application/json',
'Content-Type' => 'application/json',
'Authorization' => $pay_key,
];
$response = Http::withHeaders($headers)->get('https://api.weroutefincorp.com/api/v2/transactions/{ord_num}', $params);
import requests
import json
import base64
params = {
'cxl_seq': cxl_seq,
}
headers = {
'Accept': 'application/json',
'Content-Type': 'application/json',
'Authorization': pay_key
}
response = requests.get('https://api.weroutefincorp.com/api/v2/transactions/{ord_num}', json=params, headers=headers)
import org.springframework.web.reactive.function.client.WebClient;
Map<String, Object> params = new HashMap<>();
params.put("cxl_seq", cxl_seq);
Map<String, Object> jsonMap = new HashMap<>();
jsonMap.put("test", "결제통지로 전달받은 값");
ObjectMapper objectMapper = new ObjectMapper();
String jsonString = objectMapper.writeValueAsString(jsonMap);
String base64Encoded = Base64.getEncoder().encodeToString(jsonString.getBytes());
params.put("temp", base64Encoded);
WebClient client = WebClient.builder()
.baseUrl("https://api.weroutefincorp.com")
.defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
.defaultHeader("Authorization", payKey)
.build();
Mono<String> response = client.get()
.uri("/api/v2/transactions/{ord_num}")
.bodyValue(params)
.retrieve()
.onStatus(HttpStatus::isError, response -> Mono.error(new RuntimeException("API Error")))
.bodyToMono(String.class);
| 필드명 | 필드 ID | 필수여부 | 최대길이(byte) | 비고 |
|---|---|---|---|---|
| 가맹점 주문번호 | ord_num | O | 30 | |
| 취소회차 | cxl_seq | O | 1 | 승인거래건일 경우 0 입력 1회차 취소일경우 1 입력 (..2,3,4) |
거래조회 응답 규격
결과 코드가 0000이 아닌경우 결과 코드와 결과 메세지 파라미터만 리턴됩니다.
| 필드명 | 필드 ID | 필수여부 | 최대길이(byte) | 비고 |
|---|---|---|---|---|
| 결과 코드 | result_cd | O | 4 | 성공시: 0000, 이외 에러코드 |
| 결과 메세지 | result_msg | O | 50 | |
| 가맹점 ID | mid | O | 50 | MID |
| 단말기 ID | tid | X | 50 | TID |
| 거래금액 | amount | O | 20 | |
| 가맹점 주문번호 | ord_num | O | 30 | |
| 승인번호 | appr_num | O | 20 | |
| 상품명 | item_name | O | 100 | |
| 거래번호 | trx_id | O | 100 | |
| 발급사명 | issuer | O | 20 | |
| 매입사명 | acquirer | O | 20 | |
| 발급사 코드 | issuer_code | O | 3 | 각 코드번호는 금융기관 정의 탭을 참고하세요. |
| 매입사 코드 | acquirer_code | O | 3 | 각 코드번호는 금융기관 정의 탭을 참고하세요. |
| 카드번호 | card_num | O | 20 | |
| 할부기간 | installment | O | 2 | |
| 거래시간 | trx_dttm | O | 20 | 응답 포멧: 2023-04-30 11:11:11 |
| 취소시간 | cxl_dttm | X | 20 | 취소 거래건일시 리턴됩니다. 응답 포멧: 2023-04-30 11:11:11 |
| 취소회차 | cxl_seq | X | 20 | 취소 거래건일시 리턴됩니다. 응답 포멧: 2023-04-30 11:11:11 |
| 원거래번호 | ori_trx_id | X | 100 | 취소 거래건일시 리턴됩니다. |
결제 API
결제 API Interface의 구성과 사용방법에 대한 메뉴얼을 기술합니다.
해당 API는 전산내 결제모듈 연동정보를 요구합니다.
수기결제 승인요청 규격
URL: https://api.weroutefincorp.com/api/v2/pay/hand
수기결제는 실물 카드 없이 카드 정보를 직접 입력해 결제하는 방식입니다.
카드번호와 유효기간 등의 정보를 수기로 입력하여 결제를 진행할 수 있습니다.
결제방식은 비인증과 구인증으로 구분되며, 방식에 따라 필요한 정보는 다음과 같습니다.
- 비인증 : 카드번호, 유효기간
- 구인증 : 카드번호, 유효기간, 비밀번호, 생년월일(또는 사업자번호)
수기결제 흐름도
예시 요청:
const params = {
'mid' : mid,
'tid' : '',
'amount' : amount,
'ord_num' : '12345H13241234',
'item_name' : '테스트',
'buyer_name': '구매자명',
'buyer_phone': '01000000000',
'card_num' : '카드번호',
'yymm' : '2509',
'installment' : '00',
'auth_num' : '', //opt
'card_pw' : '', //opt
'is_send_email': 0,
'temp' : btoa(JSON.stringify({'test':'결제통지로 전달받은 값'})),
};
const headers = {
'Accept': 'application/json',
'Content-Type': 'application/json',
'Authorization': `${pay_key}`,
};
const res = $.post('https://api.weroutefincorp.com/api/v2/pay/hand', params, headers);
use Illuminate\Support\Facades\Http;
$params = [
'mid' => mid,
'tid' => '',
'amount' => amount,
'ord_num' => '12345H13241234',
'item_name' => '테스트',
'buyer_name' => '구매자명',
'buyer_phone' => '01000000000',
'card_num' => '카드번호',
'yymm' => '2509',
'installment' => '00',
'auth_num' => '', //opt
'card_pw' => '', //opt
'is_send_email' => 0,
'temp' => base64_encode(json_encode(['test' => '결제통지로 전달받은 값'])),
];
$headers = [
'Accept' => 'application/json',
'Content-Type' => 'application/json',
'Authorization' => $pay_key,
];
$response = Http::withHeaders($headers)->post('https://api.weroutefincorp.com/api/v2/pay/hand', $params);
import requests
import json
import base64
params = {
'mid': mid,
'tid': '',
'amount': amount,
'ord_num': '12345H13241234',
'item_name': '테스트',
'buyer_name': '구매자명',
'buyer_phone': '01000000000',
'card_num': '카드번호',
'yymm': '2509',
'installment': '00',
'auth_num': '',
'card_pw': '',
'is_send_email': 0,
'temp': base64.b64encode(json.dumps({'test': '결제통지로 전달받은 값'}).encode()).decode()
}
headers = {
'Accept': 'application/json',
'Content-Type': 'application/json',
'Authorization': pay_key
}
response = requests.post('https://api.weroutefincorp.com/api/v2/pay/hand', json=params, headers=headers)
import org.springframework.web.reactive.function.client.WebClient;
Map<String, Object> params = new HashMap<>();
params.put("mid", mid);
params.put("tid", "");
params.put("amount", amount);
params.put("ord_num", "12345H13241234");
params.put("item_name", "테스트");
params.put("buyer_name", "구매자명");
params.put("buyer_phone", "01000000000");
params.put("card_num", "카드번호");
params.put("yymm", "2509");
params.put("installment", "00");
params.put("auth_num", "");
params.put("card_pw", "");
params.put("is_send_email", "0");
Map<String, Object> jsonMap = new HashMap<>();
jsonMap.put("test", "결제통지로 전달받은 값");
ObjectMapper objectMapper = new ObjectMapper();
String jsonString = objectMapper.writeValueAsString(jsonMap);
String base64Encoded = Base64.getEncoder().encodeToString(jsonString.getBytes());
params.put("temp", base64Encoded);
WebClient client = WebClient.builder()
.baseUrl("https://api.weroutefincorp.com")
.defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
.defaultHeader("Authorization", payKey)
.build();
Mono<String> response = client.post()
.uri("/api/v2/pay/hand")
.bodyValue(params)
.retrieve()
.onStatus(HttpStatus::isError, response -> Mono.error(new RuntimeException("API Error")))
.bodyToMono(String.class);
| 요구 헤더명 | 요구 내용 | 비고 |
|---|---|---|
| Accept | application/json | |
| Content-Type | application/json | |
| Authorization | ${pay_key} | 온라인 결제 KEY |
| 필드명 | 필드 ID | 필수여부 | 최대길이(byte) | 비고 |
|---|---|---|---|---|
| 가맹점 ID | mid | O | 50 | MID |
| 단말기 ID | tid | O | 50 | TID(미존재시 빈값입력) |
| 승인금액 | amount | O | 20 | |
| 가맹점 주문번호 | ord_num | O | 30 | |
| 상품명 | item_name | O | 100 | |
| 구매자명 | buyer_name | O | 50 | |
| 구매자 전화번호 | buyer_phone | O | 20 | 요청포멧:01000000000 |
| 구매자 이메일 | buyer_email | X | 20 | |
| 이메일 발송여부 | is_send_email | O | 1 | 1=발송, 0=미발송 |
| 카드번호 | card_num | O | 16 | 5921123456781234 |
| 유효기간 | yymm | O | 4 | 2509 |
| 할부기간 | installment | O | 2 | 응답포멧: 00,02,03~11 (00=일시불, 02=2개월 할부, 11=11개월 할부) |
| 카드 소유자 번호 | auth_num | X | 12 | 카드 소유자 생년월일 6자리(YYMMDD), 또는 사업자 번호 |
| 카드비밀번호 | card_pw | X | 2 | 카드비밀번호 앞 2자리 |
| 임시 예약필드 | temp | X | 1000 |
인증결제 승인요청 규격
URL: https://api.weroutefincorp.com/v2/pay/auth
인증 결제는 신용카드 결제 시, PG사로부터 인증 결과를 받은 후 해당 인증키를 이용해 결제를 요청하는 방식입니다.
결제 요청 시 PG사의 결제창이 활성화되며, 이후 카드사 전용 결제 모듈을 통해 인증이 진행됩니다.
Return URL은 결제 결과를 전달받는 페이지입니다.
단, 사용자가 결제 완료 후 결제완료 버튼을 클릭하지 않고 창을 닫으면 Return URL로 데이터가 전송되지 않습니다.
따라서 거래 데이터 처리(DB 저장 등)는 Return URL이 아닌 가맹점 관리자에 등록 가능한 Noti URL을 사용하시기 바랍니다.
Noti URL 사용 방법은 결제통지 API를 참고하세요.
인증 결제 흐름
예시 요청:
<body>
<form method='post' accept-chartset='utf-8' action='https://api.weroutefincorp.com/v2/pay/auth'>
<input type='hidden' name='return_url' value='https://www.example.com/result'/>
<input type='hidden' name='user_agent' value='WP'/>
<input type='hidden' name='mid' value='{MID}'/>
<input type='hidden' name='tid' value='{TID}'/>
<input type='hidden' name='ord_num' value='5486A1697465312'/>
<input type='hidden' name='item_name' value='test'/>
<input type='hidden' name='amount' value='100'/>
<input type='hidden' name='buyer_name' value='test'/>
<input type='hidden' name='buyer_phone' value='100'/>
<input type='hidden' name='is_send_email' value='0'/>
<input type='hidden' name='installment' value='0'/>
<input type='hidden' name='pay_key' value='{PAY_KEY}'/>
<input type='hidden' name='temp' value='{예약 값}'/>
</form>
</body>
| 필드명 | 필드 ID | 필수여부 | 최대길이(byte) | 비고 |
|---|---|---|---|---|
| 돌아갈 URL | return_url | O | 255 | 승인 결과를 전달 받을 URL |
| 클라이언트 접속 환경 | user_agent | X | 1 | 클라이언트 측 접속 타입(WP=PC Web, WM=Mobile Web, WA=Mobile App(Android), WI=Mobile App(IOS), default=WP) |
| 성공시 돌아갈 URL | success_url | X | 255 | 상위 PG사별 사용/미사용 |
| 실패시 돌아갈 URL | fail_url | X | 255 | 상위 PG사별 사용/미사용 |
| 결제키 | pay_key | O | 100 | PG사로부터 발급받은 결제 KEY |
| 가맹점 ID | mid | O | 50 | MID |
| 단말기 ID | tid | O | 50 | TID(미존재시 빈값입력) |
| 승인금액 | amount | O | 20 | |
| 주문번호 | ord_num | O | 30 | |
| 상품명 | item_name | O | 100 | |
| 구매자명 | buyer_name | O | 50 | |
| 구매자 전화번호 | buyer_phone | O | 20 | 요청포멧:01000000000 |
| 구매자 이메일 | buyer_email | X | 20 | |
| 이메일 발송여부 | is_send_email | O | 1 | 1=발송, 0=미발송 |
| 할부기간 | installment | O | 2 | |
| 임시 예약필드 | temp | X | 180 |
간편결제 승인요청 규격
URL: https://api.weroutefincorp.com/v2/pay/simple
예시 요청:
<body>
<form method='post' accept-chartset='utf-8' action='https://api.weroutefincorp.com/v2/pay/simple'>
<input type='hidden' name='return_url' value='https://www.example.com/result'/>
<input type='hidden' name='mid' value='{MID}'/>
<input type='hidden' name='tid' value='{TID}'/>
<input type='hidden' name='ord_num' value='5486A1697465312'/>
<input type='hidden' name='item_name' value='test'/>
<input type='hidden' name='amount' value='100'/>
<input type='hidden' name='buyer_name' value='test'/>
<input type='hidden' name='buyer_phone' value='100'/>
<input type='hidden' name='is_send_email' value='0'/>
<input type='hidden' name='installment' value='0'/>
<input type='hidden' name='pay_key' value='{PAY_KEY}'/>
<input type='hidden' name='temp' value='{예약 값}'/>
</form>
</body>
| 필드명 | 필드 ID | 필수여부 | 최대길이(byte) | 비고 |
|---|---|---|---|---|
| 돌아갈 URL | return_url | O | 255 | 승인 결과를 전달 받을 URL |
| 성공시 돌아갈 URL | success_url | X | 255 | 상위 PG사별 사용/미사용 |
| 실패시 돌아갈 URL | fail_url | X | 255 | 상위 PG사별 사용/미사용 |
| 결제키 | pay_key | O | 100 | PG사로부터 발급받은 결제 KEY |
| 사용할 간편결제 타입 | route | O | 100 | KAKAO, NAVER |
| 가맹점 ID | mid | O | 50 | MID |
| 단말기 ID | tid | O | 50 | TID(미존재시 빈값입력) |
| 승인금액 | amount | O | 20 | |
| 주문번호 | ord_num | O | 30 | |
| 상품명 | item_name | O | 100 | |
| 구매자명 | buyer_name | O | 50 | |
| 구매자 전화번호 | buyer_phone | O | 20 | 요청포멧:01000000000 |
| 구매자 이메일 | buyer_email | X | 20 | |
| 이메일 발송여부 | is_send_email | O | 1 | 1=발송, 0=미발송 |
| 할부기간 | installment | O | 2 | |
| 임시 예약필드 | temp | X | 180 |
빌링결제 승인요청 규격
URL: https://api.weroutefincorp.com/api/v2/pay/bill-key/hand
빌링 결제는 고객이 결제할 카드에 대한 정보를 입력한 후 발급된 키 값으로 자동결제하는 방법입니다.
빌키 생성 탭에서 먼저 빌키 생성이 필요합니다.
빌키결제 흐름도
예시 요청:
const params = {
'mid' : mid,
'tid' : tid,
'ord_num' : ord_num,
'buyer_name' : buyer_name,
'buyer_phone' : buyer_phone,
'item_name' : item_name,
'is_send_email': 0,
'bill_key' : bill_key,
'amount' : amount,
};
const headers = {
'Accept': 'application/json',
'Content-Type': 'application/json',
'Authorization': `${pay_key}`,
};
const res = $.post('/api/v2/pay/bill-key/hand', params, headers);
use Illuminate\Support\Facades\Http;
$params = [
'mid' => mid,
'tid' => '',
'ord_num' => ord_num,
'buyer_name'=> buyer_name,
'buyer_phone'=> buyer_phone,
'item_name'=> item_name,
'is_send_email'=> 0,
'bill_key'=> bill_key,
'amount'=> amount,
];
$headers = [
'Accept' => 'application/json',
'Content-Type' => 'application/json',
'Authorization' => $pay_key,
];
$response = Http::withHeaders($headers)->post('https://api.weroutefincorp.com/api/v2/pay/bill-key/hand', $params);
import base64
params = {
'mid' : mid,
'tid' : tid,
'ord_num' : ord_num,
'buyer_name' : buyer_name,
'buyer_phone' : buyer_phone,
'item_name' : item_name,
'is_send_email': 0,
'bill_key' : bill_key,
'amount' : amount,
}
headers = {
'Accept': 'application/json',
'Content-Type': 'application/json',
'Authorization': pay_key
}
response = requests.post('https://api.weroutefincorp.com/api/v2/pay/bill-key/hand', json=params, headers=headers)
import org.springframework.web.reactive.function.client.WebClient;
Map<String, Object> params = new HashMap<>();
params.put("mid", mid);
params.put("tid", "");
params.put("ord_num", ord_num);
params.put("buyer_name", buyer_name);
params.put("buyer_phone", buyer_phone);
params.put("item_name", item_name);
params.put("is_send_email", 0);
params.put("bill_key", bill_key);
params.put("amount", amount);
Map<String, Object> jsonMap = new HashMap<>();
ObjectMapper objectMapper = new ObjectMapper();
String jsonString = objectMapper.writeValueAsString(jsonMap);
String base64Encoded = Base64.getEncoder().encodeToString(jsonString.getBytes());
WebClient client = WebClient.builder()
.baseUrl("https://api.weroutefincorp.com")
.defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
.defaultHeader("Authorization", payKey)
.build();
Mono<String> response = client.post()
.uri("/api/v2/pay/bill-key/hand")
.bodyValue(params)
.retrieve()
.onStatus(HttpStatus::isError, response -> Mono.error(new RuntimeException("API Error")))
.bodyToMono(String.class);
| 요구 헤더명 | 요구 내용 | 비고 |
|---|---|---|
| Accept | application/json | |
| Content-Type | application/json | |
| Authorization | ${pay_key} | 온라인 결제 KEY |
빌링 결제 요청 규격
| 필드명 | 필드 ID | 필수여부 | 최대길이(byte) | 비고 |
|---|---|---|---|---|
| 가맹점 ID | mid | O | 50 | MID |
| 단말기 ID | tid | O | 50 | TID(미존재시 빈값입력) |
| 주문번호 | ord_num | O | 30 | |
| 구매자명 | buyer_name | O | 50 | |
| 구매자 전화번호 | buyer_phone | O | 20 | 요청포멧:01000000000 |
| 상품명 | item_name | O | 100 | |
| 빌키 | bill_key | O | 100 | 빌키 생성 API를 통해 발급받은 빌키 |
| 구매자 이메일 | buyer_email | X | 20 | |
| 이메일 발송여부 | is_send_email | O | 1 | 1=발송, 0=미발송 |
| 결제금액 | amount | O | 20 |
공통 승인응답 규격
필수 항목이 아닌 값은 빈 값으로 전달됩니다.
승인 실패 시에는 result_cd와 result_msg만 응답됩니다.
인증결제 및 간편결제에서 return_url을 설정하지 않으면 기본 제공되는 응답 페이지에 결제 결과가 표시됩니다.
| 필드명 | 필드 ID | 필수여부 | 최대길이(byte) | 비고 |
|---|---|---|---|---|
| 결과 코드 | result_cd | O | 4 | 성공시: 0000, 이외 에러코드 |
| 결과 메세지 | result_msg | O | 50 | |
| 가맹점 ID | mid | O | 50 | MID |
| 단말기 ID | tid | X | 50 | TID |
| 거래금액 | amount | O | 20 | |
| 가맹점 주문번호 | ord_num | O | 30 | |
| 승인번호 | appr_num | O | 20 | |
| 상품명 | item_name | O | 100 | |
| 거래번호 | trx_id | O | 100 | 취소시 사용됩니다. |
| 발급사명 | issuer | O | 20 | |
| 매입사명 | acquirer | O | 20 | |
| 발급사 코드 | issuer_code | O | 3 | 각 코드번호는 금융기관 정의 탭을 참고하세요. |
| 매입사 코드 | acquirer_code | O | 3 | 각 코드번호는 금융기관 정의 탭을 참고하세요. |
| 카드번호 | card_num | O | 20 | |
| 할부기간 | installment | O | 2 | |
| 결제방식 | method | O | 10 | 응답포멧:수기 |
| 거래시간 | trx_dttm | O | 20 | 응답 포멧: 2023-04-30 11:11:11 |
빌링 API
빌링 결제 API Interface의 구성과 사용방법에 대한 메뉴얼을 기술합니다.
해당 API는 전산 내 빌링 결제 정보에 관련된 연동정보를 요구합니다.
빌키 생성
URL: https://api.weroutefincorp.com/api/v2/pay/bill-key
빌키 생성 흐름도
예시 요청:
const params = {
'mid' : mid,
'tid' : tid,
'ord_num' : ord_num,
'buyer_name' : buyer_name,
'buyer_phone' : buyer_phone,
'card_num' : card_num,
'yymm' : yymm,
'auth_num' : auth_num,
'card_pw' : card_pw,
};
const headers = {
'Accept': 'application/json',
'Content-Type': 'application/json',
'Authorization': `${pay_key}`,
};
const res = $.post('/api/v2/pay/bill-key', params, headers);
use Illuminate\Support\Facades\Http;
$params = [
'mid' => mid,
'tid' => '',
'ord_num' => ord_num,
'buyer_name'=> buyer_name,
'buyer_phone'=> buyer_phone,
'card_num'=> card_num,
'yymm'=> yymm,
'auth_num'=> auth_num,
'card_pw'=> card_pw,
];
$headers = [
'Accept' => 'application/json',
'Content-Type' => 'application/json',
'Authorization' => $pay_key,
];
$response = Http::withHeaders($headers)->post('https://api.weroutefincorp.com/api/v2/pay/bill-key', $params);
import base64
params = {
'mid' : mid,
'tid' : tid,
'ord_num' : ord_num,
'buyer_name' : buyer_name,
'buyer_phone' : buyer_phone,
'card_num' : card_num,
'yymm' : yymm,
'auth_num' : auth_num,
'card_pw' : card_pw,
}
headers = {
'Accept': 'application/json',
'Content-Type': 'application/json',
'Authorization': pay_key
}
response = requests.post('https://api.weroutefincorp.com/api/v2/pay/bill-key', json=params, headers=headers)
import org.springframework.web.reactive.function.client.WebClient;
Map<String, Object> params = new HashMap<>();
params.put("mid", mid);
params.put("tid", "");
params.put("ord_num", ord_num);
params.put("buyer_name", buyer_name);
params.put("buyer_phone", buyer_phone);
params.put("card_num", card_num);
params.put("yymm", yymm);
params.put("auth_num", auth_num);
params.put("card_pw", card_pw);
Map<String, Object> jsonMap = new HashMap<>();
ObjectMapper objectMapper = new ObjectMapper();
String jsonString = objectMapper.writeValueAsString(jsonMap);
String base64Encoded = Base64.getEncoder().encodeToString(jsonString.getBytes());
WebClient client = WebClient.builder()
.baseUrl("https://api.weroutefincorp.com")
.defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
.defaultHeader("Authorization", payKey)
.build();
Mono<String> response = client.post()
.uri("/api/v2/pay/bill-key")
.bodyValue(params)
.retrieve()
.onStatus(HttpStatus::isError, response -> Mono.error(new RuntimeException("API Error")))
.bodyToMono(String.class);
빌키 생성 요청 규격
| 요구 헤더명 | 요구 내용 | 비고 |
|---|---|---|
| Accept | application/json | |
| Content-Type | application/json | |
| Authorization | ${pay_key} | 온라인 결제 KEY |
| 필드명 | 필드 ID | 필수여부 | 최대길이(byte) | 비고 |
|---|---|---|---|---|
| 가맹점 ID | mid | O | 50 | MID |
| 단말기 ID | tid | O | 50 | TID(미존재시 빈값입력) |
| 주문번호 | ord_num | O | 30 | |
| 구매자명 | buyer_name | O | 50 | |
| 구매자 전화번호 | buyer_phone | O | 20 | 요청포멧:01000000000 |
| 카드번호 | card_num | O | 20 | |
| 유효기간 | yymm | O | 4 | 2509 |
| 카드 소유자 번호 | auth_num | O | 12 | 카드 소유자 생년월일 6자리(YYMMDD), 또는 사업자 번호 |
| 카드비밀번호 | card_pw | O | 2 | 카드비밀번호 앞 2자리 |
빌키 생성 응답 규격
| 필드명 | 필드 ID | 필수여부 | 최대길이(byte) | 비고 |
|---|---|---|---|---|
| 결과 코드 | result_cd | O | 4 | 성공시: 0000, 이외 에러코드 |
| 결과 메세지 | result_msg | O | 50 | |
| 빌키코드 | bill_code | O | 50 | |
| 빌키 | bill_key | O | 50 | 빌링 KEY |
| 발급사명 | issuer | O | 50 | 발급사명 |
| 발급사 코드 | issuer_code | O | 3 | 각 코드번호는 금융기관 정의 탭을 참고하세요. |
| 거래번호 | trx_id | O | 100 | |
| 거래시간 | trx_dttm | O | 20 | 응답 포멧: 2023-04-30 11:11:11 |
| 주문번호 | ord_num | O | 30 |
빌키 삭제
URL: https://api.weroutefincorp.com/api/v2/pay/bill-key
빌키 삭제 흐름도
예시 요청:
const params = {
'mid' : mid,
'ord_num' : ord_num,
'bill_key' : bill_key,
};
const headers = {
'Accept': 'application/json',
'Content-Type': 'application/json',
'Authorization': `${pay_key}`,
};
const res = $.delete('/api/v2/pay/bill-key', params, headers);
use Illuminate\Support\Facades\Http;
$params = [
'mid' => mid,
'ord_num' => ord_num,
'bill_key' => 'bill_key',
];
$headers = [
'Accept' => 'application/json',
'Content-Type' => 'application/json',
'Authorization' => $pay_key,
];
$response = Http::withHeaders($headers)->delete('https://api.weroutefincorp.com/api/v2/pay/bill-key', $params);
import base64
params = {
'mid' : mid,
'ord_num' : ord_num,
'bill_key' : bill_key,
}
headers = {
'Accept': 'application/json',
'Content-Type': 'application/json',
'Authorization': pay_key
}
response = requests.delete('https://api.weroutefincorp.com/api/v2/pay/bill-key', json=params, headers=headers)
import org.springframework.web.reactive.function.client.WebClient;
Map<String, Object> params = new HashMap<>();
params.put("mid", mid);
params.put("ord_num", ord_num);
Map<String, Object> jsonMap = new HashMap<>();
ObjectMapper objectMapper = new ObjectMapper();
String jsonString = objectMapper.writeValueAsString(jsonMap);
String base64Encoded = Base64.getEncoder().encodeToString(jsonString.getBytes());
WebClient client = WebClient.builder()
.baseUrl("https://api.weroutefincorp.com")
.defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
.defaultHeader("Authorization", payKey)
.build();
Mono<String> response = client.delete()
.uri("/api/v2/pay/bill-key")
.bodyValue(params)
.retrieve()
.onStatus(HttpStatus::isError, response -> Mono.error(new RuntimeException("API Error")))
.bodyToMono(String.class);
빌키 삭제 요청 규격
| 요구 헤더명 | 요구 내용 | 비고 |
|---|---|---|
| Accept | application/json | |
| Content-Type | application/json | |
| Authorization | ${pay_key} | 온라인 결제 KEY |
| 필드명 | 필드 ID | 필수여부 | 최대길이(byte) | 비고 |
|---|---|---|---|---|
| 가맹점 ID | mid | O | 50 | MID |
| 주문번호 | ord_num | O | 30 | |
| 빌키 | bill_key | O | 100 |
빌키 삭제 응답 규격
| 필드명 | 필드 ID | 필수여부 | 최대길이(byte) | 비고 |
|---|---|---|---|---|
| 결과 코드 | result_cd | O | 4 | 성공시: 0000, 이외 에러코드 |
| 결과 메세지 | result_msg | O | 50 | |
| 거래시간 | trx_dttm | O | 20 | 응답 포멧: 2023-04-30 11:11:11 |
| 주문번호 | ord_num | O | 30 |
취소 API
취소 API Interface의 구성과 사용방법에 대한 메뉴얼을 기술합니다.
해당 API는 전산내 결제모듈 연동정보를 요구합니다.
결제 API를 통해 발생한 결제 건을 취소할 수 있습니다.
결제 취소 흐름도
취소 요청 규격
URL: https://api.weroutefincorp.com/api/v2/pay/cancel
예시 요청:
const params = {
'mid' : mid,
'tid' : tid,
'amount' : amount,
'trx_id' : trx_id,
};
const headers = {
'Accept': 'application/json',
'Content-Type': 'application/json',
'Authorization': `${pay_key}`,
};
const res = $.post('/api/v2/pay/cancel', params, headers);
use Illuminate\Support\Facades\Http;
$params = [
'mid' => mid,
'tid' => '',
'amount' => amount,
'trx_id' => trx_id,
];
$headers = [
'Accept' => 'application/json',
'Content-Type' => 'application/json',
'Authorization' => $pay_key,
];
$response = Http::withHeaders($headers)->post('https://api.weroutefincorp.com/api/v2/pay/cancel', $params);
import base64
params = {
'mid': mid,
'tid': '',
'amount': amount,
'trx_id': trx_id,
}
headers = {
'Accept': 'application/json',
'Content-Type': 'application/json',
'Authorization': pay_key
}
response = requests.post('https://api.weroutefincorp.com/api/v2/pay/cancel', json=params, headers=headers)
import org.springframework.web.reactive.function.client.WebClient;
Map<String, Object> params = new HashMap<>();
params.put("mid", mid);
params.put("tid", "");
params.put("amount", amount);
params.put("trx_id", trx_id);
Map<String, Object> jsonMap = new HashMap<>();
jsonMap.put("test", "결제통지로 전달받은 값");
ObjectMapper objectMapper = new ObjectMapper();
String jsonString = objectMapper.writeValueAsString(jsonMap);
String base64Encoded = Base64.getEncoder().encodeToString(jsonString.getBytes());
params.put("temp", base64Encoded);
WebClient client = WebClient.builder()
.baseUrl("https://api.weroutefincorp.com")
.defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
.defaultHeader("Authorization", payKey)
.build();
Mono<String> response = client.post()
.uri("/api/v2/pay/cancel")
.bodyValue(params)
.retrieve()
.onStatus(HttpStatus::isError, response -> Mono.error(new RuntimeException("API Error")))
.bodyToMono(String.class);
| 요구 헤더명 | 요구 내용 | 비고 |
|---|---|---|
| Accept | application/json | |
| Content-Type | application/json | |
| Authorization | ${pay_key} | 온라인 결제 KEY |
| 필드명 | 필드 ID | 필수여부 | 최대길이(byte) | 비고 |
|---|---|---|---|---|
| 가맹점 ID | mid | O | 50 | MID |
| 단말기 ID | tid | O | 50 | TID(미존재시 빈값입력) |
| 취소금액 | amount | O | 20 | |
| 거래번호 | trx_id | O | 100 | 결제 API에서 응답으로온 trx_id를 입력합니다. |
취소 응답 규격
| 필드명 | 필드 ID | 필수여부 | 최대길이(byte) | 비고 |
|---|---|---|---|---|
| 결과 코드 | result_cd | O | 4 | 성공시: 0000, 이외 에러코드 |
| 결과 메세지 | result_msg | O | 50 | |
| 가맹점 ID | mid | O | 50 | MID |
| 단말기 ID | tid | X | 50 | TID |
| 취소금액 | amount | O | 20 | |
| 거래번호 | trx_id | O | 100 | |
| 원거래번호 | ori_trx_id | O | 100 | |
| 거래시간 | trx_dttm | O | 20 | 응답 포멧: 2023-04-30 11:11:11 |
| 취소시간 | cxl_dttm | O | 20 | 응답 포멧: 2023-04-30 11:11:11 |
| 임시 예약필드 | temp | X | 180 |
금융기관 정의
각 단락의 issuer_code, acquirer_code필드에 대한 정보입니다.
| 카드사 코드 | 카드사 명 |
|---|---|
| 01 | 비씨 |
| 02 | 국민 |
| 03 | 외환 |
| 04 | 삼성 |
| 06 | 신한 |
| 07 | 현대 |
| 08 | 롯데 |
| 09 | 한미 |
| 10 | 신세계 |
| 11 | 씨티 |
| 12 | 농협 |
| 13 | 수협 |
| 14 | 평화 |
| 15 | 우리 |
| 16 | 하나 |
| 17 | 동남 |
| 18 | 주택 |
| 19 | 조흥 |
| 20 | 축협 |
| 21 | 광주 |
| 22 | 전북 |
| 23 | 제주 |
| 24 | 산은 |
| 25 | 해외비자 |
| 26 | 해외마스터 |
| 27 | 해외다이너스 |
| 28 | 해외AMX |
| 29 | 해외JCB |
| 30 | 해외 |
| 31 | SK-OKCashBag |
| 32 | 우체국 |
| 33 | MG새마을체크 |
| 34 | 중국은행체크 |
| 38 | 은련 |
| 39 | 해외DISCOVER |
| 46 | 카카오 |
| 47 | 강원 |
| 48 | 토스 |
| 49 | 신협 |
| 50 | IBK기업 |
| 51 | 케이뱅크 |
| 99 | 기타 |