API 명세서
자동 결제 API
자동결제 승인 요청

자동결제(bill) 승인 요청

빌링키 생성결과 callback에서 전달받은 빌링키로 가맹점은 승인 요청을 할 수 있습니다. 유효시간이나 최대 횟수를 제한하지 않으니 승인요청 API를 활용해서 결제를 진행할 수 있습니다.

자동결제 승인요청 API 사양은 다음과 같습니다.

각 API 응답 필드와 에러코드는 사전 공지 없이 추가되거나 변경될 수도 있으니, 추가된 항목으로 인해 오류가 발생하지 않도록 처리에 유의해 주시기 바랍니다.

엔드포인트

POSThttps://pay.toss.im/api/v1/billing-key/bill

요청 파라미터

apiKeystring필수
maxLen: 30

결제 가맹점의 API Key

빌링키 생성요청 시 사용된 API Key와 동일해야 합니다.


그렇지 않으면 오류가 발생합니다.

billingKeystring필수
maxLen: 50

자동결제 사용자 빌링키

승인할 사용자의 빌링키

orderNostring필수
maxLen: 50

결제 주문번호

가맹점의 상품 주문번호


• 최대 50자로 지정하며 숫자, 영문자도 가능하되 특수문자는 _ - : . ^ @ = 만 허용합니다.
• 가맹점의 주문번호는 매회 유니크한 값으로 생성하길 권장드립니다. (테스트와 라이브 환경에서 중복되지 않아야 합니다.)

productDescstring필수
maxLen: 255

상품 설명

결제할 상품 설명

amountinteger필수
maxLen: 7

총 결제 요청 금액

토스에서 금액과 관련된 모든 필드는 Number 형태로 선언합니다.


필수 체크는 총금액(amount)과 비과세 금액(amountTaxFree)만 체크합니다.


판매 상품이 과세 상품이라면 amount와 amountTaxFree만 포함하면 되고, 이후 계산은 토스 서버에서 자동으로 계산됩니다.

amountTaxFreeinteger필수
maxLen: 7

요청 금액 중 비과세 금액

판매하는 상품이 과세 품목이라면 해당 값을 0으로 선언합니다.


그 외의 과세 계산은 토스 서버에서 자동 처리합니다.


토스에서 금액과 관련된 모든 필드는 Number 형태로 선언합니다. 필수 체크는 총금액과 비과세 금액만 체크합니다.

amountTaxableinteger
maxLen: 7

요청 금액 중 과세 금액

요청 금액 중 과세 금액

amountVatinteger
maxLen: 7

요청 금액 중 부가세

요청 금액 중 부가세

amountServiceFeeinteger
maxLen: 7

요청 금액 중 봉사료

요청 금액 중 봉사료

spreadOutinteger
maxLen: 8

카드 할부개월

사용자가 선택한 카드 할부개월 (5만원 미만은 기본 일시불 결제)


0(일시불) ~ 12개월까지 숫자 형태로 선언합니다.

cashReceiptboolean
maxLen: 5

현금영수증 발급여부

토스 현금영수증 자동발행 기능을 사용한다면 매회 결제 시 true 값을, 미 사용하는 경우(false)로 선언하면 됩니다.


반드시 true 또는 false 값을 전달해주셔야 하고 null과 같은 비정상 값을 전달할 경우 해당 필드는 명시적으로 false로 처리됩니다.

cashReceiptTradeOptionstring
maxLen: 9

현금영수증 발급타입

문화비 관련 상품의 경우, 발급타입 설정이 필요합니다.


• CULTURE : 문화비


• GENERAL : 일반(default)
• PUBLIC_TP : 교통비

sendFailPushboolean
maxLen: 5

결제실패 푸시알람 사용여부

빌링키 결제가 실패할 경우, 사용자에게 결제 실패 알람을 발송합니다.(기본값은 true)


• 같은 빌링키로 다회 요청을 하더라도, 결제 실패 알람은 1시간 최대 1회 발송 가능합니다.
• 고객에게 빌링 결제 시 잔액부족 알람 발송을 희망하지 않을 경우, 해당 파라미터 값을 false로 선언합니다.

Example Request

curl https://pay.toss.im/api/v1/billing-key/bill \
    -H "Content-Type: application/json" \
    -d '{
        "apiKey": "sk_test_w5lNQylNqa5lNQe013Nq",
        "billingKey": "example-billingKey",
        "orderNo": "TEST_billing_1",
        "productDesc": "테스트샵 빌링 상품",
        "amount": 10000,
        "amountTaxFree": 0,
        "spreadOut": 7,
        "cashReceipt": true,
        "sendFailPush": true
    }'

응답 파라미터

codeinteger
maxLen: 2

성공여부

값설명
0성공
-1실패 (실패사유는 msg와 errorCode로 제공)
modestring
maxLen: 4

결제환경

값설명
LIVE실거래용
TEST테스트용
orderNostring
maxLen: 50

결제 주문번호

가맹점의 상품 주문번호

errorCodestring
maxLen: 40

에러코드

code가 -1일 때만 에러코드와 실패 사유를 전달합니다.


(errorCode는 사전 예고 없이 추가될 수 있으니 유의가 필요합니다.)

msgstring
maxLen: 120

에러메시지

한 가지 에러코드에 상황별로 다른 에러 메시지를 전달합니다.


여러 상황이 발생할 수 있으니 되도록이면 전달되는 에러 메시지 그대로를 처리해주세요.


'잔액부족' 등의 결제 실패의 경우, 가맹점은 사용자에게 재결제 시도를 요청해야 합니다. 토스에서는 별도의 노티를 하지 않습니다.

approvalTimestring
maxLen: 20

결제건의 승인 처리 시간

결제건이 실제 승인된 시간을 리턴합니다. (yyyy-MM-dd HH:mm:ss 형식)

amountinteger
maxLen: 7

승인금액

금액과 관련된 모든 파라미터는 Number 형태로 보내주셔야 에러가 발생하지 않습니다.
payMethodstring
maxLen: 10

승인된 결제수단

값설명
TOSS_MONEY토스머니/계좌
CARD카드
payTokenstring
maxLen: 30

승인된 결제토큰

정상 승인처리 되었을 때, 토스 서버에서 매회 유니크한 결제 토큰 값을 전달합니다.


가맹점에서는 이 값을 반드시 저장해야 하며, 거래 환불요청 시 중요한 키 값이 될 수 있으니 관리가 필요합니다.

transactionIdstring
maxLen: 36

거래 트랜잭션 코드

결제의 거래 구분을 위하여 토스 서버에서는 매회 유니크한 값을 생성해서 리턴합니다.


매출전표를 호출하거나 환불 진행 시 구분 값으로 활용할 수 있습니다.

discountedAmountinteger
maxLen: 7

토스 부담 할인 금액

승인에서 할인이 적용된 금액을 전달하며 할인 적용이 없을 경우 0으로 전달합니다.


할인 금액에는 토스 앱에서 자동 적용되는 즉시할인과 토스 포인트 사용금액이 포함됩니다.

paidAmountinteger
maxLen: 7

지불수단 승인금액

총 금액에서 할인금액 등을 제외한 순수한 지불수단 승인금액을 의미합니다.


현금영수증 발행 또는 별도로 활용하는 경우 이 값을 참조할 수 있습니다.

cardUserTypestring
maxLen: 20

카드 사용자 구분

값설명
PERSONAL본인 카드
PERSONAL_FAMILY가족 카드
CORP_PERSONAL법인지정 결제계좌 임직원
CORP_PRIVATE법인 공용
CORP_COMPANY법인지정 결제계좌 회사(하나카드만)
cardMethodTypestring
maxLen: 10

카드 타입

승인된 카드의 타입을 구분

값설명
CREDIT신용카드
CHECK체크카드
PREPAYMENT선불카드
cardCompanyNamestring
maxLen: 2

승인된 카드사명

카드 결제의 경우만 전달되며, 승인된 카드사 명과 카드코드를 확인할 수 있습니다.

cardCompanyCodeinteger
maxLen: 2

카드사 코드

토스에서 정의한 카드사 코드입니다.
미지원 카드사는 현재 준비 중입니다. (매입 카드사 기준입니다.)

cardCompanyNamecardCompanyCode
신한1
현대2
삼성3
국민4
롯데5
하나6
우리7
농협8
씨티(미지원)9
비씨(BC)10
cardAuthorizationNostring
maxLen: 8

카드사 승인번호

구매자가 확인할 수 있는 카드사 승인번호 8자리


테스트 거래의 경우 00000000으로 전달되며, 정상적인 카드사 승인번호는 라이브 키 결제에서 확인하실 수 있습니다.

cardNumberstring
maxLen: 20

마스킹된 카드번호

카드번호 16자리 중 중간자리는 마스킹됩니다.

cardNum4Printstring
maxLen: 4

사용자가 선택한 카드의 끝 4자리

카드사에 따라 마스킹이 포함되어 있을 수 있습니다.

cardBinNumberstring
maxLen: 8

카드 BIN 번호

카드사에서 준 카드 BIN 번호(마스킹 되어 있을 수 있습니다.)


100% 신뢰는 불가합니다.

salesCheckLinkUrlstring
maxLen: 120

신용카드 매출전표 호출 URL

승인된 카드 결제건의 매출전표를 확인할 수 있는 URL

spreadOutinteger
maxLen: 2

카드 할부개월

승인요청에서 구매자가 선택한 할부개월이 리턴됩니다.


5만원 미만 금액 및 일시불 결제의 경우 0으로 리턴됩니다.

noInterestboolean
maxLen: 5

카드 무이자 적용 여부

값설명
true무이자
false일반
accountBankCodestring
maxLen: 3

사용자가 선택한 계좌의 은행코드

사용자가 선택한 결제수단(payMethod)이 '토스머니'인 경우 토스가 정의한 은행 코드를 전달합니다.

accountBankNamestring
maxLen: 20

사용자가 선택한 계좌의 은행명

은행코드 리스트

accountNumberstring
maxLen: 30

계좌번호

계좌번호는 일부 마스킹을 포함하고 있습니다.

Example Response

{
  "code": 0,
  "mode": "TEST",
  "approvalTime": "2020-04-06 11:28:09",
  "amount": "150000",
  "payMethod": "CARD", //"TOSS_MONEY"
  "payToken": "example-payToken",
  "orderNo": "TEST_billing_1",
  "transactionId": "3243c76e-e9cf-4669-881b-33a3b82ddf49",
  "discountedAmount": 0,
  "paidAmount": "150000",
 
  // payMethod 가 CARD 일때
  "cardCompanyName": "롯데",
  "cardCompanyCode": 5,
  "cardAuthorizationNo": "00000000",
  "salesCheckLinkUrl": "https://alpha-pay.toss.im/payfront/web/external/sales-check?payToken=example-payToken&transactionId=5a8cf658-b60d-4ae3-a959-279c66fc6743",
  "spreadOut": 0,
  "noInterest": false,
  "cardUserType": "PERSONAL",
  "cardMethodType": "CREDIT",
  "cardNumber": "534292******790*",
  "cardNum4Print": "410*",
  "cardBinNumber": "531764"
 
  // payMethod 가 TOSS_MONEY 일때
  //"accountBankCode": "88",
  //"accountBankName": "신한은행",
  //"accountNumber": "110******676"
}
빌링키 처리결과 Callback빌링키 상태 조회