토스 포인트 지급 연동하기

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

🚨 잠시만요

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

시작하기

계약하기

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

프로모션 머니 충전하기

사용자에게 토스 포인트를 지급하기 위해서는 프로모션 머니 충전이 필요해요.

워크스페이스의 프로모션 머니 탭으로 이동 후 + 충전하기 버튼을 눌러주세요.

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

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

• 국민카드 : 월 한도 100만원, 일 횟수제한 4회
• 하나카드 : 일 한도 100만원
• 신한카드 : 1일 한도 5만원
• 삼성카드 : 월 한도 50만원
• 현대카드 : 1회 한도 11만원, 1일 한도 55만원, 일 횟수제한 5회
• 롯데카드 : 1일 한도 50만원
• 농협카드 : 1회 한도 10만원, 1일 한도 50만원, 일 횟수제한 10회
• 우리카드 : 1회 한도 30만원, 1일 한도 30만원
• 비씨카드 : 준비중이에요

잠시만요

테스트용 별도의 포인트 지급은 어려워요. 불편하시겠지만 충전 후 테스트 부탁드려요.

프로모션 등록하기

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

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

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

연동 프로세스 이해하기

통신 방화벽 확인하기

In/Out Bound 방화벽 관리를 하신다면 아래 IP를 방화벽에 등록해주세요.

가맹점이 허용해야하는 outbound IP 목록(가맹점 -> 앱인토스)

도메인	IP	port
apps-in-toss-api-toss.im	117.52.3.192, 211.115.96.192, 106.249.5.192	443

API 공통규격 확인하기

도메인 정보

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

API 공통 응답

성공

// 성공일 경우 resultType이 SUCCESS로 설정되며 해당 API의 응답이 success 하위에 적재됩니다.
{
   "resultType":"SUCCESS",
   "success":{
      "sample":"data"
   }
}

실패

// 실패일 경우 resultType 이 FAIL로 설정되며 해당 실패 사유가 error 하위에 적재됩니다.
{
   "resultType":"FAIL",
   "error":{
      "errorCode":"INVALID_PARAMETER",
      "reason":"요청에 실패했습니다."
   }
}

개발하기

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-key	string	Y	토스 로그인을 통해 획득한 userKey 값

응답 파라미터

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

{
  "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-key	string	Y	토스 로그인을 통해 획득한 userKey 값

요청 파라미터

이름	타입	필수	설명
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="
  }
}

3. 프로모션 토스포인트 지급 결과 조회하기

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

• 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값

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

응답

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

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