Appearance

토스 포인트 지급 연동하기 ​

토스 사용자에게 프로모션을 통해 토스 포인트를 지급해보세요.

🚨 잠시만요

토스 포인트 지급 기능을 사용하기 위해서는 필수적으로 간편 로그인(토스 로그인)을 연동하셔야 해요.

계약하기 ​

프로모션 기능 사용을 위해서는 계약이 필요해요.
계약은 콘솔에서 진행하며, 대표관리자만 진행합니다.

정산 정보 입력하기 ​

워크스페이스의 정보 탭에서 정산 정보를 등록 후 검토 요청을 해주세요.
영업일 기준 2-3일 소요됩니다.

비즈 월렛 충전하기 ​

사용자에게 토스 포인트를 지급하기 위해서는 비즈 월렛 충전이 필요해요.

워크스페이스의 비즈 월렛 탭으로 이동 후 + 충전하기 버튼을 눌러주세요.

충전하실 금액을 선택하시고 결제를 진행해주세요.

현재 신용카드 결제만 제공하고 있어요. 카드별 결제 제한이 아래와 같으니 참고해주세요.

  • 인증결제 (viva_appin) : 전 카드사 결제제한 없음
  • 비인증결제 (viva_appinkvp) : 하나카드 1일 100만원 결제제한, 이외 카드사 결제제한 없음

잠시만요

테스트용 비즈 월렛 지급은 어려워요. 불편하시겠지만 충전 후 테스트를 부탁드려요.

프로모션 등록하기 ​

앱을 선택 후 프로모션 탭으로 이동하면 프로모션을 등록할 수 있어요.
+ 추가하기 버튼을 눌러주세요.

잠시만요

프로모션 검토 가이드라인을 확인하시어 프로모션을 등록해 주세요.

프로모션 정보를 입력해주시고 검토 요청하기 버튼을 눌러주세요.
프로모션 승인 심사를 거친 후에 결과를 메일로 발송해드립니다. 영업일 기준 2-3일 소요됩니다.

프로모션이 승인되면 결과를 확인하실 수 있어요.

테스트 진행하기 ​

프로모션 검수가 진행 중에도 테스트를 진행할 수 있어요.
등록 요청한 프로모션을 선택하시어 프로모션 코드를 확인해 주세요.
TEST_{promotionCode} 로 테스트를 부탁드립니다.

  • 테스트 진행 시에는 프로모션 머니가 차감되지 않고, 실제 사용자에게 토스 포인트가 지급되지 않습니다.
  • 포인트 지급 API 호출 시 resultType 이 SUCCESS 로 응답이 오는지 확인해 주세요.

꼭! 확인해 주세요

최소 1번의 포인트 지급 API 테스트가 진행되어야, 프로모션 검토 완료 후에도 프로모션을 사용할 수 있어요.
프로모션 별로 최소 1번의 포인트 지급 테스트가 필요해요.

개발하기 ​

1. 프로모션 리워드 지급 키 생성하기 ​

프로모션 지급을 위한 KEY를 발급합니다.

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

TIP

KEY 유효시간은 1시간이에요


요청 헤더

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

응답 파라미터

이름타입설명
keyString프로모션 지급을 위한 key 값
base64 인코딩된 값
json
{
  "resultType": "SUCCESS",
  "success": {
    "key": "3oBpxjUgl5r66edcVi7ynHGIjhzr9KOka6FfEKikev0="
  }
}

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

프로모션 지급을 실행해요.
프로모션 예산에서 차감되며, 지급 요청 이후 실제 지급까지 약간의 시간이 소요될 수 있어요.

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

요청 헤더

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

요청 파라미터

이름타입필수설명
promotionCodeStringY콘솔에서 생성한 프로모션 코드ID
keyStringY프로모션 지급을 위해 발급받은 KEY값
amountIntegerY프로모션 지급 금액
json
{
  "promotionCode": "01JPPJ6SB66BQXXDAKRQZ6SZD7",
	"key": "3oBpxjUgl5r66edcVi7ynHGIjhzr9KOka6FfEKikev0=",
  "amount": 10
}

응답

이름타입설명
keyString프로모션 지급을 위해 발급받은 KEY값
json
{
  "resultType": "SUCCESS",
  "success": {
    "key": "3oBpxjUgl5r66edcVi7ynHGIjhzr9KOka6FfEKikev0="
  }
}

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

프로모션 지급 결과를 확인해요.

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

요청 헤더

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

요청 파라미터

이름타입필수설명
promotionCodeStringY콘솔에서 생성한 프로모션 코드ID
keyStringY프로모션 지급을 위해 발급받은 KEY값
json
{
  "promotionCode": "01JPPJ6SB66BQXXDAKRQZ6SZD7",
	"key": "3oBpxjUgl5r66edcVi7ynHGIjhzr9KOka6FfEKikev0="
}

응답

이름타입설명
successString프로모션 지급 결과
- SUCCESS
- PENDING
- FAILED
json
{
  "resultType": "SUCCESS",
  "success": "PENDING"
}

에러 코드 ​

프로모션 API를 사용할 때 발생할 수 있는 에러 코드 목록이에요.
응답 코드 또는 에러 메시지를 참고해서 적절히 처리해 주세요.

코드메시지
4100프로모션 정보를 찾을 수 없어요
4110리워드를 지급/회수할 수 없어요
4111리워드 지급내역을 찾을 수 없어요
4112프로모션 머니가 부족해요
4113이미 지급/회수된 내역이에요
41141회 지급 금액을 초과했어요
4116최대 지급 금액이 예산을 초과했어요