Softment | 개발자센터

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 값으로 전달합니다.

HTTP Header
Content-Type: application/json
Authorization: {발급받은 Pay Key}

공통 응답 형식

모든 API의 응답은 아래의 공통 구조를 따릅니다.

Response Structure
{
  "data": { ... },
  "success": true,
  "message": "완료",
  "resCode": "0000"
}
필드 타입 필수 설명
data object N 응답 데이터 (성공 시에만 포함)
success boolean Y 요청 성공 여부
message string Y 결과 메시지
resCode string Y 응답 코드 (4자리)

거래등록

POST /api/webpay/create

결제창 호출에 필요한 거래를 등록합니다. 통합결제창 방식과 간편결제 직접호출 방식을 모두 지원합니다.

거래등록 API 결제창 호출 승인요청 API

요청 파라미터

필드 타입 필수 최대 설명
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 소프트먼트 거래번호

요청 예시

Request
{
  "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" }
    ]
  }
}

응답 예시

Response
{
  "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"
}

승인요청

POST /api/approval

결제창에서 신용카드 인증 완료 후 승인요청에 사용하는 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)

요청 예시

Request
{
  "trxId": "T250915069864",
  "amount": "1004",
  "authorizationId": "j+IdySeVdmy0n27fNTcGj+INg6HdNwfIHGGJpbsdqfQ="
}

응답 예시

Response
{
  "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"
}

거래취소

POST /api/refund

승인된 거래를 취소(환불)합니다.

요청 파라미터

필드 타입 필수 최대 설명
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 취소 후 잔액

요청 예시

Request
{
  "trackId": "Test1234567890",
  "rootTrxId": "T250804069772",
  "amount": "10000"
}

응답 예시

Response
{
  "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"
}

거래상태 조회

POST /api/trxStatus

거래의 현재 상태를 조회합니다.

요청 파라미터

필드 타입 필수 최대 설명
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와 동일)

요청 예시

Request
{
  "trxId": "T250801778004"
}

응답 예시

Response
{
  "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>에 대외기관 패키지명을 등록합니다.

Android — AndroidManifest.xml
<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>

WebViewClientshouldOverrideUrlLoading을 오버라이드하여 앱스킴을 처리합니다.

Android — WebViewClient
@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.plistLSApplicationQueriesSchemes에 앱스킴을 등록합니다.

iOS — Info.plist
<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>

WKWebViewdecidePolicyForNavigationAction에서 앱스킴을 처리합니다.

iOS — WKWebView
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)
}