토스 페이
파트너에게 발급된 클라이언트 인증서 기반 mTLS 인증이에요. 인증서의 CN으로 미니앱을 식별해요. 인증서 발급·관리 방법은 서버 API 이용하기 문서를 참고하세요.
사용자를 인증하기 위한 키예요. 미니앱 SDK의 User.getAnonymousKey 함수로 발급받을 수 있어요
kQ7pL2mZxN9wRt5vB8yD3jF6cA1토스페이 결제 생성을 위한 요청 본문이에요.
총 결제 금액이에요.
1000결제 금액 중 봉사료예요.
0결제 금액 중 비과세 금액이에요. 과세 상품이면 0으로 보내주세요.
0결제 금액 중 과세 금액이에요. 별도의 과세액을 설정하지 않고 비과세 금액을 0원으로 보내면 토스페이 서버에서 자동으로 과세와 부가세를 계산해요.
909결제 금액 중 부가세예요. 값이 없으면 환불할 과세 금액을 11로 나눈 후 소수점 첫째 자리에서 올림으로 계산해요.
91현금영수증 발급 가능 여부예요. null일 경우 발급되지 않아요.
false현금영수증 발급 타입이에요. CULTURE(문화비)/GENERAL(일반, 기본값)/PUBLIC_TP(교통비) 중 하나예요.
GENERAL사용 가능한 결제 수단이에요. TOSS_MONEY/CARD 또는 null 값을 사용할 수 있어요.
CARD할부 제한 타입이에요. USE(할부 사용, 기본값)/NOT_USE(할부 미사용) 중 하나예요.
USE샌드박스일 경우 false, 라이브앱일 경우 true예요. true면 실결제가 이루어져요.
false가맹점의 상품 주문번호예요. 숫자, 영문자, 특수문자(_-:.^@)를 사용할 수 있어요.
20250422-01상품 설명이에요. 한글이 포함되면 인코딩에 유의해주세요.
테스트결제결제 생성 요청이 성공적으로 처리됐어요.
요청 본문이 형식에 맞지 않아요. error.data.errorDetails에서 필드별 상세를 확인하세요.
분류되지 않은 서버 오류예요. 계속 실패하면 파트너 지원 채널로 문의해 주세요.
POST /api-partner/v1/apps-in-toss/pay/make-payment HTTP/1.1
Host: pay-apps-in-toss-api.toss.im
x-toss-user-key: {userKey}
Content-Type: application/json
{
"orderNo": "20250422-01",
"productDesc": "테스트결제",
"amount": 1000,
"amountTaxFree": 0,
"amountTaxable": 909,
"amountVat": 91,
"amountServiceFee": 0,
"enablePayMethods": "CARD",
"cashReceipt": false,
"cashReceiptTradeOption": "GENERAL",
"installment": "USE",
"isTestPayment": false
}{
"resultType": "SUCCESS",
"success": {
"payToken": "pay_9f3ac72e8d41b0"
}
}파트너에게 발급된 클라이언트 인증서 기반 mTLS 인증이에요. 인증서의 CN으로 미니앱을 식별해요. 인증서 발급·관리 방법은 서버 API 이용하기 문서를 참고하세요.
사용자를 인증하기 위한 키예요. 미니앱 SDK의 User.getAnonymousKey 함수로 발급받을 수 있어요
kQ7pL2mZxN9wRt5vB8yD3jF6cA1사용자 인증이 된 결제 건에 대한 승인 요청 본문이에요.
샌드박스일 경우 false, 라이브앱일 경우 true예요. true면 실결제가 이루어져요.
false가맹점의 상품 주문번호예요. 숫자, 영문자, 특수문자(_-:.^@)를 사용할 수 있어요.
20250422-01토스페이 토큰이에요. 승인할 결제 건의 토큰값이에요.
pay_9f3ac72e8d41b0결제 승인 요청이 성공적으로 처리됐어요.
요청 본문이 형식에 맞지 않아요. error.data.errorDetails에서 필드별 상세를 확인하세요.
분류되지 않은 서버 오류예요. 계속 실패하면 파트너 지원 채널로 문의해 주세요.
POST /api-partner/v1/apps-in-toss/pay/execute-payment HTTP/1.1
Host: pay-apps-in-toss-api.toss.im
x-toss-user-key: {userKey}
Content-Type: application/json
{
"payToken": "pay_9f3ac72e8d41b0",
"orderNo": "20250422-01",
"isTestPayment": false
}{
"resultType": "SUCCESS",
"success": {
"accountBankCode": "88",
"accountBankName": "신한은행",
"accountNumber": "5678********",
"amount": 15000,
"approvalTime": "2025-04-22 13:12:00",
"cardAuthorizationNo": "A123456789",
"cardBinNumber": "123456",
"cardCompanyCode": 25,
"cardCompanyName": "현대카드",
"cardMethodType": "CREDIT",
"cardNum4Print": "1234",
"cardNumber": "654321******1234",
"cardUserType": "PERSONAL",
"cashReceiptMgtKey": "abc123",
"code": 0,
"discountedAmount": 12000,
"errorCode": "INSUFFICIENT_BALANCE",
"mode": "NORMAL",
"msg": "잔액이 부족합니다.",
"noInterest": false,
"orderNo": "20250422-01",
"paidAmount": 12000,
"payMethod": "CARD",
"payToken": "pay_9f3ac72e8d41b0",
"salesCheckLinkUrl": "https://pay.toss.im/receipt/abc123",
"spreadOut": 3,
"stateMsg": "정상처리",
"transactionId": "txn_7f3a9c2e81b4"
}
}파트너에게 발급된 클라이언트 인증서 기반 mTLS 인증이에요. 인증서의 CN으로 미니앱을 식별해요. 인증서 발급·관리 방법은 서버 API 이용하기 문서를 참고하세요.
사용자를 인증하기 위한 키예요. 미니앱 SDK의 User.getAnonymousKey 함수로 발급받을 수 있어요
kQ7pL2mZxN9wRt5vB8yD3jF6cA1결제 상태 조회 요청 파라미터예요.
테스트 결제인지 나타내요.
false주문 번호예요. 요청할 때 이 값과 payToken 둘 중 하나는 필수예요.
ORDER_20250407결제를 식별하는 키예요. 요청할 때 이 값과 orderNo 둘 중 하나는 필수예요.
pay_9f3ac72e8d41b0결제 상태 정보가 반환돼요.
요청 본문이 형식에 맞지 않아요. error.data.errorDetails에서 필드별 상세를 확인하세요.
분류되지 않은 서버 오류예요. 계속 실패하면 파트너 지원 채널로 문의해 주세요.
POST /api-partner/v1/apps-in-toss/pay/get-payment-status HTTP/1.1
Host: pay-apps-in-toss-api.toss.im
x-toss-user-key: {userKey}
Content-Type: application/json
{
"payToken": "pay_9f3ac72e8d41b0",
"orderNo": "ORDER_20250407",
"isTestPayment": false
}{
"resultType": "SUCCESS",
"success": {
"accountBankCode": "88",
"accountBankName": "신한은행",
"accountNumber": "5678********",
"amount": 15000,
"amountServiceFee": 0,
"amountTaxFree": 0,
"amountTaxable": 10000,
"amountVat": 1000,
"card": {
"cardAuthorizationNo": "A123456789",
"cardBinNumber": "123456",
"cardCompanyCode": 25,
"cardCompanyName": "현대카드",
"cardMethodType": "SINGLE",
"cardNum4Print": "1234",
"cardNumber": "654321******1234",
"cardUserType": "PERSONAL",
"noInterest": false,
"salesCheckLinkUrl": "https://pay.toss.im/receipt/abc123",
"spreadOut": 3
},
"createdTs": "2025-04-07T13:12:00Z",
"discountAmountV2": 3000,
"discountedAmount": 12000,
"disposableCupDeposit": 500,
"mode": "NORMAL",
"orderNo": "ORDER_20250407",
"paidAmount": 10000,
"paidPointV2": 2000,
"paidTs": "2025-04-07T13:12:05Z",
"payMethod": "CARD",
"payStatus": "DONE",
"payToken": "pay_9f3ac72e8d41b0",
"refundableAmount": 8000,
"transactions": []
}
}결제 건에 대해 환불을 요청할 수 있어요. 환불 가능 여부와 잔액 조건 등을 사전에 확인해주세요.
비즈니스 오류 코드
아래 오류는 HTTP 200과 resultType: FAIL로 응답해요.
5001
토스페이 청약이 되어 있지 않습니다.
4010
인증 정보를 찾을 수 없어요.
4095
요청 한도를 초과했습니다. 잠시 후 다시 시도해주세요.
이 API는 연동된 내부 시스템의 오류 코드를 그대로 전달할 수 있어요. 문서화되지 않은 errorCode는 실패로 처리하고 reason 메시지를 참고하세요.
요청 한도: 앱당 분당 3,000회
파트너에게 발급된 클라이언트 인증서 기반 mTLS 인증이에요. 인증서의 CN으로 미니앱을 식별해요. 인증서 발급·관리 방법은 서버 API 이용하기 문서를 참고하세요.
사용자를 인증하기 위한 키예요. 미니앱 SDK의 User.getAnonymousKey 함수로 발급받을 수 있어요
kQ7pL2mZxN9wRt5vB8yD3jF6cA1토스페이 환불을 위한 요청 본문이에요.
환불할 금액이에요. 미입력 시 환불할 결제 건의 남은 전액을 환불 처리해요. 부분환불 시 필수로 amount를 활용해 주세요.
1000샌드박스일 경우 false, 라이브앱일 경우 true예요. true면 실결제가 이루어져요.
false토스페이 토큰이에요. 승인할 결제 건의 토큰값이에요.
pay_9f3ac72e8d41b0환불 사유예요.
고객 단순 변심환불 요청이 성공적으로 처리됐어요.
요청 본문이 형식에 맞지 않아요. error.data.errorDetails에서 필드별 상세를 확인하세요.
분류되지 않은 서버 오류예요. 계속 실패하면 파트너 지원 채널로 문의해 주세요.
POST /api-partner/v1/apps-in-toss/pay/refund-payment HTTP/1.1
Host: pay-apps-in-toss-api.toss.im
x-toss-user-key: {userKey}
Content-Type: application/json
{
"payToken": "pay_9f3ac72e8d41b0",
"amount": 1000,
"reason": "고객 단순 변심",
"isTestPayment": false
}{
"resultType": "SUCCESS",
"success": {
"accountBankCode": "88",
"accountBankName": "신한은행",
"accountNumber": "5678********",
"approvalTime": "2025-04-22 13:15:00",
"cardBinNumber": "123456",
"cardMethodType": "CREDIT",
"cardNum4Print": "1234",
"cardNumber": "654321******1234",
"cardUserType": "PERSONAL",
"cashReceiptMgtKey": "abc123",
"discountedAmount": 0,
"paidAmount": 1000,
"payToken": "pay_9f3ac72e8d41b0",
"refundNo": "20250422-01-R1",
"refundableAmount": 0,
"refundedAmount": 1000,
"refundedDiscountAmount": 0,
"refundedPaidAmount": 1000,
"transactionId": "txn_7f3a9c2e81b4"
}
}파트너에게 발급된 클라이언트 인증서 기반 mTLS 인증이에요. 인증서의 CN으로 미니앱을 식별해요. 인증서 발급·관리 방법은 서버 API 이용하기 문서를 참고하세요.
사용자를 인증하기 위한 키예요. 미니앱 SDK의 User.getAnonymousKey 함수로 발급받을 수 있어요
kQ7pL2mZxN9wRt5vB8yD3jF6cA1빌링키 생성 요청 본문이에요.
테스트 결제 여부예요.
false자동결제 상품명이에요.
월간 구독인증 실패 시 이동할 URL이에요.
https://example-partner.com/billing/failure인증 성공 후 이동할 URL이에요.
https://example-partner.com/billing/success요청 처리 결과예요. resultType 값으로 성공/실패를 구분하세요.
요청 본문이 형식에 맞지 않아요. error.data.errorDetails에서 필드별 상세를 확인하세요.
분류되지 않은 서버 오류예요. 계속 실패하면 파트너 지원 채널로 문의해 주세요.
POST /api-partner/v1/apps-in-toss/pay/create-billing-key HTTP/1.1
Host: pay-apps-in-toss-api.toss.im
x-toss-user-key: {userKey}
Content-Type: application/json
{
"productDesc": "월간 구독",
"returnSuccessUrl": "https://example-partner.com/billing/success",
"returnFailureUrl": "https://example-partner.com/billing/failure",
"isTestPayment": false
}{
"resultType": "SUCCESS",
"success": {
"checkoutAndroidUri": "intent://billing/checkout#Intent;package=viva.republica.toss;end",
"checkoutIosUri": "supertoss://billing/checkout?token=3fa85f64-5717-4562-b3fc-2c963f66afa6",
"checkoutUri": "supertoss://billing/checkout?token=3fa85f64-5717-4562-b3fc-2c963f66afa6",
"wrappedToken": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
}파트너에게 발급된 클라이언트 인증서 기반 mTLS 인증이에요. 인증서의 CN으로 미니앱을 식별해요. 인증서 발급·관리 방법은 서버 API 이용하기 문서를 참고하세요.
사용자를 인증하기 위한 키예요. 미니앱 SDK의 User.getAnonymousKey 함수로 발급받을 수 있어요
kQ7pL2mZxN9wRt5vB8yD3jF6cA1빌링키 상태 조회 요청 본문이에요.
테스트 결제 여부예요.
false래핑된 빌링키 토큰이에요.
3fa85f64-5717-4562-b3fc-2c963f66afa6요청 처리 결과예요. resultType 값으로 성공/실패를 구분하세요.
요청 본문이 형식에 맞지 않아요. error.data.errorDetails에서 필드별 상세를 확인하세요.
분류되지 않은 서버 오류예요. 계속 실패하면 파트너 지원 채널로 문의해 주세요.
POST /api-partner/v1/apps-in-toss/pay/get-billing-key-status HTTP/1.1
Host: pay-apps-in-toss-api.toss.im
x-toss-user-key: {userKey}
Content-Type: application/json
{
"wrappedToken": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isTestPayment": false
}{
"resultType": "SUCCESS",
"success": {
"accountBankCode": "88",
"accountBankName": "신한은행",
"accountImgUrl": "https://pay.toss.im/img/bank.png",
"accountName": "홍길동",
"accountNumber": "5678********",
"billingKeyStatus": "ACTIVE",
"cardCompanyName": "현대카드",
"cardCompanyNo": 25,
"cardImgUrl": "https://pay.toss.im/img/card.png",
"cardName": "현대카드 the Green",
"cardNumber": "654321******1234"
}
}파트너에게 발급된 클라이언트 인증서 기반 mTLS 인증이에요. 인증서의 CN으로 미니앱을 식별해요. 인증서 발급·관리 방법은 서버 API 이용하기 문서를 참고하세요.
사용자를 인증하기 위한 키예요. 미니앱 SDK의 User.getAnonymousKey 함수로 발급받을 수 있어요
kQ7pL2mZxN9wRt5vB8yD3jF6cA1자동결제 승인 요청 본문이에요.
결제 금액이에요.
1000봉사료예요.
0비과세 금액이에요.
0과세 금액이에요.
909부가세예요.
91현금영수증 발급 여부예요. 값이 없으면 true로 처리돼요.
true현금영수증 발급 타입이에요. GENERAL/CULTURE/PUBLIC_TP 중 하나이고, 값이 없으면 GENERAL로 처리돼요.
GENERAL테스트 결제 여부예요.
false주문번호예요.
ORDER-20260408-001상품 설명이에요.
월간 구독 결제결제 실패 시 푸시 발송 여부예요. 값이 없으면 true로 처리돼요.
true할부 개월 수예요. 0이면 일시불이에요.
0래핑된 빌링키 토큰이에요.
3fa85f64-5717-4562-b3fc-2c963f66afa6요청 처리 결과예요. resultType 값으로 성공/실패를 구분하세요.
요청 본문이 형식에 맞지 않아요. error.data.errorDetails에서 필드별 상세를 확인하세요.
분류되지 않은 서버 오류예요. 계속 실패하면 파트너 지원 채널로 문의해 주세요.
POST /api-partner/v1/apps-in-toss/pay/execute-billing HTTP/1.1
Host: pay-apps-in-toss-api.toss.im
x-toss-user-key: {userKey}
Content-Type: application/json
{
"wrappedToken": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"orderNo": "ORDER-20260408-001",
"productDesc": "월간 구독 결제",
"spreadOut": 0,
"amount": 1000,
"amountTaxFree": 0,
"amountTaxable": 909,
"amountVat": 91,
"amountServiceFee": 0,
"cashReceipt": true,
"sendFailPush": true,
"cashReceiptTradeOption": "GENERAL",
"isTestPayment": false
}{
"resultType": "SUCCESS",
"success": {
"accountBankCode": "88",
"accountBankName": "신한은행",
"accountNumber": "5678********",
"amount": 50000,
"approvalTime": "2026-05-21 10:00:00",
"cardAuthorizationNo": "A123456789",
"cardBinNumber": "123456",
"cardCompanyCode": 25,
"cardCompanyName": "현대카드",
"cardMethodType": "CREDIT",
"cardNum4Print": "1234",
"cardNumber": "654321******1234",
"cardUserType": "PERSONAL",
"cashReceiptMgtKey": "abc123",
"code": 0,
"discountedAmount": 45000,
"errorCode": "COMMON_BILLING_KEY_NOT_FOUND",
"mode": "NORMAL",
"msg": "등록된 빌링키를 찾을 수 없어요.",
"noInterest": false,
"orderNo": "ORDER-20260408-001",
"paidAmount": 45000,
"payMethod": "CARD",
"payToken": "pay_9f3ac72e8d41b0",
"salesCheckLinkUrl": "https://pay.toss.im/receipt/abc123",
"spreadOut": 0,
"transactionId": "txn_7f3a9c2e81b4"
}
}파트너에게 발급된 클라이언트 인증서 기반 mTLS 인증이에요. 인증서의 CN으로 미니앱을 식별해요. 인증서 발급·관리 방법은 서버 API 이용하기 문서를 참고하세요.
사용자를 인증하기 위한 키예요. 미니앱 SDK의 User.getAnonymousKey 함수로 발급받을 수 있어요
kQ7pL2mZxN9wRt5vB8yD3jF6cA1자동결제 환불 요청 본문이에요.
테스트 결제 여부예요.
false환불할 자동결제 건의 토스페이 토큰이에요.
pay_9f3ac72e8d41b0환불 사유예요.
고객 단순 변심요청 처리 결과예요. resultType 값으로 성공/실패를 구분하세요.
요청 본문이 형식에 맞지 않아요. error.data.errorDetails에서 필드별 상세를 확인하세요.
분류되지 않은 서버 오류예요. 계속 실패하면 파트너 지원 채널로 문의해 주세요.
POST /api-partner/v1/apps-in-toss/pay/refund-billing HTTP/1.1
Host: pay-apps-in-toss-api.toss.im
x-toss-user-key: {userKey}
Content-Type: application/json
{
"payToken": "pay_9f3ac72e8d41b0",
"reason": "고객 단순 변심",
"isTestPayment": false
}{
"resultType": "SUCCESS",
"success": {
"accountBankCode": "88",
"accountBankName": "신한은행",
"accountNumber": "5678********",
"approvalTime": "2026-05-21 10:00:00",
"cardBinNumber": "123456",
"cardMethodType": "CREDIT",
"cardNum4Print": "1234",
"cardNumber": "654321******1234",
"cardUserType": "PERSONAL",
"cashReceiptMgtKey": "abc123",
"discountedAmount": 2000,
"paidAmount": 10000,
"payToken": "pay_9f3ac72e8d41b0",
"refundNo": "20250422-01-R1",
"refundableAmount": 8000,
"refundedAmount": 5000,
"refundedDiscountAmount": 1000,
"refundedPaidAmount": 4000,
"transactionId": "txn_7f3a9c2e81b4"
}
}파트너에게 발급된 클라이언트 인증서 기반 mTLS 인증이에요. 인증서의 CN으로 미니앱을 식별해요. 인증서 발급·관리 방법은 서버 API 이용하기 문서를 참고하세요.
사용자를 인증하기 위한 키예요. 미니앱 SDK의 User.getAnonymousKey 함수로 발급받을 수 있어요
kQ7pL2mZxN9wRt5vB8yD3jF6cA1빌링키 삭제 요청 본문이에요.
테스트 결제 여부예요.
false래핑된 빌링키 토큰이에요.
3fa85f64-5717-4562-b3fc-2c963f66afa6요청 처리 결과예요. resultType 값으로 성공/실패를 구분하세요.
요청 본문이 형식에 맞지 않아요. error.data.errorDetails에서 필드별 상세를 확인하세요.
분류되지 않은 서버 오류예요. 계속 실패하면 파트너 지원 채널로 문의해 주세요.
POST /api-partner/v1/apps-in-toss/pay/remove-billing-key HTTP/1.1
Host: pay-apps-in-toss-api.toss.im
x-toss-user-key: {userKey}
Content-Type: application/json
{
"wrappedToken": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isTestPayment": false
}{
"resultType": "SUCCESS",
"success": {
"code": 0,
"msg": "등록된 빌링키를 찾을 수 없어요."
}
}도움이 되었나요?