Skip to content
이 내용이 도움이 되었나요?

개발하기

서비스 소개와 콘솔 설정 방법은 토스페이 소개 문서를 참고해 주세요.

BaseURL

https://pay-apps-in-toss-api.toss.im

연동 흐름은 아래 순서를 따라 주세요.

  1. 결제 생성하기 — 서버에서 결제를 생성하고 payToken을 발급받아요.
  2. 결제 인증하기 — SDK로 결제창을 띄우고 사용자 인증을 수행해요.
  3. 결제 실행하기 — 인증이 완료된 payToken으로 실제 결제를 승인해요.
  4. 결제 환불하기 — 결제 건을 환불해요.
  5. 결제 상태 조회하기 — 결제 상태와 트랜잭션을 조회해요.

1. 결제 생성하기

결제 건을 생성해요.

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

현금영수증 사용 시 반드시 확인해 주세요

현금영수증 발급이 필요한 파트너사는 결제 생성 요청 시 cashReceipt: true를 반드시 전달해야 해요.
cashReceipt는 결제 생성 시점에만 설정할 수 있으며, 결제 완료 후에는 현금영수증 발급 대상을 변경할 수 없어요.
cashReceipt를 누락하거나 false로 보내면 현금영수증 발급 대상이 아니에요.


요청 헤더

이름타입필수설명
x-toss-user-keystringY토스 로그인을 통해 획득한 userKey 값이에요.

요청 파라미터

이름타입필수설명
orderNoStringY가맹점의 주문번호예요. 가맹점별로 매회 유니크해야 하며, 중복될 경우 결제 생성 요청이 실패해요.
숫자, 영문자, 특수문자 _-:.^@만 사용 가능하며 50자 이내여야 해요. 동일 주문번호는 구매자 인증 완료 이후 재사용이 불가해요. 최초 생성 후 2년이 지난 주문번호도 재사용할 수 없어요.
productDescStringY상품 설명이에요. 공백으로만 설정할 수 없고, 백슬래시 \와 따옴표 "를 포함할 수 없으며 총 255자 이내여야 해요. 한글이 포함된 경우 UTF-8 인코딩을 사용해 주세요.
amountIntegerY총 결제 금액이에요. 금액과 관련된 모든 파라미터는 숫자 형태로 전달해야 해요.
amountTaxFreeIntegerY결제 금액 중 비과세 금액이에요. 과세 품목이면 0으로 전달해 주세요.
amountTaxableIntegerN결제 금액 중 과세 금액이에요. 별도로 설정하지 않고 비과세 금액을 0원으로 보내면 서버에서 자동으로 계산해요.
amountVatIntegerN결제 금액 중 부가세예요. 값이 없으면 과세 금액을 11로 나눈 후 소수점 첫째 자리에서 올림으로 계산해요.
amountServiceFeeIntegerN결제 금액 중 봉사료예요.
enablePayMethodsStringN결제수단 구분 변수예요.
- TOSS_MONEY: 토스머니만 노출
- CARD: 카드만 노출
- null 또는 그 외: 상점에 설정된 기본 결제수단으로 노출
cashReceiptbooleanN현금영수증 발급 가능 여부예요. 현금영수증 기능을 사용하는 경우 true, 미사용의 경우 false를 전달해 주세요. null 같은 비정상 값을 전달하면 명시적으로 false로 처리돼요.
cashReceiptTradeOptionStringN현금영수증 발급 타입이에요.
- GENERAL: 일반(기본값)
- CULTURE: 문화비
- PUBLIC_TP: 교통비
installmentStringN할부 제한 타입이에요.
- USE: 할부 사용(기본값)
- NOT_USE: 할부 미사용
isTestPaymentbooleanY샌드박스 결제 요청이면 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,
    "cashReceipt": false,
    "isTestPayment": true
}'

응답 파라미터

이름타입설명
payTokenString토스페이 토큰이에요. 매회 유니크한 토큰 값이 생성돼요. 반드시 저장하고 관리해야 해요.
json
{
  "resultType": "SUCCESS",
  "success": {
    "payToken": "string"
  }
}

2. 결제 인증하기

TossPay.checkoutPayment는 토스페이 결제창을 띄우고 사용자 인증을 수행해요.
인증이 완료되면 성공 여부를 반환해요. 실제 결제 처리는 인증 성공 후 서버에서 별도로 진행해야 해요.

TossPay

지원환경: React NativeReact Native SDKv1.0.3WebViewWebView SDKv1.0.3
실행환경: Toss AppSandbox App

TossPay는 토스페이 결제 관련 함수를 모아둔 객체예요.

시그니처

typescript
TossPay: {
  checkoutPayment: typeof checkoutPayment;
}

프로퍼티

  • checkoutPaymenttypeof checkoutPayment

    토스페이 결제를 인증하는 함수예요.

checkoutPayment

지원환경: React NativeReact Native SDKv1.0.3WebViewWebView SDKv1.0.3
실행환경: Toss AppSandbox App

시그니처

typescript
function checkoutPayment(options: CheckoutPaymentOptions): Promise<CheckoutPaymentResult>;

파라미터

  • options필수 · CheckoutPaymentOptions

    결제창을 띄울 때 필요한 옵션이에요.

반환값

  • Promise<CheckoutPaymentResult>

    인증 성공 여부를 포함한 결과를 반환해요.

예제

js
import { checkoutPayment } from '@apps-in-toss/web-framework';

async function handleCheckoutPayment() {
  try {
    // 실제 구현 시 결제 생성 역할을 하는 API 엔드포인트로 대체해 주세요.
    const { payToken } = await fetch('/my-api/payment/create').then((res) => res.json());
    const { success, reason } = await checkoutPayment({ payToken });

    if (success) {
      // 실제 구현 시 결제를 실행하는 API 엔드포인트로 대체해 주세요.
      await fetch('/my-api/payment/execute', {
        method: 'POST',
        body: JSON.stringify({ payToken }),
        headers: { 'Content-Type': 'application/json' },
      });
      console.log('결제 성공');
    } else {
      console.log('인증 실패:', reason);
    }
  } catch (error) {
    console.error('결제 인증 중 오류가 발생했어요:', error);
  }
}
tsx
import { checkoutPayment } from '@apps-in-toss/web-framework';
import { Button } from '@toss/tds-mobile';

function TossPayButton() {
  async function handlePayment() {
    try {
      const { payToken } = await fetch('/my-api/payment/create').then((res) => res.json());
      const { success, reason } = await checkoutPayment({ payToken });

      if (success) {
        await fetch('/my-api/payment/execute', {
          method: 'POST',
          body: JSON.stringify({ payToken }),
          headers: { 'Content-Type': 'application/json' },
        });
        console.log('결제 성공');
      } else {
        console.log('인증 실패:', reason);
      }
    } catch (error) {
      console.error('결제 인증 중 오류가 발생했어요:', error);
    }
  }

  return <Button onClick={handlePayment}>결제하기</Button>;
}
tsx
import { TossPay } from '@apps-in-toss/framework';
import { Button } from '@toss/tds-react-native';

function TossPayButton() {
  async function handlePayment() {
    try {
      const { payToken } = await fetch('/my-api/payment/create').then((res) => res.json());
      const { success, reason } = await TossPay.checkoutPayment({ payToken });

      if (success) {
        await fetch('/my-api/payment/execute', {
          method: 'POST',
          body: JSON.stringify({ payToken }),
          headers: { 'Content-Type': 'application/json' },
        });
        console.log('결제 성공');
      } else {
        console.log('인증 실패:', reason);
      }
    } catch (error) {
      console.error('결제 인증 중 오류가 발생했어요:', error);
    }
  }

  return <Button onPress={handlePayment}>결제하기</Button>;
}

CheckoutPaymentOptions

지원환경: React NativeReact Native SDKv1.0.3WebViewWebView SDKv1.0.3
실행환경: Toss AppSandbox App

CheckoutPaymentOptions는 토스페이 결제창을 띄울 때 필요한 옵션이에요.

시그니처

typescript
interface CheckoutPaymentOptions {
  payToken: string;
}

프로퍼티

  • payToken필수 · string

    결제 토큰이에요.

CheckoutPaymentResult

지원환경: React NativeReact Native SDKv1.0.3WebViewWebView SDKv1.0.3
실행환경: Toss AppSandbox App

CheckoutPaymentResult는 토스페이 결제창에서 사용자가 인증에 성공했는지 여부예요.

시그니처

typescript
interface CheckoutPaymentResult {
  success: boolean;
  reason?: string;
}

프로퍼티

  • success필수 · boolean

    인증이 성공했는지 여부예요.

  • reasonstring

    인증이 실패했을 경우의 이유예요.


3. 결제 실행하기

구매자가 결제 인증을 완료하면 결제 상태는 '대기' 상태예요.
payToken과 주문번호로 이 API를 호출하면 실제 승인이 완료되고 구매자의 결제 수단에서 금액이 출금돼요.

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

요청 헤더

이름타입필수설명
x-toss-user-keystringY토스 로그인을 통해 획득한 userKey 값이에요.

요청 파라미터

이름타입필수설명
payTokenStringY토스페이 토큰이에요.
orderNoStringN가맹점 주문번호예요.
isTestPaymentbooleanYpayToken이 샌드박스에서 발급된 것이면 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
}'

응답

이름타입설명
modeString결제 환경이에요. LIVE: 실거래용, TEST: 테스트용
orderNoString승인된 상품 주문번호예요.
amountInteger상품 금액이에요.
approvalTimeString결제 승인 처리 시간이에요. (yyyy-MM-dd HH:mm:ss)
stateMsgString상태 응답 텍스트예요. 정상 응답일 경우 "결제 완료"로 내려와요.
discountedAmountInteger할인된 금액이에요. 할인 적용이 없으면 0으로 내려와요. 즉시할인과 토스 포인트 사용금액이 포함돼요.
paidAmountInteger지불수단 승인금액이에요. 총 금액 중 할인 금액을 제외한 순수 지불수단 승인금액이에요.
payMethodString결제수단이에요. TOSS_MONEY: 토스머니, CARD: 카드
payTokenString토스페이 토큰이에요. 반드시 저장하고 관리해야 해요.
transactionIdString거래 트랜잭션 아이디예요. 매출전표 호출이나 환불 진행 시 구분 값으로 활용할 수 있어요.
cardCompanyCodeString승인 카드사 코드예요.
cardCompanyNameString승인 카드사명이에요.
cardAuthorizationNoString구매자가 확인할 수 있는 카드사 승인번호예요. 라이브 키 결제에서 확인할 수 있어요.
spreadOutString사용자가 선택한 카드 할부개월이에요. 5만원 미만 금액 및 일시불 결제의 경우 0으로 내려와요.
noInterestString카드 무이자 적용 여부예요. true: 무이자, false: 일반
salesCheckLinkUrlString신용카드 매출전표 호출 URL이에요.
cardMethodTypeString카드 타입이에요. CREDIT: 신용카드, CHECK: 체크카드, PREPAYMENT: 선불카드
cardNumberString마스킹된 카드번호예요. 카드번호 16자리 중 중간 자리는 마스킹돼요.
cardUserTypeString카드 사용자 구분이에요. PERSONAL: 본인카드, PERSONAL_FAMILY: 가족카드, CORP_PERSONAL: 법인지정 결제계좌 임직원, CORP_PRIVATE: 법인 공용, CORP_COMPANY: 법인지정 결제계좌 회사(하나카드만)
cardNum4PrintString사용자가 선택한 카드의 끝 4자리예요.
cardBinNumberString카드 BIN 번호예요.
cashReceiptMgtKeyString현금영수증 관리번호 식별값이에요. 이 필드가 있으면 현금영수증 발급 여부를 구분할 수 있어요.
accountBankCodeString은행 코드예요. 토스머니 결제의 경우 토스가 정의한 은행 코드를 전달해요.
accountBankNameString은행명이에요.
accountNumberString계좌번호예요. 일부 마스킹이 포함돼요.
msgString응답이 성공이 아닌 경우 설명 메시지예요.
errorCodeString에러 코드예요.
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-keystringY토스 로그인을 통해 획득한 userKey 값이에요.

요청 파라미터

이름타입필수설명
payTokenStringY토스페이 토큰이에요.
reasonStringY환불 사유예요. 한글 및 숫자, 영문자, 특수문자 _ - : . ^ @ ( ) [ ] # / ! % ? &만 허용해요.
isTestPaymentbooleanYpayToken이 샌드박스에서 발급된 것이면 true, 라이브앱에서 발급된 것이면 false예요.

응답

이름타입설명
refundNoString환불 번호예요.
approvalTimeString환불 처리 시간이에요. (yyyy-MM-dd HH:mm:ss)
cashReceiptMgtKeyString현금영수증 관리번호 식별값이에요.
refundableAmountInteger환불 가능 금액이에요.
discountedAmountInteger할인된 금액이에요.
paidAmountInteger지불수단 승인금액이에요.
refundedAmountInteger환불 요청 금액이에요.
refundedDiscountAmountInteger환불 요청 금액 중 실 차감된 할인 금액이에요.
refundedPaidAmountInteger환불 요청 금액 중 실 차감된 지불수단 금액이에요.
payTokenString환불된 결제 토큰이에요.
transactionIdString거래 트랜잭션 아이디예요.
cardMethodTypeString카드 타입이에요. CREDIT: 신용카드, CHECK: 체크카드, PREPAYMENT: 선불카드
cardNumberString마스킹된 카드번호예요.
cardUserTypeString카드 사용자 구분이에요. PERSONAL: 본인카드, PERSONAL_FAMILY: 가족카드, CORP_PERSONAL: 법인지정 결제계좌 임직원, CORP_PRIVATE: 법인 공용, CORP_COMPANY: 법인지정 결제계좌 회사(하나카드만)
cardNum4PrintString사용자가 선택한 카드의 끝 4자리예요.
cardBinNumberString카드 BIN 번호예요.
accountBankCodeString은행 코드예요. 토스머니 결제의 경우 토스가 정의한 은행 코드를 전달해요.
accountBankNameString은행명이에요.
accountNumberString마스킹된 계좌번호예요.
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-keystringY토스 로그인을 통해 획득한 userKey 값이에요.

요청 파라미터

이름타입필수설명
payTokenStringY토스페이 토큰이에요.
orderNoStringY가맹점 주문번호예요.
isTestPaymentbooleanYpayToken이 샌드박스에서 발급된 것이면 true, 라이브앱에서 발급된 것이면 false예요.

응답

이름타입설명
modeString결제 환경이에요. LIVE: 실거래용, TEST: 테스트용
payTokenString토스페이 토큰이에요.
orderNoString토스페이와 연계된 가맹점 주문번호예요.
payStatusString결제 상태예요.
payMethodString결제수단이에요. TOSS_MONEY: 토스머니, CARD: 카드
amountInteger가맹점이 전달한 결제 총 금액이에요.
discountedAmountInteger할인된 금액이에요.
discountAmountV2Integer즉시 할인 적용 금액이에요.
paidPointV2Integer토스 포인트 사용금액이에요.
paidAmountInteger지불수단 승인금액이에요.
refundableAmountInteger환불 가능 잔액이에요.
amountTaxableInteger총 결제 금액 중 과세 금액이에요.
amountTaxFreeInteger총 결제 금액 중 비과세 금액이에요.
amountVatInteger총 결제 금액 중 부가세 금액이에요.
amountServiceFeeInteger총 결제 금액 중 봉사료예요.
disposableCupDepositInteger일회용 컵 보증금이에요.
accountBankCodeString은행 코드예요.
accountBankNameString은행명이에요.
accountNumberString마스킹된 계좌번호예요.
cardObject카드 정보예요.
noInterestBoolean카드 무이자 적용 여부예요. true: 무이자, false: 일반
spreadOutInteger사용자가 선택한 카드 할부개월이에요.
cardAuthorizationNoString구매자가 확인할 수 있는 카드사 승인번호예요.
cardMethodTypeString카드 타입이에요. CREDIT: 신용카드, CHECK: 체크카드, PREPAYMENT: 선불카드
cardUserTypeString카드 사용자 구분이에요.
cardNumberString마스킹된 카드번호예요.
cardBinNumberString카드 BIN 번호예요.
cardNum4PrintString사용자가 선택한 카드의 끝 4자리예요.
salesCheckLinkUrlString신용카드 매출전표 호출 URL이에요.
cardCompanyNameString승인 카드사명이에요.
cardCompanyCodeInteger카드사 코드예요.
transactionslist거래 트랜잭션 목록이에요.
stepTypeString요청된 거래 타입이에요. PAY: 결제, REFUND: 환불
transactionIdString거래 트랜잭션 아이디예요. 거래 대사 시 활용하는 것을 권장해요.
paidAmountInteger요청된 거래 타입 중 지불수단 금액이에요.
transactionAmountInteger요청된 거래 타입의 가맹점 전달금액이에요. 환불 요청의 경우 마이너스 금액이 내려와요.
discountedAmountInteger요청된 거래 타입 중 적용된 할인금액이에요. 즉시할인과 토스 포인트 사용금액이 포함돼요.
pointAmountInteger요청된 거래 타입 중 포인트 금액이에요.
regTsString요청 처리 시간이에요.
createdTsString결제 생성 시간이에요. 사용자 최초 결제 요청 시간이에요.
paidTsString결제 완료 처리 시간이에요.
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)
002KDB산업은행
003IBK기업은행
004KB국민은행
005KEB하나은행
007수협은행
011NH농협은행
020우리은행
023SC은행
027씨티은행
031대구은행
032부산은행
034광주은행
035제주은행
037전북은행
039경남은행
045MG새마을금고
048신협
050저축은행
064산림조합
071우체국
081하나은행
088신한은행
089케이뱅크
090카카오뱅크
092토스뱅크
103SBI저축은행
218KB증권
230미래에셋증권
238미래에셋증권
240삼성증권
243한국투자증권
247NH투자증권
261교보증권
262하이투자증권
263현대차투자증권
264키움증권
265이베스트증권
266SK증권
267대신증권
269한화투자증권
270하나증권
271토스증권
278신한투자증권
279DB금융투자
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지금은 은행 점검 시간이에요. 점검이 끝난 후 사용해 주세요.
그 외의 에러코드