개발하기

게임

SDK를 통해 연동해 주세요.

게임 로그인 getUserKeyForGame 으로부터 받은 유저 식별자(hash) 를 사용해 유저에게 프로모션 리워드를 지급할 수 있어요.
별도의 서버 연동 없이도 게임 미니앱 내에서 유저에게 토스 포인트를 지급하고, 혜택탭에 프로모션을 노출하여 트래픽을 키울 수 있어요.

⚠️ 중복 호출 주의
grantPromotionRewardForGame 함수를 중복 호출하면 동일한 유저에게 리워드가 중복 지급될 수 있으니, 방어 로직을 반드시 적용해 주세요.

자세한 내용은 grantPromotionRewardForGame 문서를 참고해주세요.

주의하세요

토스앱 5.232.0 버전 이상에서만 지원해요.
이 버전 미만에서는 undefined가 반환돼요.
모든 사용자의 식별자를 안정적으로 확보하기 위해 토스앱 최소 지원 버전을 5.232.0으로 상향했어요.
최소 버전 미만에서는 미니앱 진입 시 업데이트 안내 화면이 표시돼요.
실제 프로모션을 시작하기 전에, 테스트용 프로모션 코드로 최소 1회 이상 호출해야 합니다.
테스트 호출을 통해 프로모션이 정상적으로 등록 및 승인 상태로 전환돼요.

비게임

BaseURL

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

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

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

주의해주세요

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

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

요청 헤더

이름	타입	필수값 여부	설명
x-toss-user-key	string	Y	토스 로그인을 통해 획득한 userKey 값

응답 파라미터

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

json

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

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

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

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

요청 헤더

이름	타입	필수값 여부	설명
x-toss-user-key	string	Y	토스 로그인을 통해 획득한 userKey 값

요청 파라미터

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

json

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

응답

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

json

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

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

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

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

요청 헤더

이름	타입	필수값 여부	설명
x-toss-user-key	string	Y	토스 로그인을 통해 획득한 userKey 값

요청 파라미터

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

json

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

응답

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

json

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

에러 코드

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

4109 에러가 발생한다면?

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

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

개발하기 ​

게임 ​

비게임 ​

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

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

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

에러 코드 ​

개발하기

게임

비게임

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

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

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

에러 코드