개발하기

1. 결제 생성하기

결제 건을 생성합니다.

Content-type : application/json
Method : POST
URL : /api-partner/v1/apps-in-toss/pay/make-payment

요청 헤더

이름	타입	필수값 여부	설명
x-toss-user-key	string	Y	토스 로그인을 통해 획득한 userKey 값

요청 파라미터

이름	타입	필수	설명
orderNo	String	Y	가맹점의 주문번호 주문번호는 반드시 가맹점별로 매회 유니크해야 하며, 중복될 경우 결제 생성 요청이 실패합니다. - ‘숫자, 영문자, 특수문자 `_-:.^@’` 만 사용 가능하며, 50자 이내여야 합니다. - 동일 주문번호는 구매자 인증 완료 이후 절대 재사용이 불가합니다. - 최초 생성 후 2년이 지난 주문번호는 재사용할 수 없습니다. - 테스트 환경과 라이브 환경 간의 주문번호 충돌 방지를 위해 가맹점 관리가 필요합니다.
productDesc	String	Y	상품 설명 상품 설명은 공백으로만 설정할 수 없고, 백슬래시 `\` 와 따옴표 `,`를 포함할 수 없으며 총 255자 이내여야 합니다. 이 값에 한글이 포함되었다면 인코딩에 유의해주세요. 토스 인코딩 방식은 UTF-8 형식을 사용합니다.
amount	Integer	Y	총 결제 금액 금액과 관련된 모든 파라미터는 숫자 형태로 보내주셔야 에러가 발생하지 않습니다.
amountTaxFree	Integer	Y	결제 금액 중 비과세 금액 판매하시는 상품이 과세 품목이면 해당 값을 0으로 보내주세요. 비과세액은 필수값이니 빈 값으로 보내주시는 경우 에러가 발생합니다.
amountTaxable	Integer	N	결제 금액 중 과세 금액 별도의 과세액을 설정하지 않고, 비과세 금액을 0원으로 보내주시면 토스페이 서버에서 자동으로 과세와 부가세를 계산합니다.
amountVat	Integer	N	결제 금액 중 부가세 값이 없으면 환불할 과세 금액을 11로 나눈 후 소수점 첫째 자리에서 올림으로 계산합니다.
amountServiceFee	Integer	N	결제 금액 중 봉사료 봉사료 금액입니다.
enablePayMethods	String	N	결제수단 구분 변수 가맹점 필요에 따라 결제창에 노출하는 결제수단을 제어할 수 있습니다. - TOSS_MONEY : 결제수단 중 토스머니만 노출 - CARD : 결제수단 중 카드만 노출 - null 또는 그 외의 값 : 상점에 설정된 기본 결제수단으로 노출
cashReceipt	boolean	N	현금영수증 발급 가능 여부 현금영수증 기능을 활용하시는 경우 true, 미사용의 경우 false 로 선언해 주시기 바랍니다. 반드시 true 또는 false 값을 전달해 주셔야 하고, null 과 같은 비정상 값을 전달할 경우 해당 필드는 명시적으로 false 로 처리됩니다.
cashReceiptTradeOption	String	N	현금영수증 발급 타입 - GENERAL : 일반(기본 값) - CULTURE : 문화비 - PUBLIC_TP : 교통비
installment	String	N	할부 제한 타입 신용카드 결제 시, 사용자의 할부 선택을 제한할 수 있습니다. - USE : 할부 사용 (기본값) - NOT_USE : 할부 미사용
isTestPayment	boolean	Y	샌드박스 결제 요청이면 true, 라이브앱 결제 요청이면 false

curl --location 'https://{{domain}}/api-partner/v1/apps-in-toss/pay/make-payment' \
--header 'Content-Type: application/json' \
--header 'x-toss-user-key : 1234' \
--data '{
    "orderNo":"test-20250417-3",
    "productDesc":"test02",
    "amount":10,
    "amountTaxFree":0,
    "isTestPayment":true
}'

응답 파라미터

이름	타입	설명
payToken	String	토스페이 토큰 매회 유니크한 토큰 값이 생성됩니다. 가맹점에서는 이 값을 반드시 저장하고 관리하셔야 합니다.

json

{
  "resultType": "SUCCESS",
  "success": {
    "payToken": "string"
  }
}

2. 결제 인증하기

SDK를 통해 연동해주세요.

토스페이 결제창을 띄우고, 사용자 인증을 수행해요.
인증이 완료되면 성공 여부를 반환해요.

checkoutPayment 함수는 결제창을 통해 사용자 인증만 해요.
실제 결제 처리는 인증 성공 후 서버에서 별도로 해야 해요.
checkoutPayment를 참고해 주세요.

3. 결제 실행하기

구매자가 결제를 시도하면, 먼저 결제 정보를 생성하고 인증을 받아요.
이때 결제 상태는 '대기' 중이에요. 이후 결제를 실제로 승인하려면 주어진 주문번호와 결제 토큰을 사용해서 이 함수로 생성된 결제를 승인해요.
실제 승인이 완료되면, 구매자의 결제 수단(예: 카드, 계좌)에서 실제로 금액이 출금돼요.

Content-type : application/json
Method : POST
URL : /api-partner/v1/apps-in-toss/pay/execute-payment

요청 헤더

이름	타입	필수값 여부	설명
x-toss-user-key	string	Y	토스 로그인을 통해 획득한 userKey 값

요청 파라미터

이름	타입	필수	설명
payToken	String	Y	토스페이 토큰
orderNo	String	N	가맹점 주문번호
isTestPayment	boolean	Y	payToken 이 샌드박스에서 발급된 것이면 true, 라이브앱에서 발급된 것이면 false

curl --location 'https://{{domain}}/api-partner/v1/apps-in-toss/pay/execute-payment' \
--header 'Content-Type: application/json' \
--header 'x-toss-user-key : 1234' \
--data '{
    "payToken":"test-20250417-3",
    "orderNo":"test02",
    "isTestPayment":true
}'

응답

이름	타입	설명
mode	String	결제환경 - LIVE : 실거래용 - TEST : 테스트용
orderNo	String	승인된 상품 주문번호
amount	Integer	상품금액
approvalTime	String	결제건의 승인 처리 시간 결제건의 승인 처리 시간 (yyyy-MM-dd HH:mm:ss) 요청에 따른 결제건 처리 시간입니다. 환불 시에도 동일한 변수로 리턴되므로 구분하여 관리하시기 바랍니다.
stateMsg	String	상태 응답 텍스트 값 정상 응답일 경우 “결제 완료” 로 내려감
discountedAmount	Integer	할인된 금액 할인된 금액이 리턴되며, 할인 적용이 없으면 0으로 리턴됩니다. 할인 금액에는 토스 앱에서 자동 적용되는 즉시할인과 토스 포인트 사용금액이 포함됩니다. 결제 상점에 따라 할인조건은 차이가 있을 수 있습니다.
paidAmount	Integer	지불수단 승인금액 총 금액 중 할인된 금액을 제외한 순수 지불수단 승인금액입니다. 현금영수증 자체 발행을 사용하는 가맹점은 이 값으로 발행 처리해 주시면 됩니다.
payMethod	String	결제수단 - TOSS_MONEY : 토스머니 - CARD : 카드
payToken	String	토스페이 토큰 매회 유니크한 토큰 값이 생성됩니다. 가맹점에서는 이 값을 반드시 저장하고 관리하셔야 합니다.
transactionId	String	거래 트랜잭션 아이디 결제의 거래구분을 위하여 토스 서버에서 유니크한 값을 생성해서 전달드립니다. 매출전표를 호출하거나 환불 진행 시 구분 값으로 활용할 수 있습니다.
cardCompanyCode	String	승인 카드사 코드
cardCompanyName	String	승인 카드사명
cardAuthorizationNo	String	구매자가 확인할 수 있는 카드사 승인번호 정상적인 카드사 승인번호는 라이브 키 결제에서 확인하실 수 있습니다.
spreadOut	String	사용자가 선택한 카드 할부개월 5만원 미만 금액 및 일시불 결제의 경우 0으로 리턴됩니다.
noInterest	String	카드 무이자 적용 여부 - ture : 무이자 - false : 일반
salesCheckLinkUrl	String	신용카드 매출전표 호출 URL 승인된 카드 결제건의 매출전표를 확인할 수 있는 URL 입니다. 구매자의 추가인증 완료 후 거래내역을 확인할 수 있습니다.
cardMethodType	String	카드 타입 승인된 카드의 타입을 구분할 수 있습니다. 예를 들어, 상점의 신용카드 결제 비율을 알고 싶다면 이 값을 활용해주세요. - CREDIT : 신용카드 - CHECK : 체크카드 - PREPAYMENT : 선불카드
cardNumber	String	마스킹된 카드번호 카드번호 16자리 중 중간자리는 마스킹됩니다.
cardUserType	String	카드 사용자 구분 - PERSONAL : 본인카드 - PERSONAL_FAMILY : 가족카드 - CORP_PERSONAL : 법인지정 결제계좌 임직원 - CORP_PRIVATE : 법인 공용 - CORP_COMPANY : 법인지정 결제계좌 회사 (하나카드만)
cardNum4Print	String	사용자가 선택한 카드의 끝 4자리 사용자가 선택한 결제수단( `payMethod`)이 ‘카드’ 인 경우 카드번호 끝 4자리를 전달합니다. (카드사에 따라 마스킹이 포함되어 있을 수 있습니다)
cardBinNumber	String	카드 BIN 넘버 카드사에서 준 카드 BIN 번호 (마스킹되어있을 수 있습니다) 100% 신뢰는 불가합니다.
cashReceiptMgtKey	String	현금영수증 관리번호 식별값 국세청 승인번호는 아니며 토스페이에서 자체적으로 만든 식별값입니다. 해당 필드 존재로 현금영수증 발급 구분 가능합니다.
accountBankCode	String	은행 코드 사용자가 선택한 결제수단( `payMethod`)이 ‘토스머니’인 경우 토스가 정의한 은행 코드를 전달합니다.
accountBankName	String	은행 명
accountNumber	String	계좌번호 계좌번호는 일부 마스킹을 포함하고 있습니다.
msg	String	응답이 성공이 아닌 경우 설명 메시지
errorCode	String	에러 코드

json

{
  "resultType": "SUCCESS",
  "success": {
    "code": 0,
      "mode": "TEST",
      "orderNo": "20250417-2",
      "amount": 10,
      "approvalTime": "2025-04-17 12:32:10",
      "stateMsg": "결제 완료",
      "discountedAmount": 0,
      "paidAmount": 10,
      "payMethod": "TOSS_MONEY",
      "payToken": "O1NZck9XME8ureeVJVJP67",
      "transactionId": "45a77cf4-5577-4d5c-8827-4d4dd328bf12",
      "cardCompanyCode": null,
      "cardCompanyName": null,
      "cardAuthorizationNo": null,
      "spreadOut": null,
      "noInterest": null,
      "salesCheckLinkUrl": null,
      "cardMethodType": null,
      "cardNumber": null,
      "cardUserType": null,
      "cardNum4Print": null,
      "cardBinNumber": null,
      "cashReceiptMgtKey": null,
      "accountBankCode": "092",
      "accountBankName": "토스뱅크",
      "accountNumber": "100******094",
      "msg": null,
      "errorCode": null
  }
}

4. 결제 환불하기

결제 건을 구매자에게 돌려줍니다.

Content-type : application/json
Method : POST
URL : /api-partner/v1/apps-in-toss/pay/refund-payment

요청 헤더

이름	타입	필수값 여부	설명
x-toss-user-key	string	Y	토스 로그인을 통해 획득한 userKey 값

요청 파라미터

이름	타입	필수	설명
payToken	String	Y	토스페이 토큰
reason	String	Y	환불 사유 한글 및 숫자, 영문자, 특수문자 `_ - : . ^ @ ( ) [ ] # / ! % ? &` 만 허용합니다.
isTestPayment	boolean	Y	payToken 이 샌드박스에서 발급된 것이면 true, 라이브앱에서 발급된 것이면 false

응답

이름	타입	설명
refundNo	String	환불 번호
approvalTime	String	결제건의 환불 처리 시간 (yyyy-MM-dd HH:mm:ss)
cashReceiptMgtKey	String	현금영수증 관리번호 식별
refundableAmount	Integer	환불 가능 금액
discountedAmount	Integer	할인된 금액
paidAmount	Integer	지불수단 승인금액
refundedAmount	Integer	환불요청 금액
refundedDiscountAmount	Integer	환불요청 금액 중 실 차감된 할인 금액
refundedPaidAmount	Integer	환불요청 금액 중 실 차감된 지불수단 금
payToken	String	환불된 결제토큰
transactionId	String	거래 트랜잭션 아이디
cardMethodType	String	카드 타입 - CREDIT : 신용카드 - CHECK : 체크카드 - PREPAYMENT : 선불카드
cardNumber	String	마스킹된 카드번호
cardUserType	String	카드 사용자 구분 - PERSONAL : 본인 카드 - PERSONAL_FAMILY : 가족카드 - CORP_PERSONAL : 법인지정 결제계좌 임직원 - CORP_PRIVATE : 법인 공용 - CORP_COMPANY : 법인지정 결제계좌 회사(하나카드만)
cardNum4Print	String	사용자가 선택한 카드의 끝 4자리
cardBinNumber	String	카드 BIN 넘버
accountBankCode	String	은행코드 사용자가 선택한 결제수단(`payMethod`)이 '토스머니'인 경우 토스가 정의한 은행 코드를 전달합니다.
accountBankName	String	은행 명
accountNumber	String	마스킹된 계좌번호

json

{
  "resultType": "SUCCESS",
  "success": {
    "refundNo": "string",
    "approvalTime": "string",
    "cashReceiptMgtKey": "string",
    "refundableAmount": 0,
    "discountedAmount": 0,
    "paidAmount": 0,
    "refundedAmount": 0,
    "refundedDiscountAmount": 0,
    "refundedPaidAmount": 0,
    "payToken": "string",
    "transactionId": "string",
    "cardMethodType": "string",
    "cardNumber": "string",
    "cardUserType": "string",
    "cardNum4Print": "string",
    "cardBinNumber": "string",
    "accountBankCode": "string",
    "accountBankName": "string",
    "accountNumber": "string"
  }
}

5. 결제 상태 조회하기

생성된 결제건의 거래 상태와 거래 트랜잭션을 조회할 수 있습니다.
상황에 따라, 승인 혹은 환불 응답을 수신하지 못한 경우에도 활용 가능합니다.

Content-type : application/json
Method : POST
URL : /api-partner/v1/apps-in-toss/pay/get-payment-status

요청 헤더

이름	타입	필수값 여부	설명
x-toss-user-key	string	Y	토스 로그인을 통해 획득한 userKey 값

요청 파라미터

이름	타입	필수	설명
payToken	String	Y	토스페이 토큰
orderNo	String	Y	가맹점 주문번호
isTestPayment	boolean	Y	payToken 이 샌드박스에서 발급된 것이면 true, 라이브앱에서 발급된 것이면 false

응답

이름	타입	설명
mode	String	결제환경 - LIVE : 실거래용 - TEST : 테스트용
payToken	String	토스페이 토큰
orderNo	String	토스페이와 연계된 상점 주문번호
payStatus	String	결제상태
payMethod	String	결제수단 - TOSS_MONEY : 토스머니 - CARD : 카드
amount	Integer	가맹점이 토스로 전달한 결제 총 금액
discountedAmount	Integer	할인된 금액
discountAmountV2	Integer	즉시 할인 적용 금액
paidPointV2	Integer	토스 포인트 사용금액
paidAmount	Integer	지불수단 승인금액
refundableAmount	Integer	환불 가능 잔액
amountTaxable	Integer	총 결제 금액 중 적용된 과세 금액
amountTaxFree	Integer	총 결제 금액 중 적용된 비과세 금액
amountVat	Integer	총 결제 금액 중 적용된 부가세 금액
amountServiceFee	Integer	총 결제 금액 중 적용된 봉사료
disposableCupDeposit	Integer	일회용 컵 보증금
accountBankCode	String	은행코드
accountBankName	String	은행명
accountNumber	String	마스킹된 계좌번호
card	Object	카드 정보
noInterest	Boolean	카드 무이자 적용 여부 - true : 무이자 - false : 일반
spreadOut	Integer	사용자가 선택한 카드 할부개월
cardAuthorizationNo	String	구매자가 확인할 수 있는 카드사 승인번호
cardMethodType	String	카드 타입 - CREDIT : 신용카드 - CHECK : 체크카드 - PREPAYMENT : 선불카드
cardUserType	String	카드 사용자 구분 - PERSONAL : 본인 카드 - PERSONAL_FAMILY : 가족카드 - CORP_PERSONAL : 법인지정 결제계좌 임직원 - CORP_PRIVATE : 법인 공용 - CORP_COMPANY : 법인지정 결제계좌 회사(하나카드만)
cardNumber	String	마스킹된 카드번호
cardBinNumber	String	카드 BIN 넘버
cardNum4Print	String	사용자가 선택한 카드의 끝 4자리
salesCheckLinkUrl	String	신용카드 매출전표 호출URL
cardCompanyName	String	승인 카드사명
cardCompanyCode	Integer	카드사 코드
transactions	list	거래 트랜잭션
stepType	String	요청된 거래 타입 - PAY : 결제 - REFUND : 환불
transactionId	String	거래 트랜잭션 아이디 결제의 거래구분을 위하여 유니크한 값을 생성하여 전달드립니다. 거래 대사 시, 이 값을 활용하시길 권장드립니다.
paidAmount	Integer	요청된 거래 타입(stepType) 중 적용된 지불수단 금액
transactionAmount	Integer	요청된 거래 타입(stepType)의 가맹점 전달금액 ’환불’ 요청의 경우 -(마이너스) 금액이 리턴됩니다.
discountedAmount	Integer	요청된 거래 타입(stepType) 중 적용된 할인금액 할인 금액에는 토스 앱에서 자동 적용되는 즉시할인과 토스 포인트 사용금액이 포함됩니다.
pointAmount	Integer	요청된 거래 타입(stepType) 중 포인트 금액
regTs	String	요청 처리 시간
createdTs	String	결제 생성 시간 사용자 최초 결제 요청 시간
paidTs	String	결제 완료 처리 시간

json

{
  "resultType": "SUCCESS",
  "success": {
    "mode": "string",
    "payToken": "string",
    "orderNo": "string",
    "payStatus": "string",
    "payMethod": "string",
    "amount": 0,
    "discountedAmount": 0,
    "discountAmountV2": 0,
    "paidPointV2": 0,
    "paidAmount": 0,
    "refundableAmount": 0,
    "amountTaxable": 0,
    "amountTaxFree": 0,
    "amountVat": 0,
    "amountServiceFee": 0,
    "disposableCupDeposit": 0,
    "accountBankCode": "string",
    "accountBankName": "string",
    "accountNumber": "string",
    "card": {
      "noInterest": true,
      "spreadOut": 0,
      "cardAuthorizationNo": "string",
      "cardMethodType": "string",
      "cardUserType": "string",
      "cardNumber": "string",
      "cardBinNumber": "string",
      "cardNum4Print": "string",
      "salesCheckLinkUrl": "string",
      "cardCompanyName": "string",
      "cardCompanyCode": 0
    },
    "transactions": [
      {
        "stepType": "string",
        "transactionId": "string",
        "paidAmount": 0,
        "transactionAmount": 0,
        "discountedAmount": 0,
        "pointAmount": 0,
        "regTs": "string"
      }
    ],
    "createdTs": "string",
    "paidTs": "string"
  }
}

6. 코드 정리

결제상태 리스트

값	설명
PAY_STANDBY	결제 대기 중
PAY_APPROVED	구매자 인증 완료
PAY_CANCEL	결제 취소
PAY_PROGRESS	결제 진행 중
PAY_COMPLETE	결제 완료
REFUND_PROGRESS	환불 진행 중
REFUND_SUCCESS	환불 성공
SETTLEMENT_COMPLETE	정산 완료
SETTLEMENT_REFUND_COMPLETE	환불 정산 완료

은행코드 리스트

토스머니 결제의 경우 사용자가 선택한 계좌의 정보를 함께 전달합니다.

은행 코드 (accountBankCode)	은행 명 (accountBankName)
002	KDB산업은행
003	IBK기업은행
004	KB국민은행
005	KEB하나은행
007	수협은행
011	NH농협은행
020	우리은행
023	SC은행
027	씨티은행
031	대구은행
032	부산은행
034	광주은행
035	제주은행
037	전북은행
039	경남은행
045	MG새마을금고
048	신협
050	저축은행
064	산림조합
071	우체국
081	하나은행
088	신한은행
089	케이뱅크
090	카카오뱅크
092	토스뱅크
103	SBI저축은행
218	KB증권
230	미래에셋증권
238	미래에셋증권
240	삼성증권
243	한국투자증권
247	NH투자증권
261	교보증권
262	하이투자증권
263	현대차투자증권
264	키움증권
265	이베스트증권
266	SK증권
267	대신증권
269	한화투자증권
270	하나증권
271	토스증권
278	신한투자증권
279	DB금융투자
280	유진투자
287	메리츠증권
888	토스머니
889	토스포인트

카드사코드 리스트

카드사 이름	카드(매입사) 코드
신한	1
현대	2
삼성	3
국민	4
롯데	5
하나	6
우리	7
농협	8
씨티(미지원)	9
비씨(BC)	10

에러 코드

값	설명
PAYMENT_EXISTING_PAYMENT	이미 존재하는 결제입니다.
COMMON_INVALID_API_KEY	바르지 않은 apiKey 입니다.
COMMON_BREAK_TIME_OF_BANK	지금은 은행 점검 시간입니다. 점검이 끝난 후 사용해주세요.
그 외의 에러코드

개발하기 ​

1. 결제 생성하기 ​

2. 결제 인증하기 ​

3. 결제 실행하기 ​

4. 결제 환불하기 ​

5. 결제 상태 조회하기 ​

6. 코드 정리 ​

결제상태 리스트 ​

은행코드 리스트 ​

카드사코드 리스트 ​

에러 코드 ​

개발하기

1. 결제 생성하기

2. 결제 인증하기

3. 결제 실행하기

4. 결제 환불하기

5. 결제 상태 조회하기

6. 코드 정리

결제상태 리스트

은행코드 리스트

카드사코드 리스트

에러 코드