프로모션

서비스 소개와 콘솔 설정 방법은 프로모션 소개 문서를 참고해 주세요.

프로모션을 개발하기 전에 꼭 확인해 주세요

사용자의 오인지를 방지하기 위해 토스에서 이미 사용 중인 명칭과 동일하게 사용하거나 다른 의미로 사용하는 것은 불가해요.

[예시]

• 포인트

  • 미니앱 내에서 통용되는 자체 리워드에는 '포인트' 라는 명칭을 사용할 수 없어요.

    • '토스 포인트'가 지급된 것으로 오인할 수 있어요.
  • '토스 포인트'와 명확하게 구분할 수 있는 용어로 사용해 주세요.
• 출금, 인출 등 — 현금화하는 것으로 오인할 수 있는 용어는 사용할 수 없어요.

  • 미니앱 내에서 가상 자산이 '토스 포인트'로 전환되는 경우라면 '토스 포인트 지급' 으로 표기해 주세요.

호출 제한

userKey별로 분당 최대 10회까지 호출할 수 있어요. 초과 시 에러가 반환돼요.

---

게임 미니앱

별도의 서버 연동 없이도 게임 미니앱 내에서 유저에게 토스 포인트를 지급하고, 혜택탭에 노출할 수 있어요.

SDK 함수: grantPromotionRewardForGame

이 함수는 게임 카테고리 미니앱에서만 호출할 수 있어요. 비게임 카테고리에서 실행하면 오류가 발생해요.

주의하세요

• 토스앱 5.232.0 버전 이상에서 지원해요. undefined 값은 해당 버전 미만에서 반환되며, 이 경우 미니앱 진입 시 업데이트를 안내하는 화면이 표시돼요.
• 모든 사용자의 식별자를 안정적으로 확보하기 위해 토스앱 최소 지원 버전을 5.232.0으로 상향했어요.
• 게임 사용자 식별자는 게임사 내부 식별용 키로만 사용되며, 이 키로 토스 서버에 직접 요청할 수 없어요.
• 함수를 중복 호출하면 동일한 유저에게 리워드가 중복 지급될 수 있으니, 방어 로직을 반드시 적용해 주세요.
• 실제 프로모션을 시작하기 전에 테스트용 프로모션 코드로 최소 1회 이상 호출해야 해요. (테스트 호출을 통해 프로모션이 정상적으로 등록 및 승인 상태로 전환돼요.)

시그니처

function grantPromotionRewardForGame({
  params,
}: {
  params: {
    promotionCode: string;
    amount: number;
  };
}): Promise<GrantPromotionRewardForGameResult>;

파라미터

• 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 }: 포인트 지급에 실패했어요. 에러 코드를 확인해 주세요.

에러 코드

프로모션 함수 사용 중 발생할 수 있는 에러 코드 목록이에요. 응답 코드나 메시지를 참고해 적절한 예외 처리 로직을 적용해 주세요.

4109 에러가 발생한다면?

• 프로모션 예산의 80% 소진이 이메일로 안내가 발송돼요.
• 프로모션을 계속 진행하려면 콘솔에서 예산을 증액해 주세요.
• 예산이 부족할 경우, 비즈월렛에서 금액을 충전해 예산을 늘릴 수 있어요.
• 예산이 모두 소진되면 프로모션이 자동으로 종료되어 4109 에러가 발생해요.
• 예산 부족으로 인해 포인트 지급이 실패하면 사용자 CS 이슈로 이어질 수 있으니 주의해 주세요.

코드	메시지	발생 원인 / 대응 방법
40000		게임이 아닌 미니앱에서 호출한 경우
4100	프로모션 정보를 찾을 수 없어요	콘솔에 등록되지 않은 프로모션 키로 호출한 경우
4109	프로모션이 실행중이 아니에요	콘솔에서 프로모션을 시작하지 않았거나, 예산이 모두 소진되어 자동 종료된 경우
4110	리워드를 지급/회수할 수 없어요	내부 시스템 오류 발생한 경우로, 재지급 로직을 적용해 주세요.
4111	리워드 지급내역을 찾을 수 없어요	존재하지 않은 지급 내역을 조회한 경우
4112	프로모션 머니가 부족해요	예산 부족으로 지급이 실패한 경우로, 콘솔에서 예산 증액 또는 비즈월렛 충전 필요
4114	1회 지급 금액을 초과했어요
4116	최대 지급 금액이 예산을 초과했어요
ERROR	알 수 없는 오류가 발생했어요.
undefined	앱 버전이 최소 지원 버전보다 낮아요.

예제

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);
  }
}

React

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 <button onClick={handleClick}>포인트 지급하기</button>;
}

React Native

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 <Button onPress={handlePress} title="포인트 지급하기" />;
}

---

비게임 미니앱

비게임 카테고리 미니앱에서 프로모션을 통해 유저에게 토스 포인트를 지급하는 방법은 두 가지예요.

• 서버 없이 지급: 별도의 서버 연동 없이 SDK 함수 호출만으로 포인트를 지급해요.
• 서버를 통해 지급: 파트너사 서버에서 API를 직접 호출해 포인트를 지급해요. 요청 위변조 방지 등 무결성이 중요한 경우에 사용해요.

서버 없이 프로모션 포인트 지급하기

SDK 함수: grantPromotionReward

별도의 서버 연동 없이도 비게임 미니앱 내에서 유저에게 토스 포인트를 지급하고, 혜택탭에 노출할 수 있어요.

주의하세요

• 토스앱 5.232.0 버전 이상에서 지원해요. 해당 버전 미만에서는 undefined가 반환되며, 미니앱 진입 시 업데이트 안내 화면이 표시돼요.
• 함수를 중복 호출하면 동일한 유저에게 리워드가 중복 지급될 수 있으니, 방어 로직을 반드시 적용해 주세요.
• 실제 프로모션을 시작하기 전에 테스트용 프로모션 코드로 최소 1회 이상 호출해야 해요. 테스트 프로모션 코드는 샌드박스 앱이 아닌 토스앱(QR 코드 테스트) 에서 호출해야 해요.

시그니처

function grantPromotionReward({
  params,
}: {
  params: {
    promotionCode: string;
    amount: number;
  };
}): Promise<GrantPromotionRewardResult>;

파라미터

• 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 }: 포인트 지급에 실패했어요. 에러 코드를 확인해 주세요.

에러 코드

프로모션 함수 사용 중 발생할 수 있는 에러 코드 목록이에요. 응답 코드나 메시지를 참고해 적절한 예외 처리 로직을 적용해 주세요.

4109 에러가 발생한다면?

• 프로모션 예산의 80% 소진이 이메일로 안내가 발송돼요.
• 프로모션을 계속 진행하려면 콘솔에서 예산을 증액해 주세요.
• 예산이 부족할 경우, 비즈월렛에서 금액을 충전해 예산을 늘릴 수 있어요.
• 예산이 모두 소진되면 프로모션이 자동으로 종료되어 4109 에러가 발생해요.
• 예산 부족으로 인해 포인트 지급이 실패하면 사용자 CS 이슈로 이어질 수 있으니 주의해 주세요.

코드	메시지	발생 원인 / 대응 방법
4100	프로모션 정보를 찾을 수 없어요	콘솔에 등록되지 않은 프로모션 키로 호출한 경우
4109	프로모션이 실행중이 아니에요	콘솔에서 프로모션을 시작하지 않았거나, 예산이 모두 소진되어 자동 종료된 경우
4110	리워드를 지급/회수할 수 없어요	내부 시스템 오류 발생한 경우로, 재지급 로직을 적용해 주세요.
4111	리워드 지급내역을 찾을 수 없어요	존재하지 않은 지급 내역을 조회한 경우
4112	프로모션 머니가 부족해요	예산 부족으로 지급이 실패한 경우로, 콘솔에서 예산 증액 또는 비즈월렛 충전 필요
4114	1회 지급 금액을 초과했어요
4116	최대 지급 금액이 예산을 초과했어요
ERROR	알 수 없는 오류가 발생했어요.
undefined	앱 버전이 최소 지원 버전보다 낮아요.

예제

js

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

async function handleGrantPromotionReward() {
  const result = await grantPromotionReward({
    params: {
      promotionCode: '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);
  }
}

React

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

function GrantRewardButton() {
  async function handleClick() {
    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 <button onClick={handleClick}>포인트 지급하기</button>;
}

React Native

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 <Button onPress={handlePress} title="포인트 지급하기" />;
}

---

서버를 통해 프로모션 포인트 지급하기

파트너사 서버에서 직접 API를 호출해 유저에게 토스 포인트를 지급하는 방식이에요.

프로모션 대상 사용자 식별하기

프로모션 API는 아래 2가지 방법 중 하나로 프로모션 대상을 식별해요. 두 값을 동시에 전달하지 말고 하나만 선택해 주세요.

구분	발급 방법
x-toss-user-key	토스 로그인으로 받은 userKey 값이에요.
x-anon-key	사용자 식별키 발급으로 받은 hash 값이에요.

목적에 따라 선택해 주세요.

• 이미 토스 로그인을 연동했거나, 이름·이메일 같은 회원 정보와 묶어 통합 관리하려면 토스 로그인을 사용해요.
• 로그인 연동 없이 가볍게 사용자만 식별하려면 사용자 식별키 발급 기능을 사용해요.

x-anon-key(hash)가 유효한 값인지 미리 확인하고 싶다면 식별키 검증하기 API를 사용해 주세요.

---

기본 정보

항목	값
Base URL	https://apps-in-toss-api.toss.im
서버 인증	mTLS (클라이언트 인증서)
Content-Type	application/json

서버 간 통신에는 mTLS 인증서가 필요해요

프로모션 API는 파트너 서버에서 앱인토스 서버로 호출하는 서버 간 통신이에요. 보안을 위해 서버에 mTLS 인증서를 설정한 뒤 호출해 주세요. 인증서 발급 방법은 mTLS 인증서 발급 방법을 참고해 주세요.

① 프로모션 리워드 지급 Key 생성하기

프로모션 지급을 위한 Key를 발급해요. 이 Key를 사용해 유저에게 리워드를 지급할 수 있어요.

주의해 주세요

• 유저에게 리워드를 지급하는 주체는 파트너사예요. 발급받은 Key로 유저에게 리워드를 지급하면, 프로모션 예산 한도 내에서 지속적으로 지급돼요.
• 1회 지급만 허용하려면 파트너사에서 자체적으로 제어해야 해요.
• 이미 사용한 지급 Key로 다시 지급을 시도하면 4113 에러가 발생해요. 추가 지급이 필요할 경우, 새로운 Key를 발급해 주세요.
• 발급받은 Key의 유효시간은 1시간이에요.

• Content-type: application/json
• Method: POST
• Endpoint: /api-partner/v1/apps-in-toss/promotion/execute-promotion/get-key

요청 헤더

프로모션 대상을 식별하는 헤더는 아래 2가지 중 하나를 사용해요. 두 헤더를 동시에 전달하지 마세요.

이름	타입	필수	설명
x-toss-user-key	string	택 1	토스 로그인으로 받은 userKey예요. 사용자 정보 받기를 통해 획득할 수 있어요.
x-anon-key	string	택 1	사용자 식별키 발급으로 받은 hash 값이에요.

응답 파라미터

이름	타입	설명
key	String	프로모션 지급을 위한 key 값 (base64 인코딩된 값)

{
  "resultType": "SUCCESS",
  "success": {
    "key": "3oBpxjUgl5r66edcVi7ynHGIjhzr9KOka6FfEKikev0="
  }
}

② 프로모션 리워드 지급하기

발급받은 key로 프로모션 리워드 지급을 실행해요. 지급 시 프로모션 예산에서 차감되며, 실제 지급까지는 약간의 지연이 발생할 수 있어요.

• Content-type: application/json
• Method: POST
• Endpoint: /api-partner/v1/apps-in-toss/promotion/execute-promotion

요청 헤더

프로모션 대상을 식별하는 헤더는 아래 2가지 중 하나를 사용해요. 두 헤더를 동시에 전달하지 마세요.

이름	타입	필수	설명
x-toss-user-key	string	택 1	토스 로그인으로 받은 userKey예요. 사용자 정보 받기를 통해 획득할 수 있어요.
x-anon-key	string	택 1	사용자 식별키 발급으로 받은 hash 값이에요.

요청 파라미터

이름	타입	필수	설명
promotionCode	String	Y	콘솔에서 생성한 프로모션 코드 ID
key	String	Y	프로모션 지급을 위해 발급받은 KEY
amount	Integer	Y	프로모션 지급 금액

{
  "promotionCode": "01JPPJ6SB66BQXXDAKRQZ6SZD7",
  "key": "3oBpxjUgl5r66edcVi7ynHGIjhzr9KOka6FfEKikev0=",
  "amount": 10
}

응답 파라미터

이름	타입	설명
key	String	프로모션 지급을 위해 발급받은 KEY

{
  "resultType": "SUCCESS",
  "success": {
    "key": "3oBpxjUgl5r66edcVi7ynHGIjhzr9KOka6FfEKikev0="
  }
}

③ 프로모션 지급 결과 조회하기

지급 요청 이후의 프로모션 지급 상태를 조회해요.

• Content-type: application/json
• Method: POST
• Endpoint: /api-partner/v1/apps-in-toss/promotion/execution-result

요청 헤더

프로모션 대상을 식별하는 헤더는 아래 2가지 중 하나를 사용해요. 두 헤더를 동시에 전달하지 마세요.

이름	타입	필수	설명
x-toss-user-key	string	택 1	토스 로그인으로 받은 userKey예요. 사용자 정보 받기를 통해 획득할 수 있어요.
x-anon-key	string	택 1	사용자 식별키 발급으로 받은 hash 값이에요.

요청 파라미터

이름	타입	필수	설명
promotionCode	String	Y	콘솔에서 생성한 프로모션 코드 ID
key	String	Y	프로모션 지급을 위해 발급받은 KEY

{
  "promotionCode": "01JPPJ6SB66BQXXDAKRQZ6SZD7",
  "key": "3oBpxjUgl5r66edcVi7ynHGIjhzr9KOka6FfEKikev0="
}

응답 파라미터

이름	타입	설명
success	String	프로모션 지급 결과 (SUCCESS / PENDING / FAILED)

{
  "resultType": "SUCCESS",
  "success": "PENDING"
}

에러 코드

프로모션 API 사용 중 발생할 수 있는 에러 코드 목록이에요. 응답 코드나 메시지를 참고해 적절한 예외 처리 로직을 적용해 주세요.

4109 에러가 발생한다면?

• 프로모션 예산의 80% 소진이 이메일로 안내가 발송돼요.
• 프로모션을 계속 진행하려면 콘솔에서 예산을 증액해 주세요.
• 예산이 부족할 경우, 비즈월렛에서 금액을 충전해 예산을 늘릴 수 있어요.
• 예산이 모두 소진되면 프로모션이 자동으로 종료되어 4109 에러가 발생해요.
• 예산 부족으로 인해 포인트 지급이 실패하면 사용자 CS 이슈로 이어질 수 있으니 주의해 주세요.

코드	메시지	발생 원인 / 대응 방법
4100	프로모션 정보를 찾을 수 없어요	콘솔에 등록되지 않은 프로모션 키로 호출한 경우
4109	프로모션이 실행중이 아니에요	콘솔에서 프로모션을 시작하지 않았거나, 예산이 모두 소진되어 자동 종료된 경우
4110	리워드를 지급/회수할 수 없어요	내부 시스템 오류 발생한 경우로, 재지급 로직을 적용해 주세요.
4111	리워드 지급내역을 찾을 수 없어요	존재하지 않은 지급 내역을 조회한 경우
4112	프로모션 머니가 부족해요	예산 부족으로 지급이 실패한 경우로, 콘솔에서 예산 증액 또는 비즈월렛 충전 필요
4113	이미 지급/회수된 내역이에요	동일한 Key로 중복 지급할 경우로, 새로운 Key를 발급해 재시도해 주세요.
4114	1회 지급 금액을 초과했어요
4116	최대 지급 금액이 예산을 초과했어요