시작하기
2. 결제 생성하기
이 단계에서는 결제 생성 API를 호출해서 결제 건을 만들어요. 결제를 생성하면 구매자를 보낼 결제창 URL(checkoutPage)과 결제 고유 번호(payToken)를 받아요. 이 두 값이 다음 단계의 재료가 돼요.
구매자가 'A상점'에서 35,000원짜리 'B티셔츠'를 골라 결제를 요청한 상황을 가정할게요. 이때 가맹점 서버는 토스 결제 서버에 결제 생성을 요청해야 해요.
결제 생성 API Endpoint
POST https://pay.toss.im/api/v2/payments
결제 생성 API 호출하기
가맹점 서버에서 다음과 같이 결제 생성 API를 호출해요. 필수 파라미터만 담은 예제이고, apiKey에는 1단계에서 확인한 테스트용 API Key를 넣어요.
curl https://pay.toss.im/api/v2/payments \
-H "Content-Type: application/json" \
-d '{
"orderNo": "2026-0712-000001",
"amount": 35000,
"amountTaxFree": 0,
"productDesc": "B티셔츠",
"apiKey": "sk_test_w5lNQylNqa5lNQe013Nq",
"autoExecute": true,
"callbackVersion": "V2",
"resultCallback": "https://example-shop.com/api/payments/callback",
"retUrl": "https://example-shop.com/payments/complete",
"retCancelUrl": "https://example-shop.com/payments/cancel"
}'각 파라미터의 역할은 다음과 같아요.
| 파라미터 | 필수 | 설명 |
|---|---|---|
orderNo | 필수 | 상점 주문번호예요. 나중에 상점의 주문 정보와 토스 결제 정보를 매칭할 때 사용해요. 가맹점별로 매회 유니크해야 하고, 중복되면 결제 생성이 실패해요. |
amount | 필수 | 구매자에게 받을 총 결제 금액이에요. |
amountTaxFree | 필수 | 결제 금액 중 비과세 금액이에요. 비과세 상품이 없다면 0을 넣어요. |
productDesc | 필수 | 결제할 상품 정보예요. |
apiKey | 필수 | 상점의 API Key예요. 테스트용 Key를 넣으면 테스트 결제가, 실거래용 Key를 넣으면 실제 출금되는 결제가 생성돼요. |
autoExecute | 필수 | 자동 승인 설정이에요. true면 구매자 인증이 완료됐을 때 토스가 알아서 결제를 승인해요. false면 가맹점이 직접 승인 API를 호출해야 해요. |
resultCallback | autoExecute: true면 필수 | 결제 결과를 받을 가맹점 서버 URL이에요. 토스 서버가 출금을 완료하면 이 URL로 결과를 POST 요청해요. |
callbackVersion | autoExecute: true면 필수 | 콜백 버전이에요. 신규 연동이라면 V2를 사용하세요. |
retUrl | 필수 | 구매자가 결제 인증을 완료하면 이동시킬 가맹점 페이지 URL이에요. 결제 완료 화면으로 이동시키는 용도로만 쓰여요. |
retCancelUrl | 필수 | 구매자가 결제창에서 결제를 중단했을 때 이동시킬 가맹점 페이지 URL이에요. |
과세·부가세 금액 구성, 결제 만료 시각 같은 선택 파라미터를 포함한 전체 목록은 결제 생성 API 레퍼런스에서 확인할 수 있어요.
응답 확인하기
결제 생성에 성공하면 토스가 다음과 같이 응답해요.
{
"code": 0,
"payToken": "example-payToken",
"checkoutPage": "https://pay.toss.im/payfront/auth?payToken=example-payToken",
"status": 200
}code가0이면 결제 생성에 성공한 거예요. 그 외에는 오류 코드와 메시지가 전달돼요. 오류 코드의 의미는 에러 코드에서 확인하세요.checkoutPage는 구매자가 결제를 진행할 토스페이 결제창 URL이에요. 다음 단계에서 구매자를 이 URL로 보내요.payToken은 이 결제 건을 구분하는 토스 고유 값이에요. 결제 승인, 환불, 상태 조회 모두 이 값으로 요청하니 주문 정보와 함께 저장해 두세요.status는 HTTP 상태 코드예요. 성공 여부 판단은code값으로 하세요.
다음 단계
checkoutPage와 payToken을 받았다면 이제 구매자를 결제창으로 보낼 차례예요. 3. 결제창 연결하기로 이동하세요.