시작하기
1. 빌링키 생성하기
빌링키 생성 API를 호출해 사용자별 빌링키와 인증 URI를 받아요.
이 단계에서는 사용자를 식별하는 고유한 빌링키를 만들어요. 빌링키를 생성하면 사용자를 인증시킬 OS별 인증 URI를 함께 받고, 이 URI가 다음 단계의 재료가 돼요.
빌링키 생성 API Endpoint
POST https://pay.toss.im/api/v1/billing-key
빌링키 생성 API 호출하기
가맹점 서버에서 다음과 같이 호출해요. 필수 파라미터 위주의 예제예요.
curl https://pay.toss.im/api/v1/billing-key \
-H "Content-Type: application/json" \
-d '{
"apiKey": "sk_test_w5lNQylNqa5lNQe013Nq",
"userId": "tutorial-user-001",
"productDesc": "프리미엄 멤버십 월 구독",
"resultCallback": "https://example-shop.com/api/billing/callback",
"returnSuccessUrl": "https://example-shop.com/billing/success",
"returnFailureUrl": "https://example-shop.com/billing/failure"
}'| 파라미터 | 필수 | 설명 |
|---|---|---|
apiKey | 필수 | 상점의 API Key예요. 이후 승인·조회·삭제 요청 모두 이 Key와 동일해야 해요. |
userId | 필수 | 가맹점의 사용자 식별 값이에요. 가맹점 회원 아이디를 쓸 수 있고, 승인 정보와 매칭하기 위해 유니크한 값을 권장해요. |
productDesc | 필수 | 토스 결제창에 표기될 자동 결제 상품명이에요. |
resultCallback | 필수 | 사용자가 인증을 완료하면 결과를 받을 가맹점 서버 URL이에요. 보안상 HTTPS를 권장해요. |
returnSuccessUrl | retAppScheme 없으면 필수 | 인증 성공 후 사용자를 이동시킬 가맹점 페이지예요. |
returnFailureUrl | 선택 | 인증 실패 시 사용자를 이동시킬 가맹점 페이지예요. |
retAppScheme | 선택 (App to App이면 권장) | 가맹점 자체 앱에서 등록하는 경우 인증 완료 후 앱으로 복귀시킬 앱 스킴이에요. iOS는 자동 앱 전환이 되지 않아 특히 필요해요. |
displayId | 선택 | 같은 사용자로 빌링키를 여러 개 만들고 싶을 때 쓰는 다중 빌링키 식별 값이에요. |
전체 파라미터는 빌링키 생성 요청 레퍼런스에서 확인할 수 있어요.
응답 확인하기
생성에 성공하면 이렇게 응답해요.
{
"code": 0,
"billingKey": "example-billingKey",
"checkoutAndroidUri": "intent://pay/billingKey?billingKey=example-billingKey...#Intent;scheme=supertoss;package=viva.republica.toss;end",
"checkoutIosUri": "https://ul.toss.im?scheme=supertoss%3A%2F%2Fpay%2FbillingKey...",
"checkoutUri": "https://pay.toss.im/payfront/web/billing?billingKey=example-billingKey"
}billingKey는 이 사용자의 결제수단을 가리키는 고유 값이에요. 승인, 상태 조회, 삭제 모두 이 값으로 요청하니userId와 함께 저장해 두세요.checkoutAndroidUri,checkoutIosUri,checkoutUri는 사용자를 인증시킬 URI예요. 다음 단계에서 사용자의 환경에 맞게 골라 사용해요.
이 시점의 빌링키는 아직 결제에 쓸 수 없는 CREATE(생성됨) 상태예요. 사용자가 인증을 완료해 ACTIVE가 되어야 승인할 수 있어요. 상태 전체는 개요의 빌링키 상태 표를 참고하세요.
한 상점에서 사용자당 빌링키는 하나만 허용돼요. 같은 userId로 다시 생성하면 새 빌링키가 발급되고, 상태 조회도
최신 빌링키 기준으로 응답해요. 결제수단을 여러 개 등록하려면 displayId로 구분하세요.
다음 단계
인증 URI를 받았으니 사용자를 토스 앱으로 보낼 차례예요. 2. 사용자 인증 받기로 이동하세요.