> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/common/growth/promotion.md). # 프로모션 서비스 소개와 콘솔 설정 방법은 프로모션 소개 문서를 참고해 주세요. {% hint style="info" %} **프로모션을 개발하기 전에 꼭 확인해 주세요** 사용자의 오인지를 방지하기 위해 토스에서 이미 사용 중인 명칭과 동일하게 사용하거나 다른 의미로 사용하는 것은 불가해요. **\[예시]** * **포인트** * 미니앱 내에서 통용되는 자체 리워드에는 **'포인트'** 라는 명칭을 사용할 수 없어요. * '토스 포인트'가 지급된 것으로 오인할 수 있어요. * '토스 포인트'와 명확하게 구분할 수 있는 용어로 사용해 주세요. * **출금, 인출 등** — 현금화하는 것으로 오인할 수 있는 용어는 사용할 수 없어요. * 미니앱 내에서 가상 자산이 '토스 포인트'로 전환되는 경우라면 **'토스 포인트 지급'** 으로 표기해 주세요. {% endhint %} {% hint style="info" %} **호출 제한** userKey별로 분당 최대 10회까지 호출할 수 있어요. 초과 시 에러가 반환돼요. {% endhint %} *** ### 게임 미니앱 별도의 서버 연동 없이도 **게임 미니앱 내에서 유저에게 토스 포인트를 지급**하고, 혜택탭에 노출할 수 있어요. **SDK 함수: `grantPromotionRewardForGame`** 이 함수는 게임 카테고리 미니앱에서만 호출할 수 있어요. 비게임 카테고리에서 실행하면 오류가 발생해요. {% hint style="info" %} **주의하세요** * **토스앱 5.232.0 버전 이상**에서 지원해요. 해당 버전 미만에서는 `undefined`가 반환되며, 미니앱 진입 시 업데이트 안내 화면이 표시돼요. * 모든 사용자의 식별자를 안정적으로 확보하기 위해 **토스앱 최소 지원 버전을 5.232.0으로 상향**했어요. * 게임 사용자 식별자는 **게임사 내부 식별용 키**로만 사용되며, 이 키로 토스 서버에 직접 요청할 수 없어요. * 함수를 중복 호출하면 동일한 유저에게 리워드가 중복 지급될 수 있으니, **방어 로직을 반드시 적용**해 주세요. * **실제 프로모션을 시작하기 전에 테스트용 프로모션 코드로 최소 1회 이상 호출**해야 해요. (테스트 호출을 통해 프로모션이 정상적으로 등록 및 승인 상태로 전환돼요.) {% endhint %} **시그니처** ```typescript function grantPromotionRewardForGame({ params, }: { params: { promotionCode: string; amount: number; }; }): Promise; ``` **파라미터** * **params** · 필수 · `{ params: { promotionCode: string; amount: number } }` 포인트를 지급하기 위해 필요한 정보예요. * **params.promotionCode** · 필수 · `string` 프로모션 코드예요. * **params.amount** · 필수 · `number` 지급할 포인트 금액이에요. **반환 값** * `Promise<{ key: string } | { errorCode: string; message: string } | 'ERROR' | undefined>` 포인트 지급 결과를 반환해요. * `{ key: string }`: 포인트 지급에 성공했어요. key는 리워드 키를 의미해요. * `{ errorCode: string, message: string }`: 포인트 지급에 실패했어요. 에러 코드를 확인해 주세요. **에러 코드** 프로모션 함수 사용 중 발생할 수 있는 에러 코드 목록이에요. 응답 코드나 메시지를 참고해 **적절한 예외 처리 로직**을 적용해 주세요. {% hint style="info" %} **`4109` 에러가 발생한다면?** * 프로모션 예산의 **80% 소진이 이메일로 안내**가 발송돼요. * 프로모션을 계속 진행하려면 **콘솔에서 예산을 증액**해 주세요. * 예산이 부족할 경우, **비즈월렛에서 금액을 충전**해 예산을 늘릴 수 있어요. * 예산이 모두 소진되면 프로모션이 **자동으로 종료되어 `4109` 에러가 발생**해요. * 예산 부족으로 인해 포인트 지급이 실패하면 **사용자 CS 이슈로 이어질 수 있으니 주의**해 주세요. {% endhint %} | 코드 | 메시지 | 발생 원인 / 대응 방법 | | ----------- | --------------------- | --------------------------------------------- | | `40000` | | 게임이 아닌 미니앱에서 호출한 경우 | | `4100` | 프로모션 정보를 찾을 수 없어요 | 콘솔에 등록되지 않은 프로모션 키로 호출한 경우 | | `4109` | 프로모션이 실행중이 아니에요 | 콘솔에서 프로모션을 시작하지 않았거나, 예산이 모두 소진되어 자동 종료된 경우 | | `4110` | 리워드를 지급/회수할 수 없어요 | 내부 시스템 오류 발생한 경우로, **재지급 로직**을 적용해 주세요. | | `4111` | 리워드 지급내역을 찾을 수 없어요 | 존재하지 않은 지급 내역을 조회한 경우 | | `4112` | 프로모션 머니가 부족해요 | 예산 부족으로 지급이 실패한 경우로, 콘솔에서 예산 증액 또는 비즈월렛 충전 필요 | | `4114` | 1회 지급 금액을 초과했어요 | | | `4116` | 최대 지급 금액이 예산을 초과했어요 | | | `ERROR` | 알 수 없는 오류가 발생했어요. | | | `undefined` | 앱 버전이 최소 지원 버전보다 낮아요. | | **예제** {% tabs %} {% tab title="js" %} ```js import { grantPromotionRewardForGame } from '@apps-in-toss/web-framework'; async function handleGrantPromotionRewardForGame() { const result = await grantPromotionRewardForGame({ params: { promotionCode: 'GAME_EVENT_2024', amount: 1000, }, }); if (!result) { console.warn('지원하지 않는 앱 버전이에요.'); } else if (result === 'ERROR') { console.error('포인트 지급 중 알 수 없는 오류가 발생했어요.'); } else if ('key' in result) { console.log('포인트 지급 성공!', result.key); } else if ('errorCode' in result) { console.error('포인트 지급 실패:', result.errorCode, result.message); } } ``` {% endtab %} {% tab title="React" %} ```tsx import { grantPromotionRewardForGame } from '@apps-in-toss/web-framework'; function GrantRewardButton() { async function handleClick() { const result = await grantPromotionRewardForGame({ params: { promotionCode: 'GAME_EVENT_2024', amount: 1000, }, }); if (!result) { console.warn('지원하지 않는 앱 버전이에요.'); return; } if (result === 'ERROR') { console.error('포인트 지급 중 알 수 없는 오류가 발생했어요.'); return; } if ('key' in result) { console.log('포인트 지급 성공!', result.key); } else if ('errorCode' in result) { console.error('포인트 지급 실패:', result.errorCode, result.message); } } return ; } ``` {% endtab %} {% tab title="React Native" %} ```tsx import { Button } from 'react-native'; import { grantPromotionRewardForGame } from '@apps-in-toss/framework'; function GrantRewardButton() { async function handlePress() { const result = await grantPromotionRewardForGame({ params: { promotionCode: 'GAME_EVENT_2024', amount: 1000, }, }); if (!result) { console.warn('지원하지 않는 앱 버전이에요.'); return; } if (result === 'ERROR') { console.error('포인트 지급 중 알 수 없는 오류가 발생했어요.'); return; } if ('key' in result) { console.log('포인트 지급 성공!', result.key); } else if ('errorCode' in result) { console.error('포인트 지급 실패:', result.errorCode, result.message); } } return ; } ``` {% endtab %} {% tab title="React Native" %} ```tsx import { Button } from 'react-native'; import { grantPromotionReward } from '@apps-in-toss/framework'; function GrantRewardButton() { async function handlePress() { const result = await grantPromotionReward({ params: { promotionCode: 'EVENT_2024', amount: 1000, }, }); if (!result) { console.warn('지원하지 않는 앱 버전이에요.'); return; } if (result === 'ERROR') { console.error('포인트 지급 중 알 수 없는 오류가 발생했어요.'); return; } if ('key' in result) { console.log('포인트 지급 성공!', result.key); } else if ('errorCode' in result) { console.error('포인트 지급 실패:', result.errorCode, result.message); } } return