API 레퍼런스
소프트먼트 결제 API의 전체 엔드포인트와 요청/응답 명세를 확인할 수 있습니다.
기본 정보
소프트먼트 결제 API는 HTTPS 프로토콜 기반의 RESTful API입니다.
- Protocol HTTPS (TLS v1.0 ~ v1.2)
- Data Format JSON
- Character Set UTF-8
-
Content-Type
application/json -
Base URL (개발)
https://devpapi.softment.co.kr -
Base URL (운영)
https://papi.softment.co.kr
인증 방식
모든 API 호출 시 HTTP Header에 Authorization을 포함해야 합니다. 소프트먼트에서 발급받은 Pay Key를 Authorization 값으로 전달합니다.
Content-Type: application/json
Authorization: {발급받은 Pay Key}
공통 응답 형식
모든 API의 응답은 아래의 공통 구조를 따릅니다.
{
"data": { ... },
"success": true,
"message": "완료",
"resCode": "0000"
}
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| data | object | N | 응답 데이터 (성공 시에만 포함) |
| success | boolean | Y | 요청 성공 여부 |
| message | string | Y | 결과 메시지 |
| resCode | string | Y | 응답 코드 (4자리) |
거래등록
결제창 호출에 필요한 거래를 등록합니다. 통합결제창 방식과 간편결제 직접호출 방식을 모두 지원합니다.
요청 파라미터
| 필드 | 타입 | 필수 | 최대 | 설명 |
|---|---|---|---|---|
| trackId | string | Y | 50 | 가맹점 주문번호 (unique) |
| returnUrl | string | Y | 256 | 인증 완료 후 이동할 URL |
| amount | string | Y | 13 | 결제 금액 |
| payerName | string | N | 100 | 구매자 성명 |
| payerEmail | string | N | 100 | 구매자 이메일 |
| payerTel | string | N | 20 | 구매자 전화번호 |
| goodsName | string | Y | 100 | 구매 상품명 |
| device | string | Y | 10 | pc / mobile |
| cardMethodInfo | object | N | - | 신용카드 설정정보 |
| shopValueInfo | object | N | - | 가맹점 필드 |
| appScheme | string | N | 256 | 가맹점 앱스키마. WebView 결제 시 대외기관 앱 호출 후 복귀에 사용 |
| directPay | string | N | 1 | 간편결제 직접호출 여부. Y: 통합결제창을 거치지 않고 간편결제사 인증창 직접 호출 |
| cpCode | string | 조건부 | 4 | 간편결제사 코드. directPay=Y 시 필수. NPAY(네이버페이), KKO(카카오페이), TOSS(토스페이), SAM(삼성페이), PCO(페이코) |
| cpType | string | N | 1 | 간편결제 결제타입. 네이버페이/토스페이만 가능. C: 신용카드, M: 머니/포인트 |
| rcptType | string | N | 1 | 네이버페이 포인트 결제시 현금영수증 신청타입. 0: 미발행, 1: 소득공제용, 2: 지출증빙용 |
| rcptNo | string | N | 11 | 네이버페이 포인트 현금영수증 번호. 휴대폰번호(10~11자) 또는 사업자번호(10자) |
cardMethodInfo
| 필드 | 타입 | 설명 |
|---|---|---|
| cardInfoList | array | 결제창에 보여지는 카드사 리스트 |
| cardCd | string (max 3) | 카드사 코드 |
shopValueInfo
| 필드 | 타입 | 설명 |
|---|---|---|
| value1 ~ value7 | string | 가맹점 필드 1 ~ 7 |
응답 파라미터
| 필드 | 타입 | 설명 |
|---|---|---|
| authPageUrl | string | 결제창 호출 URL |
| approvalUrl | string | 승인요청시 사용하는 URL |
| trackId | string | 가맹점 주문번호 |
| trxId | string | 소프트먼트 거래번호 |
요청 예시
{
"amount": "1004",
"returnUrl": "https://www.shop.co.kr/returnUrl",
"device": "pc",
"trackId": "TEST-202508080001",
"goodsName": "테스트상품",
"payerName": "홍길동",
"payerTel": "010-1234-5678",
"payerEmail": "",
"cardMethodInfo": {
"cardInfoList": [
{ "cardCd": "029" },
{ "cardCd": "006" },
{ "cardCd": "031" },
{ "cardCd": "027" },
{ "cardCd": "016" }
]
}
}
응답 예시
{
"data": {
"authPageUrl": "http://papi.softment.co.kr/payment/authpage/key_17579125...",
"approvalUrl": "https://papi.softment.co.kr/api/approval",
"trackId": "TEST-202509150004",
"trxId": "T250915069867"
},
"success": true,
"message": "거래등록 완료",
"resCode": "0000"
}
승인요청
결제창에서 신용카드 인증 완료 후 승인요청에 사용하는 API입니다. 인증 데이터의 결제금액을 확인하여 이상이 없을 경우 호출하여 최종 승인을 완료합니다.
요청 파라미터
| 필드 | 타입 | 필수 | 최대 | 설명 |
|---|---|---|---|---|
| trxId | string | Y | 13 | 소프트먼트 거래번호 |
| amount | string | Y | 13 | 결제 금액 |
| authorizationId | string | Y | 64 | 인증 데이터 |
응답 파라미터
| 필드 | 타입 | 설명 |
|---|---|---|
| trxId | string | 소프트먼트 거래번호 |
| trxType | string | 인증거래 (3DTR 고정) |
| trackId | string | 가맹점 주문번호 |
| mchtId | string | 가맹점 아이디 |
| tmnId | string | 결제 터미널 아이디 |
| amount | string | 결제 금액 |
| transactionDate | string | 결제일시 (yyyyMMddHHmmss) |
| payerName | string | 구매자 성명 |
| payerEmail | string | 구매자 이메일 |
| payerTel | string | 구매자 전화번호 |
| goodsName | string | 구매 상품명 |
| payInfo | object | 결제 정보 |
payInfo
| 필드 | 타입 | 설명 |
|---|---|---|
| authCd | string | 승인번호 |
| payMethodTypeCode | string | 결제수단코드 (11: 신용카드, 50: 선불결제, 60: 간편결제) |
| cpCode | string | 간편결제사 코드 (NPAY / KKO / TOSS) |
| multiCardAmount | string | 복합결제 신용카드 금액 |
| multiPntAmount | string | 복합결제 포인트 금액 |
| cardInfo | object | 카드정보 |
cardInfo
| 필드 | 타입 | 설명 |
|---|---|---|
| cardNo | string | 카드번호 (마스킹) |
| issuer | string | 발급사명 |
| issuerCode | string | 발급사코드 |
| acquirer | string | 매입사명 |
| acquirerCode | string | 매입사코드 |
| installment | string | 할부기간 |
| cardType | string | 카드구분 (신용, 체크, 기프트) |
| partCancelUsed | string | 부분취소 가능여부 (Y / N) |
요청 예시
{
"trxId": "T250915069864",
"amount": "1004",
"authorizationId": "j+IdySeVdmy0n27fNTcGj+INg6HdNwfIHGGJpbsdqfQ="
}
응답 예시
{
"data": {
"trxId": "T250808778006",
"trxType": "3DTR",
"trackId": "TEST-202508080001",
"mchtId": "test",
"tmnId": "TMN000001",
"amount": "1004",
"transactionDate": "20250808181134",
"payerName": "홍*동",
"payerEmail": "",
"payerTel": "010****5678",
"goodsName": "테스트상품",
"payInfo": {
"authCd": "46899417",
"payMethodTypeCode": "11",
"cpCode": null,
"multiCardAmount": "0",
"multiPntAmount": "0",
"cardInfo": {
"cardNo": "465887******402*",
"issuer": "신한",
"issuerCode": "029",
"acquirer": "신한",
"acquirerCode": "029",
"installment": "00",
"cardType": "신용",
"partCancelUsed": "Y"
}
}
},
"success": true,
"message": "승인완료",
"resCode": "0000"
}
거래취소
승인된 거래를 취소(환불)합니다.
요청 파라미터
| 필드 | 타입 | 필수 | 최대 | 설명 |
|---|---|---|---|---|
| trackId | string | Y | 50 | 취소 시의 가맹점 주문번호 |
| amount | string | Y | 13 | 취소 금액 |
| rootTrxId | string | Y | 13 | 원거래 소프트먼트 거래번호 |
응답 파라미터
| 필드 | 타입 | 설명 |
|---|---|---|
| trxId | string | 소프트먼트 취소 거래번호 |
| authCd | string | 승인번호 |
| refundDate | string | 취소일시 (yyyyMMddHHmmss) |
| trackId | string | 취소 시의 가맹점 주문번호 |
| rootTrxId | string | 원거래 소프트먼트 거래번호 |
| rootTrackId | string | 원거래 가맹점 주문번호 |
| rootTrxDay | string | 원거래 일자 (yyyyMMdd) |
| amount | string | 취소 금액 |
| remainAmount | string | 취소 후 잔액 |
요청 예시
{
"trackId": "Test1234567890",
"rootTrxId": "T250804069772",
"amount": "10000"
}
응답 예시
{
"data": {
"trxId": "T250804069773",
"authCd": "71721147",
"refundDate": "20250804105027",
"trackId": "Test1234567890",
"rootTrxId": "T250804069772",
"rootTrackId": "TEST-202508040002",
"rootTrxDay": "20250804",
"amount": "10000",
"remainAmount": "0"
},
"success": true,
"message": "취소가 완료되었습니다.",
"resCode": "0000"
}
거래상태 조회
거래의 현재 상태를 조회합니다.
요청 파라미터
| 필드 | 타입 | 필수 | 최대 | 설명 |
|---|---|---|---|---|
| trxId | string | Y | 13 | 소프트먼트 거래번호 |
응답 파라미터
승인요청 응답과 동일한 구조에 아래 필드가 추가됩니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| trxId | string | 소프트먼트 거래번호 |
| trxType | string | 인증거래 (3DTR 고정) |
| status | string | 거래상태 코드 (WAITING, APPROVED, PARTIAL_CANCELLED, CANCELLED) |
| statusMsg | string | 거래상태 메시지 (대기, 승인완료, 부분취소, 전체취소) |
| trackId | string | 가맹점 주문번호 |
| mchtId | string | 가맹점 아이디 |
| tmnId | string | 결제 터미널 아이디 |
| amount | string | 결제 금액 |
| rdfAmount | string | 취소금액 |
| remainAmount | string | 취소 후 잔액 |
| transactionDate | string | 결제일시 (yyyyMMddHHmmss) |
| payerName | string | 구매자 성명 |
| payerEmail | string | 구매자 이메일 |
| payerTel | string | 구매자 전화번호 |
| goodsName | string | 구매 상품명 |
| payInfo | object | 결제 정보 (승인요청 응답의 payInfo와 동일) |
요청 예시
{
"trxId": "T250801778004"
}
응답 예시
{
"data": {
"trxId": "T250801778004",
"trxType": "3DTR",
"status": "CANCELLED",
"statusMsg": "전체취소",
"trackId": "TEST-202508010002",
"mchtId": "test",
"tmnId": "TMN000001",
"amount": "1004",
"rdfAmount": "1004",
"remainAmount": "0",
"transactionDate": "20250801152907",
"payerName": "홍*동",
"payerEmail": "",
"payerTel": "010****5678",
"goodsName": "테스트상품",
"payInfo": {
"authCd": "00513749",
"payMethodTypeCode": "11",
"cpCode": null,
"multiCardAmount": "0",
"multiPntAmount": "0",
"cardInfo": {
"cardNo": "465887******402*",
"issuer": "신한",
"issuerCode": "029",
"acquirer": "신한",
"acquirerCode": "029",
"installment": "00",
"cardType": "신용",
"partCancelUsed": "Y"
}
}
},
"success": true,
"message": "조회 완료",
"resCode": "0000"
}
WebView 연동
앱 WebView에서 결제창을 호출할 경우, 카드사 및 간편결제사 앱 호출 후 가맹점 앱으로 복귀하기 위해 앱스킴 처리가 필요합니다. 거래등록 API의 appScheme 파라미터에 가맹점 앱 스킴을 전달하세요.
Android 설정
AndroidManifest.xml의 <queries>에 대외기관 패키지명을 등록합니다.
<queries>
<package android:name="com.shcard.smartpay" />
<package android:name="kr.co.samsungcard.mpocket" />
<package android:name="com.kbcard.cxh.appcard" />
<package android:name="nh.smart.nhallonepay" />
<package android:name="com.lcacApp" />
<package android:name="kvp.jjy.MispAndroid320" />
<package android:name="com.hanaskcard.paycla" />
<package android:name="com.hyundaicard.appcard" />
<package android:name="com.nhn.android.search" />
<package android:name="com.kakao.talk" />
<package android:name="viva.republica.toss" />
<package android:name="com.samsung.android.spay" />
</queries>
WebViewClient의 shouldOverrideUrlLoading을 오버라이드하여 앱스킴을 처리합니다.
@Override
public boolean shouldOverrideUrlLoading(WebView view, String url) {
if (!URLUtil.isNetworkUrl(url) && !URLUtil.isJavaScriptUrl(url)) {
final Uri uri;
try {
uri = Uri.parse(url);
} catch (Exception e) {
return false;
}
if ("intent".equals(uri.getScheme())) {
return startSchemeIntent(url);
} else {
try {
startActivity(new Intent(Intent.ACTION_VIEW, uri));
return true;
} catch (Exception e) {
return false;
}
}
}
return false;
}
iOS 설정
Info.plist의 LSApplicationQueriesSchemes에 앱스킴을 등록합니다.
<key>LSApplicationQueriesSchemes</key>
<array>
<string>ispmobile</string>
<string>kb-acp</string>
<string>shinhan-sr-ansimclick</string>
<string>nhallonepayansimclick</string>
<string>lottesmartpay</string>
<string>mpocket.online.ansimclick</string>
<string>cloudpay</string>
<string>hdcardappcardansimclick</string>
<string>naversearchthirdlogin</string>
<string>kakaotalk</string>
<string>supertoss</string>
<string>samsungpay</string>
</array>
WKWebView의 decidePolicyForNavigationAction에서 앱스킴을 처리합니다.
func webView(_ webView: WKWebView,
decidePolicyFor navigationAction: WKNavigationAction,
decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
guard let url = navigationAction.request.url else {
decisionHandler(.allow)
return
}
if url.scheme != "http" && url.scheme != "https" {
UIApplication.shared.open(url, options: [:], completionHandler: nil)
decisionHandler(.cancel)
return
}
decisionHandler(.allow)
}